---
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`；前端按“前端处理清单”接入即可。