huachuang/docs/superpowers/plans/2026-07-16-transport-task-api-query.md

# TransportTaskApi RPC 查询接口 实现计划

> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。

**目标：** 补全 `TransportTaskApi` 两个 todo——根据 taskId / taskCode 查询任务，返回 `TaskInfoDTO`，自动过滤逻辑删除。

**架构：** Api（Feign GET）→ ApiImpl（委托）→ TransportTaskService（查询 + MapStruct 转换，查不到返回 null）→ TransportTaskMapper（selectById / selectByTaskCode，`@TableLogic` 自动滤删）。新建 `TransportTaskConvert`（MapStruct，字段同名零配置）。

**技术栈：** Java 17 / Spring Boot / MyBatis-Plus（BaseMapperX）/ MapStruct 1.6.3（经 nl-common 传递依赖，无需改 pom）

**规格：** `docs/superpowers/specs/2026-07-16-transport-task-api-query-design.md`

**约定：** 注释/日志中文；`@Resource` 注入；不写测试；不频繁 commit（最后统一一次，需用户同意）。

---

## 文件结构

| 文件 | 操作 | 职责 |
|---|---|---|
| `nl-module-task/nl-module-task-api/src/main/java/cn/code/nl/module/task/api/TransportTaskApi.java` | 修改 | 新增两个 Feign GET 查询方法，删除两行 todo |
| `nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/convert/transporttask/TransportTaskConvert.java` | 创建 | DO→TaskInfoDTO MapStruct 转换 |
| `nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/dal/mysql/transporttask/TransportTaskMapper.java` | 修改 | 新增 selectByTaskCode |
| `nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/service/transporttask/TransportTaskService.java` | 修改 | 接口新增 getTaskInfoById / getTaskInfoByCode |
| `nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/service/transporttask/TransportTaskServiceImpl.java` | 修改 | 实现两个查询方法 |
| `nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/api/TransportTaskApiImpl.java` | 修改 | 实现两个 Api 方法（委托 service） |

---

### 任务 1：`TransportTaskApi` 新增两个查询方法

**文件：**
- 修改：`nl-module-task/nl-module-task-api/src/main/java/cn/code/nl/module/task/api/TransportTaskApi.java`

- [ ] **步骤 1：补充 import**

在现有 import 区追加：

```java
import cn.code.nl.module.task.dto.TaskInfoDTO;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
```

- [ ] **步骤 2：删除两行 todo，替换为两个方法声明**

将文件末尾的：

```java
    // todo 根据taskId查找任务（返回TaskInfoDTO、过滤删除）

    // todo 根据taskCode获取任务（返回TaskInfoDTO、过滤删除）
```

替换为：

```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);
```

---

### 任务 2：新建 `TransportTaskConvert`

**文件：**
- 创建：`nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/convert/transporttask/TransportTaskConvert.java`

- [ ] **步骤 1：创建文件**

```java
package cn.code.nl.module.task.convert.transporttask;

import cn.code.nl.module.task.dal.dataobject.transporttask.TransportTaskDO;
import cn.code.nl.module.task.dto.TaskInfoDTO;
import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;

/**
 * 搬运任务 Convert
 *
 * @Author: liyongde
 * @Date: 2026/7/16
 */
@Mapper
public interface TransportTaskConvert {

    TransportTaskConvert INSTANCE = Mappers.getMapper(TransportTaskConvert.class);

    /**
     * DO 转 RPC 全量信息 DTO（字段同名，零配置映射）
     */
    TaskInfoDTO convert(TransportTaskDO bean);
}
```

---

### 任务 3：`TransportTaskMapper` 新增 `selectByTaskCode`

**文件：**
- 修改：`nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/dal/mysql/transporttask/TransportTaskMapper.java`

- [ ] **步骤 1：在 `selectUnfinishedByBiz` 方法之前新增**

```java
    /**
     * 根据任务编码查询任务（taskCode 业务唯一）
     */
    default TransportTaskDO selectByTaskCode(String taskCode) {
        return selectOne(TransportTaskDO::getTaskCode, taskCode);
    }
```

说明：`selectOne(SFunction, Object)` 为 `BaseMapperX` 现有重载（BaseMapperX.java:105），`@TableLogic` 自动过滤 `deleted=1`。

---

### 任务 4：`TransportTaskService` 接口与实现新增查询方法

**文件：**
- 修改：`nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/service/transporttask/TransportTaskService.java`
- 修改：`nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/service/transporttask/TransportTaskServiceImpl.java`

- [ ] **步骤 1：接口补充 import 并新增两个声明**

import 区追加（`AcsFeedbackReqDTO` 等已存在，勿重复）：

```java
import cn.code.nl.module.task.dto.TaskInfoDTO;
```

在 `dispatchOperation` 声明之后新增：

```java
    /**
     * 根据 taskId 查询任务全量信息（RPC 用，自动过滤逻辑删除，查不到返回 null）
     *
     * @param taskId 任务ID
     * @return 任务全量信息
     */
    TaskInfoDTO getTaskInfoById(Long taskId);

    /**
     * 根据 taskCode 查询任务全量信息（RPC 用，自动过滤逻辑删除，查不到返回 null）
     *
     * @param taskCode 任务编码
     * @return 任务全量信息
     */
    TaskInfoDTO getTaskInfoByCode(String taskCode);
```

- [ ] **步骤 2：实现类补充 import 并新增两个实现（放在 `dispatchOperation` 方法之后）**

import 区追加：

```java
import cn.code.nl.module.task.convert.transporttask.TransportTaskConvert;
import cn.code.nl.module.task.dto.TaskInfoDTO;
```

新增实现：

```java
    /**
     * 根据 taskId 查询任务全量信息：查不到返回 null，由调用方判断
     */
    @Override
    public TaskInfoDTO getTaskInfoById(Long taskId) {
        TransportTaskDO task = transportTaskMapper.selectById(taskId);
        return task != null ? TransportTaskConvert.INSTANCE.convert(task) : null;
    }

    /**
     * 根据 taskCode 查询任务全量信息：查不到返回 null，由调用方判断
     */
    @Override
    public TaskInfoDTO getTaskInfoByCode(String taskCode) {
        TransportTaskDO task = transportTaskMapper.selectByTaskCode(taskCode);
        return task != null ? TransportTaskConvert.INSTANCE.convert(task) : null;
    }
```

---

### 任务 5：`TransportTaskApiImpl` 实现两个方法

**文件：**
- 修改：`nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/api/TransportTaskApiImpl.java`

- [ ] **步骤 1：补充 import**

```java
import cn.code.nl.module.task.dto.TaskInfoDTO;
```

- [ ] **步骤 2：在 `receiveCallbackResult` 方法之后新增**

```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));
    }
```

---

### 任务 6：编译验证

- [ ] **步骤 1：编译（仓库根目录）**

```bash
mvn -pl nl-module-task/nl-module-task-server -am compile
```

预期：`BUILD SUCCESS`（同时验证 MapStruct 注解处理器生成 `TransportTaskConvertImpl` 无报错）。

---

### 任务 7：统一提交（可选，需用户同意）

- [ ] **步骤 1：确认用户同意后提交（仅本次相关文件）**

```bash
git add docs/superpowers/specs/2026-07-16-transport-task-api-query-design.md \
        docs/superpowers/plans/2026-07-16-transport-task-api-query.md \
        nl-module-task/nl-module-task-api/src/main/java/cn/code/nl/module/task/api/TransportTaskApi.java \
        nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/api/TransportTaskApiImpl.java \
        nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/convert/transporttask/TransportTaskConvert.java \
        nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/dal/mysql/transporttask/TransportTaskMapper.java \
        nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/service/transporttask/TransportTaskService.java \
        nl-module-task/nl-module-task-server/src/main/java/cn/code/nl/module/task/service/transporttask/TransportTaskServiceImpl.java
git commit -m "feat：TransportTaskApi 新增按 taskId/taskCode 查询任务 RPC 接口"
```

---

## 风险与注意事项

1. **工作区有未提交改动**：`TransportTaskService(Impl)`、`TransportTaskMapper` 均已有本地改动（含上一需求的路由表代码），实现时在现有基础上叠加，不要回退。
2. **MapStruct 与 Lombok 顺序**：模块继承的编译配置已被 infra 等模块的 Convert 验证可用，若编译报 MapStruct 处理器缺失，检查是否误改了 pom（本计划不改 pom）。
3. **`TransportTaskServiceImplTest`**：test 目录引用了 `TransportTaskApi`，`compile` 阶段不编译测试代码，不受影响。