docs(fleet): add menu api validation handoff

changelogs-v2/2026-07/25_4756_车务菜单全接口验收与前端契约收口-管理后台.md

@@ -0,0 +1,63 @@
+# 【前端对接·管理后台】车务菜单全接口验收与契约收口
+
+> **Issue**: [wx/HL#4756](https://git.1814.love:8443/wx/HL/issues/4756)  
+> **PR**: [wx/HL#4757](https://git.1814.love:8443/wx/HL/pulls/4757), [wx/HL#4758](https://git.1814.love:8443/wx/HL/pulls/4758)  
+> **服务**: hl-fleet-service + hl-order-service-v3  
+> **日期**: 2026-07-05  
+> **影响范围**: 管理后台车务管理全菜单
+
+---
+
+## 1. 结论
+
+- 测试服已完成真实 API 回归：车务菜单级 `23/23` 通过，覆盖后台端点 `76` 个。
+- 补充全链路回归 `31/31` 通过，多订单并发回归 `10/10` 通过。
+- 已修复派单重复确认返回 `100000` 的问题，现在返回业务码 `605020 当前派单状态不允许此操作`。
+- `/admin/fleet/**` 已按当前登录角色拦截：车务角色可访问，定制师角色会返回 `403`。
+
+---
+
+## 2. 前端必须处理
+
+| 场景 | 前端处理 |
+|------|----------|
+| 当前角色 | 车务菜单只能由 `VEHICLE_MANAGER` 或 `SUPER_ADMIN` 访问；`wx/CUSTOMIZER` 访问 `/admin/fleet/**` 返回 `403`，提示切换车务角色。 |
+| 司机结算方式 | 司机新增/编辑/导入使用字典 `driver_settlement_mode`：`direct`=直接结算，`fleet_leader`=车队长结算。 |
+| 待审核详情 ID | `GET /admin/fleet/drivers/pending/{pendingId}` 响应主键字段是 `id`，不是 `pendingId`；路径变量仍叫 `pendingId`。 |
+| 派单重复确认 | `POST /admin/fleet/assignments/{assignmentId}/confirm` 只允许 `holding -> assigned`；非 `holding` 返回 `605020`。 |
+| 取消重复操作 | 终态派单再次取消也返回 `605020`。 |
+| 快速连点 | 多个写接口有幂等保护，会返回 `100502`，前端按钮需要 loading/disabled。不要把 `100502` 当系统故障。 |
+| 价格日历多车型批量设价 | `PUT /admin/fleet/pricing-calendar/batch-set` 幂等窗口是 300 秒，同一批完全相同入参会返回 `100502`。 |
+| 价格日历删除 | `DELETE /admin/fleet/pricing-calendar/{vehicleModelId}` 使用 query 参数 `startDate`、`endDate`，不要放 body。 |
+| 车型树字段 | `GET /admin/fleet/vehicle-types` 大类和车型主键都读 `id`；不要读旧的 `typeId`。 |
+| 看板 summary | 使用 `pendingUrgentCount`、`holdingTimeoutCount`；不要自造旧字段。 |
+| 车辆 busy | 车辆新增/编辑不能人工写 `vehicleStatus=busy`，返回 `600112`；busy 只能由派单占用反算。 |
+| 常驻司机冲突 | 车辆指定常驻司机时，司机已被别车占用返回 `605022`；司机侧改绑目标车已被占用返回 `605023`。 |
+| 自带车审核 | H5 自带车 `regCertUsage` 为营运类时必须带 `operationLicenseUrls`。 |
+
+---
+
+## 3. 本次确认的菜单覆盖
+
+| 菜单 | 关键接口 |
+|------|----------|
+| 派单看板 | `/admin/fleet/board/summary`, `/orders`, `/orders/{orderId}`, `/timeline`, `/expiry`, `/assignments/**` |
+| 矩阵派单 | `/admin/fleet/matrix/grid`, `/unassigned-orders`, `/day-orders` |
+| 车队对账 | `/admin/fleet/reconciliation/cars`, `/insurance`, `/periods`, `/actual`, `/close`, `/reopen`, `/pending-compensations/**`, `/export/cars` |
+| 价格日历 | `/admin/fleet/pricing-calendar/overview`, `/{vehicleModelId}`, `/{vehicleModelId}/status`, `/batch-set` |
+| 车辆档案 | `/admin/fleet/vehicles/page`, `/{vehicleId}`, `/{vehicleId}/disable`, `/{vehicleId}/enable`, `/import`, `/import/template` |
+| 车型管理库 | `/admin/fleet/vehicle-types`, `/list`, `/page`, `/models/page`, `/{typeId}`, `/{typeId}/models`, `/models/{modelId}` |
+| 司机档案 | `/admin/fleet/drivers/page`, `/options`, `/{driverId}`, `/{driverId}/resident-vehicle`, `/{driverId}/blacklist`, `/{driverId}/unban`, `/batch-season-renew`, `/import`, `/import/template` |
+| 待审核/自助录入 | `/admin/fleet/drivers/pending/**`, `/admin/fleet/h5/token`, `/h5/tokens/**`, `/app/h5/driver-onboard/**` |
+| 车管模板 | `/admin/fleet/message-templates/**` |
+
+---
+
+## 4. 验证证据
+
+- 菜单级真实 API：`23/23` 通过，订单 `HL20260705203149299`，覆盖 76 个后台端点。
+- 全链路真实 API：`31/31` 通过，订单 `HL20260705203226195`。
+- 多订单并发：`10/10` 通过，真实创建 3 个订单，仅 1 单派单成功，其余按 `605001` 冲突返回。
+- 本地后端验证：
+  - `mvn -pl hl-fleet-service -am "-Dtest=AssignmentServiceTest,FleetAdminRoleGuardInterceptorTest" -DfailIfNoTests=false test` 通过，69 tests。
+  - `mvn -pl hl-fleet-service spotless:check` 通过。