4.1 KiB
4.1 KiB
TransportTaskApi RPC 查询接口设计（补全 todo）
- 日期：2026-07-16
- 分支：feature/20260713/task-module
- 状态：已评审通过（方案 1：Api → Service → Mapper 标准分层）
1. 背景与目标
TransportTaskApi（Task 服务 RPC 接口，LMS/WMS 经 Feign 调用）中有两个 todo 待实现：
// 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 与方法名一致"规则；注解风格与本文件现有方法保持一致）：
@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 模块）
只做委托（与现有模式一致）：
@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
@Mapper
public interface TransportTaskConvert {
TransportTaskConvert INSTANCE = Mappers.getMapper(TransportTaskConvert.class);
TaskInfoDTO convert(TransportTaskDO bean);
}
字段全部同名，无需 @Mapping 配置。
3.5 TransportTaskMapper
新增（taskCode 业务唯一，返回单对象；selectOne 自动滤删）：
/**
* 根据任务编码查询任务
*/
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 compileBUILD SUCCESS（同时验证 MapStruct 注解处理器生成实现类无报错）。
6. 范围外（明确不做）
- taskCode 数据库唯一索引调整。
- LMS/WMS 调用方接入代码。
- 其他 Api 方法的改动。