docs(changelog): 出行人类型改为由出生日期派生，birthday 必填、travelerType 入参移除（小程序端客户出行人补全接口，PR #3981，Issue #3976）

2026-06-18 15:49:59 +08:00 · 2026-06-18 15:49:59 +08:00 · 362e104708
--- a/changelogs-v2-mp/2026-06/18_3976_出行人类型由出生日期派生-修改接口-小程序端.md
+++ b/changelogs-v2-mp/2026-06/18_3976_出行人类型由出生日期派生-修改接口-小程序端.md
@ -0,0 +1,316 @@
+# 【修改接口·小程序端】出行人类型改为由出生日期自动派生，birthday 必填、travelerType 入参移除 (#3976)
+
+> **PR**: #3981 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-18
+
+## 1. 接口背景
+
+小程序客户出行人补全接口（batch-edit）原先要求客户端传入 `travelerType`（出行人类型枚举值）。本次调整将出行人类型的计算权收归后端：**客户端只需传 `birthday`（出生日期），后端按年龄段自动派生 `travelerType`**，入参不再接受 `travelerType` 字段（传了也会被忽略）。
+
+`birthday` 同步从选填升级为**必填**，不传报 400。响应 VO 不变，`travelerType` / `travelerTypeName` 仍正常返回，展示层无需改动。
+
+> 本次为破坏性入参变更：移除 `travelerType` 入参 + `birthday` 改必填。
+
+## 2. 变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 客户出行人补全 | POST | /v3/internal/mp/order/{id}/traveler/batch-edit | 入参破坏性变更 | 出行人对象移除 `travelerType`，`birthday` 改必填 |
+
+## 3. 接口详情
+
+### 3.1 客户出行人补全（POST /v3/internal/mp/order/{id}/traveler/batch-edit）
+
+- **使用场景**：小程序用户自助补全出行信息时，批量 upsert 出行人列表（id=null 新增，id 有值则更新）。
+- **认证**：需要微信登录态 JWT（C 端 token）。
+- **幂等性**：否（写入操作）。
+- **限流**：无。
+
+入参中每个出行人对象移除 `travelerType` 字段，`birthday` 改为必填。响应 VO 不变。
+
+## 4. 接口入参
+
+### 4.1 路径参数 / Query 参数
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | String（Long） | 是 | 路径参数，订单 ID |
+
+### 4.2 请求体字段
+
+请求体外层结构示例：
+
+```json
+{
+  "travelers": [{}]
+}
+```
+
+**出行人对象字段表**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| 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 | 否 | 紧急联系人 |
+| emergencyPhone | String | 否 | 紧急联系人电话 |
+| roomGroupNo | Integer | 否 | 房间分组编号（团期订单使用） |
+| travelerType（已移除） | — | — | 入参已移除，传入将被忽略；后端按 birthday 自动派生 |
+
+## 5. 出参（响应）
+
+响应 VO 结构**不变**，`travelerType` 和 `travelerTypeName` 仍正常返回。
+
+### 5.1 响应列表元素（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 | 国籍 |
+
+## 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 | 出行人不存在 | 传了无效的出行人 id（更新场景） |
+| 401 | 未认证 | 未携带或微信 JWT 过期 |
+| 403 | 无权限 | 当前用户无权操作该订单的出行人 |
+
+## 8. 示例（3 组：典型 / 边界 / 异常）
+
+### 8.1 典型成功 — 补全两位出行人（成人 + 儿童，含 birthday，不传 travelerType）
+
+请求：POST /v3/internal/mp/order/2067178767255560193/traveler/batch-edit，Authorization: Bearer <mp-token>
+
+请求体示例：
+
+```json
+{
+  "travelers": [
+    {
+      "id": null,
+      "name": "张三",
+      "gender": "1",
+      "birthday": "1990-05-20",
+      "idType": "ID_CARD",
+      "idNo": "110101199005201234"
+    },
+    {
+      "id": null,
+      "name": "张小宝",
+      "gender": "1",
+      "birthday": "2019-08-10",
+      "idType": "BIRTH_CERT",
+      "idNo": "P110101201908101234"
+    }
+  ]
+}
+```
+
+响应示例：
+
+```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": "CHILD",
+      "travelerTypeName": "儿童",
+      "name": "张小宝",
+      "birthday": "2019-08-10",
+      "idType": "BIRTH_CERT",
+      "idTypeName": "出生证明",
+      "idCardMasked": "P1101012019****1234",
+      "gender": "1"
+    }
+  ],
+  "message": "ok",
+  "success": true
+}
+```
+
+### 8.2 边界情况 — 幼童（birthday 未满 2 周岁，派生 BABY）
+
+请求体示例：
+
+```json
+{
+  "travelers": [
+    {
+      "id": null,
+      "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。
+- **小程序是否必须同步上线**：是。调用 batch-edit 接口时，必须确保每个出行人对象带 birthday；原有 travelerType 入参代码可同步清理。
+
+### 11.2 回滚方案
+
+- **回滚方式**：revert PR #3981 并重新部署 hl-order-service-v3，恢复 travelerType 入参有效 + birthday 选填的旧行为。
+
+## 12. 注意事项
+
+- 出行人类型选择器如果仅用于控制 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