docs: hand off traveler transport linkage (#5209)

2026-07-24 11:59:35 +08:00 · 2026-07-24 11:59:35 +08:00 · fe4bdd1e2d
--- a/changelogs-v2/2026-07/24_5209_出行人省份与分批大交通关联-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/24_5209_出行人省份与分批大交通关联-修改接口-管理后台.md
@ -0,0 +1,125 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5209"
+title: "出行人省份与分批大交通关联"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "pending"
+base: "dev-v3"
+generated: "2026-07-24T11:58:00+08:00"
+---
+
+# 【修改接口·前端待处理·管理后台】出行人省份与分批大交通关联
+
+## 目标前端
+
+- 端类型：管理后台（Web）
+- 目标仓库：`mmg/hl-ui`
+- 目标分支：`v2.1`
+- 联调/验收环境：<http://192.168.100.160:9527>
+- 小程序：无需处理
+
+> **服务**: hl-order-service-v3、hl-fleet-service
+>
+> **工单**: [wx/HL#5209](https://git.1814.love:8443/wx/HL/issues/5209)
+>
+> **PR**: [wx/HL#5212](https://git.1814.love:8443/wx/HL/pulls/5212)
+>
+> **影响范围**: 车务派单详情的出行人省份标签、大交通与出行人关联、分批抵达/离开展示
+
+## 一、接口变化
+
+`GET /admin/fleet/board/orders/{orderId}`
+
+### 1. 出行人
+
+`data.travelers[]` 补充省级行政区，并继续返回稳定的大交通计划 ID：
+
+```json
+{
+  "travelerId": "3001",
+  "nameMasked": "张**",
+  "idNoMasked": "320***********108X",
+  "idProvinceCode": "32",
+  "idProvinceName": "江苏省",
+  "transportPlanIds": ["4001", "4003"]
+}
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `idProvinceCode` | `String \| null` | 身份证省级行政区代码，例如 `32` |
+| `idProvinceName` | `String \| null` | 身份证省级行政区名称，例如 `江苏省` |
+| `transportPlanIds` | `String[]` | 该出行人关联的全部大交通计划 ID |
+
+省份仅对结构、生日段和省级前缀均可识别的 18 位大陆身份证派生。护照、其他证件、空值或无法识别的身份证返回 `null`；接口不会新增身份证明文。
+
+### 2. 大交通单段和批次
+
+`data.transport.arrive`、`data.transport.depart` 及 `data.transport.batches[]` 统一补充：
+
+```json
+{
+  "planId": "4001",
+  "direction": "ARRIVAL",
+  "travelerIds": ["3001"],
+  "transportNo": "CA1234",
+  "time": "2026-07-29T11:10:00",
+  "station": "满洲里西郊机场",
+  "pickupRequired": true
+}
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `planId` | `String` | 大交通计划 ID |
+| `direction` | `String \| null` | `ARRIVAL` 抵达、`DEPARTURE` 离开；极少量历史异常数据可能为 `null` |
+| `travelerIds` | `String[]` | 本段或本批关联的出行人 ID |
+| `pickupRequired` | `Boolean \| null` | 本段或本批是否需要平台接送 |
+
+一起抵达/离开的首段仍放在 `arrive` 或 `depart`。同方向存在更多批次时，后续批次保留在 `batches[]`，不会合并为单个时间或站点。
+
+## 二、稳定关联算法
+
+前端必须按 ID 关联，不再按姓名关联：
+
+1. 将 `travelers[]` 按 `String(travelerId)` 建立索引。
+2. 将非空的 `transport.arrive`、`transport.depart` 与 `transport.batches[]` 合并为大交通段列表。
+3. 对每个大交通段遍历 `travelerIds[]`，按字符串 ID 查找对应出行人。
+4. 需要反向查询时，用出行人的 `transportPlanIds[]` 匹配各段 `planId`。
+
+所有雪花 ID 都按 JSON 字符串返回。不要转换为 JavaScript `Number`，避免精度丢失。
+
+`travelerNames` 仅为旧页面兼容展示字段，不是关联键。姓名可能重复、脱敏或变化，不得用于匹配。
+
+## 三、页面处理
+
+- 出行人卡片在 `idProvinceName` 非空时显示省份标签；为空时不显示占位标签。
+- 大交通区域按 `direction` 区分抵达和离开，不根据数组位置猜方向。
+- 每个批次独立展示时间、站点、班次、接送要求和对应出行人。
+- 同方向多个批次不得覆盖、去重或压缩为一个批次。
+- `travelerIds` 为空时显示该交通段，但不要按姓名猜测关联人。
+- `direction=null` 的历史记录可显示为“方向待完善”，不要默认当作离开。
+
+## 四、前端处理清单
+
+- [ ] 出行人卡片读取 `idProvinceName` 并按空值规则显示省份标签。
+- [ ] 按字符串 `travelerId/planId` 建立双向关联，不转换为 `Number`。
+- [ ] 同时处理 `transport.arrive`、`transport.depart` 和全部 `transport.batches[]`。
+- [ ] 按 `direction` 区分抵达/离开，并支持同方向多个批次。
+- [ ] 每个大交通段展示其 `travelerIds[]` 对应的出行人。
+- [ ] 不使用 `travelerNames`、脱敏姓名或数组位置作为关联依据。
+- [ ] 覆盖单批、多批、无关联人、无大交通、省份为空和 `direction=null` 场景。
+
+## 五、验证证据
+
+- 后端提交：`45b631cd0`；PR：[wx/HL#5212](https://git.1814.love:8443/wx/HL/pulls/5212)。
+- `mvn -pl hl-order-service-v3,hl-fleet-service -am verify`、fleet `spotless:check` 和定向测试全部通过。
+- 测试环境分支部署成功：order task `e1fc0581`、fleet task `d4cea89b`，四个实例健康。
+- 经网关遍历 11 条看板订单，详情成功 11/11；30 名出行人中 24 名返回可识别省份。
+- 9 个真实大交通段共验证 28 组双向 ID 关联，所有 ID 均为 JSON 字符串，未出现身份证明文字段。
+- 临时构造 3 个返程批次验证 `depart + batches[2]` 后已通过业务 API 完整清理，临时批次残留 0。
+- order、fleet、gateway 两实例自部署起均无目标 ERROR/Exception。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`；前端按“前端处理清单”接入即可。