From 68afb817661eb746d116fb83d20c22f5033d4ad5 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 15 Jun 2026 15:03:43 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E8=BD=A6=E5=8A=A1?= =?UTF-8?q?=E5=AE=A1=E8=AE=A1=E4=BF=AE=E5=A4=8D=E6=89=B9=E6=AC=A1=20PR#381?= =?UTF-8?q?8/#3819=20(=E6=96=B0=E9=94=99=E8=AF=AF=E7=A0=81+H5=E5=85=A5?= =?UTF-8?q?=E8=81=8C=E6=A0=A1=E9=AA=8C=E5=8A=A0=E5=9B=BA+=E7=BC=96?= =?UTF-8?q?=E8=BE=91=E8=AF=AF=E6=8B=A6=E4=BF=AE=E5=A4=8D)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...5入职校验加固+编辑误拦修复_行为变更_管理后台+司机H5.md | 144 ++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 changelogs-v2/2026-06/15_3818-3819_车务审计修复批次-新错误码+H5入职校验加固+编辑误拦修复_行为变更_管理后台+司机H5.md diff --git a/changelogs-v2/2026-06/15_3818-3819_车务审计修复批次-新错误码+H5入职校验加固+编辑误拦修复_行为变更_管理后台+司机H5.md b/changelogs-v2/2026-06/15_3818-3819_车务审计修复批次-新错误码+H5入职校验加固+编辑误拦修复_行为变更_管理后台+司机H5.md new file mode 100644 index 0000000..a6988e3 --- /dev/null +++ b/changelogs-v2/2026-06/15_3818-3819_车务审计修复批次-新错误码+H5入职校验加固+编辑误拦修复_行为变更_管理后台+司机H5.md @@ -0,0 +1,144 @@ +# 【行为变更·错误码·管理后台 + 司机H5】车务审计修复批次（PR #3818 / #3819） + +> **PR**: #3818（审计修复）、#3819（分层重构 + 唯一键并发锁） +> **服务**: hl-fleet-service | **更新时间**: 2026-06-15 +> +> **存放目录**: `changelogs-v2/2026-06/` +> **影响范围**: 管理后台「司机审核 / 司机档案编辑 / 价格日历」 + 司机自助 H5 入职（免登录端） + +--- + +## ⚠️ 关键说明 + +本批是车务服务一次**全量代码质量审计修复**，绝大部分是**内部重构**（分层归位 / 并发锁 / 事务合并 / N+1 查询优化 / 注释口径），**对前端无契约变化**——**无新增/删除端点，无字段结构变化，无字段改名**。 + +本 changelog **只列前端可感知的变化**，分三类： +1. **新增 3 个错误码** + 既有错误码的**新触发场景** —— 前端需补提示文案。 +2. **司机 H5 入职端点输入校验加固** —— 前端 H5 需补客户端校验 + 限流后重试提示。 +3. **个别编辑/删除的行为修复** —— 修掉前端原本会踩到的误拦/误清。 + +⚠️ 不需要前端改字段映射，只需按下表补错误码文案 + H5 端补几处校验。 + +--- + +## 1. 新增错误码（前端需补提示文案） + +| code | 名称 | 触发端点 | 触发场景 | 建议前端文案 | +|---|---|---|---|---| +| **600404** | RENEW_TARGET_SEASON_ILLEGAL | `POST /admin/fleet/drivers/pending/{pendingId}/approve` | 审核**续签**记录时，目标司机当前处于**黑名单**状态（防止通过续签审核绕过授权静默解封黑名单司机） | 「该司机已被拉黑，不能通过续签审核解封，请走解除黑名单流程」 | +| **600310** | APPROVED_CANNOT_VOID | `POST /admin/fleet/h5/tokens/{pendingId}/void` | 对**已通过审核**的入职链接点「作废」 | 「该链接对应的司机已审核通过，不可作废」 | +| **600311** | ONBOARD_MODE_MISMATCH | `POST /app/h5/driver-onboard/submit/new`、`POST /app/h5/driver-onboard/submit/renew` | 用**新招** token 打到「续签提交」端点，或用**续签** token 打到「新招提交」端点 | 「入职链接类型不匹配，请使用正确的链接重新进入」 | + +**既有错误码的新触发场景**（前端文案可能已有，确认覆盖即可）： + +| code | 名称 | 端点 | 新增触发 | +|---|---|---|---| +| 600203 | PHONE_DUPLICATED | `…/pending/{pendingId}/approve` | 续签审核里司机改了手机号，且新手机号与另一在册司机重复 | +| 600503 | MODEL_NOT_FOUND | `DELETE /admin/fleet/pricing-calendar`（清除价格） | 传入不存在的车型 ID（之前静默成功删 0 行，现在明确报错） | +| 600501 | DATE_RANGE_INVALID | `DELETE /admin/fleet/pricing-calendar`（清除价格） | startDate 晚于 endDate（区间反转，之前静默无效，现在明确报错） | + +--- + +## 2. 错误码语义修正（管理后台） + +**端点**：`POST /admin/fleet/h5/tokens/{pendingId}/void`（作废入职链接） + +- **旧行为**：对「已审核通过」的链接作废，返回 `600304`，消息「链接已作废」——与事实矛盾（该链接并未作废）。 +- **新行为**：返回 **`600310`「已通过的链接不可作废」**。 +- `600304`（LINK_VOIDED「链接已作废」）现在**只**用于校验真正已作废的链接。 + +> 前端：把「已通过不可作废」场景的错误码判断由 `600304` 改为 `600310`。 + +--- + +## 3. 司机 H5 入职端点输入校验加固（司机H5） + +免登录 H5 端新增以下后端校验，前端最好同步补客户端校验提升体验： + +### 3.1 证件 OCR 端点加文件校验 + 限流 + +**端点**：`POST /app/h5/driver-onboard/ocr/{step}`（multipart 上传证件照识别） + +- **新增文件校验**：文件**非空** + **仅图片**（contentType `image/*`） + **≤ 10 MB**，不满足返 `100001`「参数非法: …」。 +- **新增限流**：`@RateLimiter` **30 次 / 60 秒**（与短链端点一致），超限返限流提示。 + +``` +# 反例：上传非图片或超大文件 +POST /app/h5/driver-onboard/ocr/idcard (multipart, file=xxx.pdf) +→ { "code": 100001, "message": "参数非法: 仅支持图片格式（jpg/png/webp）" } +``` + +> 前端：上传前先校验类型/大小；遇限流（短时间多次点）给「操作过于频繁，请稍后再试」提示。 + +### 3.2 提交端点加 mode 守卫 + +- `POST /app/h5/driver-onboard/submit/new` 现要求 token 是**新招**类型，否则返 `600311`。 +- `POST /app/h5/driver-onboard/submit/renew` 现要求 token 是**续签**类型，否则返 `600311`。 + +> 防止链接被错用到另一端点造成档案污染/数据丢弃。正常流程前端按 init 返回的 `mode` 走对应页面即不会触发。 + +### 3.3 新招提交「自带车」跨字段必填 + +**端点**：`POST /app/h5/driver-onboard/submit/new` + +- `hasOwnVehicle = true` 时，`vehicle` 对象必须非空，且车牌 `plate`、车型 `model` 关键项非空，否则返 `100001`。 +- 之前 `hasOwnVehicle=true` 而 `vehicle` 为空会落库为空白车辆字段，审核侧拿到矛盾数据需人工驳回。 + +### 3.4 续签提交 `continueSeason` 必填 + +**端点**：`POST /app/h5/driver-onboard/submit/renew` + +- `continueSeason`（是否继续合作）现为 **`@NotNull` 必填**，缺失返 `400`「是否继续合作不能为空」。 +- 之前缺失会被后端兜底当「归档」处理，可能误归档司机。 + +### 3.5 入职链接 URL 为路径参数（仅文档订正，无行为变化） + +- 后端产出的入职链接一直是**路径参数**形式 `…/driver-intake/{token}`（对齐前端路由 `/driver-intake/:token`）。 +- 本次仅把 Swagger 文档/示例里残留的旧 query 形式 `?t={token}` 订正为 `/{token}`，**实际行为未变**。前端按现有路由即可。 + +--- + +## 4. 行为修复（管理后台） + +### 4.1 编辑「单次投保」司机不再被误拦 + +**端点**：`PUT /admin/fleet/drivers/{driverId}` + +- **旧问题**：编辑一个 `insuranceType=perTrip` 的司机时，若只回传 `insuranceType` 而**未重发** `insurancePlanId`，会被 `100001` 误拦（即便库里已有合法 planId）。 +- **新行为**：库里已有 planId 时，编辑不重发 planId **放行**；仅当库里也没有、入参也没有时才报必填。 + +### 4.2 编辑司机驾照不再误清有效期 + +**端点**：`PUT /admin/fleet/drivers/{driverId}` + +- 编辑 license 块时，`licenseExpire`（驾照有效期）改为**入参非空才覆盖**（对齐同块其它字段），不再因前端缺省 `expire` 而把库里的有效期清成 NULL。 + +### 4.3 gender 字段口径统一 + +- 列表 / 详情的 `gender` 取值统一为 **`0=未知` `1=男` `2=女`**（之前列表文档漏了 `0`）。司机性别可能返回 `0`，前端按「未知」渲染。 + +--- + +## 5. 投保 / 退保幂等加固（管理后台） + +**端点**： +- `POST /admin/fleet/drivers/{driverId}/insurance/purchase`（投保，真实出单扣费） +- `POST /admin/fleet/drivers/{driverId}/insurance/policies/{insuranceOrderId}/cancel`（退保） + +- 这两个端点现已加**幂等 + 分布式锁**：短时间内**重复提交**（双击 / 弱网重试）会被拦截，返回「投保处理中，请勿重复提交」/「退保处理中，请勿重复提交」。 +- 前端**无需改动**，但可借此移除自己的临时防双击逻辑（后端已兜底，不会再重复扣费）。 + +--- + +## 6. 内部变更（无前端影响，仅备查） + +以下为本批的内部重构，**不影响任何接口契约**，列出仅供排查时参考： + +- **分层重构（C5-B）**：司机/车辆/车型三子域的跨域数据访问改为 Port/Service 收口（消除循环依赖），读路径返回数据不变。 +- **常驻车唯一键（C8）**：车辆 `uk_primary_driver` 单列唯一键改复合 `(primary_driver_id, deleted_at)` + 并发锁，修掉「软删车残留常驻导致新绑定报 500」的潜在问题。绑定/解绑接口行为不变。 +- **价格日历并发**：四个价格写端点统一全局写锁，修掉并发「单改+批改」落重复记录致整页 500 的竞态。 +- **司机列表标签查询 N+1 优化**：列表返回结构不变。 + +--- + +> 有疑问或需要补具体 curl 示例的端点，随时找后端（wx）。