hl-api-changelog/changelogs-v2/2026-08/11_5818b_车务二轮审计整改-契约与枚举增量-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5818	车务第二轮审计整改：保险任务 CANCELLED 可筛、订单进度新增 SKIPPED、错误码声明纠偏、h5 附件来源白名单	admin	wx(GIT)	修改接口	deployed	not_required	implemented	mmg	a4174560		2026-08-11	PR #5864 已合并 dev-v3 并部署测试服实测（全量 3607 用例 0 失败、ArchTest 13/13）。前端已实现(2026-08-11,mmg,a4174560)——实证仅 2 项需改并落地:A1 保险任务状态下拉补 CANCELLED(已撤销,statusType 同 IGNORED 归 default 置灰,修复后 50 条已撤销任务可见,insurance/index.vue);A2 派单进度步骤条补 SKIPPED 渲染(OrderDrawer.vue stepStatus 标 finish 置灰+currentProgressStep 无进行中时计入 DONE+SKIPPED 防定位偏前)。其余实证 not_required/自动受益:A3 attemptId 后端「传了不 400 仅无效」前端兼容;B1 对账车队筛选后端修 bug 前端只展示自动受益;B2 headcountLabel display.js:940/fleetDisplay.js:99 直接展示无 N人 正则解析;B3 605007/605002 仅注释提及(活跃分支已随 #5822 清)605037/605038/605049 无硬编码走全局拦截器透传;B4 车辆删除已接 600109(vehicles/index.vue:1040)司机删除 600204 走全局拦截器透传;B5/C1/C2/C3 后端侧前端零消费。测试:insurance spec +1(下拉含 CANCELLED+状态色),新建 order-drawer-progress.spec 3 用例,fleet/board 431 + insurance 14 全绿,checkpoint 精确文件集全过。	2026-08-11	dev-v3

车务：第二轮审计整改的前端契约增量（#5818 / PR #5864）

服务: hl-fleet-service (8087/8187) PR: #5864（第一轮见 #5837，changelog 11_5818_车务全量审计整改…） 背景: 第二轮审计打第一轮自报的覆盖空洞 + 三个新镜头（安全越权 / 接口契约符合性 / 测试有效性），确认 35 条缺陷并全部修复。大部分是后端内部与门禁修复，以下是前端能看见的增量。

---

变更接口清单

接口	变化	档位
GET /admin/fleet/insurance/tasks	taskStatus / 兼容别名 status 白名单补 CANCELLED	A1
GET /admin/fleet/board/orders/{orderId}	四阶段进度 status 新增第 5 个取值 SKIPPED	A2
HOLD 通知状态查询	删除死入参 attemptId	A3
GET /admin/fleet/reconciliation/cars	按车队筛选时实付不再归零、整行不再消失	B1
GET /admin/fleet/matrix/**	headcountLabel 格式明确为「2大1童」式多段串	B2
POST /admin/fleet/assignments 等 4 个写端点	补声明必抛的 605037 / 605038 / 605049	B3
POST /admin/fleet/assignments/slots（addSlot）	删除死声明 605007	B3
POST /admin/fleet/assignments/{id}/change	删除死声明 605002	B3
DELETE /admin/fleet/vehicles/{id}、/drivers/{id}	软删守卫已生效，会真拒（600109 / 600204）	B4
对账关账 / 重开	close 删死声明 605602、reopen 补必抛 605605	B5
GET /admin/fleet/drivers（列表）	driverStatus 校验文案纠正	C1
4 个消息模板端点	notes 的成功包络写法纠正	C2
h5 司机入职提交	12 类附件 URL 新增来源白名单校验	C3

---

🔴 A. 必须改

A1. 保险任务 CANCELLED 状态现在可以筛了

GET /admin/fleet/insurance/tasks 的 taskStatus（及兼容别名 status）白名单补上 CANCELLED。

这不是新增状态——CANCELLED（派单取消且保单未出单时自动撤销投保任务）一直在真实落库，但查询侧的 Bean Validation 白名单漏了它，传该值直接 400，车务根本无法筛出这批任务。测试服实测修复后 total=50，即此前有 50 条已撤销任务对车务完全不可见。

前端处置：状态下拉补 CANCELLED（已撤销）。完整取值：PENDING / PROCESSING / SUCCESS / RESOLVED / CANCELLED / IGNORED。

A2. 订单详情四阶段进度新增第 5 个取值 SKIPPED

GET /admin/fleet/board/orders/{orderId} 的四阶段进度 status，契约此前只声明 4 个值，但后端在 holdMode=DIRECT（直接派定、跳过司机确认）时实际会下发 SKIPPED。

前端处置：进度条/步骤组件补 SKIPPED 的渲染（建议样式：置灰 + 「已跳过」），否则会落到未知分支。

A3. HOLD 通知状态查询删除死入参 attemptId

该字段 Swagger 宣称用于幂等与审计定位，但 Controller 根本不读，全服务无任何读取点。已删除。前端若在传，去掉即可（传了也不会 400，只是无效）。

---

🟡 B. 按需改

B1. 对账「车队」Tab 按车队筛选时实付不再归零

接口：GET /admin/fleet/reconciliation/cars（periodStart + periodEnd 必填）

显式筛选车队时，此前用「有没有 active prep」当费用行的过滤条件，导致整支车队本期 prep 全被反标（派单取消 / 提前完结截断）时，该队已核单的费用行被整体丢弃 → 返回 fleets=[]、实付归零、整行从页面消失。已改为按选中车队本身过滤。

财务侧会看到这类车队重新出现且实付有值——修 bug 不是回归。

B2. headcountLabel 格式明确

契约此前写「暂按 N 人」，实现在订单上下文有分档时输出的是「2大1童」式多段串（大/童/幼/婴 只拼非零档），只有无上下文或全档为 0 才回退「N人」。契约与 3 个 VO 的 example 已对齐实现。

前端处置：若有按「N人」格式做正则解析的地方，改为直接展示该字符串。

B3. 错误码声明纠偏（删死声明 / 补漏声明）

端点	变化
POST /admin/fleet/assignments（create）等 4 个写端点	补必抛的 605037 / 605038（车辆或司机处于维保、停用等不可派状态）、605049
addSlot	删 605007（该码 #5822 已撤销，全服务无定义无抛出点）
change	删 605002「车型座位不足」（零抛出点；#5810 后座位不符只提示不阻断，与 create 的 notes 本来就矛盾）

前端处置：删掉对 605007 / 605002 的分支（永远不会命中）；给 605037 / 605038 加提示（引导换车或换司机）。

B4. 车辆 / 司机软删守卫已真的生效

DELETE /admin/fleet/vehicles/{id} 与 /drivers/{id} 的 notes 此前写「守卫随派单模块落地生效、当前不拦、契约先行」，实际早已经实抛 600109（车辆今日及以后仍有在途派单）/ 600204（司机同理）。文档已改为真实口径。

前端处置：删除接口时要接住这两个码并给出「先取消派单再删除」的引导——此前前端可能因为文档写「不拦」而没做这个分支。

B5. 对账关账 / 重开错误码纠偏

close 走 upsert 语义（该期从未关过也能直接建 CLOSED 行），故删掉它的死声明 605602「对账期不存在」；reopen 补上必抛的 605605。

---

🟢 C. 只需知晓

C1. 司机列表 driverStatus 校验文案纠正

400 文案此前把 pending 解释成「待续签」（赛季维度语义），与 DriverStatusEnum 的权威语义「待激活」相反。已以枚举为准改正。仅文案，取值不变。

C2. 消息模板 4 个端点的成功包络写法纠正

notes 此前写 { code: 0, msg: "成功" }，实际统一包络是 code = 200、字段名 message（不是 msg）。仅文档纠正，实际响应一直如此。

C3. h5 司机入职提交新增附件来源白名单

免鉴权提交端点对 12 类附件 URL 此前零校验，司机可把任意外部地址写进 pending 并在审核通过后带进正式司机档案。现按 host 判定来源白名单（用 java.net.URL 解析 host 判定，而非整串 startsWith——后者会被 userinfo 混淆串骗过）。

影响：正常走本系统 OSS 上传流程的附件不受影响；若 H5 页面有任何绕过标准上传、直接填外部 URL 的路径，会被拒绝。

---

验证证据

门禁：全量 mvn -pl hl-fleet-service test 3607 用例 0 失败；FleetRedLineArchTest 13/13（含本轮把 R2/R3/R4/R12/R8 的选靶口径从包路径扩为「包路径 ∪ 注解」并集后新覆盖的 4 个 Controller / 6 个 Service）；spotless:check clean。

附带说明一个对「测试可信度」的重要修正：此前 mvn test 长期有 10 个 ReleaseEOccupancyMysql8033RecoveryTest ERROR（该类缺 @EnabledIfSystemProperty，默认构建下是硬报错而非跳过），本轮补上后全量测试第一次真正全绿（退出码 0），此后「红」即真红。同时修正了 6 个集成测试类 18+ 个 @Test 在默认构建里从不执行、却在「N 用例 0 失败」汇总里隐形的问题。

测试服实测（部署 task 47191651；期间发现进程比新 jar 旧，已 SSH 重启双实例后复验）：

1. 保险任务 taskStatus=CANCELLED → code=200、total=50（修复前必 400）。
2. 到期看板合法值 kinds=inspect&buckets=expired → 200；非法值 kinds=INSPECT → 100001 且文案明确列出合法取值。
3. 对账 /cars（periodStart/periodEnd）→ 200，4 个车队全部带 settleMode（兜底口径生效）。
4. 对账 /insurance → 200，drivers[] 已下发 manualAmount / baoyouAmount，且 insuranceAmount 70.56 = manual 70.56 + baoyou 0.00 自洽。
5. Flyway V20260811_007 执行成功，fleet_insurance_task 的 task_status / task_type 列注释已补全 CANCELLED / REFUND_CHECK。

---

前端 checklist

• A1 保险任务状态下拉补 CANCELLED（已撤销）
• A2 四阶段进度补 SKIPPED 渲染分支
• A3 HOLD 通知状态查询去掉 attemptId 入参
• B3 删除 605007 / 605002 分支，补 605037 / 605038 提示
• B4 车辆/司机删除接住 600109 / 600204 并引导「先取消派单」
• B2 headcountLabel 直接展示，不做格式解析
• B1 对账车队 Tab 复核筛选后的实付数值（预期比修复前更完整）