# 搬运任务操作重构 + PC 端操作功能设计

- 日期：2026-07-15
- 分支：feature/20260713/task-module
- 状态：已评审通过（方案 A：单类路由表）

## 1. 背景与目标

任务状态操作目前存在两个入口：

- **ACS 入口**：`AcsFeedbackController` → `TransportTaskFeedbackServiceImpl.receiveAcsFeedback()`，用字符串 if-else 按 `status` 分发到 `handleExecuting/handlePicked/handleFinished/handleCancelled`，代码凌乱。
- **PC 入口**：尚不存在。前端 `views/task/transporttask/index.vue` 已有"完成任务/取消任务/强制完成任务"三个按钮，但都错绑在 `handleEdit` 上，未传操作类型。

目标：

1. 消灭 if-else 分发，改为表驱动策略（路由表）。
2. 操作业务代码统一集中到 `TransportTaskServiceImpl`；`handleExecuting/handlePicked/handleFinished/handleCancelled/publishEvent` 方法体**原样迁移**，不改业务逻辑。
3. 新增 PC 端统一操作接口 `POST /task/transport-task/operate`（taskId + operationType），支持 FINISHED / CANCELLED / FORCE-FINISH。
4. `APPLY-AGAIN`（二次请求）、`FORCE-FINISH`（强制完成）业务未开发，路由表中注册 todo 占位（仅打日志）。
5. 前端按钮补齐操作类型标识与调用逻辑。

## 2. 操作类型与入口矩阵

| 操作类型 | code | ACS 触发 | PC 触发 | 业务 |
|---|---|---|---|---|
| EXECUTING | EXECUTING | ✅ | ❌ | handleExecuting（已有） |
| PICKED | PICKED | ✅ | ❌ | handlePicked（已有） |
| FINISHED | FINISHED | ✅ | ✅ | handleFinished（已有） |
| CANCELLED | CANCELLED | ✅ | ✅ | handleCancelled（已有） |
| APPLY_AGAIN | APPLY-AGAIN | ✅ | ❌ | todo，未开发 |
| FORCE_FINISH | FORCE-FINISH | ❌ | ✅ | todo，未开发 |

## 3. 后端设计

### 3.1 枚举增强 `TaskOperationTypeEnum`（task-api 模块）

- 增加两个布尔属性：`acsAllowed`（允许 ACS 触发）、`pcAllowed`（允许 PC 触发），取值见上表。
- 增加静态解析方法 `getByCode(String code)`：忽略大小写匹配 `code`，找不到返回 `null`。

### 3.2 `TransportTaskServiceImpl`：路由表 + PC 入口

- 从 `TransportTaskFeedbackServiceImpl` **原样迁入**：`handleExecuting`、`handlePicked`、`handleFinished`、`handleCancelled`、`publishEvent`、`buildCallbackReq`（当前无调用方，随迁保留）；依赖 `TaskEventProducer`、`TaskCommonApiFactory`、`OBJECT_MAPPER` 相关部分随迁。
- 路由表：`EnumMap<TaskOperationTypeEnum, BiConsumer<TransportTaskDO, AcsFeedbackReqDTO>>`，在 `@PostConstruct` 中注册六种类型；`APPLY_AGAIN`、`FORCE_FINISH` 注册为 todo 占位（打 log.info，不做业务）。
- 新增接口方法 `dispatchOperation(TransportTaskDO task, TaskOperationTypeEnum type, AcsFeedbackReqDTO reqDTO)`：查路由表分发，查不到打 warn 日志。
- 新增 PC 入口 `operateTransportTask(TransportTaskOperateReqVO reqVO)`，`@Transactional(rollbackFor = Exception.class)`：
  1. 查任务，不存在 → 抛 `TRANSPORT_TASK_NOT_EXISTS`。
  2. `getByCode` 解析 operationType，为 `null` 或 `pcAllowed=false` → 抛新错误码 `TRANSPORT_TASK_OPERATION_NOT_SUPPORTED`。
  3. 任务已终态（79 完成 / 89 取消）→ 抛新错误码 `TRANSPORT_TASK_ALREADY_FINAL`（PC 端需给用户明确反馈，区别于 ACS 入口的静默幂等返回）。
  4. **PC 与 ACS 的差异点——记录完成类型/来源**：`FINISHED` → `task.setFinishedType("MANUAL")`（人工完成）；`FORCE_FINISH` → `task.setFinishedType("FORCE")`（强制完成）；`CANCELLED` 不设置。注意：`FORCE_FINISH` 的业务 handler 当前为 todo 占位、不执行 `updateById`，因此该 finishedType 设置在业务开发完成前不会实际落库，属预期行为。
  5. 构造仅含 `taskId`、`status` 的 `AcsFeedbackReqDTO`，调用 `dispatchOperation` 走同一路由表（保持 handler 签名不变）。
- 新错误码追加到 `ErrorCodeConstants`，编号顺延现有 task 模块段。

### 3.3 `TransportTaskFeedbackServiceImpl` 瘦身

只保留 ACS 前置处理，注入 `TransportTaskService` 后委托分发：

1. 查任务（不存在打 warn 返回，保持现状）。
2. 终态幂等判断（保持现状）。
3. 保存 `resultParam`（保持现状）。
4. 分发段替换为：

```java
TaskOperationTypeEnum type = TaskOperationTypeEnum.getByCode(reqDTO.getStatus());
if (type == null || !type.isAcsAllowed()) {
    log.warn("未知或不允许的 ACS 反馈状态, taskId={}, status={}", reqDTO.getTaskId(), reqDTO.getStatus());
    return;
}
transportTaskService.dispatchOperation(task, type, reqDTO);
```

`handle*`、`publishEvent`、`buildCallbackReq` 从此类删除。依赖方向为 Feedback → TransportTaskService 单向，无循环依赖；`receiveAcsFeedback` 的 `@Transactional` 保持，跨 Bean 调用按 REQUIRED 传播沿用同一事务。

### 3.4 Controller / VO

- `TransportTaskController` 新增：

```java
@PostMapping("/operate")
@Operation(summary = "PC 端操作搬运任务（完成/取消/强制完成）")
@PreAuthorize("@ss.hasPermission('task:transport-task:operate')")
public CommonResult<Boolean> operateTransportTask(@Valid @RequestBody TransportTaskOperateReqVO reqVO)
```

- 新 VO `TransportTaskOperateReqVO`（controller vo 包）：`@NotNull Long taskId`；`@NotEmpty String operationType`（取值 FINISHED/CANCELLED/FORCE-FINISH）。

## 4. 前端设计（web-antdv-next）

### 4.1 API（`api/task/transporttask/index.ts`）

```ts
/** PC 端操作搬运任务（完成/取消/强制完成） */
export function operateTransportTask(data: {
  operationType: string;
  taskId: number;
}) {
  return requestClient.post('/task/transport-task/operate', data);
}
```

### 4.2 页面（`views/task/transporttask/index.vue`）

- 新增操作函数：

```ts
async function handleOperate(
  row: TaskTransportTaskApi.TransportTask,
  operationType: string,
  label: string,
) {
  await confirm(`确认要${label}【${row.taskCode}】吗？`);
  await operateTransportTask({ taskId: row.taskId!, operationType });
  message.success(`${label}成功`);
  handleRefresh();
}
```

- 三个按钮 `onClick` 替换错绑的 `handleEdit`：
  - 完成任务 → `handleOperate(row, 'FINISHED', '完成任务')`
  - 取消任务 → `handleOperate(row, 'CANCELLED', '取消任务')`
  - 强制完成任务 → `handleOperate(row, 'FORCE-FINISH', '强制完成任务')`
- 备注：强制完成按钮当前 `auth` 复用 `task:transport-task:cancel`、icon 用 `CANCEL`，本次不调整权限（需菜单配套），仅修正绑定。

## 5. 错误处理

- PC 入口：任务不存在 / 操作类型不支持 / 任务已终态，均抛 ServiceException，由全局异常处理返回给前端提示。
- ACS 入口：保持现状（不存在/终态/未知状态均打日志静默返回成功，避免 ACS 重试）。
- MQ 发布失败：沿用 `publishEvent` 现有逻辑（callbackStatus=FAILED + 记录错误信息）。

## 6. 测试与验证

- 按项目约定本次不编写测试（CLAUDE.md：除非用户允许测试）。
- 验证方式：后端 `mvn compile`（task 模块）通过；前端 lint/类型检查通过。

## 7. 范围外（明确不做）

- APPLY-AGAIN、FORCE-FINISH 的具体业务实现（todo 占位）。
- 强制完成按钮的独立权限与菜单配置。
- PC 操作联动 ACS（如向 ACS 下发取消指令）。
- `finishedType` 的字典配置与前端字典展示。