# SecondEntrustUser 字段更新说明

## 更新时间
2025-11-21

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

## 表结构变更

### 新表结构
```sql
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）

#### 旧请求体
```json
{
  "tradeId": 1,
  "userPhone": "13800138000",
  "userName": "张三",
  "idCard": "110101199001011234",
  "idCardImg": "https://example.com/id_card.jpg"
}
```

#### 新请求体
```json
{
  "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：

```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;
```

```sql
-- 方案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