wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
44456186969226c51c0e169459804a2b43bd03c8
hl-api-changelog/changelogs-v2/2026-09/30_8613_异常处置605072文案订正与座位强禁码下线说明-修复-管理后台.md
T

11 KiB
原始文件 Blame 文件历史

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 8613 605072 恢复动作文案订正 + 605002 座位强禁码下线口径澄清（本条目同时覆盖 #8614） admin wx(GIT) 修复 deployed not_required not_required 本条目合并覆盖 #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）。 2026-09-30 dev-v3

车务派单：605072 恢复动作文案订正 + 605002 座位强禁码下线口径澄清

存放目录: 二期（order-v3/fleet）→ changelogs-v2/2026-09/

服务: hl-fleet-service（端口 8087） PR: #8616 Issue: #8613、#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 当前零产出方，与文案订正内容一致。

十、相关文档

关联 / 联系人

链接

联系人

  • 后端负责人: @wx
在新工单中引用 查看 Git Blame 复制永久链接