API Changelog Bot a2b1b821a5 docs(changelog): FLEET 接口契约审计修复(错误码补全+校验收紧+拉黑收口) PR#3874

经 api-contract-audit workflow 全量审计 fleet 11 控制器,修复实现与契约不符 14 处。
前端相关:多端点错误码补全 + typeKey 编辑放宽 + vehicleStatus 仅 maint 人工设 +
拉黑收口专用端点 + CSV 审核状态中文 + generateToken 请前端防抖。
已部署测试服实测通过(health + CSV + V004 真库应用)。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-16 16:47:43 +08:00

5.8 KiB

原始文件 永久链接 Blame 文件历史

FLEET 接口契约审计修复（错误码补全 + 校验收紧 + 拉黑收口）— 修改接口 — 管理后台 / 司机端 H5

变更类型：⚠️ 部分行为收紧（含前端需配合的校验/调用方式变更）端类型：管理后台（车务）+ 司机端 H5（OCR/入职）日期：2026-06-16 服务：hl-fleet-service PR：wx/HL#3874

1. 背景

用接口契约语义审计工作流全量扫描车务（fleet）11 个 Controller，逐端点比对「Swagger @ApiOperation 声明的契约 ⨯ 实际实现 ⨯ 业务规则」，修复了 14 处「接口能跑但返回值/落库逻辑与契约不符」。其中与前端对接相关的列在下方。已部署测试服并实测通过（fleet 双实例健康、Flyway 迁移应用成功）。

绝大多数是错误码补全（实现真会抛、但 Swagger 之前漏列，前端按文档做错误处理时会落到「未知错误」兜底）；另有几处校验收紧 / 调用方式变更，前端需配合。

2. 错误码补全（前端按 Swagger 对接错误处理时请补上这些业务码）

平台 HTTP 始终 200，业务码在 Result.code。以下错误码实现一直会抛，本次补进 Swagger notes：

接口	方法	路径	新增错误码	触发场景
删除车型型号	DELETE	`/admin/fleet/vehicle-types/models/{modelId}`	600107	型号已配置价格日历，禁删（请先清价格日历）
编辑司机档案	PUT	`/admin/fleet/drivers/{driverId}`	600209	关联的保游网保单不存在/不属于该司机/状态不可关联
审核通过	POST	`/admin/fleet/drivers/pending/{pendingId}/approve`	605022 / 600404 / 600203	自带车常驻司机已被别车占用 / 续签目标司机为黑名单 / 续签改号撞他人手机号
批量改价格日历状态	PUT	`/admin/fleet/pricing-calendar/{vehicleModelId}/status`	600501 / 600502	日期范围非法 / 范围超 366 天
清除价格日历	DELETE	`/admin/fleet/pricing-calendar/{vehicleModelId}`	600502	范围超 366 天
司机险退保	POST	`/admin/fleet/drivers/{driverId}/insurance/policies/{insuranceOrderId}/cancel`	540224	手工录入的司机年保单禁退保，请在司机档案维护
OCR 识别（H5）	POST	`/app/h5/driver-onboard/ocr/{step}`	600303 / 600305 / 600306 / 600312 / 600313	step 非法或证件识别失败 / 身份证 / 驾驶证 / 行驶证识别失败 / 服务未就绪

⚠️ OCR 端点修正：原 Swagger 写「step 非法返回 400」是错的——实际返业务码 600303（HTTP 仍 200）。前端请按 Result.code===600303 判断，不要按 HTTP 400。

3. 行为变更（前端需配合）

3.1 编辑车型大类：typeKey 可不传（放宽，兼容性变更）

PUT /admin/fleet/vehicle-types/{typeId} 过去若不传 typeKey 会被必填校验打回 400；现已修正为编辑时 typeKey 可不传（后端本就忽略不更新）。前端编辑表单不必再为过校验塞一个占位 typeKey。新增（POST）仍必填 typeKey，不变。

3.2 车辆占用态 vehicleStatus：仅 maint 可人工设（收紧）

POST/PUT /admin/fleet/vehicles 的 vehicleStatus 过去前端可任意写 idle/busy/maint。占用态 busy/idle 是「按派单反算的缓存值」，不允许前端手动设。新规则：

操作	允许	拒绝（返 600112 占用态非法转移）
新增	不传 / `idle` / `maint`	`busy`
编辑	不传（保持原值）/ `idle↔maint`（送修、修好）	设 `busy`；在用车(busy)被人工改

前端车辆表单：只保留「送修(maint)/恢复(idle)」操作，去掉手动设 busy；非法转移会收到 600112。

3.3 司机拉黑：收口到专用端点（收紧，调用方式变更）

PUT /admin/fleet/drivers/{driverId}（通用编辑）不再支持 season: active→blacklist，传了会返 100001（赛季转移非法）。拉黑必须走专用端点 POST /admin/fleet/drivers/{driverId}/blacklist（与解封走 POST /unban 同口径，二者均有幂等/锁保护）。前端拉黑入口请改调专用端点。

4. 其它

4.1 已发放链接导出 CSV：审核状态列中文化

GET /admin/fleet/h5/tokens/export 导出的 CSV「审核状态」列由英文码（pending/approved/rejected）改为中文（待审核/已通过/已驳回），与同表「类型」「状态」列一致。前端基本无感（导出文件给人看）。

4.2 生成入职链接：请前端做按钮防抖（无后端拦截）

POST /admin/fleet/h5/token（生成 token）未加后端幂等（因幂等键无法区分「双击」与「作废后合法重新生成/同司机多次邀请」）。请前端在提交时做按钮 disable / loading 防抖，避免车管双击落两条 pending 记录。

5. 前端 Action 清单

补充第 2 节各端点的错误码文案/分支处理（尤其 OCR 的 600303 按业务码而非 HTTP 400 判断）。
编辑车型大类表单：可不传 typeKey（去掉占位逻辑）。
车辆表单：vehicleStatus 只保留「送修/恢复」(idle↔maint)，去掉手动设 busy。
司机拉黑入口：改调专用端点 POST /drivers/{driverId}/blacklist，通用编辑不要再传 season=blacklist。
生成入职链接按钮：加防抖。

6. 关联

项目	信息
PR	wx/HL#3874（squash 合并 dev-v3，via api-contract-audit workflow）
部署	已部署测试服并实测：fleet 4 端点网关 9443 + admin token 返 code:200；CSV 审核状态列实测为中文；Flyway V20260616_004（group_dispatch 软删唯一键加固）真库应用成功
本地测试	mvn test 全绿（803 tests，含集成测试 H2 全链路）
后端负责人	wx

5.8 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape