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

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

概述

本模块为 alien-store-platform 服务提供商户证照历史记录的完整管理功能，包括证照的创建、更新、删除、查询等操作。

数据库表结构

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

• 请求体:

  {
  "storeId": 1,
  "licenseStatus": 1,
  "licenseExecuteStatus": 1,
  "imgUrl": "https://example.com/image.jpg"
  }
  

• 响应:

  {
  "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

• 请求体:

  {
  "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

• 响应:

  {
  "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. 添加导出功能