113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# TransportTaskApi RPC 查询接口设计（补全 todo）
|
||
|
||
- 日期：2026-07-16
|
||
- 分支：feature/20260713/task-module
|
||
- 状态：已评审通过（方案 1：Api → Service → Mapper 标准分层）
|
||
|
||
## 1. 背景与目标
|
||
|
||
`TransportTaskApi`（Task 服务 RPC 接口，LMS/WMS 经 Feign 调用）中有两个 todo 待实现：
|
||
|
||
```java
|
||
// todo 根据taskId查找任务（返回TaskInfoDTO、过滤删除）
|
||
// todo 根据taskCode获取任务（返回TaskInfoDTO、过滤删除）
|
||
```
|
||
|
||
目标：补全这两个 RPC 查询接口，返回已存在的 `TaskInfoDTO`（35 字段全量数据），自动过滤逻辑删除的数据。
|
||
|
||
## 2. 关键事实（探索确认）
|
||
|
||
- `TaskInfoDTO` 已存在于 `nl-module-task-api/.../dto/TaskInfoDTO.java`，字段与 `TransportTaskDO` 同名同义（vehicleQty=Long、callbackRetryCount=Integer 均一致），可零配置映射。
|
||
- `BaseDO.deleted` 带 `@TableLogic`，MyBatis-Plus 的 `selectById`/`selectOne` 自动追加 `deleted=0`，"过滤删除"无需手写条件。
|
||
- MapStruct 1.6.3 经 `nl-common` 传递依赖对 task-server 可用（infra 模块 `ConfigConvert` 即此模式），无需改 pom。
|
||
- task 模块尚无 `convert` 包，需新建。
|
||
- Mapper 已有 `selectOne` 简单查询先例（`selectUnfinishedByBiz`），团队规范允许简单查询用 MyBatis-Plus 自带方法。
|
||
|
||
## 3. 设计
|
||
|
||
### 3.1 `TransportTaskApi`（api 模块）
|
||
|
||
删除两行 todo，新增两个 GET 方法（遵循"feign 方法名驼峰、url 与方法名一致"规则；注解风格与本文件现有方法保持一致）：
|
||
|
||
```java
|
||
@GetMapping(PREFIX + "/getTaskById")
|
||
@Operation(summary = "根据 taskId 查询任务（LMS/WMS 调用）")
|
||
CommonResult<TaskInfoDTO> getTaskById(@RequestParam("taskId") Long taskId);
|
||
|
||
@GetMapping(PREFIX + "/getTaskByCode")
|
||
@Operation(summary = "根据 taskCode 查询任务（LMS/WMS 调用）")
|
||
CommonResult<TaskInfoDTO> getTaskByCode(@RequestParam("taskCode") String taskCode);
|
||
```
|
||
|
||
需补充 import：`GetMapping`、`RequestParam`、`TaskInfoDTO`。
|
||
|
||
### 3.2 `TransportTaskApiImpl`（server 模块）
|
||
|
||
只做委托（与现有模式一致）：
|
||
|
||
```java
|
||
@Override
|
||
public CommonResult<TaskInfoDTO> getTaskById(Long taskId) {
|
||
return success(transportTaskService.getTaskInfoById(taskId));
|
||
}
|
||
|
||
@Override
|
||
public CommonResult<TaskInfoDTO> getTaskByCode(String taskCode) {
|
||
return success(transportTaskService.getTaskInfoByCode(taskCode));
|
||
}
|
||
```
|
||
|
||
### 3.3 `TransportTaskService(Impl)`
|
||
|
||
新增两个方法（中文 javadoc）：
|
||
|
||
- `TaskInfoDTO getTaskInfoById(Long taskId)`：`transportTaskMapper.selectById(taskId)`，为 null 返回 null，否则 `TransportTaskConvert.INSTANCE.convert(task)`。
|
||
- `TaskInfoDTO getTaskInfoByCode(String taskCode)`：`transportTaskMapper.selectByTaskCode(taskCode)`，同上。
|
||
|
||
查不到（含已逻辑删除）统一返回 null，由调用方判断——不抛业务异常（已确认）。
|
||
|
||
### 3.4 新建 `TransportTaskConvert`（server 模块，仿 infra `ConfigConvert`）
|
||
|
||
路径：`nl-module-task-server/src/main/java/cn/code/nl/module/task/convert/transporttask/TransportTaskConvert.java`
|
||
|
||
```java
|
||
@Mapper
|
||
public interface TransportTaskConvert {
|
||
|
||
TransportTaskConvert INSTANCE = Mappers.getMapper(TransportTaskConvert.class);
|
||
|
||
TaskInfoDTO convert(TransportTaskDO bean);
|
||
}
|
||
```
|
||
|
||
字段全部同名，无需 `@Mapping` 配置。
|
||
|
||
### 3.5 `TransportTaskMapper`
|
||
|
||
新增（taskCode 业务唯一，返回单对象；`selectOne` 自动滤删）：
|
||
|
||
```java
|
||
/**
|
||
* 根据任务编码查询任务
|
||
*/
|
||
default TransportTaskDO selectByTaskCode(String taskCode) {
|
||
return selectOne(TransportTaskDO::getTaskCode, taskCode);
|
||
}
|
||
```
|
||
|
||
## 4. 错误处理
|
||
|
||
- 查不到 / 已逻辑删除：`success(null)`，调用方自行判断。
|
||
- 参数校验：Long/String 由 Spring MVC `@RequestParam` 必填约束兜底（缺参即 400），不额外写判空。
|
||
|
||
## 5. 测试与验证
|
||
|
||
- 按项目约定不编写测试。
|
||
- 验证：`mvn -pl nl-module-task/nl-module-task-server -am compile` BUILD SUCCESS（同时验证 MapStruct 注解处理器生成实现类无报错）。
|
||
|
||
## 6. 范围外（明确不做）
|
||
|
||
- taskCode 数据库唯一索引调整。
|
||
- LMS/WMS 调用方接入代码。
|
||
- 其他 Api 方法的改动。
|