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