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

> **Issue**: [#5068](https://git.1814.love:8443/wx/HL/issues/5068) | **PR**: [#5069](https://git.1814.love:8443/wx/HL/pulls/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 | 是 | 以订单出发日期为基准计算的周岁 |

### 响应示例

```json
{
  "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` 仍为脱敏值。