# 商户证照历史管理接口文档

## 概述

本模块为 `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. 添加导出功能