# 管理端补齐出行人后订单 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）已同步修复。