diff --git a/changelogs-v2/2026-07/25_4756_车务菜单全接口验收与前端契约收口-管理后台.md b/changelogs-v2/2026-07/25_4756_车务菜单全接口验收与前端契约收口-管理后台.md new file mode 100644 index 0000000..96a8f45 --- /dev/null +++ b/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` 通过。