证照合同

alien-store-platform/doc/SECOND_ENTRUST_USER_README.md

@@ -0,0 +1,254 @@
+# 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 功能
+

alien-store-platform/doc/SECOND_ENTRUST_USER_UPDATE_LOG.md

@@ -0,0 +1,238 @@
+# 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
+

alien-store-platform/doc/STORE_LICENSE_HISTORY_API.md

@@ -0,0 +1,198 @@
+# 商户证照历史管理接口文档
+
+## 概述
+
+本模块为 `alien-store-platform` 服务提供商户证照历史记录的完整管理功能，包括证照的创建、更新、删除、查询等操作。
+
+## 数据库表结构
+
+```sql
+CREATE TABLE `store_license_history` (
+  `id` int NOT NULL AUTO_INCREMENT COMMENT '主键',
+  `store_id` int NULL COMMENT '商户ID',
+  `license_status` int NOT NULL COMMENT '证照类型: 1-合同管理，2-食品经营许可证',
+  `license_execute_status` int NOT NULL COMMENT '审核状态: 1-审核中, 2-审核拒绝, 3-审核通过',
+  `img_url` varchar(500) NOT NULL COMMENT '图片URL',
+  `delete_flag` int NOT NULL DEFAULT '0' COMMENT '删除标记, 0:未删除, 1:已删除',
+  `created_time` datetime 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
+);
+```
+
+## 创建的文件清单
+
+### 1. Entity 实体类
+- **路径**: `alien-entity/src/main/java/shop/alien/entity/store/StoreLicenseHistory.java`
+- **说明**: 商户证照历史记录实体类，使用 MyBatis-Plus 注解映射数据库表
+
+### 2. Mapper 数据访问层
+- **路径**: `alien-entity/src/main/java/shop/alien/mapper/StoreLicenseHistoryMapper.java`
+- **说明**: 继承 MyBatis-Plus 的 BaseMapper，提供基础 CRUD 操作
+
+### 3. DTO 数据传输对象
+- **路径**: `alien-entity/src/main/java/shop/alien/entity/store/dto/StoreLicenseHistoryDTO.java`
+- **说明**: 用于接收前端请求参数，包含参数验证注解
+
+### 4. VO 视图对象
+- **路径**: `alien-entity/src/main/java/shop/alien/entity/store/vo/StoreLicenseHistoryVO.java`
+- **说明**: 用于返回给前端的视图对象，包含额外的显示字段（如商户名称、状态名称等）
+
+### 5. Service 服务接口
+- **路径**: `alien-store-platform/src/main/java/shop/alien/storeplatform/service/StoreLicenseHistoryService.java`
+- **说明**: 定义业务逻辑接口
+
+### 6. ServiceImpl 服务实现类
+- **路径**: `alien-store-platform/src/main/java/shop/alien/storeplatform/service/impl/StoreLicenseHistoryServiceImpl.java`
+- **说明**: 实现业务逻辑，包含完整的增删改查功能
+
+### 7. Controller 控制器
+- **路径**: `alien-store-platform/src/main/java/shop/alien/storeplatform/controller/StoreLicenseHistoryController.java`
+- **说明**: RESTful API 接口控制器，提供 HTTP 访问端点
+
+## API 接口列表
+
+### 1. 创建证照历史记录
+- **URL**: `POST /storeLicenseHistory/create`
+- **请求体**:
+```json
+{
+  "storeId": 1,
+  "licenseStatus": 1,
+  "licenseExecuteStatus": 1,
+  "imgUrl": "https://example.com/image.jpg"
+}
+```
+- **响应**:
+```json
+{
+  "code": 200,
+  "msg": "创建成功",
+  "data": {
+    "id": 1,
+    "storeId": 1,
+    "licenseStatus": 1,
+    "licenseExecuteStatus": 1,
+    "imgUrl": "https://example.com/image.jpg",
+    "createdTime": "2025-11-24 10:00:00"
+  }
+}
+```
+
+### 2. 更新证照历史记录
+- **URL**: `PUT /storeLicenseHistory/update`
+- **请求体**:
+```json
+{
+  "id": 1,
+  "storeId": 1,
+  "licenseStatus": 1,
+  "licenseExecuteStatus": 2,
+  "imgUrl": "https://example.com/image.jpg"
+}
+```
+
+### 3. 删除证照历史记录
+- **URL**: `DELETE /storeLicenseHistory/delete?id=1`
+- **说明**: 逻辑删除，将 delete_flag 设置为 1
+
+### 4. 根据ID查询证照历史记录
+- **URL**: `GET /storeLicenseHistory/getById?id=1`
+- **响应**:
+```json
+{
+  "code": 200,
+  "data": {
+    "id": 1,
+    "storeId": 1,
+    "storeName": "测试商户",
+    "licenseStatus": 1,
+    "licenseStatusName": "合同管理",
+    "licenseExecuteStatus": 3,
+    "licenseExecuteStatusName": "审核通过",
+    "imgUrl": "https://example.com/image.jpg",
+    "createdTime": "2025-11-24 10:00:00"
+  }
+}
+```
+
+### 5. 根据商户ID查询证照历史记录列表
+- **URL**: `GET /storeLicenseHistory/listByStoreId?storeId=1`
+- **响应**: 返回该商户的所有证照历史记录列表
+
+### 6. 根据商户ID和证照类型查询
+- **URL**: `GET /storeLicenseHistory/listByStoreIdAndType?storeId=1&licenseStatus=1`
+- **参数**:
+  - `storeId`: 商户ID
+  - `licenseStatus`: 证照类型（1-合同管理，2-食品经营许可证）
+- **响应**: 返回指定商户和类型的证照历史记录列表
+
+### 7. 分页查询证照历史记录
+- **URL**: `GET /storeLicenseHistory/page?current=1&size=10&storeId=1&licenseStatus=1&licenseExecuteStatus=3`
+- **参数**:
+  - `current`: 当前页（必填，默认 1）
+  - `size`: 每页大小（必填，默认 10）
+  - `storeId`: 商户ID（可选）
+  - `licenseStatus`: 证照类型（可选）
+  - `licenseExecuteStatus`: 审核状态（可选）
+- **响应**: 返回分页结果
+
+## 枚举值说明
+
+### 证照类型 (licenseStatus)
+- `1`: 合同管理
+- `2`: 食品经营许可证
+
+### 审核状态 (licenseExecuteStatus)
+- `1`: 审核中
+- `2`: 审核拒绝
+- `3`: 审核通过
+
+## 功能特性
+
+1. **完整的 CRUD 操作**: 支持创建、读取、更新、删除操作
+2. **参数验证**: 使用 `@Validated` 和 `@NotNull` 进行参数校验
+3. **逻辑删除**: 使用 MyBatis-Plus 的 `@TableLogic` 实现软删除
+4. **自动填充**: 创建时间和更新时间自动填充
+5. **异常处理**: 完善的异常捕获和错误提示
+6. **业务验证**: 
+   - 验证商户是否存在
+   - 验证证照类型和审核状态的有效性
+7. **数据转换**: 
+   - DTO 到 Entity 的转换
+   - Entity 到 VO 的转换，包含商户名称和状态名称的解析
+8. **分页查询**: 支持多条件组合查询和分页
+9. **Swagger 文档**: 完整的 API 文档注解
+
+## 使用示例
+
+### Swagger UI 访问
+启动 `alien-store-platform` 服务后，访问：
+- Swagger UI: `http://localhost:{port}/swagger-ui.html`
+- Swagger Bootstrap UI: `http://localhost:{port}/doc.html`
+
+在 "商家端-证照历史管理" 分组下可以看到所有接口。
+
+## 注意事项
+
+1. **数据库字段类型**: 原表结构中 `img_url` 字段类型为 `int`，这应该是错误的。实际代码中已将其定义为 `String` 类型用于存储图片 URL。建议修改数据库字段类型为 `varchar(500)`。
+
+2. **依赖关系**: 
+   - 依赖 `StoreInfo` 表用于验证商户是否存在和获取商户名称
+   - 需要确保 `StoreInfoMapper` 已正确注入
+
+3. **权限控制**: 当前接口未添加权限验证，如需要请在 Controller 中添加相应注解
+
+4. **事务管理**: 建议在 Service 实现类的方法上添加 `@Transactional` 注解
+
+## 后续扩展建议
+
+1. 添加审核日志记录
+2. 添加审核拒绝原因字段
+3. 添加证照过期时间字段
+4. 实现证照到期提醒功能
+5. 添加批量操作接口
+6. 添加导出功能
+