From 0ab42ab0d4a80606f335f425a2cdb6736735477d Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 11 Aug 2026 17:26:33 +0800 Subject: [PATCH] =?UTF-8?q?changelog(#5818):=20=E7=AC=AC=E4=BA=8C=E8=BD=AE?= =?UTF-8?q?=E5=AE=A1=E8=AE=A1=E6=95=B4=E6=94=B9=E5=A5=91=E7=BA=A6=E5=A2=9E?= =?UTF-8?q?=E9=87=8F=E2=80=94=E2=80=94CANCELLED=20=E5=8F=AF=E7=AD=9B/SKIPP?= =?UTF-8?q?ED=20=E6=96=B0=E5=8F=96=E5=80=BC/=E9=94=99=E8=AF=AF=E7=A0=81?= =?UTF-8?q?=E7=BA=A0=E5=81=8F/h5=20=E9=99=84=E4=BB=B6=E7=99=BD=E5=90=8D?= =?UTF-8?q?=E5=8D=95=EF=BC=88PR=20#5864=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...审计整改-契约与枚举增量-修改接口-管理后台.md | 150 ++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 changelogs-v2/2026-08/11_5818b_车务二轮审计整改-契约与枚举增量-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/11_5818b_车务二轮审计整改-契约与枚举增量-修改接口-管理后台.md b/changelogs-v2/2026-08/11_5818b_车务二轮审计整改-契约与枚举增量-修改接口-管理后台.md new file mode 100644 index 0000000..0996ead --- /dev/null +++ b/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 复核筛选后的实付数值（预期比修复前更完整）