# SecondEntrustUser 委托人信息模块

## 功能说明

本模块用于管理二手交易平台的委托人信息，支持委托人信息的创建、查询、更新和删除操作。

---

## 文件清单

### 1. Entity（实体类）
**路径**: `alien-entity/src/main/java/shop/alien/entity/second/SecondEntrustUser.java`

**功能**: 委托人信息实体类，对应数据库表 `second_entrust_user`

**主要字段**:
- `id`: 主键
- `tradeId`: 交易ID
- `userPhone`: 委托人电话
- `userName`: 委托人姓名
- `idCard`: 委托人身份证
- `idCardImg`: 委托人身份证照片
- `deleteFlag`: 删除标记（逻辑删除）
- `createdTime`: 创建时间（自动填充）
- `createdUserId`: 创建人ID（自动填充）
- `updatedTime`: 修改时间（自动填充）
- `updatedUserId`: 修改人ID（自动填充）

---

### 2. DTO（数据传输对象）
**路径**: `alien-entity/src/main/java/shop/alien/entity/second/vo/SecondEntrustUserDTO.java`

**功能**: 用于接收前端请求参数，包含参数校验

**校验规则**:
- `tradeId`: 必填
- `userPhone`: 必填，不能为空
- `userName`: 必填，不能为空
- `idCard`: 可选
- `idCardImg`: 可选

---

### 3. Mapper（数据访问层）
**路径**: `alien-entity/src/main/java/shop/alien/mapper/second/SecondEntrustUserMapper.java`

**功能**: 继承 MyBatis-Plus 的 `BaseMapper`，提供基础 CRUD 操作

---

### 4. Mapper XML（映射文件）
**路径**: `alien-entity/src/main/resources/mapper/second/SecondEntrustUserMapper.xml`

**功能**: MyBatis 映射配置文件，定义结果集映射和通用 SQL

---

### 5. Service（服务接口）
**路径**: `alien-second/src/main/java/shop/alien/second/service/SecondEntrustUserService.java`

**功能**: 定义委托人信息业务逻辑接口

**方法列表**:
- `createEntrustUser(SecondEntrustUserDTO dto)`: 创建委托人信息
- `getByTradeId(Integer tradeId)`: 根据交易ID获取委托人信息
- `updateEntrustUser(Integer id, SecondEntrustUserDTO dto)`: 更新委托人信息
- `deleteEntrustUser(Integer id)`: 删除委托人信息（逻辑删除）
- `getByUserPhone(String userPhone)`: 根据用户电话查询委托人信息列表

---

### 6. ServiceImpl（服务实现类）
**路径**: `alien-second/src/main/java/shop/alien/second/service/impl/SecondEntrustUserServiceImpl.java`

**功能**: 实现委托人信息业务逻辑

**特性**:
- 使用 `@Transactional` 保证事务一致性
- 完整的异常处理和日志记录
- 创建时检查交易是否已存在委托人信息
- 更新和删除时检查记录是否存在

---

### 7. Controller（控制器）
**路径**: `alien-second/src/main/java/shop/alien/second/controller/SecondEntrustUserController.java`

**功能**: 提供 RESTful API 接口

**接口列表**:
1. `POST /secondEntrustUser/create` - 创建委托人信息
2. `GET /secondEntrustUser/getByTradeId` - 根据交易ID获取委托人信息
3. `GET /secondEntrustUser/getById` - 根据ID获取委托人信息
4. `PUT /secondEntrustUser/update/{id}` - 更新委托人信息
5. `DELETE /secondEntrustUser/delete` - 删除委托人信息
6. `GET /secondEntrustUser/getByUserPhone` - 根据用户电话查询委托人信息列表

**特性**:
- 使用 Swagger 注解，自动生成 API 文档
- 参数校验（使用 `@Validated`）
- 完整的异常处理和日志记录
- 统一的响应格式（使用 `R` 封装）

---

## 数据库表结构

```sql
CREATE TABLE `second_entrust_user` (
  `id` int NOT NULL AUTO_INCREMENT COMMENT '主键',
  `trade_id` int NOT NULL COMMENT '交易ID',
  `user_phone` varchar(50) COMMENT '委托人电话',
  `user_name` varchar(20) COMMENT '委托人姓名',
  `id_card` varchar(255) COMMENT '委托人身份证',
  `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
);
```

---

## 技术栈

- **框架**: Spring Boot + MyBatis-Plus
- **数据库**: MySQL
- **文档**: Swagger 2
- **日志**: Lombok + SLF4J
- **参数校验**: Hibernate Validator

---

## 业务逻辑

### 创建委托人信息
1. 校验必填参数（tradeId、userPhone、userName）
2. 检查该交易是否已存在委托人信息
3. 如果不存在，创建新记录
4. 自动填充创建时间和创建人ID

### 更新委托人信息
1. 校验参数
2. 检查记录是否存在
3. 更新记录
4. 自动填充修改时间和修改人ID

### 删除委托人信息
1. 检查记录是否存在
2. 逻辑删除（设置 `delete_flag = 1`）
3. 不会物理删除数据

### 查询委托人信息
- 支持根据交易ID查询
- 支持根据ID查询
- 支持根据用户电话查询（可能返回多条记录）

---

## 使用示例

### 1. 创建委托人信息

```java
// Controller 调用
SecondEntrustUserDTO dto = new SecondEntrustUserDTO();
dto.setTradeId(1);
dto.setUserPhone("13800138000");
dto.setUserName("张三");
dto.setIdCard("110101199001011234");
dto.setIdCardImg("https://example.com/id_card.jpg");

boolean result = secondEntrustUserService.createEntrustUser(dto);
```

### 2. 查询委托人信息

```java
// 根据交易ID查询
SecondEntrustUser entrustUser = secondEntrustUserService.getByTradeId(1);

// 根据用户电话查询
List<SecondEntrustUser> list = secondEntrustUserService.getByUserPhone("13800138000");
```

### 3. 更新委托人信息

```java
SecondEntrustUserDTO dto = new SecondEntrustUserDTO();
dto.setTradeId(1);
dto.setUserPhone("13800138001");
dto.setUserName("李四");

boolean result = secondEntrustUserService.updateEntrustUser(1, dto);
```

### 4. 删除委托人信息

```java
boolean result = secondEntrustUserService.deleteEntrustUser(1);
```

---

## 注意事项

1. **逻辑删除**: 删除操作为逻辑删除，数据不会真正从数据库中删除
2. **自动填充**: 创建时间、修改时间、创建人ID、修改人ID 会自动填充，需要配置 MyBatis-Plus 的 MetaObjectHandler
3. **参数校验**: 创建和更新时会自动校验必填参数
4. **事务处理**: 创建、更新、删除操作都使用了事务，保证数据一致性
5. **异常处理**: 所有接口都有完整的异常处理，业务异常会返回友好的错误信息
6. **一个交易只能有一个委托人**: 创建时会检查该交易是否已存在委托人信息

---

## API 文档

启动项目后，访问 Swagger UI 查看完整的 API 文档：
```
http://localhost:端口/swagger-ui.html
```

在 Swagger 中搜索 "二手平台-委托人信息管理" 即可查看所有接口。

---

## 测试

详细的测试文档和测试数据请参考：`alien-second/API_TEST.md`

---

## 扩展建议

如果需要扩展功能，可以考虑：

1. **批量操作**: 添加批量创建、批量删除接口
2. **分页查询**: 添加分页查询接口
3. **高级查询**: 支持多条件组合查询
4. **文件上传**: 集成文件上传功能，直接上传身份证照片
5. **数据校验**: 添加身份证号码、手机号码的格式校验
6. **审核流程**: 添加委托人信息审核功能
7. **关联查询**: 与交易记录表关联查询，返回更详细的信息

---

## 版本历史

- **v1.0.0** (2025-11-21): 初始版本，实现基础 CRUD 功能