From c095a9d2faf63f58ee4a7e70cf835d9b7e6ffc31 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 3 Aug 2026 20:18:16 +0800 Subject: [PATCH] =?UTF-8?q?chore(5336):=20change=20=E7=AB=AF=E7=82=B9=20re?= =?UTF-8?q?questId=20=E6=8C=81=E4=B9=85=E5=B9=82=E7=AD=89=E4=BA=A4?= =?UTF-8?q?=E6=8E=A5=EF=BC=88605059=20=E4=B8=8E=E9=87=8D=E6=94=BE=E8=AF=AD?= =?UTF-8?q?=E4=B9=89=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...派单requestId持久幂等-修改接口-管理后台.md | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 changelogs-v2/2026-08/03_5336_修改派单requestId持久幂等-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/03_5336_修改派单requestId持久幂等-修改接口-管理后台.md b/changelogs-v2/2026-08/03_5336_修改派单requestId持久幂等-修改接口-管理后台.md new file mode 100644 index 0000000..480947d --- /dev/null +++ b/changelogs-v2/2026-08/03_5336_修改派单requestId持久幂等-修改接口-管理后台.md @@ -0,0 +1,72 @@ +--- +schema: "hl-changelog/v2" +ticket: "5336" +title: "修改派单 requestId 持久幂等：同键重放冻结结果、不同载荷 605059" +consumer: "admin" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-08-03" +status_note: "PR #5427 已 squash 合并到 dev-v3@d4243a2f6；测试部署任务 111419d8 双实例健康；网关真实 change 验证首次 200、同键同载荷重放冻结结果、同键异载荷 605059（前置 #5433 修复 clear 凭证 500 回归）。前端尚未领取，保持 pending。" +updated_at: "2026-08-03" +base: "dev-v3" +--- + +# 修改派单 requestId 持久幂等：同键重放冻结结果、不同载荷 605059 + +> **服务**：`hl-fleet-service` +> +> **Issue**：[#5336](https://git.1814.love:8443/wx/HL/issues/5336) +> +> **影响范围**：管理后台「修改派单」接口的幂等语义与错误码 + +--- + +## ⚠️ 关键变化 + +- 以前：`change` 接口对 `requestId` 只有 Redis 10 秒快速防重；TTL 到期后**同一 requestId + 相同 payload 重放会再次执行改派**（取消旧切片、生成新 group/assignment ID 与生命周期副作用）。 +- 现在：`(operationType=CHANGE, requestId)` 在数据库持久唯一；成功后同键同 payload 重放**直接返回首次冻结结果，不再产生任何改派副作用**；同键不同 payload 返回 `605059`。 +- 前端/调用方以前以为的重放安全不再成立，**重试安全成为持久承诺**；任何新 `requestId` 的合法再次改派不受影响。 + +## 变更接口 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 修改派单 | POST | `/admin/fleet/assignments/:assignmentId/change` | 错误码与幂等语义 | 无请求/响应字段变化 | + +## 变更详情 + +### 3.1 幂等语义（行为变化） + +- 请求体字段（含 `requestId`）与响应字段**均不变**。 +- 首次成功后，相同 `requestId` + 相同业务载荷（规范化后）重放：返回首次冻结的完整响应（同 `assignmentId/assignmentSlotId/newAssignmentGroupId/...` 等），**不**生成新的 group/assignment、OperationLog、Outbox 或生命周期 intent。 +- Redis 10 秒快速防重仍保留，仅承担首次并发抑制，不再承担业务正确性；DB 唯一回执跨 TTL 兜底。 +- 同 `requestId` + 不同业务载荷：稳定失败，返回： + +| code | 含义 | +|---|---| +| `605059` | 幂等请求标识已用于不同业务载荷 | + +- `requestId` 大小写精确区分；首尾空白或超过 64 字符返回参数错误。 +- 新 `requestId` 的再次合法改派不受阻，正常形成新业务变更。 + +## 前端消费动作 + +1. 正常业务无需改动；重试逻辑可依赖持久幂等（同键同载荷重复提交不再重复改派）。 +2. 若收到 `605059`，说明同一 `requestId` 被用于不同内容，必须更换新 `requestId` 重新提交，不得原地重试。 +3. 前端双击/重放场景：响应内容与首次一致，无需重新拉取详情。 + +## 验证证据 + +- Fleet H2 集成：`AssignmentChangeReceiptServiceIntegrationTest` 8/8、迁移测试 2/2。 +- 真实 MySQL 8.0.33 + Redis + Spring AOP：`AssignmentChangeReceiptMysqlTest` 1/1（含跨 TTL 并发 exactly-once）。 +- `AssignmentServiceTest` 340/340；Fleet 全量 verify 结果以 PR 合入后工单回写为准。 +- oasdiff 与 Spring Cloud Contract 未配置，不能标记工具 PASS；以上为源码级字段对比与集成测试回退证据。 + +## Internal Feign / shared Java + +无内部 Feign 或共享 Java 契约变化。