yaosutu
627c4c8721
changelog-filename-gate / validate (push) Failing after 2s
补充 #5855 changelog：smart-parse（dryRun=false 正式落库）与 5 个保存入口复用同一 成人手机门禁；dryRun=true 预览不校验。部署测试服网关实调通过：无成人手机导入被 581136 阻断且 DB 零写入，含 1 成人手机导入 200 放行落库。
164 行
9.0 KiB
Markdown
164 行
9.0 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5855"
|
||
title: "出行人保存新增「至少一名成人必须填手机号」服务端硬校验（新增错误码 581136）"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
author: "yst"
|
||
backend_status: "deployed"
|
||
gateway_status: "not_required"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "24f31813"
|
||
target_release: ""
|
||
verified_at: "2026-08-11"
|
||
status_note: "前端已实现(2026-08-11,mmg,24f31813)。实证保存链路天然兼容——persistTravelerInfo(order-v2/detail/index.vue:1005)走统一拦截器,581136 由后端 message 透传 toast,无需特殊分支。并按 §11「建议」落地表单提示增强:TravelerInfoEditor submit 校验通过后对「最终生效集合」判定,无任何成人(复用 isChildTraveler,travelerType 或 birthday<12 兜底)phone 非空(脱敏含*算已有)时 message.warning 提前提示「至少需要一名成人出行人填写手机号用于合同签署」,不阻断由后端 581136 兜底。测试:useMessage mock 补 warning,+2 用例(无成人手机提示且仍返回 payload/有则不提示),TravelerInfoEditor 11 全绿,checkpoint 精确文件集全过。"
|
||
updated_at: "2026-08-11"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 出行人保存新增「至少一名成人必须填手机号」服务端硬校验（#5855 / PR #5858）
|
||
|
||
## 1. 接口背景
|
||
|
||
电子合同签署要求订单中至少有一名成人出行人预留手机号（用于接收签署短信）。此前该约束只在 `traveler/validate` 校验接口里做软提示，保存接口本身不拦截，导致可以保存出"无成人有手机号"的订单，后续签约环节才暴露问题。本次在出行人保存链路上补齐服务端硬校验：保存时若"最终生效的出行人集合"中没有任何一名成人填写手机号，整个保存请求被拒绝（不写库），并返回新增错误码 `581136`。
|
||
|
||
## 2. 变更清单
|
||
|
||
| # | 接口 | 变更类型 | 说明 |
|
||
|---|------|----------|------|
|
||
| 1 | `PUT /v3/admin/order/{id}/traveler-info` | 新增服务端校验 | 补全出行信息（全量同步）保存时新增硬校验，触发返回 581136 |
|
||
| 2 | `POST /v3/admin/order/{id}/traveler/batch-edit` | 新增服务端校验 | 批量编辑出行人保存时新增硬校验，触发返回 581136 |
|
||
| 3 | `POST /v3/admin/order/{id}/traveler/add` | 新增服务端校验 | 单个新增出行人时新增硬校验，触发返回 581136 |
|
||
| 4 | `GET /v3/admin/order/{id}/traveler/validate` | 出参文案收紧 | `blockReasons[]` 文案由"至少需要一名出行人填写手机号"收紧为"至少需要一名成人出行人填写手机号"，判定口径同步收紧 |
|
||
| 5 | `POST /v3/admin/order/{id}/traveler/smart-parse` | 新增服务端校验 | 智能批量导入（`dryRun=false` 正式落库）保存时新增硬校验，触发返回 581136（#5867 补入，与 5 入口同一门禁） |
|
||
|
||
> 说明：删除出行人接口**不**加此校验；智能导入的 `dryRun=true` 预览模式**不**校验（仅解析不落库）。入参 / 出参结构、字段名、类型均无变化。
|
||
|
||
## 3. 接口详情
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 方法 + 路径 | `PUT /v3/admin/order/{id}/traveler-info`；`POST /v3/admin/order/{id}/traveler/batch-edit`；`POST /v3/admin/order/{id}/traveler/add`；`GET /v3/admin/order/{id}/traveler/validate`；`POST /v3/admin/order/{id}/traveler/smart-parse` |
|
||
| 使用场景 | 管理后台订单详情 - 出行人 Tab：补全出行信息 / 批量编辑 / 单个新增 / 保存前校验 |
|
||
| 认证 | 管理后台 JWT（admin 端） |
|
||
| 幂等性 | PUT traveler-info 为全量同步天然幂等；batch-edit / add 为普通写操作 |
|
||
| 限流 | 无特殊限流 |
|
||
|
||
## 4. 接口入参
|
||
|
||
入参结构**无变化**，此处仅强调与本校验相关的字段语义。
|
||
|
||
### 4.1 路径参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 订单 ID |
|
||
|
||
### 4.2 请求体关键字段（出行人行）
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| travelerType | String | 是 | 出行人类型，`ADULT`=成人；本校验只统计成人行 |
|
||
| phone | String | 否 | 手机号。更新时传 `null`=保留原值（不修改），传 `""` 空串=清空；若清空后无任何成人有手机，触发 581136 |
|
||
|
||
## 5. 出参字段
|
||
|
||
三个保存接口出参结构**无变化**，仍为统一 `Result<T>`：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| code | Integer | `200`=成功；`581136`=本次新增的"无成人有手机号"业务错误 |
|
||
| success | Boolean | 成功 true / 失败 false |
|
||
| message | String | 失败时为错误文案，前端直接 toast |
|
||
| data | T | 成功时的业务数据（结构不变） |
|
||
|
||
`GET /traveler/validate` 出参 `blockReasons[]`（String 数组）中文案变化：
|
||
|
||
| 原来 | 现在 |
|
||
|------|------|
|
||
| 至少需要一名出行人填写手机号用于合同签署 | 至少需要一名**成人**出行人填写手机号用于合同签署 |
|
||
|
||
## 6. 枚举 / 数据字典
|
||
|
||
| 枚举 | 取值 | 说明 |
|
||
|------|------|------|
|
||
| travelerType | `ADULT` | 成人，本校验的统计对象 |
|
||
| travelerType | 其他（儿童等） | 不计入"是否有手机"判定 |
|
||
|
||
## 7. 错误码
|
||
|
||
| code | message | 触发条件 |
|
||
|------|---------|----------|
|
||
| 581136 | 至少需要一名成人出行人填写手机号用于合同签署 | 保存后"最终生效的出行人集合"中没有任何一名成人（travelerType=ADULT）填写手机号；整个请求被拒，不写库。适用接口：traveler-info 全量同步 / batch-edit 批量编辑 / add 单个新增 / smart-parse 智能批量导入（dryRun=false） |
|
||
|
||
## 8. 示例
|
||
|
||
### 8.1 典型成功（至少 1 名成人有手机）
|
||
|
||
请求 `PUT /v3/admin/order/123/traveler-info`，出行人中含成人且至少一名成人 phone 非空：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"success": true,
|
||
"message": "success",
|
||
"data": { }
|
||
}
|
||
```
|
||
|
||
### 8.2 边界（成人 phone 传 null 保留原值）
|
||
|
||
更新出行人时成人行 `phone: null` 表示保留原手机号不修改，只要原有数据里仍有成人有手机即通过校验，响应同 8.1。
|
||
|
||
### 8.3 业务失败（无任何成人有手机 → 581136）
|
||
|
||
请求 `PUT /v3/admin/order/123/traveler-info`，提交的所有成人 phone 均为空（或清空）：
|
||
|
||
```json
|
||
{
|
||
"code": 581136,
|
||
"success": false,
|
||
"message": "至少需要一名成人出行人填写手机号用于合同签署",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
出行人**未落库**，前端按 Result 约定 `code != 200` toast `message` 即可。
|
||
|
||
## 9. 业务边界
|
||
|
||
- 适用：订单出行人的补全 / 批量编辑 / 单个新增 / 智能批量导入（`smart-parse` 且 `dryRun=false`）保存。
|
||
- 不适用：删除出行人接口（删除不加此校验，即使删完后无成人有手机也不拦截删除动作本身）；智能导入 `dryRun=true` 预览模式（仅解析不落库，不校验）。
|
||
- 特殊边界：校验看的是"保存后最终生效的集合"，不是单条提交行——例如 batch-edit 把唯一有手机的成人 phone 清空，即使其他行不变也会触发 581136。智能导入为**追加式**（最终集合 = 库中现有 + 本次解析行），只要合并后存在一名成人有手机即放行。
|
||
|
||
## 10. 修改前后对比
|
||
|
||
| 维度 | 原来 | 现在 |
|
||
|------|------|------|
|
||
| 保存接口校验 | 不校验"成人是否有手机"，可保存出无成人手机号的订单 | 保存时硬校验，无成人有手机则整单拒存，返回 581136 |
|
||
| validate 判定口径 | 任意出行人有手机即通过 | 必须是**成人**有手机才通过 |
|
||
| validate blockReasons 文案 | 至少需要一名出行人填写手机号用于合同签署 | 至少需要一名成人出行人填写手机号用于合同签署 |
|
||
| 入参 / 出参结构 | — | 无变化 |
|
||
|
||
## 11. 影响评估 / 回滚
|
||
|
||
- 破坏兼容：否。入参 / 出参结构不变，仅新增一个业务错误码与文案收紧。
|
||
- 前端同步上线：非强制。前端按现有 `code != 200` toast 约定即可天然兼容；建议在补全 / 编辑出行人表单对成人行补充"至少一名成人需填手机号"的提示，提升体验。
|
||
- 回滚方案：后端回滚 PR #5858 即恢复原行为，前端无需改动。
|
||
|
||
## 12. 注意事项
|
||
|
||
- 581136 通过 HTTP 200 + `code=581136` 返回（Result 约定），**不是** HTTP 4xx/5xx，前端拦截器按业务 code 处理。
|
||
- `phone` 字段更新语义：`null`=保留原值，`""`=清空。前端表单回显时注意区分"未改动"与"主动清空"。
|
||
- 删除出行人不受此校验约束。
|
||
- 智能批量导入：仅 `dryRun=false` 正式落库时校验，`dryRun=true` 预览不校验；导入文本中无法识别手机号属正常，门禁统计的是"最终集合里是否有成人带手机"，不是"每行是否都有手机"。
|
||
|
||
## 13. 关联 / 联系人
|
||
|
||
- Issue: https://git.1814.love:8443/wx/HL/issues/5855
|
||
- PR: https://git.1814.love:8443/wx/HL/pulls/5858
|
||
- Commit: https://git.1814.love:8443/wx/HL/commit/06f03e40c3
|
||
- 关联补充（智能批量导入纳入同一门禁）：Issue https://git.1814.love:8443/wx/HL/issues/5867 ｜ PR https://git.1814.love:8443/wx/HL/pulls/5868
|
||
- 后端负责人：腰苏图（yst）
|