87 行
3.7 KiB
Markdown
87 行
3.7 KiB
Markdown
# 【修改接口·管理后台】核团详情出行人补充出生日期和年龄（#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` 仍为脱敏值。
|