ab0151e84d
- 新增 getLastVehicleNo 接口用于查询最新车次号 - 在 PurchaseOrderController 中添加对应 GET 接口 - 实现 LastVehicleNoQry 查询执行器及查询逻辑 - 扩展相关 DTO 和 Gateway 接口定义 - 更新 OrderDealer 实体类及其映射配置 - 添加新的查询参数类 LastVehicleNoQry - 在 CostItem 中增加 requireQuantityAndPrice 字段 - 扩展 CostItemCostTypeEnum 枚举值
157 lines
5.4 KiB
Markdown
157 lines
5.4 KiB
Markdown
---
|
||
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`注解
|