changelog(#5559): 派单候选接口司机自动代入建议（suggestedDriverId/reason/message）

changelogs-v2/2026-08/05_5559_矩阵派单司机自动代入-修改接口-管理后台.md

@@ -0,0 +1,65 @@
+---
+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: "pending"
+frontend_owner: "pi-main-session"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: ""
+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 违规