---
schema: "hl-changelog/v1"
ticket: "5193"
title: "用车需求增加独立接机送机选择"
consumer: "admin"
backend: "verified"
gateway: "verified"
frontend: "not_required"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "#5236 明确 supersedes #5193；85851ad6 已删除独立开关并改用实时大交通聚合，继续实现会回滚后续契约。"
updated_at: "2026-07-27"
base: "dev-v3"
generated: "2026-07-23T17:39:06+08:00"
---

# 【修改接口·前端待处理·管理后台】用车需求增加独立接机送机选择

## 目标前端

- 端类型：管理后台（Web）
- 目标仓库：`mmg/hl-ui`
- 目标分支：`v2.1`
- 联调/验收环境：<http://192.168.100.160:9527>
- 小程序：无需处理

> **服务**: hl-order-service-v3、hl-fleet-service
>
> **工单**: [wx/HL#5193](https://git.1814.love:8443/wx/HL/issues/5193)
>
> **影响范围**: 提交/调整用车需求、订单详情用车摘要、车务派单详情

## 业务口径

“是否需要平台接送”拆分为两个相互独立的业务选择：

- `pickupRequired`：是否需要平台接机/接站；
- `dropoffRequired`：是否需要平台送机/送站。

提交用车需求时两个选项默认都选中，即默认都为 `true`。定制师可以分别取消，支持四种组合。接机与送机选择是用车需求本身的明确口径，不从航班、站点、接送时间或大交通批次推断。

## 一、提交/调整用车需求

### 1. 直接提交或修改

`PUT /v3/admin/order/{id}/vehicle-requirement`

请求体新增：

```json
{
  "fleet": [
    {
      "vehicleType": "SUV",
      "seats": 7,
      "count": 1
    }
  ],
  "pickupRequired": true,
  "dropoffRequired": true,
  "specialTags": ["中文司机"],
  "remark": "司机会蒙语"
}
```

### 2. 调整订单

`POST /v3/admin/order/{id}/adjustment/submit`

`updates.vehicleRequirement` 新增相同字段：

```json
{
  "updates": {
    "vehicleRequirement": {
      "fleet": [
        {
          "vehicleType": "SUV",
          "seats": 7,
          "count": 1
        }
      ],
      "pickupRequired": false,
      "dropoffRequired": true,
      "specialTags": [],
      "remark": ""
    }
  }
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pickupRequired` | `Boolean` | 前端应显式提交 | `true` 需要接机/接站，`false` 不需要 |
| `dropoffRequired` | `Boolean` | 前端应显式提交 | `true` 需要送机/送站，`false` 不需要 |

兼容规则：

- 首次提交缺少字段时，后端按 `true` 保存；
- 修改或调整既有需求时缺少字段，后端继承当前有效需求的原值；
- 前端不要依赖兼容兜底，提交时始终显式发送两个字段。

## 二、前端表单

在“车辆安排/提交用车需求”表单中增加两个独立开关或复选框：

- 是否需要接机/接站；
- 是否需要送机/送站。

交互要求：

- 新建用车需求时两个选项默认选中；
- 编辑或调整时以接口回显值为准，不要每次强制重置为选中；
- 两个选项均可独立取消，不做互斥或联动；
- 不根据有没有大交通、航班时间或站点决定勾选状态。

## 三、回显接口

以下响应均新增 `pickupRequired` 和 `dropoffRequired`，用于无损回显：

- 用车需求提交/修改响应；
- `GET /v3/admin/order/{id}/adjustment/snapshot` 的 `data.vehicleRequirement`；
- `GET /v3/admin/order/{id}/itinerary` 的 `data.vehicleGroup.requirement`；
- order-v3 内部用车需求契约。

示例：

```json
{
  "pickupRequired": false,
  "dropoffRequired": true
}
```

## 四、车务派单详情

`GET /admin/fleet/board/orders/{orderId}` 的 `data.transport` 新增/明确返回：

```json
{
  "pickupRequired": false,
  "dropoffRequired": true
}
```

这两个值来自订单当前有效用车需求，是车务详情页展示的权威值。前端不得再用抵达/返程班次、站点、接送时间或批次记录推断。

页面分别显示：

| 字段值 | 接机标签 | 送机标签 |
| --- | --- | --- |
| `true` | 需要平台接机 | 需要平台送机 |
| `false` | 无需平台接机 | 无需平台送机 |

不要再合并显示单个“需要平台接送”标签。滚动部署期间若字段暂为 `null`，可以暂不显示对应标签；部署完成后现有历史需求会按默认值返回 `true`。

## 五、前端处理清单

- [ ] 提交用车需求表单增加“是否需要接机/接站”和“是否需要送机/送站”。
- [ ] 新建时两个选项默认选中，提交时显式发送两个 Boolean。
- [ ] 调整订单预填读取 `vehicleRequirement.pickupRequired/dropoffRequired`，不覆盖既有值。
- [ ] 订单详情用车需求摘要按两个字段分别展示。
- [ ] 车务派单详情按 `transport.pickupRequired/dropoffRequired` 分别展示接机、送机标签。
- [ ] 不再展示单个“需要平台接送”，不根据大交通信息反推。
- [ ] 覆盖需要/不需要的四种组合及旧需求默认双 `true`。

## 六、不影响范围

- 大交通录入中的批次级 `pickupRequired` 继续表示该批次自身是否接送，本次不修改其录入和计算逻辑。
- 接送班次、站点、时间和备注字段结构不变。
- 车型、座位数、数量、特殊诉求和备注提交结构不变。

## 七、验证证据

- 后端提交：`2112396b1`；PR：[wx/HL#5197](https://git.1814.love:8443/wx/HL/pulls/5197)，已合并 `dev-v3`（合并提交 `f9e05fbe4`）。
- 用车需求默认值、显式选择、版本继承、调整透传、订单详情回显及 order-v3 → fleet 契约均有单元测试覆盖。
- order-v3 定向测试 311 项、fleet board 定向测试 49 项通过。
- `mvn -pl hl-order-service-v3 -am verify`、`mvn -pl hl-fleet-service -am verify` 和 fleet `spotless:check` 全部通过。
- 测试环境滚动部署成功：order-v3 任务 `af6ff925`，8086/8186 两实例健康；fleet 任务 `e11bca29`，8087/8187 两实例健康。
- 以 `admin` 车务经网关查询团号 `26-8550` 的派车详情，HTTP/code 200，`transport.pickupRequired=true`、`transport.dropoffRequired=true`。
- 以 `wx` 定制师经网关查询同订单调整预填，HTTP/code 200，`vehicleRequirement.pickupRequired=true`、`vehicleRequirement.dropoffRequired=true`。
- 测试库只读核验：两列均为 `NOT NULL DEFAULT 1`，该历史活动需求已迁移为 `1/1`。

> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`；前端按“前端处理清单”接入即可。