wx/hl-api-changelog

派生 0

API Changelog Bot fe4bdd1e2d

changelog-filename-gate / validate (push) Successful in 1s

详情

docs: hand off traveler transport linkage (#5209 )

2026-07-24 12:00:15 +08:00

5.3 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, backend, gateway, frontend, base, generated

schema	ticket	title	consumer	backend	gateway	frontend	base	generated
hl-changelog/v1	5209	出行人省份与分批大交通关联	admin	verified	verified	pending	dev-v3	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

PR: wx/HL#5212

影响范围: 车务派单详情的出行人省份标签、大交通与出行人关联、分批抵达/离开展示

一、接口变化

GET /admin/fleet/board/orders/{orderId}

1. 出行人

data.travelers[] 补充省级行政区，并继续返回稳定的大交通计划 ID：

{
  "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[] 统一补充：

{
  "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 关联，不再按姓名关联：

将 travelers[] 按 String(travelerId) 建立索引。
将非空的 transport.arrive、transport.depart 与 transport.batches[] 合并为大交通段列表。
对每个大交通段遍历 travelerIds[]，按字符串 ID 查找对应出行人。
需要反向查询时，用出行人的 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。
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；前端按“前端处理清单”接入即可。

5.3 KiB 原始文件 Blame 文件历史 Unescape Escape