{ "openapi": "3.1.0", "info": { "title": "Knowledge Governance API", "version": "v1", "description": "独立知识治理控制平面API。所有响应使用安全投影；不返回来源凭据、签名下载地址、原始内容、内部目标连接或生产密钥。" }, "servers": [ { "url": "/", "description": "当前治理控制平面" } ], "tags": [ { "name": "Health" }, { "name": "Jobs" }, { "name": "Source catalog" }, { "name": "Monitoring" }, { "name": "Scope" }, { "name": "Source connections" }, { "name": "Review" }, { "name": "Release" }, { "name": "Test processing" }, { "name": "Settings" } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "operationId": "getHealth", "summary": "读取服务健康状态", "responses": { "200": { "description": "服务可响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/jobs": { "get": { "tags": [ "Jobs" ], "operationId": "listJobs", "summary": "列出最近治理任务", "parameters": [ { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Jobs" ], "operationId": "createJob", "summary": "创建幂等后台任务", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-items": { "get": { "tags": [ "Source catalog" ], "operationId": "listSourceItems", "summary": "列出安全来源文件投影", "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/sources": { "get": { "tags": [ "Source catalog" ], "operationId": "listCatalogSources", "summary": "列出当前可浏览来源快照", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/nodes": { "get": { "tags": [ "Source catalog" ], "operationId": "listCatalogNodes", "summary": "按父目录分页列出当前快照直接子项", "parameters": [ { "$ref": "#/components/parameters/ConnectionID" }, { "name": "parent_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 36 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/change-sets/latest": { "get": { "tags": [ "Source catalog" ], "operationId": "getLatestCatalogChangeSet", "summary": "读取某来源最新持久ChangeSet", "parameters": [ { "$ref": "#/components/parameters/ConnectionID" }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "add", "update", "move", "move_scope", "delete", "no_change" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/routing-capabilities": { "get": { "tags": [ "Source catalog" ], "operationId": "getCatalogRoutingCapabilities", "summary": "读取对内和对外测试路由是否已配置", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/route": { "post": { "tags": [ "Source catalog" ], "operationId": "setCatalogPolicy", "summary": "写入目录或文件的期望处理策略", "description": "当前接口只修改治理策略和审计记录，不代表已经上传、解析或发布。调用方必须为每次用户动作生成新的 Idempotency-Key；网络重试复用原键会返回原结果且 operation=replayed，同键不同请求返回409。", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogRouteRequest" } } } }, "responses": { "202": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/sources/{id}/refresh": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Source catalog" ], "operationId": "refreshCatalogSource", "summary": "创建来源目录刷新任务", "description": "调用方必须为每次用户动作生成新的 Idempotency-Key；网络重试复用原键会返回同一刷新任务且 operation=replayed。", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/monitor/overview": { "get": { "tags": [ "Monitoring" ], "operationId": "getMonitorOverview", "summary": "读取主机、服务和知识库处理概览", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/monitor/knowledge-bases/{id}/files": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "get": { "tags": [ "Monitoring" ], "operationId": "listKnowledgeBaseFiles", "summary": "按处理状态分页列出知识库文件", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "finalizing", "completed", "failed", "cancelled" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/filename-filters": { "get": { "tags": ["Source connections"], "operationId": "listFilenameFilters", "summary": "列出来源和目录的文件扩展名筛选规则", "parameters": [{"name":"connection_id","in":"query","required":true,"schema":{"type":"string"}}], "responses": {"200":{"description":"筛选规则"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}} }, "put": { "tags": ["Source connections"], "operationId": "setFilenameFilter", "summary": "设置来源或目录文件扩展名筛选", "parameters": [{"$ref":"#/components/parameters/IdempotencyKey"}], "responses": {"200":{"description":"筛选规则已生效"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalError"}} }, "delete": { "tags": ["Source connections"], "operationId": "clearFilenameFilter", "summary": "移除本级筛选并恢复继承", "parameters": [{"$ref":"#/components/parameters/IdempotencyKey"}], "responses": {"200":{"description":"本级筛选已移除"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalError"}} } }, "/api/v1/scope-rules": { "get": { "tags": [ "Scope" ], "operationId": "listScopeRules", "summary": "读取来源范围规则", "parameters": [ { "$ref": "#/components/parameters/ConnectionID" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "tags": [ "Scope" ], "operationId": "setScopeRule", "summary": "创建或更新范围规则", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeRuleMutation" } } } }, "responses": { "200": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": [ "Scope" ], "operationId": "clearScopeRule", "summary": "清除范围规则", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeRuleMutation" } } } }, "responses": { "200": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/dingtalk-session": { "post": { "tags": [ "Source connections" ], "operationId": "startDingtalkSession", "summary": "发起钉钉扫码登录会话（管理员）", "responses": { "201": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/dingtalk-session/{id}": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "get": { "tags": [ "Source connections" ], "operationId": "getDingtalkSession", "summary": "轮询钉钉扫码会话状态（管理员）", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": [ "Source connections" ], "operationId": "cancelDingtalkSession", "summary": "取消钉钉扫码会话（管理员）", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/dingtalk-spaces": { "post": { "tags": [ "Source connections" ], "operationId": "registerDingtalkSpace", "summary": "解析并登记钉钉知识库空间（管理员）", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-connections": { "get": { "tags": [ "Source connections" ], "operationId": "listSourceConnections", "summary": "列出安全来源连接投影", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-connections/{id}/scan": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Source connections" ], "operationId": "triggerSourceScan", "summary": "创建旧PP来源扫描任务", "responses": { "202": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/source-connections/{id}/scans": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "get": { "tags": [ "Source connections" ], "operationId": "listSourceScans", "summary": "分页读取来源扫描记录", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-connections/{id}/scans/{scan_id}": { "parameters": [ { "$ref": "#/components/parameters/ID" }, { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "tags": [ "Source connections" ], "operationId": "getSourceScan", "summary": "读取单次扫描及其安全变更投影", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/review-candidates": { "get": { "tags": [ "Review" ], "operationId": "listReviewCandidates", "summary": "分页列出可审核测试知识", "parameters": [ { "name": "review_state", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "not_required" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/review-candidates/{id}/decision": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Review" ], "operationId": "reviewCandidate", "summary": "提交人工审核决定", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewDecisionRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/release-plan": { "get": { "tags": [ "Release" ], "operationId": "getReleasePlan", "summary": "预览当前测试到生产的发布计划", "description": "当前是实时预览，不是不可变Release ChangeSet；R1会替换为持久发布ChangeSet。", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/release-batches": { "get": { "tags": [ "Release" ], "operationId": "listReleaseBatches", "summary": "分页列出草稿或已封存发布批次", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "draft", "sealed", "cancelled" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Release" ], "operationId": "createReleaseBatch", "summary": "创建草稿发布批次", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseBatchCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/release-batches/{id}": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "get": { "tags": [ "Release" ], "operationId": "getReleaseBatch", "summary": "读取发布批次详情", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/release-batches/{id}/seal": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Release" ], "operationId": "sealReleaseBatch", "summary": "封存草稿发布批次，不触发生产发布", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseBatchSealRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/release-batches/{id}/authorize-production": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Release" ], "operationId": "authorizeProductionRelease", "summary": "受门禁保护的生产发布授权（页面按钮或运维脚本）", "description": "默认关闭。调用方不得提交审核人身份。两条通道：运维脚本用受限配置的 Bearer token（审计记固定授权人）；页面按钮用管理员会话 + 固定确认语句（审计记该管理员）。请求门禁、备份恢复门禁与 Release Worker 执行门禁不变。 确认语句：publish-to-production。", "responses": { "202": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/release-executions": { "get": { "tags": [ "Release" ], "operationId": "listReleaseExecutions", "summary": "分页读取生产发布和回滚审计", "parameters": [ { "name": "operation", "in": "query", "schema": { "type": "string", "enum": [ "publish", "rollback" ] } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending", "running", "rolling_back", "completed", "failed", "rolled_back", "rollback_failed" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/release-executions/{id}": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "get": { "tags": [ "Release" ], "operationId": "getReleaseExecution", "summary": "读取单次生产发布或回滚详情", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/release-executions/{id}/authorize-rollback": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Release" ], "operationId": "authorizeProductionRollback", "summary": "受门禁保护的生产回滚授权（页面按钮或运维脚本）", "description": "两条通道：运维脚本用受限配置的 Bearer token（审计记固定授权人）；页面按钮用管理员会话 + 固定确认语句（审计记该管理员）。请求门禁、备份恢复门禁与 Release Worker 执行门禁不变。 确认语句：rollback-production-release。", "responses": { "202": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/release-executions/{id}/retry": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Release" ], "operationId": "retryProductionRelease", "summary": "受门禁保护地重排失败发布（页面按钮或运维脚本）", "description": "两条通道：运维脚本用受限配置的 Bearer token（审计记固定授权人）；页面按钮用管理员会话 + 固定确认语句（审计记该管理员）。请求门禁、备份恢复门禁与 Release Worker 执行门禁不变。 确认语句：retry-production-release。重排沿用原执行的授权人记录。", "responses": { "202": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/release-capabilities": { "get": { "tags": [ "Release" ], "operationId": "getReleaseCapabilities", "summary": "读取不含敏感信息的生产门禁能力", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/routing-bindings": { "get": { "tags": [ "Settings" ], "operationId": "getRoutingBindings", "summary": "读取对内/对外知识库绑定", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "tags": [ "Settings" ], "operationId": "saveRoutingBindings", "summary": "绑定对内/对外知识库（管理员）", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/production-kb-bindings": { "get": { "tags": [ "Settings" ], "operationId": "getProductionBindings", "summary": "读取对内/对外生产知识库绑定（源库 → 目标库）", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "tags": [ "Settings" ], "operationId": "saveProductionBindings", "summary": "绑定发布目标的 对内/对外生产知识库（管理员）", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/production-kb-bindings/options": { "get": { "tags": [ "Settings" ], "operationId": "listProductionBindingOptions", "summary": "列出可绑定的生产 WeKnora 知识库", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/routing-bindings/options": { "get": { "tags": [ "Settings" ], "operationId": "listRoutingBindingOptions", "summary": "列出可绑定的 WeKnora 知识库", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/ui-settings": { "get": { "tags": [ "Settings" ], "operationId": "getActiveUISettings", "summary": "读取当前活动的安全刷新和告警设置", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/ui-settings/candidates": { "post": { "tags": [ "Settings" ], "operationId": "createUISettingsCandidate", "summary": "创建待验证的安全设置版本", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UISettingsCandidateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/ui-settings/{id}/activate": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Settings" ], "operationId": "activateUISettings", "summary": "验证并原子启用设置版本", "responses": { "200": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "parameters": [ { "$ref": "#/components/parameters/ID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/test-publications": { "get": { "tags": [ "Test processing" ], "operationId": "listTestPublications", "summary": "按处理状态分页读取测试发布记录", "parameters": [ { "name": "processing_state", "in": "query", "description": "解析状态过滤。可传单个状态，或用逗号拼接多个状态（例如 failed,stalled）一次取出全部失败项。", "schema": { "type": "string", "pattern": "^(planned|pending|processing|finalizing|completed|failed|stalled|cancelled)(,(planned|pending|processing|finalizing|completed|failed|stalled|cancelled))*$" } }, { "in": "query", "name": "target_scope", "description": "Filter the test queue by routing target: internal or external (P4).", "required": false, "schema": { "type": "string", "enum": [ "internal", "external" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/test-publications/start": { "post": { "tags": [ "Test processing" ], "operationId": "startTestPublications", "summary": "人工确认后启动测试解析任务", "description": "当前按TestPublication确认；P3会把该操作改为按Catalog ChangeSet确认。网络重试复用原 Idempotency-Key。", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartTestPublicationsRequest" } } } }, "responses": { "202": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/test-publications/{id}/acceptance": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "get": { "tags": [ "Test processing" ], "operationId": "listTestPublicationAcceptance", "summary": "读取测试发布的安全验收记录", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/test-publications/{id}/retry": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Test processing" ], "operationId": "retryTestPublication", "summary": "重新排队一份可重试测试发布", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/snapshots": { "get": { "tags": [ "Source catalog" ], "operationId": "listCatalogSnapshots", "summary": "按来源分页读取历史快照清单", "description": "Head当前生效快照排在最前；只返回安全投影，不返回snapshot hash或locator hash。", "parameters": [ { "$ref": "#/components/parameters/ConnectionID" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/snapshots/{id}/nodes": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "get": { "tags": [ "Source catalog" ], "operationId": "listCatalogSnapshotNodes", "summary": "只读分页查看历史快照中的目录节点", "description": "该接口只读，绝不切换当前Head。content_sha256仅在来源实际提供时返回；未知即null，不伪造。", "parameters": [ { "$ref": "#/components/parameters/ConnectionID" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-catalog/change-sets/{id}/confirm": { "parameters": [ { "$ref": "#/components/parameters/ID" } ], "post": { "tags": [ "Source catalog" ], "operationId": "confirmCatalogChangeSet", "summary": "确认 ChangeSet 中选中的变更项并创建解析任务", "description": "仅执行选中的 item_seqs；NO_CHANGE 永不入队；禁止/删除项形成测试库移除任务。重复确认返回第一次结果 operation=replayed；同键不同请求 409。绝不返回内部 locator hash。", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmChangeSetRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/job-failures/{id}/requeue": { "post": { "operationId": "requeueJobFailure", "summary": "重排一条终端失败的“源头取件”死信", "description": "取件任务的幂等键绑在来源版本上，失败那次已占住它，所以重新标注同一文件不会再入队。本接口按新轮次重新入队并复位意图取件状态，同时把死信标记为 requeued。仅限 artifact.fetch 类型且仍为 open 的记录。", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "已重新入队；replayed=true 表示幂等重放" }, "400": { "description": "请求无效或缺少 Idempotency-Key" }, "409": { "description": "该失败记录不可重排，或幂等键与不同请求冲突" }, "500": { "description": "服务端错误" } } } }, "/api/v1/job-failures": { "get": { "summary": "分页列出解析死信（DLQ）投影", "description": "终端失败尝试的只读投影；原 jobs 与发布审计行永不移动或删除。", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "requeued", "abandoned" ] }, "description": "默认 open" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "死信投影分页", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "job_id": { "type": "string" }, "job_type": { "type": "string" }, "publication_id": { "type": "string" }, "source_item_id": { "type": "string" }, "error_code": { "type": "string" }, "attempt": { "type": "integer" }, "max_attempts_at_failure": { "type": "integer" }, "change_set_id": { "type": "string" }, "action": { "type": "string" }, "target_kb_id": { "type": "string" }, "state": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "operationId": "listJobFailures" } }, "/api/v1/test-publications/retry-batch": { "post": { "summary": "服务端批量重试失败发布", "description": "一次事务内逐项返回 started/already_running/not_retryable；批量操作人、原因与幂等信封原子记录。最多100项，前端不得循环调用单项接口。", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publication_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }, "operator_ref": { "type": "string", "minLength": 1, "maxLength": 128 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "publication_ids", "operator_ref", "reason" ] } } } }, "responses": { "200": { "description": "批量重试结果（含逐项outcome）", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batch_key": { "type": "string" }, "total": { "type": "integer" }, "started": { "type": "integer" }, "already_running": { "type": "integer" }, "not_retryable": { "type": "integer" }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "publication_id": { "type": "string" }, "result": { "type": "string", "enum": [ "started", "already_running", "not_retryable" ] }, "detail": { "type": "string" } } } } }, "required": [ "batch_key", "total", "started", "already_running", "not_retryable", "outcomes" ] }, "operation": { "type": "string", "enum": [ "created", "replayed" ] } }, "required": [ "data", "operation" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "operationId": "retryPublicationsBatch" } }, "/api/v1/test-publications/cancel-batch": { "post": { "summary": "服务端批量取消失败发布（不再自动重试）", "description": "用于源头即空文档等永久性失败：一次事务内把 failed/stalled 发布置为 cancelled，撤销排队中的上传任务并放弃对应死信；逐项返回 cancelled/already_running/not_retryable。原始记录与暂存文件保留，重新标记入库可再次处理。最多100项，操作人与原因由服务端会话注入并原子审计。", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publication_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "publication_ids", "reason" ] } } } }, "responses": { "200": { "description": "批量取消结果（含逐项outcome）", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batch_key": { "type": "string" }, "total": { "type": "integer" }, "started": { "type": "integer", "description": "成功取消的项数" }, "already_running": { "type": "integer" }, "not_retryable": { "type": "integer", "description": "不可取消的项数（如已完成或不在失败态）" }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "publication_id": { "type": "string" }, "result": { "type": "string", "enum": [ "cancelled", "already_running", "not_retryable" ] }, "detail": { "type": "string" } } } } }, "required": [ "batch_key", "total", "started", "already_running", "not_retryable", "outcomes" ] }, "operation": { "type": "string", "enum": [ "created", "replayed" ] } }, "required": [ "data", "operation" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "operationId": "cancelPublicationsBatch" } }, "/api/v1/monitor/metrics": { "get": { "operationId": "getMonitorMetrics", "summary": "真实运行指标（Worker/队列/吞吐/成功率/耗时分布）", "description": "冻结1小时与24小时统计窗口；样本不足的比率与分位数返回null而非0；活跃Worker按PostgreSQL新鲜租约去重计数，不按容器数猜测。模拟模式声明worker_source=simulation。", "parameters": [], "responses": { "200": { "description": "运行指标快照", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "observed_at": { "type": "string", "format": "date-time" }, "active_workers": { "type": "integer" }, "worker_source": { "type": "string", "enum": [ "pg_lease", "simulation" ] }, "queue": { "type": "object", "properties": { "pending": { "type": "integer" }, "running": { "type": "integer" }, "retry": { "type": "integer" }, "failed": { "type": "integer" }, "oldest_pending_age_seconds": { "type": [ "number", "null" ] } } }, "short_window": { "$ref": "#/components/schemas/JobWindowMetrics" }, "long_window": { "$ref": "#/components/schemas/JobWindowMetrics" } } } } } } } }, "503": { "description": "指标暂不可用", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/livez": { "get": { "operationId": "getLivez", "summary": "存活探针（Liveness）", "description": "仅回答“本进程能否服务HTTP”。绝不依赖PostgreSQL、WeKnora、MinerU或Worker：第三方故障时本端点必须保持200。", "responses": { "200": { "description": "进程存活", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "observed_at" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "tags": [ "Health" ] } }, "/readyz": { "get": { "operationId": "getReadyz", "summary": "就绪探针（Readiness）", "description": "逐服务独立评估Liveness与Readiness（P10）。只有“已部署且已配置但当前不可工作”的服务阻塞就绪并返回503；未部署=not_applicable、缺配置=not_configured 仅警告不阻塞；结果绝不泄漏URL、密钥或主机。", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "503": { "description": "存在已配置依赖当前不可接单", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "blocked": { "type": "array", "items": { "type": "string" } }, "not_configured": { "type": "array", "items": { "type": "string" } }, "observed_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "blocked", "not_configured", "observed_at" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "tags": [ "Health" ] } }, "/api/v1/release-change-sets": { "get": { "tags": [ "Release" ], "operationId": "listReleaseChangeSets", "summary": "分页列出版本化发布计划集", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "每页数量，默认20上限100" }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "偏移" } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Release" ], "operationId": "generateReleaseChangeSet", "summary": "把当前实时发布计划固化为不可变版本化ChangeSet", "description": "生成即冻结：绑定当前head快照集与确认过的目录ChangeSet集，按精确字段顺序与分隔符计算清单摘要。相同计划并发去重（唯一索引冲突则复用最新planned或取下一版本）。来源刷新绝不可能改变已固化清单。", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "created_by": { "type": "string" } }, "required": [ "name", "created_by" ] } } } }, "responses": { "201": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/release-change-sets/latest": { "get": { "tags": [ "Release" ], "operationId": "getLatestReleaseChangeSet", "summary": "最新发布计划集（含冻结逐项清单）", "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/release-change-sets/{id}": { "get": { "tags": [ "Release" ], "operationId": "getReleaseChangeSet", "summary": "按ID读取发布计划集与清单", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/release-change-sets/{id}/confirm": { "post": { "tags": [ "Release" ], "operationId": "confirmReleaseChangeSet", "summary": "冻结planned发布计划集供正式批次引用", "description": "planned转confirmed幂等重放；非法状态迁移返回409。确认后清单与摘要永不改变。", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmed_by": { "type": "string" } }, "required": [ "confirmed_by" ] } } } }, "responses": { "200": { "$ref": "#/components/responses/OperationEnvelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/release-executions/{id}/audit-chain": { "get": { "tags": [ "Release" ], "operationId": "getReleaseAuditChain", "summary": "发布审计链（R6 只读投影）", "description": "一次执行可追溯到批次、已确认发布计划集、绑定的来源快照与目录变更集、逐项审核/验收/来源身份，以及补偿回滚行。所有链路通过真实外键读取（迁移30），只返回安全标识、名称、计数与时间戳，绝不返回Bundle内部路径、凭据、Base URL或对象签名URL。", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "完整证据链", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-connections/{id}/settings/revisions": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "来源连接 ID" } ], "get": { "operationId": "listSourceSettingsRevisions", "summary": "来源设置修订历史（V1）", "description": "validated→active→retired 完整历史；仅安全投影：credential_ref 是凭据引用名，真实凭据不可回读。", "tags": [ "governance" ], "responses": { "200": { "description": "修订列表", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "revision_number": { "type": "integer" }, "state": { "enum": [ "validated", "active", "retired", "failed" ] }, "name": { "type": "string" }, "endpoint": { "type": "string" }, "credential_ref": { "type": "string", "description": "引用名，非密钥本身" }, "enabled": { "type": "boolean" }, "refresh_interval_seconds": { "type": "string" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "validated_at": { "type": [ "string", "null" ], "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "retired_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "operation": { "enum": [ "created", "replayed" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createSourceSettingsRevision", "summary": "创建来源设置草稿修订（V1）", "description": "校验通过落为 validated 修订，不影响运行态；需要 X-Governance-Action: source-settings 与 Idempotency-Key。", "tags": [ "governance" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "in": "header", "name": "X-Governance-Action", "required": true, "schema": { "type": "string", "enum": [ "source-settings" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_type", "name", "operator", "schedule" ], "additionalProperties": false, "properties": { "source_type": { "enum": [ "pp", "alist", "dingtalk", "manual" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "endpoint": { "type": "string", "maxLength": 2048 }, "credential_ref": { "type": "string", "maxLength": 255, "description": "密钥引用名；真实凭据永不入库、永不回显" }, "enabled": { "type": "boolean" }, "schedule": { "type": "object", "additionalProperties": false, "properties": { "refresh_interval_seconds": { "type": "integer", "nullable": true, "description": "缺省/0=仅手动；非零最低300秒" } } }, "operator": { "type": "string", "minLength": 1, "maxLength": 128 } } } } } }, "responses": { "201": { "description": "修订已创建", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "operation": { "enum": [ "created", "replayed" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/source-connections/{id}/settings/revisions/{revision_id}/activate": { "post": { "operationId": "activateSourceSettingsRevision", "summary": "激活来源设置修订（V1）", "description": "原子切换：退休旧 active、同步运行态快照、由服务端按周期推导下次刷新时间；停用立即清空到期时间（停止新扫描与新任务），历史全部保留。", "tags": [ "governance" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "revision_id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "in": "header", "name": "X-Governance-Action", "required": true, "schema": { "type": "string", "enum": [ "source-settings" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "maxProperties": 0 } } } }, "responses": { "200": { "description": "已激活", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "connection_id": { "type": "string" }, "revision_id": { "type": "string" } } }, "operation": { "enum": [ "created", "replayed" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "parameters": { "ID": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "每次用户动作使用一个新键；仅网络重试复用同一键。不得包含凭据或业务内容。", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "ConnectionID": { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64 } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "Offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } }, "State": { "name": "state", "in": "query", "schema": { "type": "string", "maxLength": 32 } } }, "responses": { "Envelope": { "description": "安全数据响应", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "OperationEnvelope": { "description": "可安全重试的目录操作响应；operation=created 表示首次执行，replayed 表示返回原操作结果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" } } } }, "BadRequest": { "description": "请求参数或状态非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "安全门禁或权限拒绝", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "资源已变更、状态冲突或重复动作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "安全的服务端错误码", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IdempotencyConflict": { "description": "资源已变更、状态冲突或重复动作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Health": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "const": "ok" } } }, "Envelope": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "description": "端点定义的安全投影" } } }, "OperationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "operation" ], "properties": { "data": { "description": "端点定义的安全投影" }, "operation": { "type": "string", "enum": [ "created", "replayed" ] } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "maxLength": 512 } } }, "JobCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "type", "idempotency_key" ], "properties": { "type": { "type": "string", "maxLength": 100 }, "payload": { "type": "object" }, "priority": { "type": "integer" }, "max_attempts": { "type": "integer", "minimum": 1, "maximum": 100 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "CatalogRouteRequest": { "type": "object", "additionalProperties": false, "required": [ "connection_id", "node_ids", "operator_ref", "reason" ], "properties": { "connection_id": { "type": "string", "maxLength": 64 }, "node_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, "policy": { "type": "string", "enum": [ "internal", "external", "both", "blocked" ] }, "visibility": { "type": "string", "enum": [ "internal", "external", "both", "blocked" ] }, "operator_ref": { "type": "string", "minLength": 1, "maxLength": 128 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "ScopeRuleMutation": { "type": "object", "additionalProperties": false, "required": [ "target_type", "operator_ref", "reason" ], "properties": { "target_type": { "type": "string", "enum": [ "directory", "item" ] }, "connection_id": { "type": "string", "maxLength": 64 }, "directory_path": { "type": "string", "maxLength": 4096 }, "source_item_id": { "type": "string", "maxLength": 64 }, "visibility": { "type": "string", "enum": [ "internal", "external", "both", "blocked" ] }, "operator_ref": { "type": "string", "minLength": 1, "maxLength": 128 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "ReviewDecisionRequest": { "type": "object", "additionalProperties": false, "required": [ "decision", "decided_visibility", "reviewer_ref", "decision_code" ], "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "decided_visibility": { "type": "string", "enum": [ "internal", "external" ] }, "reviewer_ref": { "type": "string", "minLength": 1, "maxLength": 128 }, "decision_code": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "ReleaseBatchCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "created_by" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "created_by": { "type": "string", "minLength": 1, "maxLength": 128 }, "publication_ids": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, "delete_publication_ids": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, "release_change_set_id": { "type": "string", "description": "R1正式批次绑定的confirmed发布计划集ID；绑定时所有请求项必须在该集冻结清单内且可发布，否则422" } } }, "ReleaseBatchSealRequest": { "type": "object", "additionalProperties": false, "required": [ "sealed_by" ], "properties": { "sealed_by": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "UISettingsCandidateRequest": { "type": "object", "additionalProperties": false, "required": [ "document_refresh_seconds", "resource_refresh_seconds", "stalled_after_seconds", "finalizing_after_seconds", "updated_by" ], "properties": { "document_refresh_seconds": { "type": "integer", "enum": [ 15, 30, 60 ] }, "resource_refresh_seconds": { "type": "integer", "enum": [ 30, 60 ] }, "stalled_after_seconds": { "type": "integer", "enum": [ 1800, 3600 ] }, "finalizing_after_seconds": { "type": "integer", "enum": [ 7200, 14400 ] }, "updated_by": { "type": "string", "minLength": 2, "maxLength": 128 } } }, "StartTestPublicationsRequest": { "type": "object", "additionalProperties": false, "required": [ "publication_ids", "operator_ref", "reason" ], "properties": { "publication_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, "operator_ref": { "type": "string", "minLength": 1, "maxLength": 128 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "ConfirmChangeSetRequest": { "type": "object", "additionalProperties": false, "required": [ "item_seqs", "operator_ref", "reason" ], "properties": { "item_seqs": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "integer", "minimum": 1 } }, "operator_ref": { "type": "string", "minLength": 1, "maxLength": 128 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "JobWindowMetrics": { "type": "object", "properties": { "window_seconds": { "type": "integer" }, "jobs_started": { "type": "integer" }, "jobs_completed": { "type": "integer" }, "jobs_failed": { "type": "integer" }, "success_rate": { "type": [ "number", "null" ] }, "failure_rate": { "type": [ "number", "null" ] }, "duration_avg_seconds": { "type": [ "number", "null" ] }, "duration_p50_seconds": { "type": [ "number", "null" ] }, "duration_p95_seconds": { "type": [ "number", "null" ] } } } } } }