wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

docs: add fleet demand dispatch contract

浏览代码
这个提交包含在：
API Changelog Bot 2026-07-09 17:40:05 +08:00
父节点 96797a8e93
当前提交 ed32d5bfc8
共有 1 个文件被更改，包括 487 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

487
changelogs-v2/2026-07/53_4871_车务提需求派单看板闭环契约-管理后台.md 普通文件
查看文件

@ -0,0 +1,487 @@
# 【前端对接·管理后台】车务提需求与派单看板闭环契约
> Issue: [wx/HL#4871](https://git.1814.love:8443/wx/HL/issues/4871)
> 服务: `hl-order-service-v3` / `hl-fleet-service` / `hl-user-service`
> 日期: 2026-07-09
> 影响范围: 订单详情车辆需求、车务工作台、派单看板、车务聊天、派单操作
## 1. 结论
- 用车需求只选车型大类，不选具体车型型号；`fleet[].vehicleType` 传大类 key，`fleet[].seats` 传该大类 seatOptions 中的座位数。
- 司机占 1 个座位：后端新增并返回 `passengerSeatCapacity`、`remainingPassengerSeats` 等字段，前端余座展示以这些字段为准。
- 派单看板状态枚举以后读 `GET /admin/fleet/board/summary` 的 `statusOptions`，前端不要再独立维护状态文案映射。
- `holding` 的业务含义是“排车中”：车务已经派给司机，但司机还没有确认。
- 派单看板列表/工作台补齐联系人、团号、定制师展示名、操作能力字段，支持按联系人/团号/定制师筛选。
- 车务聊天在线态按“是否有任一车务管理员角色在线”聚合，不再绑定单个 admin。
- 派单取消和司机拒接/退回待派已补后端接口。已告知司机也允许取消，但前端必须做强提示确认。
## 2. 提交用车需求
```http
PUT /v3/admin/order/2074746808742928386/vehicle-requirement
Authorization: Bearer <admin-token>
Content-Type: application/json
```
请求示例：
```json
{
"fleet": [
{
"vehicleType": "suv2",
"seats": 5,
"count": 1
}
],
"specialTags": ["大行李空间", "中文司机"],
"remark": "接机后直接去酒店"
}
```
成功响应新增座位字段：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"id": "2075000000000000001",
"orderId": "2074746808742928386",
"version": 1,
"status": "PENDING",
"fleet": [
{ "vehicleType": "suv", "seats": 5, "count": 1 }
],
"specialTags": ["大行李空间", "中文司机"],
"remark": "接机后直接去酒店",
"passengerCount": 3,
"vehicleCount": 1,
"totalSeatCount": 5,
"driverSeatCount": 1,
"passengerSeatCapacity": 4,
"remainingPassengerSeats": 1
}
}
```
座位公式：
```text
vehicleCount = sum(fleet[].count)
totalSeatCount = sum(fleet[].seats * fleet[].count)
driverSeatCount = vehicleCount
passengerSeatCapacity = totalSeatCount - driverSeatCount
remainingPassengerSeats = passengerSeatCapacity - passengerCount
```
示例：1 台 5 座车只能坐 4 名乘客，司机占 1 座。订单 5 名乘客提交 1 台 5 座车会失败：
```json
{
"code": 582027,
"message": "车辆载客座位不足：每辆车需扣除1个司机座",
"success": false,
"data": null
}
```
前端处理：
- “余 X 座”展示请读 `remainingPassengerSeats`，不要用 `seats * count - passengerCount` 自行计算。
- 仍然从 `GET /admin/fleet/vehicle-types/list` 读取车型大类和 `seatOptions`。
- `fleet[].vehicleType` 传 `typeKey`；`fleet[].seats` 只能从该大类 `seatOptions` 里选。
- `specialTags` 继续来自字典 `vehicle_special_demand`。
## 3. 订单详情行程 Tab
```http
GET /v3/admin/order/2074746808742928386/itinerary
Authorization: Bearer <admin-token>
```
`vehicleGroup.requirement` 同步新增座位字段：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"canContactFleet": true,
"contactFleetDisabledReason": null,
"vehicleGroup": {
"requirement": {
"requirementId": "2075000000000000001",
"status": "PENDING",
"vehicleTypeSummary": "suv×1",
"specialTags": ["大行李空间", "中文司机"],
"remark": "接机后直接去酒店",
"passengerCount": 3,
"vehicleCount": 1,
"totalSeatCount": 5,
"driverSeatCount": 1,
"passengerSeatCapacity": 4,
"remainingPassengerSeats": 1
},
"assignments": []
}
}
}
```
## 4. 派单看板汇总与状态选项
```http
GET /admin/fleet/board/summary
Authorization: Bearer <fleet-admin-token>
```
响应示例：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"totalOrders": 132,
"unassigned": 111,
"holding": 2,
"assigned": 8,
"changeRequested": 3,
"completed": 3,
"canceled": 2,
"statusOptions": [
{
"value": "unassigned",
"label": "待派车",
"description": "未派车，可派车/可驳回用车需求",
"count": 111,
"urgentCount": 2
},
{
"value": "holding",
"label": "排车中",
"description": "车务已派给司机，司机未确认",
"count": 2,
"urgentCount": 2
},
{
"value": "assigned",
"label": "已派车",
"description": "司机已确认执行",
"count": 8,
"urgentCount": 0
},
{
"value": "change_requested",
"label": "换车请求",
"description": "客户或定制师提出换车",
"count": 3,
"urgentCount": 0
},
{
"value": "completed",
"label": "已完结",
"description": "派车已完结",
"count": 3,
"urgentCount": 0
},
{
"value": "canceled",
"label": "已取消",
"description": "派车已取消",
"count": 2,
"urgentCount": 0
}
]
}
}
```
前端处理：
- 筛选下拉和状态文案读 `statusOptions[].value/label/count/urgentCount`。
- 前端不要把 `holding` 显示成“待派车”或“已派车”；它固定显示为“排车中”。
- 红色急单角标可读 `urgentCount`；列表行是否急单仍读行内 `assignmentStatus` 派生态。
## 5. 派单看板列表
```http
GET /admin/fleet/board/orders?page=1&pageSize=10&statuses=unassigned&contactName=乐瑶&teamNo=26-7218&consultantName=阿如娜
Authorization: Bearer <fleet-admin-token>
```
新增/强化查询参数：
| 参数 | 类型 | 说明 |
|------|------|------|
| `contactName` | string | 联系人/客户名模糊筛选。 |
| `contactKeyword` | string | `contactName` 别名，二者任选其一。 |
| `teamNo` | string | 团号模糊筛选，例如 `26-7218`。 |
| `plannerName` | string | 定制师模糊筛选，旧字段保留。 |
| `consultantName` | string | 定制师模糊筛选，`plannerName` 别名。 |
| `statuses` | string[] | 状态多选，值来自 `statusOptions[].value`。 |
| `status` | string | 单状态或逗号分隔状态。 |
| `typeKeys` | string[] | 车型大类筛选。 |
| `startDate/endDate` | date | 行程日期区间。 |
| `keyword` | string | 司机姓名搜索，兼容旧页面。 |
响应示例：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"page": 1,
"pageSize": 10,
"total": 27,
"records": [
{
"id": "HL20260708144557879",
"orderId": "2074746808742928386",
"orderNo": "HL20260708144557879",
"teamNo": "26-7218",
"customerName": "何子墨",
"contactName": "何子墨",
"productName": "测试核心产品-单档-固定订金",
"headcount": 2,
"startDate": "2026-07-20",
"endDate": "2026-07-22",
"tripDays": 3,
"assignmentStatus": "unassigned_urgent",
"assignmentStatusLabel": "待派车",
"urgentBadge": "待派即将超时",
"consultantName": "阿如娜",
"consultantDisplayName": "阿如娜",
"plannerName": "阿如娜",
"customerNote": "需要接送机",
"requiredVehicles": [
{
"vehicleType": "suv",
"categoryLabel": "SUV系列",
"seats": 5,
"count": 1
}
],
"canAssign": true,
"canRejectRequirement": true,
"unreadMessageCount": 0
}
]
}
}
```
前端处理：
- 列表卡片至少展示联系人/人数/定制师/团号；字段优先级：
- 联系人：`contactName || customerName`
- 定制师：`consultantDisplayName || consultantName || plannerName`
- 团号：`teamNo`
- 派车按钮展示条件：`canAssign === true`。
- 驳回用车需求按钮展示条件：`canRejectRequirement === true`。
- 红色即将超时订单也必须显示派车/驳回按钮，不能因为急单样式隐藏操作区。
- 当前接口仍是分页接口；前端不要改成不分页一次性全拉。
## 6. 车务工作台
```http
GET /admin/fleet/dashboard/summary
Authorization: Bearer <fleet-admin-token>
```
`upcomingTrips[]` 与派单看板列表同步字段：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"pendingAssignmentCount": 111,
"upcomingTrips": [
{
"orderId": "2074746808742928386",
"orderNo": "HL20260708144557879",
"teamNo": "26-7218",
"contactName": "何子墨",
"customerName": "何子墨",
"productName": "测试核心产品-单档-固定订金",
"startDate": "2026-07-20",
"headcount": 2,
"assignmentStatus": "unassigned",
"assignmentStatusLabel": "待派车",
"consultantName": "阿如娜",
"consultantDisplayName": "阿如娜",
"canAssign": true,
"canRejectRequirement": true
}
]
}
}
```
前端处理同派单看板列表：工作台快捷入口可直接根据 `canAssign/canRejectRequirement` 展示派车/驳回入口。
## 7. 取消派单
```http
DELETE /admin/fleet/assignments/2075001000000000001
Authorization: Bearer <fleet-admin-token>
Content-Type: application/json
{
"cancelReason": "客户调整接送时间，原司机无法执行",
"driverNotified": true
}
```
响应示例：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"assignmentStatus": "canceled",
"sideEffects": {
"vehicleReleased": true,
"driverReleased": true
}
}
}
```
前端处理：
- `driverNotified=false`：可直接二次确认后取消。
- `driverNotified=true`：仍可取消，但必须用强提示，例如“已告知司机，取消后需线下同步司机，确认取消？”。
- 不要因为已告知司机就禁用取消按钮；后端已经允许并记录该标记。
## 8. 司机拒接/退回待派
司机拒接或车务确认本次排车无效时调用。只允许 `holding` 状态。
```http
POST /admin/fleet/assignments/2075001000000000001/driver-reject
Authorization: Bearer <fleet-admin-token>
Content-Type: application/json
{
"rejectReason": "司机临时无法出车"
}
```
响应示例：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"assignmentStatus": "unassigned",
"assignmentGroupId": "2075001000000000001",
"sideEffects": {
"vehicleReleased": true,
"driverReleased": true
}
}
}
```
错误响应示例：
```json
{
"code": 605020,
"message": "当前状态不允许退回待派",
"success": false,
"data": null
}
```
前端处理：
- 司机未确认前的 `holding` 行可展示“司机拒接/退回待派”。
- 调用成功后该行回到 `unassigned`，可重新派车。
- 已 `assigned` 的行不走本接口，如需取消用 §7 取消派单。
## 9. 车务聊天在线态
```http
POST /admin/message/chat/open-fleet
Authorization: Bearer <admin-token>
Content-Type: application/json
{
"orderId": "2074746808742928386",
"peerAdminId": null
}
```
响应中的对端在线态现在按“车务管理员角色是否有人在线”聚合：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"conversationKey": "FLEET:2074746808742928386",
"peer": {
"peerAdminId": "0",
"peerRole": "FLEET",
"peerRoleLabel": "车务",
"peerOnline": true
},
"order": {
"orderId": "2074746808742928386",
"orderNo": "HL20260708144557879",
"customerName": "何子墨",
"teamNo": "26-7218"
}
}
}
```
前端处理：
- `peerRole=FLEET` 且 `peerAdminId=0` 表示车务团队，不是某一个 admin。
- 只要任一车务管理员在线，`peerOnline=true`。
- 管理员必须以车务角色登录系统，才会被计入车务团队在线态。
## 10. 前端对接清单
| 页面/弹窗 | 必做 |
|----------|------|
| 调整订单车辆页 | 车型选大类，座位选 seatOptions；余座读后端 `remainingPassengerSeats`。 |
| 订单详情行程 Tab | `vehicleGroup.requirement` 新增座位字段直接展示，不要前端自算司机座。 |
| 派单看板 | 状态下拉读 `summary.statusOptions`；列表保持分页；卡片展示联系人/人数/定制师/团号。 |
| 派单看板操作 | `canAssign` 控制派车按钮，`canRejectRequirement` 控制驳回需求按钮。 |
| 派单取消 | `driverNotified=true` 时强提示，但不能禁用取消。 |
| 排车中 | `holding` 显示为“排车中”，含义是司机未确认。 |
| 车务聊天 | `peerOnline` 按车务团队聚合显示在线/离线。 |
## 11. 后端本地验证
```bash
mvn -pl hl-order-service-v3 -am "-Dtest=RequirementServiceTest,OrderDetailServiceTest,OrderDetailConverterTest" "-DfailIfNoTests=false" test
mvn -pl hl-fleet-service -am "-Dtest=BoardOrderServiceTest,BoardSummaryServiceTest,FleetDashboardSummaryServiceTest,AssignmentControllerTest,AssignmentServiceTest,AssignmentStateMachineHelperTest" "-DfailIfNoTests=false" test
mvn -pl hl-user-service -am "-Dtest=ChatManagerTest,ConversationMemberServiceTest,AdminPresenceServiceTest,AdminSseServiceTest" "-DfailIfNoTests=false" test
```
覆盖点：
- 5 座车只允许 4 名乘客；5 名乘客提交 1 台 5 座车返回 `582027`。
- 订单详情 `vehicleGroup.requirement` 返回 `passengerSeatCapacity/remainingPassengerSeats`。
- 派车 strictSeats 对 5 座车 + 5 名乘客返回 `605002`。
- 派单看板返回联系人/团号/定制师/操作能力/状态文案。
- `statusOptions` 由后端返回，含 `holding=排车中`。
- 车务团队在线态按车务角色聚合。