实现七月迭代公共技术基础

docs/tech-public-foundation/创建命令幂等契约.md

@@ -0,0 +1,19 @@
+# 创建命令幂等与并发职责契约
+
+创建类命令使用“调用主体 + 操作类型 + `request_id`”作为入口身份，并把影响业务结果的专用命令 DTO 计算为带版本的 SHA-256 指纹。时间戳、签名、Token、Authorization、Cookie 和 Nonce 等易变传输字段不进入指纹；业务模块应尽量直接传专用 DTO，避免把任意 HTTP 请求整体作为业务身份。
+
+同一作用域中，相同 `request_id` 与相同指纹返回已保存的业务结果；指纹不同返回统一冲突且不得覆盖原事实。不同主体或不同操作类型即使复用同一 `request_id`，也属于不同命令。
+
+应用层预查只改善返回体验。并发首写必须由业务表或业务幂等事实上的 PostgreSQL 唯一约束裁决，并与业务事实处于同一事务。公共基础不创建万能幂等表，业务模块自行保存结果定位和稳定业务唯一键。
+
+各类身份与并发职责不得混用：
+
+| 构件 | 唯一职责 |
+|---|---|
+| `request_id` + 指纹 | 识别入口命令重放与内容冲突 |
+| `event_id` | 识别至少一次投递中的同一事件 |
+| 业务唯一键/唯一流水 | 防止同一业务副作用重复落库 |
+| 状态条件更新 | 裁决状态机是否可从预期状态推进 |
+| 钱包 `version` | 裁决余额、冻结额等并发数值更新 |
+| Worker 租约 | 暂时决定当前处理者，不证明副作用尚未发生 |
+| Redis 锁或 `SETNX` | 降低热点并发；故障、过期或切主不能破坏最终正确性 |