From fe4bdd1e2d1bbd2e1a31fcc9f43259f54c1c5afb Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 24 Jul 2026 11:59:35 +0800 Subject: [PATCH] docs: hand off traveler transport linkage (#5209) --- ...人省份与分批大交通关联-修改接口-管理后台.md | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 changelogs-v2/2026-07/24_5209_出行人省份与分批大交通关联-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/24_5209_出行人省份与分批大交通关联-修改接口-管理后台.md b/changelogs-v2/2026-07/24_5209_出行人省份与分批大交通关联-修改接口-管理后台.md new file mode 100644 index 0000000..69b9cb7 --- /dev/null +++ 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` +- 联调/验收环境： +- 小程序：无需处理 + +> **服务**: 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`；前端按“前端处理清单”接入即可。