hl-api-changelog/changelogs-v2/2026-08/11_5855_出行人保存校验至少一成人填手机号-修改接口-管理后台.md

schema, ticket, title, consumer, change_type, author, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	author	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5855	出行人保存新增「至少一名成人必须填手机号」服务端硬校验（新增错误码 581136）	admin	修改接口	yst	deployed	not_required	implemented	mmg	24f31813		2026-08-11	前端已实现(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 精确文件集全过。	2026-08-11	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[] 文案由"至少需要一名出行人填写手机号"收紧为"至少需要一名成人出行人填写手机号"，判定口径同步收紧

说明：删除出行人接口不加此校验。入参 / 出参结构、字段名、类型均无变化。

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
使用场景	管理后台订单详情 - 出行人 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）填写手机号；整个请求被拒，不写库

8. 示例

8.1 典型成功（至少 1 名成人有手机）

请求 PUT /v3/admin/order/123/traveler-info，出行人中含成人且至少一名成人 phone 非空：

{
  "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 均为空（或清空）：

{
  "code": 581136,
  "success": false,
  "message": "至少需要一名成人出行人填写手机号用于合同签署",
  "data": null
}

出行人未落库，前端按 Result 约定 code != 200 toast message 即可。

9. 业务边界

• 适用：订单出行人的补全 / 批量编辑 / 单个新增保存。
• 不适用：删除出行人接口（删除不加此校验，即使删完后无成人有手机也不拦截删除动作本身）。
• 特殊边界：校验看的是"保存后最终生效的集合"，不是单条提交行——例如 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=保留原值，""=清空。前端表单回显时注意区分"未改动"与"主动清空"。
• 删除出行人不受此校验约束。

13. 关联 / 联系人

• Issue: wx/HL#5855
• PR: wx/HL#5858
• Commit: https://git.1814.love:8443/wx/HL/commit/06f03e40c3
• 后端负责人：腰苏图（yst）