diff --git a/changelogs-v2/2026-07/65_5068_核团详情出行人补充出生日期和年龄-修改接口-管理后台.md b/changelogs-v2/2026-07/65_5068_核团详情出行人补充出生日期和年龄-修改接口-管理后台.md new file mode 100644 index 0000000..6e17d14 --- /dev/null +++ b/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 条件跳过。