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 方法的改动。
|