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

管理端补齐出行人后订单 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 修复：

UPDATE order_info SET process_status='PENDING_ROOM_CONFIG'
WHERE order_id=? AND process_status='PENDING_TRAVELER_INFO';

本次测试环境订单 HL20260423175303-5448（id=2047252402389598209）已同步修复。