合并 origin/master

保留 External v1 去背景接口与队列契约纳入 master 的编辑器幂等 receipt、绑定生成和相关 smoke 测试
2026-08-24 12:32:38 +08:00
parent 3c8ece15f8 2449e77461
commit ba4639cc74
49 changed files with 15619 additions and 1636 deletions
@@ -418,6 +418,11 @@
            "ExternalApiKey": []
          }
        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/IdempotentCreateKey"
+          }
+        ],
        "requestBody": {
          "required": false,
          "content": {
@@ -439,11 +444,17 @@
              }
            }
          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
@@ -684,6 +695,9 @@
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/IdempotentCreateKey"
          }
        ],
        "requestBody": {
@@ -718,6 +732,9 @@
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
@@ -766,6 +783,11 @@
            "ExternalApiKey": []
          }
        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/IdempotentCreateKey"
+          }
+        ],
        "requestBody": {
          "required": true,
          "content": {
@@ -795,6 +817,9 @@
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/IdempotentCreateConflict"
          }
        }
      }
@@ -1611,6 +1636,18 @@
          "maxLength": 128,
          "pattern": "^[!-~]+$"
        }
+      },
+      "IdempotentCreateKey": {
+        "name": "Idempotency-Key",
+        "in": "header",
+        "required": false,
+        "description": "可选的稳定创建幂等键。同一账号、接口与键使用相同规范化请求体重试时返回首次结果的当前记录，即使该记录后来已被修改；同键不同请求体返回 409。首次结果已删除时，同键重放同样返回 409 且不会重新创建。网络结果不确定时必须复用原值。",
+        "schema": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[!-~]+$"
+        }
      }
    },
    "responses": {
@@ -1664,6 +1701,16 @@
          }
        }
      },
+      "IdempotentCreateConflict": {
+        "description": "稳定创建幂等冲突：同一 Idempotency-Key 携带不同规范化请求体，或首次创建结果已删除 / 缺少耐久回执；服务端不会重新创建或重复首次副作用",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      },
      "UpstreamError": {
        "description": "上游生成服务失败",
        "content": {