{ "openapi": "3.1.0", "info": { "title": "upi-checkout-link API", "version": "canary-20261031-v13", "description": "由当前 Go handler 路由登记表生成的实例级合同。" }, "servers": [ { "description": "当前部署域名", "url": "/" } ], "tags": [ { "name": "System", "description": "进程存活、角色就绪和摘流状态" }, { "name": "Configuration", "description": "版本化 Provider 和运行策略" }, { "name": "Capacity", "description": "多实例容量和队列视图" }, { "name": "Analytics", "description": "提炼结果统计投影" }, { "name": "Billing", "description": "CDK 状态和计费控制面" }, { "name": "Compatibility", "description": "" }, { "name": "AccountPool", "description": "" }, { "name": "Workflows", "description": "" }, { "name": "Frontend", "description": "" }, { "name": "Publisher", "description": "" }, { "name": "Documentation", "description": "实例级 API 合同" } ], "paths": { "/api-docs": { "get": { "operationId": "getAPIDocumentation", "summary": "查看中文 API 文档", "tags": [ "Documentation" ], "responses": { "200": { "description": "中文 API 文档", "content": { "text/html; charset=utf-8": { "schema": { "type": "string" } } } } } } }, "/api/capacity": { "post": { "operationId": "getCapacity", "summary": "查询全局和分维度容量", "tags": [ "Capacity" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "容量快照", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "请求参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "容量数据暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cdk-fuse": { "post": { "operationId": "legacyFuseCdks", "summary": "兼容提交 CDK 融合操作", "tags": [ "Compatibility" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "兼容融合结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "201": { "description": "兼容融合完成结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "融合输入或上游业务条件不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "客户端动作冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "CDK 融合服务限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "CDK 融合上游不可用或响应无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "融合配置或 operation 存储不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "CDK 融合上游超时", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "x-successor": "/api/v1/cdk/fuse" } }, "/api/cdk-status": { "post": { "operationId": "legacyGetCdkStatus", "summary": "兼容查询 CDK 状态", "tags": [ "Compatibility" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "兼容 CDK 状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "CDK 查询参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "CDK 可用点数不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "CDK 或渠道不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CDK 不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "CDK 服务限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "CDK 上游服务不可用或响应无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "CDK 上游查询超时", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "x-successor": "/api/v1/cdk/status" } }, "/api/config": { "get": { "operationId": "getRuntimeConfig", "summary": "查询版本化运行配置", "tags": [ "Configuration" ], "parameters": [ { "name": "X-Checkout-Config-Schema", "in": "header", "description": "客户端支持的配置 schema 版本", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "运行配置", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "426": { "description": "客户端配置 schema 版本过旧", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "运行配置生成失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health": { "get": { "operationId": "getLiveness", "summary": "查询进程存活状态", "tags": [ "System" ], "responses": { "200": { "description": "进程可响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } } } } }, "/api/link-success-stats": { "get": { "operationId": "getLinkSuccessStats", "summary": "查询提炼成功率时间桶", "tags": [ "Analytics" ], "parameters": [ { "name": "hours", "in": "query", "description": "统计窗口小时数", "schema": { "minimum": 1, "type": "integer" } }, { "name": "bucket_minutes", "in": "query", "description": "时间桶分钟数", "schema": { "minimum": 1, "type": "integer" } }, { "name": "provider", "in": "query", "description": "支付 Provider", "schema": { "type": "string" } }, { "name": "rail", "in": "query", "description": "Checkout rail", "schema": { "type": "string" } }, { "name": "stage", "in": "query", "description": "流程阶段", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功率时间桶", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "统计窗口参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "成功率统计暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payment-platform/balance": { "post": { "operationId": "legacyGetPublisherBalance", "summary": "兼容查询发布平台余额", "tags": [ "Compatibility" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "兼容余额结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "平台或凭据参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "平台未启用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "发布平台暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "x-successor": "/api/v1/publishers/{publisher_id}/balance" } }, "/api/payment-platform/masi/teams": { "get": { "operationId": "legacyGetMasiTeams", "summary": "兼容查询 Masi 团队", "tags": [ "Compatibility" ], "responses": { "200": { "description": "兼容 Masi 团队列表", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "Masi 未启用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Masi 暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "x-successor": "/api/v1/publishers/masi/options" } }, "/api/ready": { "get": { "operationId": "getReadiness", "summary": "查询当前角色接单状态", "tags": [ "System" ], "responses": { "200": { "description": "当前角色可以接单", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "503": { "description": "当前角色未就绪或正在摘流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/batch-deletions/{delete_id}": { "get": { "operationId": "getAccountPoolBatchDeletion", "summary": "查询分块删除进度", "tags": [ "AccountPool" ], "parameters": [ { "name": "delete_id", "in": "path", "description": "删除操作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "批次所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "删除阶段和精确计数", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "删除操作不存在或 CDK 不匹配", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "删除状态暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/batches": { "get": { "operationId": "listAccountPoolBatches", "summary": "分页查询账号批次和导入进度", "tags": [ "AccountPool" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "批次所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "cursor", "in": "query", "description": "上一页返回的 opaque 批次游标", "schema": { "type": "string" } }, { "name": "before_batch_no", "in": "query", "description": "旧版批次编号游标", "schema": { "minimum": 1, "type": "integer" } }, { "name": "limit", "in": "query", "description": "每页 1-500 个批次", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "批次、服务端总数、下一页游标和 operation 进度", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "CDK 或分页参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "批次状态暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/batches/{batch_id}": { "delete": { "operationId": "deleteAccountPoolBatch", "summary": "提交可续传的账号批次删除操作", "tags": [ "AccountPool" ], "parameters": [ { "name": "batch_id", "in": "path", "description": "持久化批次 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "批次所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "批次删除幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "刷新后续传删除操作", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "202": { "description": "删除任务已持久化受理", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "批次不存在或 CDK 不匹配", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "批次仍有活动任务或操作冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "删除服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getAccountPoolBatch", "summary": "查询单个账号批次和导入进度", "tags": [ "AccountPool" ], "parameters": [ { "name": "batch_id", "in": "path", "description": "持久化批次 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "批次所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "批次、operation 和精确导入进度", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "CDK 不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "批次不存在或 CDK 不匹配", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "批次状态暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/batches/{batch_id}/accounts": { "get": { "operationId": "listAtBatchAccounts", "summary": "按 keyset 分页查询批次账号展示状态", "tags": [ "AccountPool" ], "parameters": [ { "name": "batch_id", "in": "path", "description": "持久化批次 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "批次所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "cursor", "in": "query", "description": "上一页 next_cursor；账号 ID keyset", "schema": { "minimum": 1, "type": "integer" } }, { "name": "after_account_id", "in": "query", "description": "旧版账号 ID keyset", "schema": { "minimum": 1, "type": "integer" } }, { "name": "limit", "in": "query", "description": "每页 1-500 个账号", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "脱敏账号、完整总数、has_more 和下一页游标", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "CDK 或分页参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "批次不存在或 CDK 不匹配", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "批次账号暂时不可读取", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/import-errors/{import_id}": { "get": { "operationId": "getAccountPoolImportErrors", "summary": "查询或下载稳定错误码报告", "tags": [ "AccountPool" ], "parameters": [ { "name": "import_id", "in": "path", "description": "持久化导入 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "导入所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "after_row", "in": "query", "description": "错误行 keyset 游标", "schema": { "minimum": 1, "type": "integer" } }, { "name": "limit", "in": "query", "description": "每页 1-5000 行", "schema": { "minimum": 1, "type": "integer" } }, { "name": "format", "in": "query", "description": "json 或 csv", "schema": { "type": "string" } } ], "responses": { "200": { "description": "错误总数和报告行", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "游标参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "导入不存在或 CDK 不匹配", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "错误报告暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/import-errors/{import_id}/replay": { "post": { "operationId": "replayAccountPoolImportErrors", "summary": "按原 parser version 重放失败行", "tags": [ "AccountPool" ], "parameters": [ { "name": "import_id", "in": "path", "description": "原导入 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "失败行重放幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "刷新后续传重放导入", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "201": { "description": "失败行重放完成", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "202": { "description": "失败行重放已受理", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "原导入不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "parser version 或幂等输入冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "重放服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/import-paste": { "post": { "operationId": "importAccountPoolPaste", "summary": "提交可续传账号导入任务", "tags": [ "AccountPool" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "同一输入重放时返回原导入操作", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器断线续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "201": { "description": "已完成的原导入结果重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "202": { "description": "导入任务已持久化受理", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "导入参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等键或动作 ID 冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "导入服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/imports/by-client-action/{client_action_id}": { "get": { "operationId": "getAccountPoolImportByClientAction", "summary": "按客户端动作续传账号导入", "tags": [ "AccountPool" ], "parameters": [ { "name": "client_action_id", "in": "path", "description": "浏览器持久化的动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "导入所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "原 operation、响应和导入进度", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "导入不存在或 CDK 不匹配", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "导入状态暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/imports/{import_id}": { "get": { "operationId": "getAccountPoolImport", "summary": "查询账号导入进度", "tags": [ "AccountPool" ], "parameters": [ { "name": "import_id", "in": "path", "description": "持久化导入 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "导入所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "导入状态、checkpoint 和精确计数", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "导入不存在或 CDK 不匹配", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "导入状态暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/runs/{run_id}": { "get": { "operationId": "getAccountPoolBatchRun", "summary": "查询批次目标数和 materialize 精确进度", "tags": [ "AccountPool" ], "parameters": [ { "name": "run_id", "in": "path", "description": "批次运行 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "运行所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "目标数、已生成数和拒绝数", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "运行不存在或 CDK 不匹配", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "运行状态暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/at-pools/start": { "post": { "operationId": "startAccountPoolBatch", "summary": "原子受理批次目标数并分块生成提炼任务", "tags": [ "AccountPool" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "启动操作幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "刷新后续传启动操作", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "202": { "description": "目标数已原子记录并开始后台 materialize", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "启动参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "批次不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "批次状态不允许启动", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "启动服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cdk/fuse": { "post": { "operationId": "fuseCdks", "summary": "提交可续传 CDK 融合操作", "tags": [ "Billing" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "客户端动作键；服务端另以融合组合 hash 保证计费幂等", "schema": { "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "刷新和断流恢复使用的客户端动作 ID", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "上游已存在相同融合结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "201": { "description": "融合完成并持久化结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "融合输入或上游业务条件不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "客户端动作冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "CDK 融合服务限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "CDK 融合上游不可用或响应无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "融合配置或 operation 存储不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "CDK 融合上游超时", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cdk/fusions/by-client-action/{client_action_id}": { "get": { "operationId": "getCdkFusionByClientAction", "summary": "按目标 CDK 查询融合 operation 和结果", "tags": [ "Billing" ], "parameters": [ { "name": "client_action_id", "in": "path", "description": "原融合请求的客户端动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "原融合目标 CDK；仅用于匹配脱敏 actor identity", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "融合 operation 和已持久化响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "目标 CDK 不匹配或 operation 不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "operation 存储暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cdk/status": { "post": { "operationId": "getCdkStatus", "summary": "查询 CDK 状态", "tags": [ "Billing" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "CDK 状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "CDK 查询参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "CDK 可用点数不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "CDK 或渠道不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CDK 不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "CDK 服务限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "CDK 上游服务不可用或响应无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "CDK 上游查询超时", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/publishers": { "get": { "operationId": "listPublishers", "summary": "查询动态发布平台和公开表单能力", "tags": [ "Publisher" ], "responses": { "200": { "description": "已启用发布平台描述", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } } } } }, "/api/v1/publishers/{publisher_id}/balance": { "post": { "operationId": "getPublisherBalance", "summary": "查询指定发布平台余额", "tags": [ "Publisher" ], "parameters": [ { "name": "publisher_id", "in": "path", "description": "发布平台 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "余额和可用状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "平台或凭据参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "平台未启用或不支持余额查询", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "发布平台暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/publishers/{publisher_id}/options": { "get": { "operationId": "getPublisherOptions", "summary": "查询发布平台公开选项", "tags": [ "Publisher" ], "parameters": [ { "name": "publisher_id", "in": "path", "description": "发布平台 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "版本化发布选项", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "平台未启用或不支持选项查询", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "发布平台暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/billing/ledger": { "get": { "operationId": "getCdkBillingLedger", "summary": "查询当前 CDK 隔离的额度流水和关联任务", "tags": [ "Billing" ], "parameters": [ { "name": "email", "in": "query", "description": "完整账号邮箱，不区分大小写", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "流水状态：all、reserve、commit、release、refund", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "RFC3339 起始时间，包含", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "RFC3339 结束时间，不包含", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "上一页返回的 ledger ID 游标", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "每页 1–500 条", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "当前 CDK 的额度流水、汇总和下一页游标", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "CDK 或查询条件不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "额度明细数据库暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/frontend/bootstrap": { "get": { "operationId": "getFrontendBootstrap", "summary": "读取同一前端快照中的配置、计数、批次和任务", "tags": [ "Frontend" ], "parameters": [ { "name": "X-Checkout-Projection-Schema", "in": "header", "description": "客户端支持的前端投影 schema 版本", "schema": { "minimum": 1, "type": "integer" } }, { "name": "X-UPI-CDK", "in": "header", "description": "可选；提供后返回该 CDK 的任务和账号批次快照", "schema": { "type": "string" } } ], "responses": { "200": { "description": "同一 snapshot ID 下的首屏投影", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "CDK 不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "前端投影 schema 不兼容", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "前端投影暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflow-operations/by-client-action/{client_action_id}": { "get": { "operationId": "getWorkflowOperationByClientAction", "summary": "按 CDK 和客户端动作恢复原任务操作", "tags": [ "Workflows" ], "parameters": [ { "name": "client_action_id", "in": "path", "description": "客户端生成并在重试时保持不变的动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "command_type", "in": "query", "description": "workflow.* 稳定命令类型", "schema": { "type": "string" } } ], "responses": { "200": { "description": "原 operation 和持久化响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "命令类型或 CDK 不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "操作不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务状态服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflow-timelines/{workflow_id}": { "get": { "operationId": "getWorkflowTimeline", "summary": "按 cursor 分页查询任务公开时间线", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_id", "in": "path", "description": "持久化 workflow ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "after", "in": "query", "description": "已读取的最后事件 cursor", "schema": { "minimum": 1, "type": "integer" } }, { "name": "limit", "in": "query", "description": "每页 1-500 条事件", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "不含内部快照和私密详情的公开事件时间线", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "分页参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "任务不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务时间线暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows": { "get": { "operationId": "listWorkflows", "summary": "按 keyset 分页查询任务投影", "tags": [ "Workflows" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "cursor", "in": "query", "description": "上一页 opaque 游标", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "每页 1-500 个任务", "schema": { "minimum": 1, "type": "integer" } }, { "name": "state", "in": "query", "description": "任务状态筛选", "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "description": "Provider 筛选", "schema": { "type": "string" } }, { "name": "batch_id", "in": "query", "description": "批次筛选", "schema": { "type": "string" } } ], "responses": { "200": { "description": "精确总数、as_of_cursor 和任务投影", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "分页参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务状态服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWorkflow", "summary": "原子创建单个持久化任务", "tags": [ "Workflows" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "命令幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器刷新后续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "201": { "description": "workflow 和首个 work 已原子创建", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等输入冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务或 CDK 服务不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/batches": { "post": { "operationId": "createWorkflowBatch", "summary": "快速受理并后台分块创建任务", "tags": [ "Workflows" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "命令幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器刷新后续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "202": { "description": "完整 target_count 已持久化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "批次参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等输入冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务或 CDK 服务不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/batches/{batch_id}": { "get": { "operationId": "getWorkflowBatch", "summary": "查询批量创建精确进度", "tags": [ "Workflows" ], "parameters": [ { "name": "batch_id", "in": "path", "description": "workflow batch ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "目标、已创建和失败计数", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "批次不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/cancel/batch": { "post": { "operationId": "cancelWorkflowBatch", "summary": "提交可续传批量取消操作", "tags": [ "Workflows" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "命令幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器刷新后续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "202": { "description": "批量取消 operation 已受理", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/clear-unfinished": { "post": { "operationId": "clearUnfinishedWorkflows", "summary": "按 cutoff 和 CAS 清除未完成任务", "tags": [ "Workflows" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "命令幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器刷新后续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "202": { "description": "tombstone operation 已受理", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/events": { "get": { "operationId": "streamWorkflowEvents", "summary": "按单调 cursor 获取任务 SSE 事件", "tags": [ "Workflows" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "after", "in": "query", "description": "已消费的最后事件 cursor", "schema": { "minimum": 1, "type": "integer" } }, { "name": "limit", "in": "query", "description": "单次最多 1000 个事件", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "workflow 事件和下一 cursor", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "cursor 参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务事件服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/history": { "get": { "operationId": "getWorkflowHistory", "summary": "按 CDK 精确聚合历史任务统计", "tags": [ "Workflows" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "range", "in": "query", "description": "时间范围：1h、6h、24h、7d、30d、today、yesterday", "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "description": "Provider 筛选", "schema": { "type": "string" } }, { "name": "billing_status", "in": "query", "description": "账单状态：with_billing、without_billing、unknown", "schema": { "type": "string" } }, { "name": "ignore_error", "in": "query", "description": "不计入失败 KPI 的原始错误码，可重复传入", "schema": { "type": "string" } }, { "name": "success_cursor", "in": "query", "description": "成功记录上一页 opaque 游标", "schema": { "type": "string" } }, { "name": "success_limit", "in": "query", "description": "每页 1-500 条成功记录", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "精确统计、趋势、原始失败分布和 as_of_cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "历史查询参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务历史服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/lifecycle/{lifecycle_id}": { "get": { "operationId": "getWorkflowLifecycleOperation", "summary": "查询取消或清理 operation 进度", "tags": [ "Workflows" ], "parameters": [ { "name": "lifecycle_id", "in": "path", "description": "workflow lifecycle ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "operation 精确进度", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "operation 不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/progress/batch": { "post": { "operationId": "getWorkflowProgressBatch", "summary": "迁移期批量进度兼容接口", "tags": [ "Workflows" ], "parameters": [ { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "最多 1000 个 workflow 投影", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/{workflow_id}": { "get": { "operationId": "getWorkflow", "summary": "查询单任务及独立维度状态", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_id", "in": "path", "description": "持久化 workflow ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "workflow、维度、work、attempt 和 artifact 投影", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "404": { "description": "任务不存在或已清除", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务状态服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/{workflow_id}/cancel": { "post": { "operationId": "cancelWorkflow", "summary": "请求任务取消并等待补偿完成", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_id", "in": "path", "description": "持久化 workflow ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "命令幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器刷新后续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "任务生命周期状态已持久化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "任务不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "状态或版本冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/{workflow_id}/pause": { "post": { "operationId": "pauseWorkflow", "summary": "请求任务在安全 checkpoint 暂停", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_id", "in": "path", "description": "持久化 workflow ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "命令幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器刷新后续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "任务生命周期状态已持久化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "任务不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "状态或版本冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/{workflow_id}/resume": { "post": { "operationId": "resumeWorkflow", "summary": "从持久化 checkpoint 恢复任务", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_id", "in": "path", "description": "持久化 workflow ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "命令幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器刷新后续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "任务生命周期状态已持久化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "任务不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "状态或版本冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/workflows/{workflow_id}/retry": { "post": { "operationId": "retryWorkflow", "summary": "创建独立 retry attempt", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_id", "in": "path", "description": "持久化 workflow ID", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-UPI-CDK", "in": "header", "description": "任务所属 CDK", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "命令幂等键", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "name": "X-Client-Action-ID", "in": "header", "description": "浏览器刷新后续传动作 ID", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } }, "required": true }, "responses": { "200": { "description": "任务生命周期状态已持久化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "400": { "description": "参数不正确", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "任务不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "状态或版本冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "任务服务暂时不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenAPISpec", "summary": "下载当前实例 OpenAPI 合同", "tags": [ "Documentation" ], "responses": { "200": { "description": "OpenAPI 3.1 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONObject" } } } }, "304": { "description": "合同未变化" } } } } }, "components": { "schemas": { "Error": { "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message_key": { "type": "string" }, "ok": { "const": false, "type": "boolean" }, "private_detail": { "type": "string" }, "retry_class": { "enum": [ "never", "retry", "query", "refresh" ], "type": "string" }, "stage": { "type": "string" }, "support_code": { "type": "string" } }, "required": [ "ok", "code", "error", "message_key", "retry_class", "stage", "support_code" ], "type": "object" }, "JSONObject": { "additionalProperties": true, "type": "object" } }, "securitySchemes": { "AdminSession": { "description": "短期签名管理会话；不包含原始内部密钥", "in": "cookie", "name": "upi_private_lane", "type": "apiKey" }, "InternalKey": { "description": "版本化内部密钥；轮换客户端同时发送 X-UPI-Internal-Key-Version", "in": "header", "name": "X-UPI-Internal-Key", "type": "apiKey" } } }, "x-generated-from": "internal/controlplane route registry", "x-route-count": 48 }