hl-api-changelog/changelogs-v2-mp/2026-06/18_3976_出行人类型由出生日期派生-修改接口-小程序端.md

【修改接口·小程序端】出行人类型改为由出生日期自动派生，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 请求体字段

请求体外层结构示例：

{
  "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

请求体示例：

{
  "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"
    }
  ]
}

响应示例：

{
  "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）

请求体示例：

{
  "travelers": [
    {
      "id": null,
      "name": "李小婴",
      "gender": "2",
      "birthday": "2025-06-01",
      "idType": "BIRTH_CERT",
      "idNo": "P110101202506011234"
    }
  ]
}

响应示例：

{
  "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）：

{
  "travelers": [
    {
      "name": "王五",
      "gender": "1"
    }
  ]
}

响应示例：

{
  "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
• PR: #3981
• Merge commit: 8209c5702

13.2 联系人

• 后端负责人: @yaosutu