---
schema: "hl-changelog/v2"
ticket: "5656"
title: "派单详情 travelers 补 nativePlace 跨服务透传（#5642 链路补全）"
consumer: "admin"
author: "wx"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "7e7085b6"
target_release: ""
verified_at: ""
status_note: "后端完成：PR #5661 合并 dev-v3（3ee5770af）并部署 TEST（order-v3+fleet 双服务）；网关实测派单详情与 travelers 端点 nativePlace 解析正确（150784→内蒙古呼伦贝尔市等 5 场景）。"
updated_at: "2026-08-08"
base: "dev-v3"
generated: "2026-08-07T18:40:00+08:00"
---

# 派单详情 travelers 补 nativePlace 跨服务透传（#5656）

## 背景

#5642 仅为 order 管理端 `TravelerVO`（traveler/list 等）加了 `nativePlace`；派单详情走跨服务链路（order `GET /v3/internal/order/orders/{orderId}/fleet-detail-context` → fleet `BoardOrderDetailVO.travelers`），该链路 traveler DTO 未带 `nativePlace`，派单页/看板详情展示出行人时缺所属地。本单补全该链路。

## 变更内容

| 层 | 变更 |
|---|---|
| hl-common | `OrderTravelerForFleetDTO` 新增可空 `nativePlace`（身份证所属地，省+地级行政区名；非身份证/未命中为 null） |
| order 生产者 | `OrderFleetProviderService#toMaskedTraveler` 填充（复用 #5642 `IdCardParser` 解析结果，同源 `idProvinceName`） |
| fleet 消费者 | `BoardOrderDetailVO.travelers` / `GET /admin/fleet/board/orders/{id}/travelers` / `FleetTravelerAccessService#listMasked` 均直接复用共享 DTO，无逐字段映射，自动获得字段 |

受影响接口（均为新增只读字段，无破坏性）：

- `GET /admin/fleet/board/orders/{orderId}`（派单详情聚合）→ `data.travelers[].nativePlace`
- `GET /admin/fleet/board/orders/{orderId}/travelers` → `data[].nativePlace`
- internal：`GET /v3/internal/order/orders/{orderId}/fleet-detail-context`、`GET /v3/internal/order/orders/{orderId}/fleet-travelers` 的 traveler 投影同步带 `nativePlace`

取值口径与 #5642 一致：大陆身份证命中地级码→省短名+地市名（如 `150784…`→内蒙古呼伦贝尔市）；直辖市→市名；省直辖县级（4190/4290/4690/6590）→6 位精确映射；非身份证或未命中（含已撤销历史码）→`null` 不报错。

## 关联 / 联系人

- 工单：https://git.1814.love:8443/wx/HL/issues/5656
- PR：https://git.1814.love:8443/wx/HL/pulls/5661
- 后端：wx

## 变更接口或验证证据

### 接口契约

- 接口路径/方法/请求体：不变。
- 响应 travelers 项新增 `nativePlace`（string | null）。

### 验证证据

- 定向测试：order `OrderFleetProviderServiceTest` 53 全过（含 fleet-detail-context nativePlace 断言）；fleet `BoardOrderServiceTest` 87 + `BoardControllerTest` 11 全过（含派单详情 travelers.nativePlace 透传断言）。
- 全量：fleet `mvn -pl hl-fleet-service -am verify` 3256 测试，失败仅 ReleaseEMixedBinaryHarnessTest(1F)+ReleaseEOccupancyMysql8033RecoveryTest(10E) 两个 harness 类，git stash 基线复跑同类同败；order `-pl hl-order-service-v3 -am verify` 7610 测试 7F/95E 失败类集与 #5642 基线逐一相同；fleet spotless:check 通过。
- 部署 TEST 成功（hl-order-service-v3 + hl-fleet-service）。
- 网关验证（自建 HLTEST 订单 2085637067265449985，复用 #5642 五场景出行人）：派单详情与 travelers 端点均断言 150784→内蒙古呼伦贝尔市、469001→海南五指山市、110101→北京市、PASSPORT→null、371201（已撤销码）→null；脱敏与省级字段回归通过。

## 前端/调用方动作

- 派单页/看板详情展示出行人所属地时直接使用 `travelers[].nativePlace`；`null` 展示空（如 "-"）。
- 与 #5642 traveler/list 口径一致，前端两处共用同一展示逻辑即可。

## 前端核查（2026-08-08 mmg 实查，前端无需新改动）

本单即 #5642 协调台更正中所述「另立后端工单补 fleet-detail-context→BoardOrderDetailVO 链路」的后端补全。前端派单页所属地列早在 #5642（hl-admin@7e7085b6）已接入并透传：

- `src/views/fleet/board/components/Step1OrderDetail.vue` 所属地列渲染 `traveler.nativePlace || traveler.idProvinceName || '—'`。
- 数据链 `loadBoardOrderDetail → normalizeBoardOrder(...row) → buildActiveAssignmentOrder(...order) → travelers map(...traveler)` 全程透传、无白名单丢字段。
- 后端在 `BoardOrderDetailVO.travelers` 补 nativePlace 后，前端列自动取值生效，**前端零改动**。frontend_ref 沿用 #5642 的 7e7085b6（无新提交）。