docs(changelog/order-v3): 修正补全弹窗②为紧急联系人必填(后端PR#4041补强581109),原误写非必填

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

changelogs-v2/2026-06/19_补全出行信息弹窗三处缺陷-前端待修-管理后台.md

@@ -1,21 +1,21 @@
-# 「补全出行信息」弹窗三处缺陷（回显不全 / 紧急联系人误必填 / 保存后不关闭） — 前端待修 — 管理后台
+# 「补全出行信息」弹窗三处缺陷（回显不全 / 紧急联系人必填 / 保存后不关闭） — 前端待修 + 后端已补强 — 管理后台
 
-> 变更类型：🐛 前端缺陷（**无后端代码变更、零 DDL**；后端接口与数据经测试服实测均正常，本文档给出对接修复方式 + 数据丢失避坑）
+> 变更类型：🐛 前端缺陷（①回显、③保存后不关闭，无后端代码变更）+ 🔧 后端门禁补强（②紧急联系人必填，PR #4041，零 DDL、无新增接口）；本文档给出前端对接修复方式 + 数据丢失避坑
 > 端类型：管理后台（订单详情页 → 「补全出行信息」弹窗）
 > 日期：2026-06-19
-> 服务：hl-order-service-v3（出行人 / 订单详情接口，均已上线且行为正常）
-> 责任端：前端 hl-ui（mmg）
+> 服务：hl-order-service-v3（出行人补全接口已补紧急联系人必填门禁 581109 / 订单详情明文回显接口已上线）
+> 责任端：前端 hl-ui（mmg，① ③ + ② 配合保持必填）；后端 order-v3（② 已修，PR #4041）
 > 实测样本：测试服网关 9443 + 真实 admin token，订单 `HL20260618165816942`（orderId=`2067532338723504130`，定制中 / 待补全信息）
 
 ---
 
 ## ⚠️ 关键说明
 
-这三个问题**全部在前端侧**。后端经测试服逐项实测均正常：
+问题 ① 回显不全、③ 保存后弹窗不关闭为**前端侧**；问题 ② 紧急联系人必填的**后端门禁已补强并部署测试服**（PR #4041），前端需配合「保持必填 + 处理新错误码」。后端经测试服逐项实测：
 
 - 后端**有**该出行人的完整明文数据，且已提供**明文回显接口**（订单详情 overview，#3509）；
-- 保存接口对该场景返回 **HTTP 200 `success=true`**（不是保存失败）；
-- 紧急联系人后端**不要求必填**（VO 无 `@NotBlank`，Service 无校验），空值提交返回 200。
+- 保存接口对「资料齐全」场景返回 **HTTP 200 `success=true`**（不是保存失败 → ③ 是前端没关弹窗）；
+- 紧急联系人按**合同要求必填**：后端原先未校验（空值可落库），现已补强制校验（错误码 `581109`，PR #4041 已合并 dev-v3 + 部署测试服实测）。
 
 > 🔴 **最高优先级警告（修复问题一时必读 §4）**：补全弹窗里被清空显示的「证件号 / 手机号」，若在保存时以**空字符串 `""`** 回传，后端会把数据库里**已有的真实证件号 / 手机号抹掉**（merge 语义：`null` 保留原值、`""` 覆盖为空）。修回显的同时必须改对保存回传，否则会造成线上数据丢失。
 
@@ -86,15 +86,21 @@ curl -k "https://api.test.1814.love:9443/v3/admin/order/2067532338723504130" \
 
 ---
 
-## 2. 问题二：紧急联系人被前端设为必填（后端并不要求）
+## 2. 问题二：紧急联系人必填（合同要求）— 后端已补强制校验
 
-**现象**：不填紧急联系人无法保存（前端拦截）。
+**结论**：紧急联系人**按合同要求必须填写**（弹窗副标题「根据合同要求，需填写所有出行人证件号与紧急联系人信息」即此意）。前端保持必填即可。
 
-**实测**：保存接口传**空紧急联系人**（`emergencyContactName=""`、`emergencyContactPhone=""`）→ **HTTP 200，`success=true`**，保存成功。后端 `TravelerInfoSaveReqVO` 的 `emergencyContactName` / `emergencyContactPhone` 无 `@NotBlank`，Service 层也无必填校验。
+**后端补强（PR #4041，已合并 dev-v3 + 部署测试服）**：此前后端 `saveTravelerInfo` 对紧急联系人**无任何校验**，空值提交会成功落库（合同必报字段只靠前端单点拦截不安全）。现已在后端补强制门禁，与前端必填形成双层保障：
 
-**修复方式**：前端去掉紧急联系人两个字段的「必填」校验。弹窗副标题「需填写……紧急联系人信息」也应同步改为非强制措辞（如「如有请填写紧急联系人」）。
+| 场景 | 后端返回 |
+|---|---|
+| 紧急联系人姓名 / 电话任一为空 | `581109`「紧急联系人姓名和电话必填」，不落库 |
+| 紧急联系人电话格式非法（非 11 位） | `581113`「手机号格式非法（应为 11 位数字）」 |
+| 姓名 + 合法电话齐全 | 200 正常保存 |
 
-> 注：紧急联系人手机号**若填了**，后端会校验 11 位手机号格式（不合法返 `581113`）；不填则跳过。即「非必填，但填了要合法」。
+**前端配合**：
+1. **保持**紧急联系人姓名 + 电话的「必填」前端校验（不要去掉），弹窗副标题维持「需填写紧急联系人」。
+2. 透传后端 `581109` / `581113` 的 `message` 给用户（用户绕过前端校验或格式不对时的兜底提示）。
 
 ---
 
@@ -152,7 +158,7 @@ curl -k "https://api.test.1814.love:9443/v3/admin/order/2067532338723504130" \
 | travelers[].**idNo** | 否 | 证件号**明文**回传（回显源字段叫 `idCard`，注意映射）；空串会覆盖，见 §4 |
 | travelers[].**phone** | 否 | 手机号明文回传；空串会覆盖，见 §4 |
 | travelers[].nationality / race | 否 | 不传后端默认「中国」/「汉族」；**传空串 `""` 会被拒**（`581101`） |
-| emergencyContactName / emergencyContactPhone | **否**（见 §2） | 订单级紧急联系人；电话填了要合法 11 位 |
+| emergencyContactName / emergencyContactPhone | **是**（合同要求，见 §2） | 订单级紧急联系人；姓名 + 电话必填（任一空 → `581109`），电话须合法 11 位（→ `581113`） |
 | customerRemark | 否 | 客户备注 |
 
 **幂等**：同订单 3 秒窗口重复提交被拒（HTTP 200 但 `success=false`），前端按 §3 判 `success`。
@@ -164,14 +170,16 @@ curl -k "https://api.test.1814.love:9443/v3/admin/order/2067532338723504130" \
 - `GET /v3/admin/order/{id}`：明文证件号 `152522198605311079`、手机号 `18547062756`、备注 `测试测试 哈哈哈哈`、profileStatus `COMPLETED` 均正常返回 ✓
 - `GET /v3/admin/order/{id}/traveler/list`：证件号为脱敏 `152***********1079`、手机号 `185****2756`（确认前端用错了脱敏源会留空）✓
 - `PUT /v3/admin/order/{id}/traveler-info`（保留明文值）：HTTP 200 `success=true`、`allCompleted=true` ✓
-- `PUT`（空紧急联系人）：HTTP 200 `success=true`（确认紧急联系人非必填）✓
+- `PUT`（空紧急联系人，PR #4041 部署后）：返 `581109`「紧急联系人姓名和电话必填」、不落库 ✓
+- `PUT`（紧急联系人电话格式非法）：返 `581113`「手机号格式非法」 ✓
+- `PUT`（姓名 + 合法电话齐全）：HTTP 200 `success=true` 回归正常 ✓
 - 连续两次 `PUT`：第二次 `success=false`（确认 3 秒幂等窗口，前端需判 `success`）✓
-- 测试结束已将订单数据恢复原状（紧急联系人 `1`/`18547056215`、证件号、profileStatus 均还原）✓
+- 测试结束已将订单数据恢复原状（紧急联系人 `1`/`18547056215`、证件号、profileStatus 均完好）✓
 
 ---
 
 ## 备注
 
-- 本文为前端缺陷通知 + 现有接口对接说明，**无后端代码变更、零 DDL、无新增 / 改动接口**。
-- 不建 Gitea 工单（前端 bug 走 changelog 通知前端同事）。
+- 问题 ①③ 为前端缺陷（**无后端代码变更**），走本 changelog 通知前端同事，不建工单。
+- 问题 ② 紧急联系人必填后端门禁经 **PR #4041 补强**（新增错误码 `581109`，复用 `581113`，**无 DDL、无新增接口**），已合并 dev-v3 + 部署测试服实测；对应工单 **#4040**（已关）。
 - 后端明文回显能力（`TravelerPlainVO`）为 #3509 已上线特性，admin 端业务例外、需 admin 权限，前端可放心使用。