docs: 补充核团出行人出生日期年龄契约 (#5068)

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

@@ -0,0 +1,85 @@
+# 【修改接口·管理后台】核团详情出行人补充出生日期和年龄（#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:06
+
+## 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. 验证证据
+
+- #5069 原始定向测试覆盖正常年龄、生日边界、空出生日期、空出发日期和未来出生日期。
+- 与 PR #5064 最新基线融合后，相关冲突面 41 项测试全部通过。
+- 最终 `hl-order-service-v3` reactor 共 5,799 项测试：0 failures、0 errors、15 条件跳过。