changelog(#5818): 第二轮审计整改契约增量——CANCELLED 可筛/SKIPPED 新取值/错误码纠偏/h5 附件白名单（PR #5864）

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

@@ -0,0 +1,150 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5818"
+title: "车务第二轮审计整改：保险任务 CANCELLED 可筛、订单进度新增 SKIPPED、错误码声明纠偏、h5 附件来源白名单"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-08-11"
+status_note: "PR #5864 已合并 dev-v3 并部署测试服实测（全量 3607 用例 0 失败、ArchTest 13/13）。本条是 11_5818 那条的**增量**，只列第二轮新产生的前端可见变化；第一轮的变化仍以 11_5818 为准（前端已实现 46a57557）。实测确认：CANCELLED 筛选返回 total=50（此前这 50 条车务完全看不到）、到期看板非法值返 100001 文案明确、对账保险 drivers[] 已下发 manualAmount/baoyouAmount 且与 insuranceAmount 自洽。"
+updated_at: "2026-08-11"
+base: "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 复核筛选后的实付数值（预期比修复前更完整）