---
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`注解