{
 "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": {
  "/api/v1/qa-ops/organization/sync": {
   "get": {"tags":["QA operations"],"operationId":"getQAOrganizationSync","summary":"管理员读取通讯录同步执行器状态及最近任务的安全汇总，不返回人员名单或运行配置","responses":{"200":{"$ref":"#/components/responses/Envelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"状态存储不可用，不伪装为空记录"}}},
   "post": {"tags":["QA operations"],"operationId":"startQAOrganizationSync","summary":"管理员同源发起持久化通讯录同步；重复请求重放同一任务，进行中任务合并；失败保留现有快照","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-organization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"202":{"$ref":"#/components/responses/OperationEnvelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员同源操作"},"409":{"description":"操作标识与原请求冲突"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"同步未接线、执行器离线或入队失败；未创建新任务"}}}
  },
  "/api/v1/qa-ops/organization": {
   "get": {
    "tags": ["QA operations"],
    "operationId": "getQAOrganization",
    "summary": "管理员读取服务器固定租户的完整部门路径、已保存区域归属与快照时间，不返回人员名单",
    "responses": {
     "200": {"$ref": "#/components/responses/Envelope"},
     "400": {"$ref": "#/components/responses/BadRequest"},
     "401": {"description": "需要登录"},
     "403": {"description": "仅管理员可访问"},
     "500": {"$ref": "#/components/responses/InternalError"},
     "503": {"description": "治理侧组织存储不可用"}
    }
   }
  },
  "/api/v1/qa-ops/organization/preview": {
   "post": {
    "tags": ["QA operations"],
    "operationId": "previewQAOrganizationRegions",
    "summary": "预览当前通讯录版本下的父子部门区域归属和去重人数，不保存修改",
    "parameters": [{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-organization"}}],
    "requestBody": {"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["directory_id","base_revision","rules"],"properties":{"directory_id":{"type":"string"},"base_revision":{"type":"string"},"rules":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["department_id","region"],"properties":{"department_id":{"type":"string"},"region":{"enum":["国内工业","APAC","EMEA","America"]}}}}}}}}},
    "responses": {
     "200": {"$ref": "#/components/responses/Envelope"},
     "400": {"$ref": "#/components/responses/BadRequest"},
     "401": {"description": "需要登录"},
     "403": {"description": "仅管理员同源操作可访问"},
     "409": {"description": "通讯录或配置版本已变化，需重新读取"},
     "500": {"$ref": "#/components/responses/InternalError"},
     "503": {"description": "治理侧组织存储不可用"}
    }
   }
  },
  "/api/v1/qa-ops/organization/regions": {
   "put": {
    "tags": ["QA operations"],
    "operationId": "saveQAOrganizationRegions",
    "summary": "保存版本化区域配置；操作人取管理员会话，不改变钉钉或DobotAI数据",
    "parameters": [{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-organization"}}],
    "requestBody": {"$ref":"#/paths/~1api~1v1~1qa-ops~1organization~1preview/post/requestBody"},
    "responses": {
     "200": {"$ref": "#/components/responses/Envelope"},
     "400": {"$ref": "#/components/responses/BadRequest"},
     "401": {"description": "需要登录"},
     "403": {"description": "仅管理员同源操作可访问"},
     "409": {"description": "版本冲突或尚无完整通讯录"},
     "500": {"$ref": "#/components/responses/InternalError"},
     "503": {"description": "治理侧组织存储不可用"}
    }
   }
  },
  "/api/v1/qa-ops/usage/people": {"post": {"tags": ["QA operations"], "operationId": "queryQAOperationsMonthlyPeople", "summary": "按北京时间自然月列出当前名册人员的2.0用量（含零记录），仅管理员，不返回原始员工标识，不作为在职/考核名单", "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用，不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "完整名册缺失或目录/区域版本变化，请同步/重新查询，不返回伪零"}}, "description": "只读查询，不写治理库或生产库；姓名筛选置于 JSON 请求体，不进入 URL；整名册指标不随人员筛选变化。第2页起须带首页目录、区域版本及 end 截止。", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["month"], "properties": {"month": {"type": "string", "pattern": "^(?!0000)[0-9]{4}-(0[1-9]|1[0-2])$"}, "cutoff": {"type": "string", "format": "date-time"}, "region": {"type": "string", "enum": ["国内工业", "APAC", "EMEA", "America", "unassigned", "cross_region"]}, "department_id": {"type": "string"}, "activity": {"type": "string", "enum": ["all", "used", "zero"]}, "search": {"type": "string", "maxLength": 100}, "page": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 1}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}, "directory_id": {"type": "string"}, "revision_id": {"type": "string"}}}}}}, "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-usage-read"]}}]}},
  "/api/v1/qa-ops/usage": {"get": {"tags": ["QA operations"], "operationId": "getQAOperationsUsage", "summary": "完整筛选范围内按当前通讯录和区域版本回看2.0问答使用；固定租户、管理员访问，不输出绩效结论", "parameters": [{"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "keyword", "in": "query", "schema": {"type": "string", "maxLength": 200}}], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用，不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}}}},
  "/api/v1/qa-ops/quality/query": {"post": {"operationId": "queryQAQualityCounts", "summary": "按完整筛选范围读取指纹/规则元数据并留档统计，最多5000条；summary.rates 返回 quality-rates-human-first-v1、原始分子/分母、百分比与分母构成。覆盖率=covered/(covered+uncovered+partial)，正确率=covered_correct/(covered_correct+covered_incorrect)；失效/不计入/相应待确认与未评估排除，零分母percent=null。原文仅在读取问答/复核时采集", "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"start": {"type": "string", "format": "date-time"}, "end": {"type": "string", "format": "date-time"}, "keyword": {"type": "string", "maxLength": 200}}, "required": ["start", "end"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用，不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致，未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
  "/api/v1/qa-ops/records/{id}/reviews": {"post": {"operationId": "saveQAQualityReview", "summary": "治理库追加人工复核，登录身份审计，源端只读，输入/复核乐观锁和nonce幂等；正确时根因为空，不计入须说明原因", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"input_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "input_epoch": {"type": "integer", "minimum": 1}, "base_revision": {"type": "integer", "minimum": 0}, "nonce": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}, "fields": {"type": "object", "additionalProperties": false, "properties": {"coverage": {"type": "string", "enum": ["covered", "uncovered", "partial", "pending", "excluded"]}, "correctness": {"type": "string", "enum": ["correct", "incorrect", "pending"]}, "product_category": {"type": "string", "maxLength": 128}, "problem_type": {"type": "string", "maxLength": 128}, "root_cause": {"type": "string", "maxLength": 2000}, "exclusion_reason": {"type": "string", "maxLength": 2000}}, "required": ["coverage", "correctness"]}, "reason": {"type": "string", "minLength": 1, "maxLength": 4000}}, "required": ["input_hash", "input_epoch", "base_revision", "nonce", "fields", "reason"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用，不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致，未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
  "/api/v1/qa-ops/records/{id}/quality/history": {"get": {"operationId": "listQAQualityHistory", "summary": "按当前固定租户查询不可变复检/人工历史，分别倒序分页，各20条", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "review_before", "in": "query", "schema": {"type": "integer", "minimum": 1}}, {"name": "check_before", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用，不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致，未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
  "/api/v1/qa-ops/records/{id}/quality/inputs/{epoch}": {"get": {"operationId": "getQAQualityInputSnapshot", "summary": "管理员读取已采集的历史质量输入快照，不另存人员关联/反馈字段；元数据留档但未采集原文返回409，不编造空快照", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "epoch", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1}}], "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用，不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "该输入版本仅有指纹/规则元数据、原文未采集"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
  "/api/v1/qa-ops/status": {
   "get": {
    "tags": ["QA operations"],
    "operationId": "getQAOperationsStatus",
    "summary": "读取独立问答只读数据源状态与安全告警，不返回连接信息；需要管理员会话",
    "responses": {
     "200": {"$ref": "#/components/responses/Envelope"},
     "400": {"$ref": "#/components/responses/BadRequest"},
     "401": {"description": "需要登录"},
     "403": {"description": "未获员工问答查看授权"},
     "500": {"$ref": "#/components/responses/InternalError"}
    }
   }
  },
  "/api/v1/qa-ops/records": {
   "get": {
    "tags": ["QA operations"],
    "operationId": "listQAOperationsRecords",
    "summary": "按半开提问时间范围、原问题关键词、稳定游标列出钉钉问答；租户由后端固定；答案包含暂无已发布则治理侧未覆盖",
    "parameters": [
     {"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}},
     {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}},
     {"name": "keyword", "in": "query", "schema": {"type": "string", "maxLength": 200}},
     {"name": "cursor", "in": "query", "schema": {"type": "string", "maxLength": 2048}},
     {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}
    ],
    "responses": {
     "200": {"$ref": "#/components/responses/Envelope"},
     "400": {"$ref": "#/components/responses/BadRequest"},
     "401": {"description": "需要登录"},
     "403": {"description": "未获员工问答查看授权"},
     "503": {"description": "源库未接入、不可用或权限护栏阻断，不返回空列表伪装成功"},
     "500": {"$ref": "#/components/responses/InternalError"}
    }
   }
  },
  "/api/v1/qa-ops/records/{id}": {
   "get": {
    "tags": ["QA operations"],
    "operationId": "getQAOperationsRecord",
    "summary": "读取授权租户内的完整问答与源端覆盖对照；治理覆盖规则独立，不写回源库",
    "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 256}}],
    "responses": {
     "200": {"$ref": "#/components/responses/Envelope"},
     "400": {"$ref": "#/components/responses/BadRequest"},
     "401": {"description": "需要登录"},
     "403": {"description": "未获员工问答查看授权"},
     "404": {"description": "当前授权范围内不存在此问答"},
     "503": {"description": "独立只读源不可用或权限校验阻断"},
     "500": {"$ref": "#/components/responses/InternalError"}
    }
   }
  },
  "/api/v1/build-info": {
   "get": {
    "tags": [
     "Runtime"
    ],
    "operationId": "getBuildInfo",
    "summary": "读取当前运行产物的构建身份（正式版本/构建类型/完整提交 SHA）；拿不到注入就明确返回不可用",
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     }
    }
   }
  },
  "/api/v1/version-history": {
   "get": {
    "tags": [
     "Runtime"
    ],
    "operationId": "listVersionHistory",
    "summary": "按快照游标分页列出远端 main 可达的提交、版本号证据与「当前运行」判据",
    "parameters": [
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "all",
        "release",
        "development",
        "historical"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "409": {
      "description": "游标指向的记录快照已被清理，需要刷新后重新加载"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     }
    }
   }
  },
  "/api/v1/version-history/sync": {
   "post": {
    "tags": [
     "Runtime"
    ],
    "operationId": "syncVersionHistory",
    "summary": "手动同步一次版本记录（仅管理员；并发同步复用同一个作业）",
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "202": {
      "description": "已入队同步任务"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     }
    }
   }
  },
  "/api/v1/backup-schedule": {
   "get": {
    "tags": [
     "Settings"
    ],
    "operationId": "getBackupSchedule",
    "summary": "读取整库逻辑备份的定时计划（不探测主机）",
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     },
     "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     }
    }
   },
   "put": {
    "tags": [
     "Settings"
    ],
    "operationId": "saveBackupSchedule",
    "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"
     },
     "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
     }
    }
   }
  },
  "/api/v1/backup-schedule/host": {
   "get": {
    "tags": [
     "Settings"
    ],
    "operationId": "getBackupScheduleHost",
    "summary": "读取目标主机上生效的 cron 计划与最近一次备份结果",
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     },
     "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     }
    }
   }
  },
  "/api/v1/backup-schedule/apply": {
   "post": {
    "tags": [
     "Settings"
    ],
    "operationId": "applyBackupSchedule",
    "summary": "把当前设置重新下发到目标主机（管理员）",
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     },
     "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
     }
    }
   }
  },
  "/api/v1/backup-schedule/run": {
   "post": {
    "tags": [
     "Settings"
    ],
    "operationId": "runBackupNow",
    "summary": "在目标主机上立即执行一次整库备份（管理员，异步）",
    "responses": {
     "202": {
      "$ref": "#/components/responses/Envelope"
     },
     "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     }
    }
   }
  },
  "/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}/archive": {
   "parameters": [
    {
     "$ref": "#/components/parameters/ID"
    }
   ],
   "post": {
    "operationId": "archiveSourceConnection",
    "summary": "归档下架来源（去掉入口；不物理删除）",
    "description": "把来源从数据源配置、来源与目录、计划刷新与手动扫描里摘掉：目录快照、发布记录与审计数据原样保留；恢复只需再次登记同一来源（钉钉空间登记是确定性 ID，原地复活同一行）。幂等：重复归档不改归档时间与归档人。仅管理员可写。",
    "tags": [
     "governance"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "in": "header",
      "name": "X-Governance-Action",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "source-archive"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     },
     "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
     }
    }
   }
  },
  "/api/v1/source-connections/{id}/restore": {
   "parameters": [
    {
     "$ref": "#/components/parameters/ID"
    }
   ],
   "post": {
    "operationId": "restoreSourceConnection",
    "summary": "撤销来源归档（保持停用，调度不自动恢复）",
    "description": "归档的反向操作：来源重新出现在列表里，但保持停用且不带调度，需要管理员再显式启用。幂等：未归档时视为成功；连接不存在返回 404。仅管理员可写。",
    "tags": [
     "governance"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "in": "header",
      "name": "X-Governance-Action",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "source-restore"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     },
     "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
     }
    }
   }
  },
  "/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"
     },
     {
      "in": "query",
      "name": "removal",
      "description": "removal=required 只返回「被禁止导入但仍存活在测试库」的条目（解析监控 → 需下架 车道使用）。",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "required"
       ]
      }
     },
     {
      "$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"
     }
    }
   }
  },
  "/api/v1/test-publications/{id}/removal": {
   "parameters": [
    {
     "$ref": "#/components/parameters/ID"
    }
   ],
   "post": {
    "tags": [
     "Test processing"
    ],
    "operationId": "startTestPublicationRemoval",
    "summary": "把被禁止导入但仍存活在测试库的知识置为下架（入队既有 test.remove 工作流）",
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "202": {
      "$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/review-candidates/batch-decision": {
   "post": {
    "tags": [
     "Release"
    ],
    "operationId": "batchReviewCandidates",
    "summary": "一次对多条审核候选做同一个决定（批量批准/驳回，逐条复用单条写入路径）",
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "409": {
      "$ref": "#/components/responses/Conflict"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     }
    }
   }
  },
  "/api/v1/release-batches/publish-now": {
   "post": {
    "tags": [
     "Release"
    ],
    "operationId": "publishNowPublications",
    "summary": "一个动作完成「建批（冻结+锁定）→ 授权生产发布」（沿用门禁、固定语句与管理员身份）",
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "202": {
      "$ref": "#/components/responses/OperationEnvelope"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "409": {
      "$ref": "#/components/responses/Conflict"
     },
     "412": {
      "$ref": "#/components/responses/PreconditionFailed"
     },
     "422": {
      "$ref": "#/components/responses/Unprocessable"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     }
    }
   }
  },
  "/api/v1/dingtalk-spaces/available": {
   "get": {
    "tags": [
     "Source connections"
    ],
    "operationId": "listAvailableDingtalkSources",
    "summary": "列举当前钉钉账号可见的知识库与钉盘空间（管理员，只读）",
    "description": "用平台持有的钉钉凭据（dws）只读列举租户目录：知识库与钉盘空间。钉盘列举在某些租户下会被拒，这时返回 drive_notice；接口整体不可用时返回 503，不会伪装成空列表。",
    "responses": {
     "200": {
      "$ref": "#/components/responses/Envelope"
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "500": {
      "$ref": "#/components/responses/InternalError"
     },
     "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
     }
    }
   }
  }
 },
 "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"
      }
     }
    }
   },
   "Unauthorized": {
    "description": "需要生产发布授权（管理员会话或运维通道）",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "PreconditionFailed": {
    "description": "生产门禁未满足（例如备份恢复验证未通过）",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "Unprocessable": {
    "description": "请求内容不满足发布条件",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "ServiceUnavailable": {
    "description": "依赖的第三方或本地工具当前不可用（例如 dws 未登录/权限不足）。",
    "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"
      ]
     }
    }
   }
  }
 }
}