---
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 违规