141 行
11 KiB
Markdown
141 行
11 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8613"
|
||
title: "605072 恢复动作文案订正 + 605002 座位强禁码下线口径澄清（本条目同时覆盖 #8614）"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "修复"
|
||
backend_status: "deployed"
|
||
gateway_status: "not_required"
|
||
frontend_status: "not_required"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "本条目合并覆盖 #8613 与 #8614（同一 PR #8616 一并修复，两者均为文案订正，未新增/删除/变更任何字段或路径）。#8613：605002「车型座位不足」自 #5810 起已是死码，create/change 均不再做座位强禁校验，全仓（含测试）零产出方；POST /admin/fleet/assignments 的 headcount、strictSeats 两个字段的 Swagger 文案已订正为如实描述——headcount 仅落库记录与下游统计，不再用于任何服务端座位判定；strictSeats 是历史兼容字段，服务端完全忽略，传 true 不会触发 605002，新代码不要依赖它做分支。座位不足的非阻断提示只在 POST /admin/fleet/assignments/precheck 以 warning（type=seats_short）形式给出，precheck 本身零变化。#8614：605072 错误码数值不变（仍是 605072），message 文案从「请先释放资源再处置完成」订正为「请对本单重新执行一次「一键清除已取消派单的占用」后再处置完成」——即撞上 605072 时正确的前端引导是让车务重新调用 POST /admin/fleet/assignments/clear-cancelled-occupancy，而不是原地反复重试 POST /admin/fleet/assignments/resolve-exception；服务端拦回的同时已在独立事务补写一次占用反算意图，按提示重新执行清除占用后再重试 resolve-exception 通常可以收敛。backend_status=deployed：hl-fleet-service 已部署测试服并与本条目所依据的源码提交一致（deploy-status.sh 实测 COMMIT=d57498d38，STATE=ok，2026-09-30 05:34:07 部署）；resolve-exception 路由已实测可达（未登录态返 200 信封 code=401）。"
|
||
updated_at: "2026-09-30"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 车务派单：605072 恢复动作文案订正 + 605002 座位强禁码下线口径澄清
|
||
|
||
> **存放目录**: 二期（order-v3/fleet）→ `changelogs-v2/2026-09/`
|
||
>
|
||
> **服务**: hl-fleet-service（端口 8087）
|
||
> **PR**: [#8616](https://git.1814.love:8443/wx/HL/pulls/8616)
|
||
> **Issue**: [#8613](https://git.1814.love:8443/wx/HL/issues/8613)、[#8614](https://git.1814.love:8443/wx/HL/issues/8614)
|
||
> **日期**: 2026-09-30
|
||
> **性质**: 两处均为 Swagger 描述文案 / 错误消息文案订正，**接口路径、方法、请求参数、响应字段结构、错误码数值均零变更**——不触发接口契约模板，本文档按「修复」类轻量格式书写。
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
1. **605072（异常派单占用未释放）的错误消息文案变了，正确的恢复动作也变了**：旧文案「请先释放资源再处置完成」不点名具体动作，车务只能反复点「处置完成」（`resolve-exception`）本身，而这在「一车/一司机被多张单的异常行共用、逐单释放」的场景下会卡死——即便实际占用已经释放，缓存态仍可能停在旧读数上。新文案明确指向唯一有效的恢复动作：**重新调用一次「一键清除已取消派单的占用」（`clear-cancelled-occupancy`）**，再重试处置完成。**若前端在 605072 分支里硬编码过旧文案、或只做了「提示后原地重试」的处理，需要改成引导用户重新执行清除占用。**
|
||
2. **605002（车型座位不足）确认为死码，不会再从 create/change 派单接口抛出**：这不是本次改的行为，而是订正一处此前不准确的文档描述——该码自 #5810 起已无任何产出方。若前端此前在派车弹窗里对 605002 做过专门的错误分支处理，那段代码从未被触发过、以后也不会。座位不足唯一的提示渠道是 `precheck` 预检接口的非阻断 warning（`type=seats_short`），该渠道本身没有变化。
|
||
|
||
---
|
||
|
||
## 二、涉及接口（非接口契约变更，仅列出文案改动落点，供联调核对）
|
||
|
||
| 接口 | 方法 | 路径 | 改动内容 |
|
||
|------|------|------|----------|
|
||
| 异常派单处置完成 | POST | `/admin/fleet/assignments/resolve-exception` | 605072 错误消息文案改写（#8614） |
|
||
| 创建派单 | POST | `/admin/fleet/assignments` | `headcount`/`strictSeats` 两字段 Swagger 描述文案订正（#8613），字段本身未增删未改类型 |
|
||
|
||
---
|
||
|
||
## 三、逐项说明
|
||
|
||
### 1. `POST /admin/fleet/assignments/resolve-exception`（#8614）
|
||
|
||
**背景**：该接口把订单下全部 `exception` 状态派单行推进到 `completed`，前置条件是这些行的车辆/司机占用已经释放。占用是否释放，判定依据是车辆/司机的**缓存状态列**（`vehicle_status`/`driver_status`）是否为 `busy`。这个缓存列只在特定写口（如 `clear-cancelled-occupancy`）被触发时才会反算刷新。
|
||
|
||
**问题场景**：同一车辆或司机被多张单各自的 `exception` 行共用时，逐单释放会出现死局——释放 A 单时缓存态被判 `busy`（当时正确）；随后处置完 A 单，B 单这边再没有任何写口触发反算 ⇒ 缓存态永远停在旧的 `busy`，即便实际已经没有在途占用支撑，B 单调用 `resolve-exception` 也会永远撞 605072。
|
||
|
||
**本次改动**：
|
||
- 错误消息文案（605072 数值不变）：
|
||
|
||
| | 内容 |
|
||
|---|---|
|
||
| 旧 | `异常派单的车辆/司机占用尚未释放，请先释放资源再处置完成` |
|
||
| 新 | `异常派单的车辆/司机占用尚未释放，请对本单重新执行一次「一键清除已取消派单的占用」后再处置完成` |
|
||
|
||
- 服务端在拦回抛出 605072 的同时，已在独立事务里补写一次「按当前在途口径」的占用反算意图（不影响本次请求仍会失败，是为下一次重试铺路）。
|
||
- Swagger `@ApiOperation` 说明文本同步更新，明确写出 605072 的恢复动作。
|
||
|
||
**对前端的影响**：撞上 605072 时，正确引导是提示用户重新调用 `POST /admin/fleet/assignments/clear-cancelled-occupancy`（该接口路径/参数/行为本身未变），再重试 `resolve-exception`；不建议做「原地无限重试 resolve-exception」的兜底逻辑，因为缓存态陈旧这种情形下光重试 `resolve-exception` 本身不会让状态收敛（要靠 `clear-cancelled-occupancy` 触发反算）。若之前的前端文案直接透传了服务端 message 字符串，会自动拿到新文案，无需改代码；若前端针对 605072 有自己的本地化文案覆盖了服务端 message，建议同步这句新的恢复动作提示。
|
||
|
||
### 2. `POST /admin/fleet/assignments`（#8613）
|
||
|
||
**背景**：该接口的 `CreateAssignmentReqVO` 里有 `headcount`（人数）和 `strictSeats`（座位严格模式）两个历史字段。#5810 起，车型/座位差异已经不再阻断派车（`create`/`change` 均不做座位强禁校验），但这两个字段的 Swagger 描述当时没有同步更新，仍然写着「座位不足判定用」「true=座位不足强禁抛605002」，与实际行为不符。
|
||
|
||
**本次改动（仅 `@ApiModelProperty` 描述文案，字段名/类型/是否必填均未变）**：
|
||
|
||
| 字段 | 旧描述 | 新描述 |
|
||
|------|--------|--------|
|
||
| `headcount` | `人数(座位不足判定用,可空时不判座位)` | `人数(仅落库记录与下游统计;#5810 起 create 不做任何座位校验,车辆座位少于人数也照常派车、不会返回 605002。座位不足的非阻断提示只在 precheck 预检端点以 warning(seats_short) 形式返回,create 侧不产出该提示;本字段可空)` |
|
||
| `strictSeats` | （Java 层注释，非 Swagger 描述）`座位严格模式：true=座位不足强禁抛 605002 / false=仅 warning 不阻断（默认 false）` | `历史兼容字段，#5810 起服务端完全忽略：座位差异不再阻断派车，传 true 也不会抛 605002。全仓无读取方，仅装配侧恒写 false 以保持 BO 形状；新代码不要依赖本字段做任何分支` |
|
||
|
||
**对前端的影响**：
|
||
- 如果前端此前依赖「create 接口会因座位不足报 605002」做过任何拦截逻辑（例如提交前弹确认框、或捕获 605002 单独处理），这段逻辑**从未生效过**——create/change 从 #5810 起就不做这个校验，以后也不会恢复（605002 码位保留但不会复用给别的语义）。
|
||
- `strictSeats` 传什么值都不影响服务端行为，前端无需继续维护/传递这个字段的真实语义（可以继续传，服务端只是忽略）。
|
||
- 座位不足的唯一提示渠道是 `precheck`（`POST /admin/fleet/assignments/precheck`）响应里的 warning 数组，`type=seats_short`——这个渠道本身没有任何变化，仍照旧使用。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
- `resolve-exception` 撞 605072 后的正确恢复序列：`POST clear-cancelled-occupancy` → 重试 `POST resolve-exception`。中间不需要额外等待，服务端的补写反算意图是同步在拦回请求的事务外完成的。
|
||
- `create`（`POST /admin/fleet/assignments`）不会因为座位不足返回任何错误码；如需在提交前给用户座位不足提示，唯一正确渠道是先调用 `precheck` 读取 warning 数组。
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- `resolve-exception` 605072 之外的错误码（401 未登录、其它业务校验失败码）均未变化，本次不涉及。
|
||
- `create` 接口除 Swagger 描述文本外，请求校验、成功路径、其余错误码均未变化。
|
||
|
||
---
|
||
|
||
## 七、不影响范围
|
||
|
||
- `POST /admin/fleet/assignments/precheck` 的请求/响应结构与 `seats_short` warning 的产生条件——零变化。
|
||
- `POST /admin/fleet/assignments/clear-cancelled-occupancy` 的路径、参数、返回结构——零变化。
|
||
- 605002、605072 两个错误码的**数值**本身——均未变化（只是 605072 的 message 文案变了，605002 的可触发性说明被订正，数值都没动）。
|
||
- 除本文档列出的 2 处 `@ApiModelProperty`/错误消息字符串外，`CreateAssignmentReqVO`、`ResolveExceptionReqVO`、响应 VO 均无字段增删或类型变更。
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
- `deploy-status.sh`（测试服现状表）实测：`hl-fleet-service` COMMIT=`d57498d38`、STATE=ok，2026-09-30 05:34:07 部署——与本条目所依据的源码提交（含 #8613/#8614 合并提交 `2bf98beb491`）一致。
|
||
- 测试服内网 `curl` 实测 `resolve-exception` 路由已挂载且鉴权前置生效：
|
||
|
||
```
|
||
POST http://127.0.0.1:8080/admin/fleet/assignments/resolve-exception （无 Authorization 头）
|
||
→ HTTP 200
|
||
{"code":401,"message":"缺少有效的 Authorization 头","data":null,"traceId":"f8da1e80a5e1400b","success":false}
|
||
```
|
||
|
||
- 源码级核对：全仓 grep `SEATS_NOT_ENOUGH` 仅命中 `AssignmentErrorCode.java` 的定义处一行，`hl-fleet-service` 主代码与测试代码中均无第二处引用，确认 605002 当前零产出方，与文案订正内容一致。
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#8613](https://git.1814.love:8443/wx/HL/issues/8613)、[wx/HL#8614](https://git.1814.love:8443/wx/HL/issues/8614)
|
||
- 关联 PR: [wx/HL#8616](https://git.1814.love:8443/wx/HL/pulls/8616)
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8613](https://git.1814.love:8443/wx/HL/issues/8613)、[#8614](https://git.1814.love:8443/wx/HL/issues/8614)
|
||
- **PR**: [#8616](https://git.1814.love:8443/wx/HL/pulls/8616)
|
||
- **Merge commit**: [`2bf98beb491`](https://git.1814.love:8443/wx/HL/commit/2bf98beb49159de09087522d12b532cca720d5db)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|