78 行
4.0 KiB
Markdown
78 行
4.0 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5559"
|
||
title: "派单候选接口新增司机自动代入建议（suggestedDriverId/reason/message）"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "pi-main-session"
|
||
frontend_ref: "hl-admin@c6b107b89320e3bc9103314cd8eb5ef32897f51f"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-08-05"
|
||
status_note: "管理后台矩阵/看板共用派单弹窗已接入三类司机自动建议；建议仅使用本次真实可用候选并携车辆、司机二次校验，NONE 清空本轮旧司机并展示后端提示，多槽位排除、人工改选、跨常驻确认和请求竞态门禁保持。"
|
||
updated_at: "2026-08-05"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 矩阵派单司机自动代入：候选接口返回代入建议
|
||
|
||
> **服务**: hl-fleet-service
|
||
> **PR**: #5560、#5561
|
||
> **Issue**: #5559
|
||
> **日期**: 2026-08-05
|
||
> **影响范围**: 管理后台派单弹窗（矩阵派单/看板共用候选接口）
|
||
|
||
## 变更接口
|
||
|
||
| 接口 | 方法 | 路径 | 变更 |
|
||
|---|---|---|---|
|
||
| 派单候选资源查询 | POST | `/admin/fleet/assignments/candidates` | 响应新增 `suggestedDriverId`、`suggestedDriverReason`、`suggestedDriverMessage`（选车后司机自动代入建议） |
|
||
|
||
## 响应字段（顶层新增）
|
||
|
||
| 字段 | 类型 | 必填性 | 值 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `suggestedDriverId` | `Long` / null | 否 | 司机雪花 ID | 已选车辆的自动代入司机；未选车或无空闲司机为 null |
|
||
| `suggestedDriverReason` | `String` | 否 | `RESIDENT_AVAILABLE` / `RESIDENT_BUSY_FALLBACK` / `FIRST_AVAILABLE` / `NONE` | 代入原因码 |
|
||
| `suggestedDriverMessage` | `String` | 否 | 中文文案 | 后端可直接展示的代入原因 |
|
||
|
||
### 代入规则
|
||
|
||
1. 已选车辆（`selectedVehicleId`）有**常驻司机且空闲** → 代入常驻司机（`RESIDENT_AVAILABLE`）；常驻司机权威源为车辆候选列表 `primaryDriverId`（与前端展示同源），不依赖 `VehicleDO.primary_driver_id` 投影
|
||
2. 常驻司机**档期冲突/停用/休息** → 回退代入司机候选排序后第一个**纯空闲**司机（`RESIDENT_BUSY_FALLBACK`）
|
||
3. **无常驻司机** → 代入排序后第一个空闲司机（`FIRST_AVAILABLE`；SMART 排序：可用性→评分→完成单量→年限）
|
||
4. **无任何空闲司机或未选车** → `suggestedDriverId=null`、`NONE`
|
||
|
||
空闲判定与候选一致（无 blocking 档期冲突）；同城衔接共享（`CITY_JUNCTION_SHAREABLE`）不自动代入（需人工决策）。
|
||
|
||
## 前端配合
|
||
|
||
派单弹窗**选车后**以 `suggestedDriverId` 填充司机选择：
|
||
- 现有逻辑只代入常驻司机（且常驻忙时不回退、无常驻不代入）→ 改用 `suggestedDriverReason` 三态：`RESIDENT_AVAILABLE`/`RESIDENT_BUSY_FALLBACK`/`FIRST_AVAILABLE` 均自动选中对应司机；`NONE` 保持手动选择并展示 `suggestedDriverMessage`
|
||
- `suggestedDriverId` 为 null 时清空司机选择（`NONE`）
|
||
|
||
## 验证证据
|
||
|
||
- 网关实测（TEST，2026-08-05）：
|
||
- 蒙A-K1999/S6666/T1557 常驻空闲 → `RESIDENT_AVAILABLE`（代入常驻司机，其 `available=true`）
|
||
- 蒙C04E04（无常驻）→ `FIRST_AVAILABLE`（代入朝鲁门，`available=true`）
|
||
- 蒙A-H7777（常驻阿拉坦 08-10~12 有 2 个 blocking 档期冲突）→ `RESIDENT_BUSY_FALLBACK`（回退朝鲁门，`available=true`）
|
||
- 蒙A-G8888（常驻司机停用，候选列表仍有 `primaryDriverId`）→ `RESIDENT_BUSY_FALLBACK`（回退空闲司机）
|
||
- 未传 `selectedVehicleId` → `suggestedDriverId=null`、`NONE`
|
||
- 测试：AssignmentCandidateServiceTest 41 全绿（新增 7 场景：常驻可用/档期冲突回退/停用回退/无常驻/无空闲/未选车/VehicleDO 投影缺失）；fleet 全量 3155 仅 1 既有基线 flaky；spotless 0 违规
|
||
|
||
## 关联/联系人
|
||
|
||
### 链接
|
||
|
||
- [后端工单 #5559](https://git.1814.love:8443/wx/HL/issues/5559)
|
||
- [后端 PR #5561](https://git.1814.love:8443/wx/HL/pulls/5561)
|
||
- Merge commit: `efb981ca2a`
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|