253 lines
9.4 KiB
Markdown
253 lines
9.4 KiB
Markdown
# 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` 阶段不编译测试代码，不受影响。
|