Add phone backend support

backend/src/main/java/com/xyw/console/XywConsoleBackendApplication.java

@@ -9,9 +9,12 @@ import org.springframework.boot.autoconfigure.SpringBootApplication;
 public class XywConsoleBackendApplication {
 
   /**
-   * 代码作用（白话）：启动企微后端服务，让前端可以通过 localhost:8080 访问真实接口；关联文件：F:/Project/xyw_console/backend/src/main/resources/application.yml、F:/Project/xyw_console/start.bat；关联逻辑（调用链/消息链/数据流）：mvn spring-boot:run -> main() -> Spring 容器启动 -> Controller 对外提供 HTTP 接口。
+   * 代码作用（白话）：启动后端服务，让前端可以通过 localhost:8080 访问真实接口。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/resources/application.yml、F:/Project/xyw_console/start.bat。
+   * 关联逻辑（调用链/消息链/数据流）：main() -> Spring 容器启动 -> Controller 提供 HTTP 接口。
    */
   public static void main(String[] args) {
     SpringApplication.run(XywConsoleBackendApplication.class, args);
   }
 }
+

backend/src/main/java/com/xyw/console/config/WebConfig.java

@@ -8,13 +8,15 @@ import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 public class WebConfig implements WebMvcConfigurer {
 
   /**
-   * 代码作用（白话）：允许本地 8000 端口的前端页面跨域调用 8080 后端接口，否则浏览器会直接拦截请求；关联文件：F:/Project/xyw_console/src/modules/shared/wechat-api-client.js、F:/Project/xyw_console/start.bat；关联逻辑（调用链/消息链/数据流）：浏览器 fetch(http://localhost:8080) -> addCorsMappings() 放行 -> Controller 正常接收请求。
+   * 代码作用（白话）：允许本地 8000 端口前端跨域访问后端接口，避免浏览器把 fetch 请求挡掉。
+   * 关联文件：F:/Project/xyw_console/src/modules/shared/phone-api-client.js、F:/Project/xyw_console/src/modules/shared/wechat-api-client.js。
+   * 关联逻辑（调用链/消息链/数据流）：浏览器 fetch -> /api/** -> addCorsMappings() -> 后端控制器正常返回 JSON。
    */
   @Override
   public void addCorsMappings(CorsRegistry registry) {
     registry.addMapping("/api/**")
       .allowedOrigins("http://localhost:8000", "http://127.0.0.1:8000")
-      .allowedMethods("GET", "POST", "PUT", "OPTIONS")
+      .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
       .allowedHeaders("*");
   }
 }

backend/src/main/java/com/xyw/console/phone/config/PhoneMybatisConfig.java

+package com.xyw.console.phone.config;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean;
+import com.zaxxer.hikari.HikariDataSource;
+import javax.sql.DataSource;
+import org.apache.ibatis.logging.stdout.StdOutImpl;
+import org.apache.ibatis.session.SqlSessionFactory;
+import org.mybatis.spring.SqlSessionTemplate;
+import org.mybatis.spring.annotation.MapperScan;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.boot.autoconfigure.jdbc.DataSourceProperties;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@MapperScan(basePackages = "com.xyw.console.phone.mapper", sqlSessionTemplateRef = "phoneSqlSessionTemplate")
+public class PhoneMybatisConfig {
+
+  /**
+   * 代码作用（白话）：读取手机号模块独立数据库的连接配置，和主库配置分开，避免 phone 表误连到别的库。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/resources/application.yml。
+   * 关联逻辑（调用链/消息链/数据流）：application.yml -> app.datasource.phone -> phoneDataSourceProperties() -> 后续数据源初始化。
+   */
+  @Bean
+  @ConfigurationProperties(prefix = "app.datasource.phone")
+  public DataSourceProperties phoneDataSourceProperties() {
+    return new DataSourceProperties();
+  }
+
+  /**
+   * 代码作用（白话）：按 phone 独立配置创建 MySQL 连接池，让 wx_phone 走 xyw_data_test 库而不影响主库。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/resources/application.yml、F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/mapper/WxPhoneMapper.java。
+   * 关联逻辑（调用链/消息链/数据流）：phoneDataSourceProperties() -> phoneDataSource() -> phoneSqlSessionFactory() -> WxPhoneMapper。
+   */
+  @Bean(name = "phoneDataSource")
+  public DataSource phoneDataSource(@Qualifier("phoneDataSourceProperties") DataSourceProperties properties) {
+    return properties.initializeDataSourceBuilder().type(HikariDataSource.class).build();
+  }
+
+  /**
+   * 代码作用（白话）：给手机号模块单独建 MyBatis-Plus 会话工厂，让 phone Mapper 只连自己的数据源。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/mapper/WxPhoneMapper.java、F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/entity/WxPhoneEntity.java。
+   * 关联逻辑（调用链/消息链/数据流）：phoneDataSource() -> phoneSqlSessionFactory() -> MyBatis-Plus BaseMapper -> CRUD SQL。
+   */
+  @Bean(name = "phoneSqlSessionFactory")
+  public SqlSessionFactory phoneSqlSessionFactory(@Qualifier("phoneDataSource") DataSource phoneDataSource)
+    throws Exception {
+    MybatisSqlSessionFactoryBean factoryBean = new MybatisSqlSessionFactoryBean();
+    factoryBean.setDataSource(phoneDataSource);
+
+    MybatisConfiguration configuration = new MybatisConfiguration();
+    configuration.setMapUnderscoreToCamelCase(true);
+    configuration.setLogImpl(StdOutImpl.class);
+    factoryBean.setConfiguration(configuration);
+    factoryBean.setTypeAliasesPackage("com.xyw.console.phone.entity");
+
+    SqlSessionFactory sqlSessionFactory = factoryBean.getObject();
+    if (sqlSessionFactory == null) {
+      throw new IllegalStateException("手机号数据源 SqlSessionFactory 初始化失败");
+    }
+    return sqlSessionFactory;
+  }
+
+  /**
+   * 代码作用（白话）：把手机号模块的 SqlSessionFactory 包成模板对象，供 @MapperScan 指向 phone mapper 使用。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/mapper/WxPhoneMapper.java。
+   * 关联逻辑（调用链/消息链/数据流）：phoneSqlSessionFactory() -> phoneSqlSessionTemplate() -> WxPhoneMapper CRUD 执行。
+   */
+  @Bean(name = "phoneSqlSessionTemplate")
+  public SqlSessionTemplate phoneSqlSessionTemplate(@Qualifier("phoneSqlSessionFactory") SqlSessionFactory phoneSqlSessionFactory) {
+    return new SqlSessionTemplate(phoneSqlSessionFactory);
+  }
+}

backend/src/main/java/com/xyw/console/phone/controller/WxPhoneController.java

+package com.xyw.console.phone.controller;
+
+import com.xyw.console.common.ApiResponse;
+import com.xyw.console.phone.dto.WxPhoneSaveRequest;
+import com.xyw.console.phone.entity.WxPhoneEntity;
+import com.xyw.console.phone.service.WxPhoneService;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/wx-phones")
+@RequiredArgsConstructor
+public class WxPhoneController {
+
+  private final WxPhoneService wxPhoneService;
+
+  /**
+   * 代码作用（白话）：返回手机号卡列表，给前端列表页和筛选页直接用。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/service/WxPhoneService.java、F:/Project/xyw_console/src/modules/shared/phone-api-client.js。
+   * 关联逻辑（调用链/消息链/数据流）：GET /api/wx-phones -> listRecords() -> ApiResponse.success(data) -> 前端列表渲染。
+   */
+  @GetMapping
+  public ResponseEntity<ApiResponse<List<WxPhoneEntity>>> listRecords() {
+    return ResponseEntity.ok(ApiResponse.success(wxPhoneService.listRecords()));
+  }
+
+  /**
+   * 代码作用（白话）：按 id 读取单条手机号卡，给详情抽屉和编辑弹窗用。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/service/WxPhoneService.java、F:/Project/xyw_console/src/modules/phone/phone-detail-drawer.js。
+   * 关联逻辑（调用链/消息链/数据流）：GET /api/wx-phones/{id} -> getRecordById() -> ApiResponse.success(data) -> 详情/编辑打开。
+   */
+  @GetMapping("/{id}")
+  public ResponseEntity<ApiResponse<WxPhoneEntity>> getRecord(@PathVariable Long id) {
+    WxPhoneEntity entity = wxPhoneService.getRecordById(id);
+    if (entity == null) {
+      return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ApiResponse.<WxPhoneEntity>error(404, "未找到对应手机号卡"));
+    }
+    return ResponseEntity.ok(ApiResponse.success(entity));
+  }
+
+  /**
+   * 代码作用（白话）：校验并新增手机号卡，新增成功后返回最新入库结果。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/dto/WxPhoneSaveRequest.java、F:/Project/xyw_console/src/modules/phone/phone-add-dialog.js。
+   * 关联逻辑（调用链/消息链/数据流）：POST /api/wx-phones -> validateSaveRequest() -> createRecord() -> 列表刷新。
+   */
+  @PostMapping
+  public ResponseEntity<ApiResponse<WxPhoneEntity>> createRecord(@RequestBody WxPhoneSaveRequest request) {
+    String validationMessage = validateSaveRequest(request);
+    if (validationMessage != null) {
+      return ResponseEntity.badRequest().body(ApiResponse.<WxPhoneEntity>error(400, validationMessage));
+    }
+    WxPhoneEntity entity = wxPhoneService.createRecord(request);
+    return ResponseEntity.status(HttpStatus.CREATED).body(ApiResponse.success("新增成功", entity));
+  }
+
+  /**
+   * 代码作用（白话）：校验并编辑指定手机号卡，编辑成功后返回最新数据库记录。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/dto/WxPhoneSaveRequest.java、F:/Project/xyw_console/src/modules/phone/phone-add-dialog.js。
+   * 关联逻辑（调用链/消息链/数据流）：PUT /api/wx-phones/{id} -> validateSaveRequest() -> updateRecord() -> 列表刷新。
+   */
+  @PutMapping("/{id}")
+  public ResponseEntity<ApiResponse<WxPhoneEntity>> updateRecord(@PathVariable Long id, @RequestBody WxPhoneSaveRequest request) {
+    String validationMessage = validateSaveRequest(request);
+    if (validationMessage != null) {
+      return ResponseEntity.badRequest().body(ApiResponse.<WxPhoneEntity>error(400, validationMessage));
+    }
+    WxPhoneEntity entity = wxPhoneService.updateRecord(id, request);
+    if (entity == null) {
+      return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ApiResponse.<WxPhoneEntity>error(404, "未找到对应手机号卡"));
+    }
+    return ResponseEntity.ok(ApiResponse.success("编辑成功", entity));
+  }
+
+  /**
+   * 代码作用（白话）：删除指定手机号卡，删除成功后给前端一个明确结果。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/service/WxPhoneService.java、F:/Project/xyw_console/src/modules/phone/phone-list-runtime.js。
+   * 关联逻辑（调用链/消息链/数据流）：DELETE /api/wx-phones/{id} -> deleteRecord() -> ApiResponse.success() -> 列表重新加载。
+   */
+  @DeleteMapping("/{id}")
+  public ResponseEntity<ApiResponse<Boolean>> deleteRecord(@PathVariable Long id) {
+    boolean deleted = wxPhoneService.deleteRecord(id);
+    if (!deleted) {
+      return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ApiResponse.<Boolean>error(404, "未找到对应手机号卡"));
+    }
+    return ResponseEntity.ok(ApiResponse.success("删除成功", Boolean.TRUE));
+  }
+
+  /**
+   * 代码作用（白话）：集中校验新增和编辑的必填项，避免空手机号或空运营商直接写进数据库。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/dto/WxPhoneSaveRequest.java、F:/Project/xyw_console/src/modules/phone/phone-add-dialog.js。
+   * 关联逻辑（调用链/消息链/数据流）：createRecord()/updateRecord() -> validateSaveRequest() -> 返回 400 或继续保存。
+   */
+  public String validateSaveRequest(WxPhoneSaveRequest request) {
+    if (request == null) {
+      return "请求体不能为空";
+    }
+    if (!hasText(request.getPhoneNumber())) {
+      return "手机号不能为空";
+    }
+    if (!hasText(request.getChannelOperator())) {
+      return "渠道运营商不能为空";
+    }
+    return null;
+  }
+
+  /**
+   * 代码作用（白话）：判断字符串是不是有效内容，给表单必填校验复用。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/controller/WxPhoneController.java、F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/service/WxPhoneService.java。
+   * 关联逻辑（调用链/消息链/数据流）：validateSaveRequest() -> hasText() -> 决定返回 400 还是继续保存。
+   */
+  public boolean hasText(String value) {
+    return value != null && !value.trim().isEmpty();
+  }
+}

backend/src/main/java/com/xyw/console/phone/dto/WxPhoneSaveRequest.java

+package com.xyw.console.phone.dto;
+
+import lombok.Data;
+
+@Data
+public class WxPhoneSaveRequest {
+
+  private Long id;
+
+  private String phoneNumber;
+
+  private String realPerson;
+
+  private String iccid;
+
+  private String city;
+
+  private String imageAttachment1;
+
+  private String imageAttachment2;
+
+  private String cardStatus;
+
+  private String cardUsageLocation;
+
+  private Boolean wecom;
+
+  private Boolean wechat;
+
+  private Boolean outboundCall;
+
+  private String douyinAccount;
+
+  private Boolean miniProgramFiling;
+
+  private Boolean packageChange5yuan;
+
+  private String channelOperator;
+
+  private Boolean numberStatus;
+
+  private String linkedWecom;
+
+  private Boolean numberRetentionStatus;
+}

backend/src/main/java/com/xyw/console/phone/entity/WxPhoneEntity.java

+package com.xyw.console.phone.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+@Data
+@TableName("wx_phone")
+public class WxPhoneEntity {
+
+  @TableId(value = "id", type = IdType.AUTO)
+  private Long id;
+
+  @TableField("phone_number")
+  private String phoneNumber;
+
+  @TableField("real_person")
+  private String realPerson;
+
+  @TableField("iccid")
+  private String iccid;
+
+  @TableField("city")
+  private String city;
+
+  @TableField("image_attachment_1")
+  private String imageAttachment1;
+
+  @TableField("image_attachment_2")
+  private String imageAttachment2;
+
+  @TableField("card_status")
+  private String cardStatus;
+
+  @TableField("card_usage_location")
+  private String cardUsageLocation;
+
+  @TableField("wecom")
+  private Boolean wecom;
+
+  @TableField("wechat")
+  private Boolean wechat;
+
+  @TableField("outbound_call")
+  private Boolean outboundCall;
+
+  @TableField("douyin_account")
+  private String douyinAccount;
+
+  @TableField("mini_program_filing")
+  private Boolean miniProgramFiling;
+
+  @TableField("package_change_5yuan")
+  private Boolean packageChange5yuan;
+
+  @TableField("channel_operator")
+  private String channelOperator;
+
+  @TableField("mobile_status")
+  private Boolean numberStatus;
+
+  @TableField("linked_wecom")
+  private String linkedWecom;
+
+  @TableField("number_retention_status")
+  private Boolean numberRetentionStatus;
+
+  @TableField(exist = false)
+  private String wechatStatus;
+
+  @TableField(exist = false)
+  private String outbound;
+}

backend/src/main/java/com/xyw/console/phone/mapper/WxPhoneMapper.java

+package com.xyw.console.phone.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xyw.console.phone.entity.WxPhoneEntity;
+
+public interface WxPhoneMapper extends BaseMapper<WxPhoneEntity> {
+}

backend/src/main/java/com/xyw/console/phone/service/WxPhoneService.java

+package com.xyw.console.phone.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.xyw.console.phone.dto.WxPhoneSaveRequest;
+import com.xyw.console.phone.entity.WxPhoneEntity;
+import com.xyw.console.phone.mapper.WxPhoneMapper;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+@Service
+@RequiredArgsConstructor
+public class WxPhoneService {
+
+  private final WxPhoneMapper wxPhoneMapper;
+
+  /**
+   * 代码作用（白话）：把手机号列表按 id 倒序读出来，给前端列表页直接渲染。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/controller/WxPhoneController.java、F:/Project/xyw_console/src/modules/shared/phone-api-client.js。
+   * 关联逻辑（调用链/消息链/数据流）：GET /api/wx-phones -> listRecords() -> Mapper.selectList() -> 前端 normalizePhoneRecord() -> 列表展示。
+   */
+  public List<WxPhoneEntity> listRecords() {
+    return wxPhoneMapper.selectList(new QueryWrapper<WxPhoneEntity>().orderByDesc("id"))
+      .stream()
+      .map(this::normalizeEntity)
+      .toList();
+  }
+
+  /**
+   * 代码作用（白话）：按主键读一条手机号卡，给详情抽屉和编辑弹窗用。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/controller/WxPhoneController.java、F:/Project/xyw_console/src/modules/phone/phone-detail-drawer.js。
+   * 关联逻辑（调用链/消息链/数据流）：GET /api/wx-phones/{id} -> getRecordById() -> Mapper.selectById() -> 详情/编辑打开。
+   */
+  public WxPhoneEntity getRecordById(Long id) {
+    return normalizeEntity(wxPhoneMapper.selectById(id));
+  }
+
+  /**
+   * 代码作用（白话）：把前端新增表单写入 wx_phone 表，并返回带主键的新记录。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/controller/WxPhoneController.java、F:/Project/xyw_console/src/modules/phone/phone-add-dialog.js。
+   * 关联逻辑（调用链/消息链/数据流）：POST /api/wx-phones -> createRecord() -> copyRequestToEntity() -> Mapper.insert() -> 前端刷新列表。
+   */
+  public WxPhoneEntity createRecord(WxPhoneSaveRequest request) {
+    WxPhoneEntity entity = new WxPhoneEntity();
+    copyRequestToEntity(request, entity);
+    wxPhoneMapper.insert(entity);
+    return normalizeEntity(wxPhoneMapper.selectById(entity.getId()));
+  }
+
+  /**
+   * 代码作用（白话）：更新指定手机号卡，并把数据库里的最新记录返回给前端。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/controller/WxPhoneController.java、F:/Project/xyw_console/src/modules/phone/phone-add-dialog.js。
+   * 关联逻辑（调用链/消息链/数据流）：PUT /api/wx-phones/{id} -> updateRecord() -> Mapper.updateById() -> 前端刷新列表。
+   */
+  public WxPhoneEntity updateRecord(Long id, WxPhoneSaveRequest request) {
+    WxPhoneEntity entity = wxPhoneMapper.selectById(id);
+    if (entity == null) {
+      return null;
+    }
+    copyRequestToEntity(request, entity);
+    wxPhoneMapper.updateById(entity);
+    return normalizeEntity(wxPhoneMapper.selectById(id));
+  }
+
+  /**
+   * 代码作用（白话）：删除指定手机号卡，给控制器判断是否需要返回 404。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/controller/WxPhoneController.java、F:/Project/xyw_console/src/modules/phone/phone-list-runtime.js。
+   * 关联逻辑（调用链/消息链/数据流）：DELETE /api/wx-phones/{id} -> deleteRecord() -> Mapper.deleteById() -> 列表重新加载。
+   */
+  public boolean deleteRecord(Long id) {
+    return wxPhoneMapper.deleteById(id) > 0;
+  }
+
+  /**
+   * 代码作用（白话）：把接口入参安全地拷贝到数据库实体里，顺手做空白清洗和默认值处理。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/dto/WxPhoneSaveRequest.java、F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/entity/WxPhoneEntity.java。
+   * 关联逻辑（调用链/消息链/数据流）：createRecord()/updateRecord() -> copyRequestToEntity() -> Entity -> Mapper 持久化。
+   */
+  public void copyRequestToEntity(WxPhoneSaveRequest request, WxPhoneEntity entity) {
+    entity.setPhoneNumber(normalizeText(request.getPhoneNumber()));
+    entity.setRealPerson(normalizeText(request.getRealPerson()));
+    entity.setIccid(normalizeText(request.getIccid()));
+    entity.setCity(normalizeText(request.getCity()));
+    entity.setImageAttachment1(normalizeText(request.getImageAttachment1()));
+    entity.setImageAttachment2(normalizeText(request.getImageAttachment2()));
+    entity.setCardStatus(normalizeCardStatus(request.getCardStatus()));
+    entity.setCardUsageLocation(normalizeText(request.getCardUsageLocation()));
+    entity.setWecom(normalizeBoolean(request.getWecom(), Boolean.FALSE));
+    entity.setWechat(normalizeBoolean(request.getWechat(), Boolean.FALSE));
+    entity.setOutboundCall(normalizeBoolean(request.getOutboundCall(), Boolean.FALSE));
+    entity.setDouyinAccount(normalizeText(request.getDouyinAccount()));
+    entity.setMiniProgramFiling(normalizeBoolean(request.getMiniProgramFiling(), Boolean.FALSE));
+    entity.setPackageChange5yuan(normalizeBoolean(request.getPackageChange5yuan(), Boolean.FALSE));
+    entity.setChannelOperator(normalizeText(request.getChannelOperator()));
+    entity.setNumberStatus(normalizeBoolean(request.getNumberStatus(), Boolean.TRUE));
+    entity.setLinkedWecom(normalizeText(request.getLinkedWecom()));
+    entity.setNumberRetentionStatus(normalizeBoolean(request.getNumberRetentionStatus(), Boolean.TRUE));
+    entity.setWechatStatus(Boolean.TRUE.equals(entity.getWechat()) ? "正常" : "异常");
+    entity.setOutbound(Boolean.TRUE.equals(entity.getOutboundCall()) ? "可外呼" : "不可外呼");
+  }
+
+  /**
+   * 代码作用（白话）：把数据库里取回来的手机号卡统一整理成前端能直接吃的状态文本和空值格式。
+   * 关联文件：F:/Project/xyw_console/src/modules/shared/record-adapters.js、F:/Project/xyw_console/src/modules/phone/phone-list-runtime.js。
+   * 关联逻辑（调用链/消息链/数据流）：Mapper.selectList()/selectById() -> normalizeEntity() -> controller response -> 前端 normalizePhoneRecord()。
+   */
+  public WxPhoneEntity normalizeEntity(WxPhoneEntity entity) {
+    if (entity == null) {
+      return null;
+    }
+    entity.setPhoneNumber(normalizeText(entity.getPhoneNumber()));
+    entity.setRealPerson(normalizeText(entity.getRealPerson()));
+    entity.setIccid(normalizeText(entity.getIccid()));
+    entity.setCity(normalizeText(entity.getCity()));
+    entity.setImageAttachment1(normalizeText(entity.getImageAttachment1()));
+    entity.setImageAttachment2(normalizeText(entity.getImageAttachment2()));
+    entity.setCardStatus(normalizeCardStatus(entity.getCardStatus()));
+    entity.setCardUsageLocation(normalizeText(entity.getCardUsageLocation()));
+    entity.setDouyinAccount(normalizeText(entity.getDouyinAccount()));
+    entity.setChannelOperator(normalizeText(entity.getChannelOperator()));
+    entity.setLinkedWecom(normalizeText(entity.getLinkedWecom()));
+    entity.setWechatStatus(Boolean.TRUE.equals(entity.getWechat()) ? "正常" : "异常");
+    entity.setOutbound(Boolean.TRUE.equals(entity.getOutboundCall()) ? "可外呼" : "不可外呼");
+    return entity;
+  }
+
+  /**
+   * 代码作用（白话）：把前端可能传来的 0/1、正常/异常等卡状态，统一成页面能稳定显示的文本。
+   * 关联文件：F:/Project/xyw_console/src/modules/phone/phone-add-dialog.js、F:/Project/xyw_console/src/modules/phone/phone-list-runtime.js。
+   * 关联逻辑（调用链/消息链/数据流）：request.cardStatus/DB.card_status -> normalizeCardStatus() -> response.cardStatus -> 列表和详情显示。
+   */
+  public String normalizeCardStatus(String value) {
+    String normalized = normalizeText(value);
+    if (normalized == null) {
+      return "正常";
+    }
+    return switch (normalized) {
+      case "1", "正常", "正常在用" -> "正常";
+      case "0", "异常", "异常停机", "停机" -> "异常停机";
+      default -> normalized;
+    };
+  }
+
+  /**
+   * 代码作用（白话）：把字符串里的首尾空格去掉，空白内容直接当成没填。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/dto/WxPhoneSaveRequest.java、F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/entity/WxPhoneEntity.java。
+   * 关联逻辑（调用链/消息链/数据流）：request/entity 字段 -> normalizeText() -> 入库/出库前的统一清洗。
+   */
+  public String normalizeText(String value) {
+    if (value == null) {
+      return null;
+    }
+    String trimmedValue = value.trim();
+    return trimmedValue.isEmpty() ? null : trimmedValue;
+  }
+
+  /**
+   * 代码作用（白话）：给可空布尔字段补默认值，避免数据库和页面出现一堆 null。
+   * 关联文件：F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/dto/WxPhoneSaveRequest.java、F:/Project/xyw_console/backend/src/main/java/com/xyw/console/phone/entity/WxPhoneEntity.java。
+   * 关联逻辑（调用链/消息链/数据流）：request.Boolean -> normalizeBoolean() -> Entity.Boolean -> MyBatis-Plus 保存。
+   */
+  public Boolean normalizeBoolean(Boolean value, Boolean defaultValue) {
+    return value == null ? defaultValue : value;
+  }
+}

backend/src/main/java/com/xyw/console/wechat/entity/WxDataEntity.java

@@ -43,14 +43,15 @@ public class WxDataEntity {
   private String realNameOwner;
 
   @JsonProperty("account_location")
-  @TableField("账号位置")
+  @TableField("account_position")
   private String accountLocation;
 
   @JsonProperty("phone_image")
-  @TableField("手机图片")
+  @TableField("phone_image_url")
   private String phoneImage;
 
   @JsonProperty("real_name_owner_status")
   @TableField("real_name_owner_status")
   private Integer realNameOwnerStatus;
 }
+