API 幂等与重试规则

适用于派单、审批、支付、工单等关键写操作接口的幂等控制与重试治理。

规则文件内容

请复制以下内容，保存为 .cursor/rules/api-idempotency-retry.mdc：

---
description: API 幂等键、去重窗口、重试策略与冲突返回规则
globs: src/api/**, src/modules/orders/**, src/modules/dispatch/**
---

# API 幂等与重试业务规则

## 1. 核心原则
- **写操作必须幂等**：重复请求不能产生重复业务结果。
- **重试可控**：仅在可重试错误场景触发重试。
- **冲突可解释**：冲突返回要明确当前状态与处理建议。

## 2. 幂等键规则
- 客户端必须传 `idempotency_key`。
- 推荐组合：`tenant_id + api_name + business_id + request_hash`。
- 幂等窗口默认 `24` 小时，可按业务配置。

## 3. 去重处理规则
- 首次请求：执行业务并缓存结果快照。
- 重复请求：直接返回首个结果，不重复执行业务。
- `request_hash` 不一致但 key 相同：返回 `IDEMPOTENCY_CONFLICT`。

```ts
interface IdempotencyRecord {
  key: string;
  requestHash: string;
  responseSnapshot: string;
  statusCode: number;
  expiresAt: string;
}

4. 重试策略规则

• 429/503/UPSTREAM_TIMEOUT 可重试。
• 400/401/403/IDEMPOTENCY_CONFLICT 禁止重试。
• 默认重试次数 2，退避 200ms -> 800ms。

5. 并发与锁规则

• 同一幂等键并发写请求需分布式锁保护。
• 获取锁失败返回 REQUEST_IN_PROGRESS。
• 锁释放必须放在 finally，避免死锁。

6. 结果一致性规则

• 幂等缓存结果与业务主表状态必须一致。
• 业务失败不应写成功快照。
• 失败后可重试时，保留失败原因码。

7. 监控告警规则

• 幂等冲突率超过阈值触发告警。
• REQUEST_IN_PROGRESS 高频出现需排查热点键。
• 重试失败连续升高需检查下游稳定性。

8. 数据模型约束

• api_idempotency_records 必须包含：idempotency_key, request_hash, response_snapshot, status_code, expires_at, created_at
• api_retry_logs 必须包含：trace_id, endpoint, retry_count, last_error_code, finished_at

9. 实施注意事项

• 幂等键传输建议放 Header，避免被代理改写。
• 大响应体可存摘要 + 对象存储引用，避免主库膨胀。
• 高价值交易接口建议增加签名防重放。

## 适用场景

- 派单/抢单接口
- 审批提交流程
- 支付与订单写入

## scripts 可执行校验版本（P3）

- **脚本路径**：`yihuohao/proven/dev-assets/cursor-skills/scripts/check-api-idempotency.cjs`
- **输入文件**：`apis` 数组 JSON（包含 `method/path/idempotency/retry/conflictCode`）

```bash
node yihuohao/proven/dev-assets/cursor-skills/scripts/check-api-idempotency.cjs ./api-spec.json

• 校验结果：发现错误返回退出码 2，可直接接入 CI 门禁。