Mimingguang
87ed9d0a3f
changelog-filename-gate / validate (push) Failing after 2s
处置明细(mmg 2026-09-18): - 68 条机械核验通过批量翻 verified:frontend_ref 均可达且为 v2.1 祖先、 交付文件 HEAD 均在、关联 spec 批量 58 文件 891 例全绿。 - 11 条带演进史的例外逐条核后翻 verified:3 条交付自删文件(06_5610/ 07_5655/11_5810,删除即交付内容且终态保持);8 条被后续 changelog 预期 演进(10_5784→#5810、07_5664/08_5592→#5827、07_5665→去槽位化 U1、 01_5380/05_5356/06_5567/06_5581→settlement 族A扁平化与 mock 清理), status_note 均如实记录演进链。 - 05_5552 改判 not_required:frontend_ref 自述前端无需改动,grep 实证 vehicleFeeAmount.js 直接读后端 calendarPrice/calendarPriceMissing。 - 11_5827 frontend_ref 原空,经核交付即 753503c8(向导 4 步改 3 步提交 即派定),补登全哈希 753503c87cc635e5646b4368a8ed506746c79cf1。 另:保险域 2 条相邻条目(05_5530/06_5593)同标准复核翻 verified。 2026-07 历史月 45 条按规则不回扫,保持原状。
78 行
4.2 KiB
Markdown
78 行
4.2 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: "verified"
|
||
frontend_owner: "pi-main-session"
|
||
frontend_ref: "hl-admin@c6b107b89320e3bc9103314cd8eb5ef32897f51f"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-09-18"
|
||
status_note: "管理后台矩阵/看板共用派单弹窗已接入三类司机自动建议；建议仅使用本次真实可用候选并携车辆、司机二次校验，NONE 清空本轮旧司机并展示后端提示，多槽位排除、人工改选、跨常驻确认和请求竞态门禁保持。[mmg 2026-09-18 批量复核翻 verified] ref c6b107b8 可达且为 v2.1 祖先;交付文件 HEAD 均在;关联 spec 批量 891 例全绿。"
|
||
updated_at: "2026-09-18"
|
||
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
|