# 订单待办完成接口补齐业务前置校验（杜绝空点成功）

**日期**: 2026-04-23
**PR**: #1327 (dev)
**Issue**: #1324
**类型**: fix
**服务**: hl-order-service-v2

---

## 摘要

订单详情页「待办」按钮（分配房间 / 分配车辆 / 确认清单 / 购买保险 / 签署合同）**过去即使对应业务未完成也能直接点成功**，仅改 `order_todo.status=COMPLETED`，但 `order.checklist_confirmed` / `process_status` / 下游保险合同事件全未触发，相当于 UI 假成功。

本次修复在 `PUT /admin/order/todo/{todoId}/complete` 内部补齐业务前置校验，未就绪直接返回业务异常。

## 接口

**路径没变**：`PUT /admin/order/todo/{todoId}/complete`

**新的错误响应**（HTTP 仍为 200，业务码在 `Result.code`）：

| 触发场景 | `Result.code` | `Result.msg` |
|---|---|---|
| 点「分配房间」但房间未安排 | BUSINESS_ERROR | `请先在行程安排中完成房间分配` |
| 点「分配车辆」但车辆未安排 | BUSINESS_ERROR | `请先在行程安排中完成车辆分配` |
| 点「购买保险」但未投保 | BUSINESS_ERROR | `请先完成保险购买` |
| 点「签署合同」但合同未签 | BUSINESS_ERROR | `请先完成合同签署` |
| 点「确认清单」但 `process_status ≠ PENDING_CHECKLIST_CONFIRM` | BUSINESS_ERROR | `流程状态不正确,当前: {状态label}` |
| 点「确认清单」但尾款为负 | BUSINESS_ERROR | `确认后尾款为负(¥X),请调整优惠/增项后再确认` |

> 正常成功仍返回 `{"code":"SUCCESS","data":null}`。

## 「确认清单」待办的完整行为（本次接通）

以前：点「确认清单」只改 `order_todo.status`，没任何副作用。
现在：点「确认清单」会真正执行锁单全流程：

- 状态机 `PENDING_CHECKLIST_CONFIRM → READY`
- `order.checklist_confirmed = true`，`order.ready_at` 填充
- 所有未确认的 `order_discount` / `order_surcharge` 批量 `confirmed = 1`（优惠/增项金额锁定）
- 尾款锁定
- afterCommit 发布 `ChecklistConfirmedEvent` → 下游保险自动投保 + 合同自动签约流程启动
- Timeline 新增 `CHECKLIST_CONFIRMED` 记录

## 前端联调建议

1. 待办按钮点击后的错误提示继续按 `Result.msg` 显示即可，无需改接口调用方式
2. 「确认清单」按钮点击后建议**刷新订单详情页**，因为会联动触发 process_status + checklist_confirmed + 保险/合同状态变化
3. 行程安排 tab 的「暂未安排房间/车辆」与顶部待办按钮是一个系统：只要这边没数据，对应待办就点不动（符合直觉）
4. 「购买保险」/「签署合同」待办：只有当前端子模块或管理员在保险/合同页面成功操作后，对应待办才能被点

## 幂等与并发

- 「确认清单」受 `@Idempotent(keyArg=orderId+operatorId, timeout=60s)` + `@Lock4j('order:checklist:' + orderId)` 双重保护
- 其余待办按钮依然被单例 activeTodo 机制限制（只有当前序号最小的 PENDING 待办能被完成）

## 关联字典

无新增字典。`ProcessStatus` 枚举取值见 PR #1318 已发布的字典项（本次不动）。

## 风险与回滚

- 纯后端校验增强，**不改接口签名/返回结构**
- 回滚方式：revert PR #1327 即可恢复到空点成功的旧行为