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

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5559	派单候选接口新增司机自动代入建议（suggestedDriverId/reason/message）	admin	wx(GIT)	修改接口	deployed	verified	implemented	pi-main-session	hl-admin@c6b107b89320e3bc9103314cd8eb5ef32897f51f	v2.1	2026-08-05	管理后台矩阵/看板共用派单弹窗已接入三类司机自动建议；建议仅使用本次真实可用候选并携车辆、司机二次校验，NONE 清空本轮旧司机并展示后端提示，多槽位排除、人工改选、跨常驻确认和请求竞态门禁保持。	2026-08-05	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
• 后端 PR #5561
• Merge commit: efb981ca2a

联系人

• 后端负责人: @wx