---
schema: "hl-changelog/v2"
ticket: "5236"
title: "用车接送改由大交通默认驱动"
consumer: "admin"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端 PR #5241 已合并至 dev-v3（9578f78d5），order/fleet 已部署测试环境（b57ce915/0da3b9e6），双实例 internal 契约与网关汇总/列表/详情已验证；前端仍为 pending，待删除车辆接送开关并改用大交通摘要。"
updated_at: "2026-07-24"
base: "dev-v3"
---

# 用车接送改由大交通默认驱动

## 关联

- Issue: [wx/HL#5236](https://git.1814.love:8443/wx/HL/issues/5236)
- Backend PR: [wx/HL#5241](https://git.1814.love:8443/wx/HL/pulls/5241)
- Supersedes: [wx/HL#5193](https://git.1814.love:8443/wx/HL/issues/5193) 中“用车需求独立决定接送”的业务口径
- 服务: `hl-order-service-v3`、`hl-fleet-service`
- 前端仓库/分支: `mmg/hl-ui` / `v2.1`

## 关键变化

车辆安排不再让定制师重复选择“是否需要接机/接站”和“是否需要送机/送站”。
接送结论由订单当前大交通批次直接决定：

- `ARRIVAL` 批次聚合接机/接站。
- `DEPARTURE` 批次聚合送机/送站。
- 同方向任一批 `pickupRequired=true`，该方向为需要接送。
- 同方向全部批次均为 `false`，该方向为客人自理。
- 没有该方向批次时返回 `null`，表示未知。
- 新建大交通未传 `pickupRequired` 时默认保存为 `true`；显式 `false` 保持客人自理。

用车需求和订单调整中的 `pickupRequired`、`dropoffRequired` 字段暂不删除，继续兼容旧请求和回显，
但不再覆盖实时大交通结论。

## 变更接口

| 方法 | 路径 | 变化 |
|---|---|---|
| `POST` | `/v3/admin/order/:id/transport-plan/add` | 新增大交通未传 `pickupRequired` 时默认 `true` |
| `POST` | `/v3/admin/order/:id/transport-plan/batch` | 批量替换中每个未传值的批次默认 `true` |
| `POST` | `/v3/admin/order/:id/transport-plan/:planId/edit` | 未传该字段时保留原值；显式值正常覆盖 |
| `PUT` | `/v3/admin/order/:id/vehicle-requirement` | 两个接送字段改为兼容字段，不再是权威来源 |
| `GET` | `/v3/admin/order/:id/adjustment/snapshot?scope=VEHICLE_REQ` | 继续通过 `vehicleTransportSummary` 返回大交通批次摘要 |
| `POST` | `/v3/admin/order/:id/adjustment/submit` | `updates.vehicleRequirement` 中两个接送字段仅兼容接收 |
| `GET` | `/admin/fleet/board/orders` | 卡片接送就绪状态改为按实时大交通方向聚合 |
| `GET` | `/admin/fleet/board/orders/:orderId` | `transport.pickupRequired/dropoffRequired` 只取实时大交通聚合 |

小程序内部大交通新增与批量接口使用相同默认规则，但本 changelog 的前端处理范围仅为管理后台。

## 字段语义

### 大交通请求 `pickupRequired`

| 场景 | 入参 | 保存结果 |
|---|---|---|
| 新增单批/批量批次未传 | 字段省略或 `null` | `true` |
| 新增单批/批量批次显式自理 | `false` | `false` |
| 编辑既有批次未传 | 字段省略或 `null` | 保留原值 |
| 编辑既有批次显式修改 | `true` / `false` | 按提交值覆盖 |

数据库列仍为 `TINYINT(1) NOT NULL`，仅把新记录的数据库默认值从 `0` 改为 `1`，不回填或改写历史行。

### 派单详情响应

| 字段 | 类型 | 空值 | 说明 |
|---|---|---|---|
| `transport.pickupRequired` | `Boolean` | 无 ARRIVAL 批次时为 `null` | ARRIVAL 批次聚合 |
| `transport.dropoffRequired` | `Boolean` | 无 DEPARTURE 批次时为 `null` | DEPARTURE 批次聚合 |
| `transport.arrive/depart` | `Object/null` | 对应整团批次不存在时为 `null` | 到达/返程整团大交通 |
| `transport.batches[]` | `Object[]` | 无分批时为空数组 | 分批大交通，保留方向、时间、站点和关联出行人 |

## 前端处理

1. 删除“调整订单 → 车辆安排”中的“是否需要接机/接站”和“是否需要送机/送站”两个开关。
2. 提交用车需求或订单调整时，不再主动提交 `pickupRequired`、`dropoffRequired`。
3. 车辆安排页直接展示 `vehicleTransportSummary.arrivals[]` 与 `departures[]`；继续使用其中的
   `direction`、`time`、`station`、`transportNo`、`pickupRequired`、`pickupRemark` 和
   `travelerNames[]`。
4. 派单看板和详情不得回退到 `vehicleRequirement.pickupRequired/dropoffRequired`；
   使用看板接送摘要与详情 `transport.pickupRequired/dropoffRequired`。
5. 雪花 ID 仍按字符串处理，本次没有字段删除、类型变化或新增错误码。

## 展示矩阵

| 大交通场景 | 接机/接站 | 送机/送站 | 页面展示 |
|---|---:|---:|---|
| ARRIVAL 任一批需要，DEPARTURE 全部自理 | `true` | `false` | 分方向显示“平台接 / 客人自理” |
| ARRIVAL 全部自理，DEPARTURE 任一批需要 | `false` | `true` | 分方向显示“客人自理 / 平台送” |
| 同方向多批混合 | `true` | 按返程批次聚合 | 明细保留每个批次及关联出行人 |
| 只有 ARRIVAL | 按到达批次聚合 | `null` | 返程显示未提供，不回退旧用车需求 |
| 只有 DEPARTURE | `null` | 按返程批次聚合 | 到达显示未提供，不回退旧用车需求 |
| 完全无大交通 | `null` | `null` | 显示“暂无接送机时间” |

## 验证证据

- Order 定向测试 57 项通过。
- Fleet `BoardOrderServiceTest` 50 项通过。
- 调整/需求/出行人兼容链路 357 项通过。
- 调整快照完整字段断言 `AdjustmentServiceTest` 10 项通过。
- `mvn -pl hl-order-service-v3 -am verify` 通过。
- Order 模块 Surefire 汇总 6646 项，0 失败、0 错误、28 跳过。
- `mvn -pl hl-fleet-service -am verify` 通过：Fleet 模块 2361 项，0 失败、0 错误、1 跳过。
- Fleet `spotless:check` 与 `git diff --check` 通过。
- OpenAPI/oasdiff: `not_configured`，使用源码字段/语义比对和测试作为 fallback。
- Spring Cloud Contract: `not_configured`，使用 order-v3 生产者与 Fleet 消费者测试作为 fallback。
- 后端 PR #5241 已合并，merge commit 为 `9578f78d5f0241db502d94b22283cbff0a351c53`。
- 测试环境部署任务：order `b57ce915`、fleet `0da3b9e6`。
- `order_transport_plan.pickup_required` 已验证为 `TINYINT(1) NOT NULL DEFAULT 1`，Flyway
  `20260724.001` 执行成功。
- order `8086/8186` 均通过 `/v3/internal/order/orders/:orderId/transport` 与批量看板上下文实测；
  `true/false/null` 三态及 ARRIVAL/DEPARTURE 分方向聚合符合字段语义。
- 测试网关 `/admin/fleet/board/summary`、`/orders`、`/orders/:orderId` 均返回成功；
  详情连续 4 次通过，运行时证据为 `D:/work2/hl-workflow/.tmp/5236-gateway-evidence.json`。