ERPTurbo_Server/.lingma/rules/api_addition_guide.md

trigger
manual

新增接口需要添加的组件清单

注意： 不用管 erp-turbo-svc 这个目录的代码

本文档描述了在本项目中添加一个新的API接口时需要修改或创建的组件。

1. API层 (接口定义层)

注意这个 biz 可以是其他的名，如：user、goods、order等

1.1 DTO定义

• 查询参数类(Query)

  • 路径: erp-turbo-common/erp-turbo-api/src/main/java/com/xunhong/erp/turbo/api/biz/dto/qry/
  • 命名规范: 功能名+CountQry 或 功能名+ListQry 或 功能名+PageQry
  • 继承: Query 基类
  • 注解: @Data, @Schema, @EqualsAndHashCode(callSuper = true)

• 命令类(Command)

  • 路径: erp-turbo-common/erp-turbo-api/src/main/java/com/xunhong/erp/turbo/api/biz/dto/cmd/
  • 命名规范: 功能名+CreateCmd 或 功能名+UpdateCmd 或 功能名+DestroyCmd
  • 继承: Command 基类
  • 注解: @Data, @Schema, @EqualsAndHashCode(callSuper = true)

• 返回值类(Value Object)

  • 路径: erp-turbo-common/erp-turbo-api/src/main/java/com/xunhong/erp/turbo/api/biz/dto/vo/
  • 命名规范: 功能名+VO
  • 注解: @Data, @Schema

1.2 服务接口定义

• 接口文件
  • 路径: erp-turbo-common/erp-turbo-api/src/main/java/com/xunhong/erp/turbo/api/biz/api/
  • 文件命名: 功能名+ServiceI
  • 方法签名: 定义业务方法

2. 业务实现层 (Biz层)

2.1 服务实现

• 服务实现类
  • 路径: erp-turbo-business/erp-turbo-biz/src/main/java/com/xunhong/erp/turbo/biz/app/service/
  • 文件命名: 功能名+ServiceImpl
  • 实现接口: 实现对应的ServiceI接口
  • 注解: @Service, @DubboService, @RequiredArgsConstructor
  • 依赖注入: 通过构造函数注入执行器

2.2 查询执行器

• 查询执行器类
  • 路径: erp-turbo-business/erp-turbo-biz/src/main/java/com/xunhong/erp/turbo/biz/app/executor/query/
  • 文件命名: 功能名+QryExe
  • 注解: @Component, @RequiredArgsConstructor
  • 方法: execute()方法处理具体查询逻辑

2.3 命令执行器

• 命令执行器类
  • 路径: erp-turbo-business/erp-turbo-biz/src/main/java/com/xunhong/erp/turbo/biz/app/executor/cmd/
  • 文件命名: 功能名+CmdExe
  • 注解: @Component, @RequiredArgsConstructor
  • 方法: execute()方法处理具体命令逻辑

2.4 网关接口

• 网关接口
  • 路径: erp-turbo-business/erp-turbo-biz/src/main/java/com/xunhong/erp/turbo/biz/domain/gateway/
  • 文件命名: 功能名+Gateway
  • 定义数据访问方法

2.5 领域实体

• 领域实体类
  • 路径: erp-turbo-business/erp-turbo-biz/src/main/java/com/xunhong/erp/turbo/biz/domain/entity/
  • 文件命名: 功能名
  • 注解: @Data, @ToString, @Builder, @NoArgsConstructor, @AllArgsConstructor

2.6 数据实体

• 数据实体类
  • 路径: erp-turbo-business/erp-turbo-biz/src/main/java/com/xunhong/erp/turbo/biz/infrastructure/entity/
  • 文件命名: 功能名+DO
  • 继承: BaseDO
  • 注解: @Data, @TableName, @EqualsAndHashCode(callSuper = true)

2.7 数据转换器

• 转换器类
  • 路径: erp-turbo-business/erp-turbo-biz/src/main/java/com/xunhong/erp/turbo/biz/infrastructure/convert/
  • 文件命名: 功能名+Convert
  • 注解: @Mapper
  • 方法: 定义DO与领域实体、DO与VO之间的转换方法

2.8 数据访问层

• Mapper接口

  • 路径: erp-turbo-business/erp-turbo-biz/src/main/java/com/xunhong/erp/turbo/biz/infrastructure/mapper/
  • 文件命名: 功能名+Mapper
  • 继承: BaseMapper<实体类>
  • 注解: @Mapper

• Mapper XML文件

  • 路径: erp-turbo-business/erp-turbo-biz/src/main/resources/mapper/
  • 文件命名: 功能名+Mapper.xml

3. 控制层 (Controller层)

3.1 控制器

• 控制器类
  • 路径: erp-turbo-admin/src/main/java/com/xunhong/erp/turbo/admin/controller/
  • 文件命名: 功能名+Controller
  • 注解: @RestController, @RequestMapping, @RequiredArgsConstructor
  • 方法注解: @SaCheckLogin, @GetMapping/@PostMapping, @Operation
  • Dubbo引用: @DubboReference 注解引入服务接口

4. 枚举类 (如有需要)

4.1 枚举定义

• 枚举类
  • 路径: erp-turbo-common/erp-turbo-api/src/main/java/com/xunhong/erp/turbo/api/biz/dto/enums/
  • 文件命名: 功能名+Enum
  • 实现接口: DictEnum
  • 注解: @Getter, @AllArgsConstructor

5. 数据库变更 (如有需要)

5.1 数据库迁移脚本

• SQL脚本
  • 路径: db/migration/
  • 文件命名: V版本号__变更描述.sql

6. 测试用例 (建议)

6.1 单元测试

• 测试类
  • 路径: 对应模块的test目录下
  • 文件命名: 被测试类+Test

7. 接口文档

7.1 Swagger注解

• 所有Controller方法都应添加Swagger注解，包括:
  • @Tag - 类级别，描述接口分类
  • @Operation - 方法级别，描述接口功能
  • @Schema - 类属性级别，描述字段含义

8. 权限控制

8.1 权限注解

• 使用@SaCheckLogin进行登录检查
• 使用@SaCheckRole进行角色检查
• 使用@SaCheckPermission进行权限检查（如需要）

9. 校验注解

9.1 参数校验

• 在Query和Command类的字段上使用校验注解，如:
  • @NotNull - 非空校验
  • @NotBlank - 非空字符串校验
  • @Min/@Max - 数值范围校验
• 在Controller方法参数中使用@Validated注解