7d76ee0cde
所有检测均成功
changelog-filename-gate / validate (push) Successful in 2s
修改原因：#5236 已明确 supersedes #5193，并由前端提交 85851ad6 删除独立接送开关、停止提交兼容字段，继续执行旧契约会回滚现行大交通聚合口径。 修改内容：将 #5193 的前端消费状态从 claimed 收口为 not_required，清理旧负责人并补齐新版消费元数据和取代原因。 实际验证：相关前端 5 个 Vitest 文件共 50 项通过；changelog 仓库 46 项测试通过；path alias 校验与 git diff --check 通过。 Changelog: changelogs-v2/2026-07/23_5193_用车需求增加独立接机送机选择-修改接口-管理后台.md
188 行
6.5 KiB
Markdown
188 行
6.5 KiB
Markdown
---
|
||
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`；前端按“前端处理清单”接入即可。
|