alien_cloud/alien-store-platform/doc/SECOND_ENTRUST_USER_UPDATE_LOG.md

SecondEntrustUser 字段更新说明

更新时间

2025-11-21

更新原因

数据库表结构调整，所有字段添加 entrust_ 前缀，新增 entrust_trade_no 字段

表结构变更

新表结构

CREATE TABLE `second_entrust_user` (
  `id` int NOT NULL AUTO_INCREMENT COMMENT '主键',
  `entrust_trade_id` int NOT NULL COMMENT '交易ID',
  `entrust_trade_no` varchar(50) NOT NULL COMMENT '交易编号',
  `entrust_user_phone` varchar(50) COMMENT '委托人电话',
  `entrust_user_name` varchar(20) COMMENT '委托人姓名',
  `entrust_id_card` varchar(255) COMMENT '委托人身份证',
  `entrust_id_card_img` varchar(255) COMMENT '委托人身份证照片',
  `delete_flag` int NOT NULL DEFAULT '0' COMMENT '删除标记, 0:未删除, 1:已删除',
  `created_time` datetime(1) NOT NULL COMMENT '创建时间',
  `created_user_id` int DEFAULT NULL COMMENT '创建人ID',
  `updated_time` datetime DEFAULT NULL COMMENT '修改时间',
  `updated_user_id` int DEFAULT NULL COMMENT '修改人ID',
  PRIMARY KEY (`id`) USING BTREE
);

字段对比

旧字段名	新字段名	说明
trade_id	entrust_trade_id	交易ID
-	entrust_trade_no	交易编号（新增）
user_phone	entrust_user_phone	委托人电话
user_name	entrust_user_name	委托人姓名
id_card	entrust_id_card	委托人身份证
id_card_img	entrust_id_card_img	委托人身份证照片

代码调整清单

1. Entity 实体类

文件: alien-entity/src/main/java/shop/alien/entity/second/SecondEntrustUser.java

变更内容:

• tradeId → entrustTradeId
• 新增 entrustTradeNo
• userPhone → entrustUserPhone
• userName → entrustUserName
• idCard → entrustIdCard
• idCardImg → entrustIdCardImg

2. DTO 数据传输对象

文件: alien-entity/src/main/java/shop/alien/entity/second/vo/SecondEntrustUserDTO.java

变更内容:

• 字段名全部更新为带 entrust_ 前缀
• 移除继承 SecondTradeRecord（不合适的设计）
• 恢复参数校验注解

3. Mapper XML

文件: alien-entity/src/main/resources/mapper/second/SecondEntrustUserMapper.xml

变更内容:

• 更新 resultMap 的字段映射
• 更新 Base_Column_List

4. Service 接口

文件: alien-second/src/main/java/shop/alien/second/service/SecondEntrustUserService.java

变更内容:

• 方法参数名更新
• 新增 getByTradeNo(String entrustTradeNo) 方法

5. Service 实现类

文件: alien-second/src/main/java/shop/alien/second/service/impl/SecondEntrustUserServiceImpl.java

变更内容:

• 所有字段引用更新为新字段名
• 实现 getByTradeNo 方法
• 添加 StringUtils 导入

6. Controller 控制器

文件: alien-second/src/main/java/shop/alien/second/controller/SecondEntrustUserController.java

变更内容:

• 接口参数名更新
• 新增 /getByTradeNo 接口

7. API 测试文档

文件: alien-second/API_TEST.md

变更内容:

• 更新所有请求示例
• 更新响应示例
• 更新测试 SQL

API 接口变更

新增接口

GET /secondEntrustUser/getByTradeNo?entrustTradeNo=TRADE202511210001

根据交易编号查询委托人信息

参数名变更

接口	旧参数名	新参数名
getByTradeId	tradeId	entrustTradeId
getByUserPhone	userPhone	entrustUserPhone

请求体变更（POST/PUT）

旧请求体

{
  "tradeId": 1,
  "userPhone": "13800138000",
  "userName": "张三",
  "idCard": "110101199001011234",
  "idCardImg": "https://example.com/id_card.jpg"
}

新请求体

{
  "entrustTradeId": 1,
  "entrustTradeNo": "TRADE202511210001",
  "entrustUserPhone": "13800138000",
  "entrustUserName": "张三",
  "entrustIdCard": "110101199001011234",
  "entrustIdCardImg": "https://example.com/id_card.jpg"
}

兼容性说明

⚠️ 重大变更（Breaking Changes）

1. API 接口参数名变更: 前端需要同步修改请求参数名
2. 响应数据字段名变更: 前端需要同步修改字段名解析
3. 数据库表结构变更: 需要执行数据迁移 SQL

数据迁移 SQL

如果原表已有数据，需要执行以下迁移 SQL：

-- 方案1: 重命名字段（如果表已存在且有数据）
ALTER TABLE second_entrust_user 
  CHANGE COLUMN trade_id entrust_trade_id int NOT NULL COMMENT '交易ID',
  ADD COLUMN entrust_trade_no varchar(50) COMMENT '交易编号' AFTER entrust_trade_id,
  CHANGE COLUMN user_phone entrust_user_phone varchar(50) COMMENT '委托人电话',
  CHANGE COLUMN user_name entrust_user_name varchar(20) COMMENT '委托人姓名',
  CHANGE COLUMN id_card entrust_id_card varchar(255) COMMENT '委托人身份证',
  CHANGE COLUMN id_card_img entrust_id_card_img varchar(255) COMMENT '委托人身份证照片';

-- 如果需要填充 entrust_trade_no 字段，可以从交易表关联查询
UPDATE second_entrust_user seu
INNER JOIN second_trade_record str ON seu.entrust_trade_id = str.id
SET seu.entrust_trade_no = str.trade_no;

-- 方案2: 创建新表并迁移数据（推荐，更安全）
-- 1. 备份原表
CREATE TABLE second_entrust_user_backup AS SELECT * FROM second_entrust_user;

-- 2. 删除原表
DROP TABLE second_entrust_user;

-- 3. 创建新表（使用新的表结构）
CREATE TABLE `second_entrust_user` (
  `id` int NOT NULL AUTO_INCREMENT COMMENT '主键',
  `entrust_trade_id` int NOT NULL COMMENT '交易ID',
  `entrust_trade_no` varchar(50) NOT NULL COMMENT '交易编号',
  `entrust_user_phone` varchar(50) COMMENT '委托人电话',
  `entrust_user_name` varchar(20) COMMENT '委托人姓名',
  `entrust_id_card` varchar(255) COMMENT '委托人身份证',
  `entrust_id_card_img` varchar(255) COMMENT '委托人身份证照片',
  `delete_flag` int NOT NULL DEFAULT '0' COMMENT '删除标记, 0:未删除, 1:已删除',
  `created_time` datetime(1) NOT NULL COMMENT '创建时间',
  `created_user_id` int DEFAULT NULL COMMENT '创建人ID',
  `updated_time` datetime DEFAULT NULL COMMENT '修改时间',
  `updated_user_id` int DEFAULT NULL COMMENT '修改人ID',
  PRIMARY KEY (`id`) USING BTREE
);

-- 4. 迁移数据
INSERT INTO second_entrust_user (
  id, entrust_trade_id, entrust_user_phone, entrust_user_name, 
  entrust_id_card, entrust_id_card_img, delete_flag, 
  created_time, created_user_id, updated_time, updated_user_id
)
SELECT 
  id, trade_id, user_phone, user_name, 
  id_card, id_card_img, delete_flag, 
  created_time, created_user_id, updated_time, updated_user_id
FROM second_entrust_user_backup;

-- 5. 填充 entrust_trade_no
UPDATE second_entrust_user seu
INNER JOIN second_trade_record str ON seu.entrust_trade_id = str.id
SET seu.entrust_trade_no = str.trade_no;

测试建议

1. 单元测试: 测试所有 Service 方法
2. 接口测试: 使用 Postman 测试所有接口
3. 集成测试: 测试与交易记录表的关联查询
4. 数据校验: 确认 entrust_trade_no 字段填充正确

回滚方案

如果需要回滚到旧版本：

1. 从备份表恢复数据
2. 恢复旧的代码版本
3. 重启服务

注意事项

1. ⚠️ 此次更新为不兼容更新，前端必须同步修改
2. ⚠️ 执行数据迁移前务必备份数据
3. ⚠️ 建议在测试环境先验证后再上生产
4. ✅ 代码已通过 Linter 检查，无错误
5. ✅ 新增了按交易编号查询的功能

版本信息

• 旧版本: v1.0.0
• 新版本: v1.1.0
• 更新日期: 2025-11-21