From 663b93a64129a2c065ccb58f4bf1d7fe70997f99 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Thu, 18 Jun 2026 15:49:46 +0800 Subject: [PATCH] docs(changelog): birthday required, travelerType removed in admin 3 APIs (PR #3981) --- ...行人类型由出生日期派生-修改接口-管理后台.md | 348 ++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 changelogs-v2/2026-06/18_3976_出行人类型由出生日期派生-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/18_3976_出行人类型由出生日期派生-修改接口-管理后台.md b/changelogs-v2/2026-06/18_3976_出行人类型由出生日期派生-修改接口-管理后台.md new file mode 100644 index 0000000..21e4b25 --- /dev/null +++ b/changelogs-v2/2026-06/18_3976_出行人类型由出生日期派生-修改接口-管理后台.md @@ -0,0 +1,348 @@ +# 【修改接口·管理后台】出行人类型改为由出生日期自动派生，birthday 必填、travelerType 入参移除 (#3976) + +> **PR**: #3981 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-18 + +## 1. 接口背景 + +出行人保存相关接口（补全出行信息 / 批量 upsert / 单个新增）原先要求前端显式传入 `travelerType`（成人 / 儿童 / 小童 / 幼童）。本次重构将出行人类型的计算权收归后端：**前端只需传 `birthday`（出生日期），后端按年龄段自动派生 `travelerType`**，前端入参不再接受 `travelerType` 字段（传了也会被忽略）。 + +`birthday` 同步从选填升级为**必填**，不传报 400。出行人响应 VO 不变，`travelerType` / `travelerTypeName` 仍正常返回，前端展示层无需改动。 + +> 本次为破坏性入参变更：移除 `travelerType` 入参 + `birthday` 改必填。 + +## 2. 变更清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 补全出行信息 | PUT | /v3/admin/order/{id}/traveler-info | 入参破坏性变更 | 出行人对象移除 `travelerType`，`birthday` 改必填 | +| 2 | 批量 upsert 出行人 | POST | /v3/admin/order/{id}/traveler/batch-edit | 入参破坏性变更 | 出行人对象移除 `travelerType`，`birthday` 改必填 | +| 3 | 单个出行人新增 | POST | /v3/admin/order/{id}/traveler/add | 入参破坏性变更 | 请求体移除 `travelerType`，`birthday` 改必填 | + +## 3. 接口详情 + +### 3.1 补全出行信息（PUT /v3/admin/order/{id}/traveler-info） + +- **使用场景**：管理后台「补全出行信息」功能页，全量同步出行人列表 + 紧急联系人 + 备注，一次性提交。 +- **认证**：需要 JWT（管理员角色）。 +- **幂等性**：否（写入操作，全量覆盖出行人列表）。 +- **限流**：无。 + +入参中每个出行人对象移除 `travelerType` 字段，`birthday` 改为必填。出参 VO 不变。 + +### 3.2 批量 upsert 出行人（POST /v3/admin/order/{id}/traveler/batch-edit） + +- **使用场景**：管理后台出行人 Tab 批量录入 / 编辑出行人（id=null 新增，id 有值则更新）。 +- **认证**：需要 JWT（管理员角色）。 +- **幂等性**：否（写入操作）。 +- **限流**：无。 + +入参中每个出行人对象移除 `travelerType` 字段，`birthday` 改为必填。出参 VO 不变。 + +### 3.3 单个出行人新增（POST /v3/admin/order/{id}/traveler/add） + +- **使用场景**：管理后台出行人 Tab 单条新增出行人。 +- **认证**：需要 JWT（管理员角色）。 +- **幂等性**：否（写入操作）。 +- **限流**：无。 + +请求体移除 `travelerType` 字段，`birthday` 改为必填。出参 TravelerVO 不变（仍含 travelerType / travelerTypeName）。 + +## 4. 接口入参 + +### 4.1 路径参数 / Query 参数 + +| 接口 | 字段 | 类型 | 必填 | 说明 | +|------|------|------|------|------| +| PUT /v3/admin/order/{id}/traveler-info | id | String（Long） | 是 | 路径参数，订单 ID | +| POST /v3/admin/order/{id}/traveler/batch-edit | id | String（Long） | 是 | 路径参数，订单 ID | +| POST /v3/admin/order/{id}/traveler/add | id | String（Long） | 是 | 路径参数，订单 ID | + +### 4.2 请求体字段 + +接口 1（PUT traveler-info）外层结构示例： + +```json +{ + "travelers": [{}], + "emergencyContact": "张三", + "emergencyPhone": "13800138000", + "remark": "备注" +} +``` + +接口 2（POST batch-edit）外层结构示例： + +```json +{ + "travelers": [{}] +} +``` + +接口 3（POST add）请求体即为单个出行人对象（见下表）。 + +**出行人对象字段表**： + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| id | String（Long） | 否 | null 或不传=新增；有值=更新已有出行人 | +| name | String | 否 | 出行人姓名 | +| gender | String | 否 | 性别字典码（1=男 / 2=女 / 0=未知） | +| birthday | String | **是** | 出生日期，格式 yyyy-MM-dd，不能晚于今天。**本次改为必填** | +| idType | String | 否 | 证件类型枚举值，见第 6 节 | +| idNo | String | 否 | 证件号码（明文） | +| nationality | String | 否 | 国籍 | +| race | String | 否 | 民族 | +| phone | String | 否 | 手机号 | +| emergencyContact | String | 否 | 紧急联系人（接口 3 单独字段；接口 1/2 在请求体外层） | +| emergencyPhone | String | 否 | 紧急联系人电话（同上） | +| roomGroupNo | Integer | 否 | 房间分组编号（团期订单使用） | +| travelerType（已移除） | — | — | 入参已移除，传入将被忽略；后端按 birthday 自动派生 | + +## 5. 出参（响应） + +出参 VO 结构**不变**，travelerType 和 travelerTypeName 仍正常返回。 + +### 5.1 接口 2、3 出参（TravelerVO 关键字段） + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | String | 出行人记录 ID | +| orderId | String | 所属订单 ID | +| travelerType | String | 出行人类型枚举值（后端由 birthday 派生后返回） | +| travelerTypeName | String | 出行人类型中文名（成人 / 儿童 / 小童 / 幼童） | +| name | String | 出行人姓名 | +| birthday | String | 出生日期（yyyy-MM-dd） | +| idType | String | 证件类型枚举值 | +| idTypeName | String | 证件类型中文名 | +| idCardMasked | String | 证件号（脱敏后） | +| gender | String | 性别字典码 | +| nationality | String | 国籍 | + +### 5.2 接口 1（PUT traveler-info）出参 + +Result，成功时 data 为 null。 + +## 6. 枚举 / 数据字典 + +### 6.1 travelerType 派生规则（后端自动计算，前端仅需理解出参含义） + +| 年龄段（按 birthday 计算） | travelerType 枚举值 | travelerTypeName | +|--------------------------|-------------------|-----------------| +| 0-1 岁（未满 2 周岁） | BABY | 幼童 | +| 2-6 岁（未满 7 周岁） | YOUNG_CHILD | 小童 | +| 7-17 岁（未满 18 周岁） | CHILD | 儿童 | +| 18 岁及以上 | ADULT | 成人 | + +### 6.2 idType（证件类型字典：id_card_type） + +| 枚举值 | 中文名 | 说明 | +|--------|--------|------| +| ID_CARD | 身份证 | 中国居民身份证 | +| PASSPORT | 护照 | 中外护照 | +| BIRTH_CERT | 出生证明 | 婴幼儿出生医学证明 | +| HK_MACAU | 港澳通行证 | 港澳居民来往内地通行证 | +| TAIWAN | 台胞证 | 台湾居民来往大陆通行证 | +| MILITARY | 军官证 | 军人证件 | + +## 7. 错误码 + +| code | 含义 | 触发场景 | +|------|------|----------| +| 400 | 出生日期不能为空 | 出行人对象未传 birthday 或传 null | +| 400 | 出生日期不能晚于今天 | birthday 传入了未来日期 | +| 581201 | 订单不存在 | orderId 无效 | +| 581200 | 出行人不存在 | batch-edit 中传了无效的出行人 id（更新场景） | +| 401 | 未认证 | 未携带或 JWT 过期 | +| 403 | 无权限 | 当前角色无此操作权限 | + +## 8. 示例（3 组：典型 / 边界 / 异常） + +### 8.1 典型成功 — batch-edit 批量保存（含 birthday，不传 travelerType） + +请求：POST /v3/admin/order/2067178767255560193/traveler/batch-edit，Authorization: Bearer + +请求体示例： + +```json +{ + "travelers": [ + { + "id": null, + "name": "张三", + "gender": "1", + "birthday": "1990-05-20", + "idType": "ID_CARD", + "idNo": "110101199005201234" + }, + { + "id": null, + "name": "张小宝", + "gender": "1", + "birthday": "2022-03-15", + "idType": "BIRTH_CERT", + "idNo": "P110101202203151234" + } + ] +} +``` + +响应示例： + +```json +{ + "code": 200, + "data": [ + { + "id": "2067178767255560201", + "orderId": "2067178767255560193", + "travelerType": "ADULT", + "travelerTypeName": "成人", + "name": "张三", + "birthday": "1990-05-20", + "idType": "ID_CARD", + "idTypeName": "身份证", + "idCardMasked": "110***********1234", + "gender": "1" + }, + { + "id": "2067178767255560202", + "orderId": "2067178767255560193", + "travelerType": "YOUNG_CHILD", + "travelerTypeName": "小童", + "name": "张小宝", + "birthday": "2022-03-15", + "idType": "BIRTH_CERT", + "idTypeName": "出生证明", + "idCardMasked": "P1101012022****1234", + "gender": "1" + } + ], + "message": "ok", + "success": true +} +``` + +### 8.2 边界情况 — 单个新增幼童（birthday 刚满 1 岁，派生 BABY） + +请求体示例（POST /v3/admin/order/{id}/traveler/add）： + +```json +{ + "name": "李小婴", + "gender": "2", + "birthday": "2025-06-01", + "idType": "BIRTH_CERT", + "idNo": "P110101202506011234" +} +``` + +响应示例： + +```json +{ + "code": 200, + "data": { + "id": "2067178767255560210", + "orderId": "2067178767255560193", + "travelerType": "BABY", + "travelerTypeName": "幼童", + "name": "李小婴", + "birthday": "2025-06-01", + "idType": "BIRTH_CERT", + "idTypeName": "出生证明", + "idCardMasked": "P1101012025****1234", + "gender": "2" + }, + "message": "ok", + "success": true +} +``` + +### 8.3 业务失败 — birthday 缺失，报出生日期不能为空 + +请求体示例（缺少 birthday）： + +```json +{ + "travelers": [ + { + "name": "王五", + "gender": "1" + } + ] +} +``` + +响应示例： + +```json +{ + "code": 400, + "data": null, + "message": "出生日期不能为空", + "success": false +} +``` + +## 9. 业务边界 + +- 适用：订单处于可编辑出行人的状态时（如待补全信息阶段），三个写入接口均可调用。 +- 不适用：订单已完成（COMPLETED）或已取消（CANCELLED）后，出行人信息不可再写入。 +- 特殊边界：birthday 为整周岁当天（如刚满 2 岁、7 岁、18 岁生日当天）时，当天即按新档位计算（满龄升档）。 +- 特殊边界：如果前端表单中仍有 travelerType 字段的存储或传入，不影响功能（后端忽略），建议同步清理。 +- 特殊边界：birthday 只允许不晚于今天的日期，传入未来日期（包括明天）报 400。 +- 特殊边界：birthday 格式须为 yyyy-MM-dd，格式错误报 400。 + +## 10. 修改前后对比 + +### 10.1 字段级对比（入参） + +| 字段 | 改前 | 改后 | +|------|------|------| +| travelerType（入参） | 选填，由前端传入，控制出行人类型 | 已移除，传入被忽略 | +| birthday（入参） | 选填 | 必填，不传报 400 | + +### 10.2 字段级对比（出参，不变） + +| 字段 | 改前 | 改后 | +|------|------|------| +| travelerType（出参） | 返回前端传入值 | 返回后端按 birthday 派生值（语义不变） | +| travelerTypeName（出参） | 返回中文名 | 不变 | +| birthday（出参） | 原样返回 | 不变 | + +### 10.3 行为级对比 + +| 行为 | 改前 | 改后 | +|------|------|------| +| 出行人类型来源 | 前端传入 travelerType，后端直接存储 | 后端按 birthday 自动派生，前端无需传 | +| birthday 必填性 | 选填，不传不报错 | 必填，不传报 400 | + +## 11. 影响评估 / 回滚 + +### 11.1 影响评估 + +- **是否破坏向后兼容**：是，birthday 改必填属破坏性变更。旧版前端表单若未传 birthday，保存时报 400。 +- **前端是否必须同步上线**：是。三个写入接口（traveler-info / batch-edit / add）调用时都需确保传入 birthday；原有 travelerType 入参代码可同步清理。 + +### 11.2 回滚方案 + +- **回滚方式**：revert PR #3981 并重新部署 hl-order-service-v3，恢复 travelerType 入参有效 + birthday 选填的旧行为。 + +## 12. 注意事项 + +- 出行人类型选择器（下拉 / radio）如果仅用于控制 travelerType 入参，本次可直接移除，出行人类型由 birthday 派生后在出参中正常回显，展示无需调整。 +- birthday 格式严格为 yyyy-MM-dd（如 1990-05-20），不接受时间戳或其他格式。 +- 响应中的 travelerType / travelerTypeName 仍正常返回，出行人卡片上的类型标签展示逻辑无需改动。 +- 年龄以服务器当天日期（北京时间）计算，生日当天视为满周岁。 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#3976](https://git.1814.love:8443/wx/HL/issues/3976) +- **PR**: [#3981](https://git.1814.love:8443/wx/HL/pulls/3981) +- **Merge commit**: [8209c5702](https://git.1814.love:8443/wx/HL/commit/8209c5702) + +### 13.2 联系人 + +- **后端负责人**: @yaosutu