feat: admin 补齐出行人后 process_status 自动推进 (PR #1336)

changelogs/2026-04/23_fix_order-v2_traveler-process-advance.md

@@ -0,0 +1,66 @@
+# 管理端补齐出行人后订单 process_status 自动推进（修复顶部常驻「待补全出行人信息」）
+
+**日期**: 2026-04-23
+**PR**: #1336 (dev)
+**Issue**: #1335
+**类型**: fix
+**服务**: hl-order-service-v2
+
+---
+
+## 摘要
+
+订单详情页顶部的流程状态标签（如「待补全出行人信息」「待分配房间」「确认中」等）在管理员**逐个补齐出行人**场景下**不会**自动推进。表现：出行人列表 1/1 已完整填写，但顶部仍挂「待补全出行人信息」橙标，同时下游自动化（自动投保 / 自动签约）也不触发。
+
+本次修复让管理端两个出行人接口（新增 / 修改）在补齐后自动推进流程状态 `PENDING_TRAVELER_INFO → PENDING_ROOM_CONFIG`，与用户侧小程序自改订单走的是同一条状态机路径（T2, PROC_TRAVELER_DONE）。
+
+## 接口（路径不变，响应结构不变）
+
+- `POST /admin/order/{orderId}/travelers` — 新增出行人
+- `PUT  /admin/order/{orderId}/travelers/{travelerId}` — 修改出行人
+
+两个接口仍返回 `{"code":200,"message":"成功","data":{TravelerVO}}`，**入参 / 出参均未改动**。
+
+## 触发推进的条件
+
+满足以下**全部**条件时，接口在事务内自动把 `order.process_status` 从 `PENDING_TRAVELER_INFO` 推进到 `PENDING_ROOM_CONFIG`：
+
+1. 调用前订单 `process_status = PENDING_TRAVELER_INFO`
+2. `actualCount ≥ requiredCount`（`adultCount + childCount + youngChildCount + babyCount`）
+3. 所有出行人 `name + idCardType + idCardNo` 三字段均不为空
+
+不满足任一条件时**不推进**，也不报错 — 出行人仍能成功新增 / 修改。
+
+## 联动变化
+
+- 订单详情顶部流程标签：`待补全出行人信息` → `待分配房间`
+- 行程安排 tab 待办按钮随之联动（新状态下可点「分配房间」）
+- **订单已支付**（status = PAID / DEPOSIT_PAID）时，afterCommit 触发 `orderAutoProcessingService.triggerAutoProcessing`，按原有规则自动投保 + 启动合同签约流程（与 `OrderFieldEditService.replaceTravelers` 已有的触发点行为一致）
+
+## 前端联调建议
+
+1. 补齐 / 修改出行人接口调用后，**建议刷新订单详情**（流程标签 + 待办按钮 + 合同/保险 tab 会联动更新）
+2. 「待补全出行人信息」顶部标签不再是"静态数据"，现在会被后端主动翻译 — 前端无需额外判定
+3. `process_status` 字段类型仍为字符串枚举（`PENDING_TRAVELER_INFO` / `PENDING_ROOM_CONFIG` / …），字典详见 `process_status` 字典表，本次未新增值
+
+## 幂等与并发
+
+- 推进走状态机 + `casAdvanceProcess(PENDING_TRAVELER_INFO → PENDING_ROOM_CONFIG)`，非 `PENDING_TRAVELER_INFO` 状态 CAS miss 自然返回
+- 出行人新增 / 修改保持原有并发语义，无新增锁
+
+## 风险与回滚
+
+- 纯后端业务逻辑增强，不改接口签名 / 返回结构
+- 最多副作用：每次 add / update 内部多一次 `validateTravelers` 调用（2 次 SELECT），非性能热点
+- 回滚：revert PR #1336 即可恢复为空点成功（继续挂「待补全」橙标）
+
+## 数据修复
+
+生产订单如果出现类似状况（出行人已填完但顶部仍「待补全出行人信息」），可直接 SQL 修复：
+
+```sql
+UPDATE order_info SET process_status='PENDING_ROOM_CONFIG'
+WHERE order_id=? AND process_status='PENDING_TRAVELER_INFO';
+```
+
+本次测试环境订单 `HL20260423175303-5448`（id=2047252402389598209）已同步修复。