From b86916bc8c44e7501ff95698cbee978f4146a27b Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 19 Jun 2026 11:51:17 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog/order-v3):=20=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=E8=A1=A5=E5=85=A8=E5=BC=B9=E7=AA=97=E2=91=A1=E4=B8=BA=E7=B4=A7?= =?UTF-8?q?=E6=80=A5=E8=81=94=E7=B3=BB=E4=BA=BA=E5=BF=85=E5=A1=AB(?= =?UTF-8?q?=E5=90=8E=E7=AB=AFPR#4041=E8=A1=A5=E5=BC=BA581109),=E5=8E=9F?= =?UTF-8?q?=E8=AF=AF=E5=86=99=E9=9D=9E=E5=BF=85=E5=A1=AB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- ...全出行信息弹窗三处缺陷-前端待修-管理后台.md | 42 +++++++++++-------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/changelogs-v2/2026-06/19_补全出行信息弹窗三处缺陷-前端待修-管理后台.md b/changelogs-v2/2026-06/19_补全出行信息弹窗三处缺陷-前端待修-管理后台.md index 8a5d238..bce2909 100644 --- a/changelogs-v2/2026-06/19_补全出行信息弹窗三处缺陷-前端待修-管理后台.md +++ b/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 权限，前端可放心使用。