---
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`。
