diff --git a/changelogs-v2/2026-08/12_5927_车务管理写端点补齐短窗幂等-修改接口-管理后台.md b/changelogs-v2/2026-08/12_5927_车务管理写端点补齐短窗幂等-修改接口-管理后台.md new file mode 100644 index 0000000..e1708c8 --- /dev/null +++ b/changelogs-v2/2026-08/12_5927_车务管理写端点补齐短窗幂等-修改接口-管理后台.md @@ -0,0 +1,53 @@ +--- +schema: "hl-changelog/v2" +ticket: "5927" +title: "车务管理写端点补齐短窗幂等与重复提交错误码" +consumer: "admin" +change_type: "修改接口" +author: "wx(GIT)" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "pending" +target_release: "v2.1" +verified_at: "2026-08-12" +updated_at: "2026-08-12" +status_note: "后端 PR #5943 已合并 dev-v3 并部署测试服。车队/车辆/车型/司机管理写端点增加 10 秒短窗防重复提交;更新操作按实体 ID + 请求摘要区分,同实体不同内容的连续编辑不会互拦。重复请求返回 100502,前端沿用统一错误提示即可。" +base: "dev-v3" +--- + +# 车务管理写端点补齐短窗幂等(#5927) + +## 变更接口 + +以下现有管理端写接口增加短窗幂等保护,**路径、请求字段和成功响应均不变**: + +- 车队新增、编辑、删除、启用、停用; +- 车辆新增、编辑、删除、启用、停用; +- 车型大类/型号新增、编辑、删除、启用、停用; +- 司机编辑; +- 整团重配沿用 Service 持久幂等。 + +原子确认和司机拒接不使用 Redis 短窗拒绝,分别保留持久回执重放和状态机/CAS 业务幂等,避免断网重试或下一轮派车被误拦。 + +## 行为变化 + +- 相同业务请求在 10 秒窗口内重复提交:返回业务码 `100502`,提示“处理中,请勿重复提交”。 +- 更新操作的 key 为“实体 ID + 稳定请求摘要”: + - 相同实体、相同内容的重复请求会被拒; + - 相同实体、不同内容的合法连续编辑可以正常执行。 +- 内部导入、司机审核等 Service 调用不受管理端防双击 key 影响。 + +## 前端适配 + +无需修改请求或成功响应结构。收到 `100502` 时展示后端 message,并保持按钮短暂禁用/等待当前请求结果;不要自动改成其他请求参数重试。 + +## 验证证据 + +- 后端 PR:`#5943`,squash merge `9d2c29fd`。 +- fresh 编译:763 个生产源、293 个测试源。 +- 幂等定向测试:24/24;Fleet ArchTest:13/13;spotless:通过。 +- fleet 全量:3704 项中仅既有 Windows 进程管道 flaky 2 项失败;该类独立重跑 23/23 通过,其余无失败/错误。 +- 测试服 Deploy Panel:任务 `5042749e` 成功。 +- 9443 网关只读健康验证:车辆、司机、车队分页接口均 `HTTP 200 / code 200`。