wx/hl-api-changelog

API Changelog Bot ed8448c625 docs(fleet): add menu api validation handoff

2026-07-05 20:35:20 +08:00

4.4 KiB

原始文件 Blame 文件历史

【前端对接·管理后台】车务菜单全接口验收与契约收口

Issue: wx/HL#4756
PR: wx/HL#4757, wx/HL#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 通过。