hl-api-changelog/changelogs-v2/2026-07/65_5068_核团详情出行人补充出生日期和年龄-修改接口-管理后台.md

【修改接口·管理后台】核团详情出行人补充出生日期和年龄（#5068）

Issue: #5068 | PR: #5069 | 服务: hl-order-service-v3 | 更新时间: 2026-07-19 11:23

1. 关键变化

• 核团详情 travelers[] 新增可空字段 birthday 和 age。
• birthday 为出行人出生日期，格式 yyyy-MM-dd。
• age 为按订单出发日期计算的周岁。
• 出生日期为空、订单出发日期为空，或出生日期晚于出发日期时，age 返回 null。
• 出行人手机号和证件号继续沿用原有脱敏规则。

2. 受影响接口

GET /v3/admin/order/{orderId}/settlement/return-detail

• HTTP 方法、URL、认证、路径参数及响应整体结构均不变。
• 本次只增加 data.travelers[] 的响应字段，不增加请求参数。

3. 新增响应字段

字段	JSON 类型	是否可空	说明
data.travelers[].birthday	string	是	出生日期，格式 yyyy-MM-dd
data.travelers[].age	number	是	以订单出发日期为基准计算的周岁

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "travelers": [
      {
        "travelerId": "71001",
        "travelerName": "张三",
        "travelerType": "ADULT",
        "travelerTypeName": "成人",
        "birthday": "1990-07-20",
        "age": 36,
        "idType": "ID_CARD",
        "idTypeName": "身份证",
        "phone": "138****1234",
        "idCardNo": "110***********1234"
      }
    ]
  },
  "success": true
}

示例仅展示本次相关结构；核团详情中的订单、司机车辆、应收和收款等字段保持不变。

4. 年龄计算与空值边界

场景	birthday	age
出生日期和订单出发日期均有效	返回出生日期	返回两个日期之间的完整周岁
出生日期为空	null	null
订单出发日期为空	返回出生日期	null
出生日期晚于订单出发日期	返回出生日期	null

当前已合并实现不会在订单出发日期缺失时改用服务器当前日期。Issue #5068 初始描述中的“按当前日期兜底”尚未进入代码；若业务仍需要该口径，应另行变更后端实现和本通知。

5. 前端适配清单

• 在核团详情出行人列表展示 birthday 和 age。
• 对两个字段均做 null 兼容，不拼接 null岁 或展示无效日期。
• 年龄直接使用后端返回值，不在浏览器端按当前日期重新计算。
• 继续使用现有脱敏后的 phone 和 idCardNo，不要尝试恢复明文。
• 不改变接口 URL、请求参数和其他响应字段的解析逻辑。

6. 兼容性与发布边界

• 新增字段对忽略未知 JSON 字段的旧客户端向后兼容。
• 字段为可空值，前端不能把 birthday 或 age 设为必填。
• PR #5069 已于 2026-07-19 10:47 合并到 dev-v3，合并提交为 1da9389fbbc567dfd8b98703a6b9ebbfb2ea1d69。
• 测试环境公网网关已验证新字段返回，见下方验证证据。

7. 验证证据

• 后端定向测试：mvn -pl hl-order-service-v3 -am -DfailIfNoTests=false -Dtest=SettlementReturnDetailQueryServiceTest,SettlementControllerTest test。
• 测试环境公网网关验证：GET https://web.test.1814.love:9443/v3/admin/order/2077233855281971202/settlement/return-detail 连续 6 次返回 code=200。
• 实测订单出发日为 2026-07-13，首位出行人 birthday=1991-05-27，接口返回 age=35，与按订单出发日计算的周岁一致。
• 实测响应中 phone、idCardNo 仍为脱敏值。