姚章浩
e00cab2f70
用户对 系统设置 → 数据源配置 的四条要求： ① 这里不要做文件格式筛选（格式归目录级标注决定）； ② 列出我账号下能看到的知识库；③ 列出钉盘能看到哪些；④ 勾选那些作为来源。 ① 来源卡片不再渲染 FilenameFilterEditor（目录级筛选仍在「来源与目录」里，按目录就近覆盖）。 ②③ 新端点 GET /api/v1/dingtalk-spaces/available（管理员，只读）：用 dws 列举 - 知识库：wiki +space-list --type orgWikiSpace/myWikiSpace（实测 17 + 1 个） - 钉盘：wiki space list --type mySpace/orgSpace（实测 我的文件 + 6 个组织空间） 实测约束写进命令形态：--limit 上限是 50；翻页必须 --page-all（--max-items 兜底）， 否则超过一页的知识库会被静默截断（被截断时页面显示"可能不全"而不是假装列全）。 列不出来 ≠ 空列表：dws 未登录/权限不足 → 503 + 原因；某一类失败只丢那一类。 ④ 面板勾选后走既有登记路径（/api/v1/dingtalk-spaces），首次目录扫描自动排队； 已登记的按空间名标「已是来源」并禁用勾选；扫码会话失效时直接弹二维码，扫完自动重试。 基础设施：api 与 worker 共享同一份 dws 状态（bind mount 同一份，refresh token 是轮换制， 不能各留一份）。子进程 HOME 必须指向 DWS_HOME —— 这条是实测踩出来的：漏了会报"未登录"， 已有回归测试钉住。dws 子进程沿用白名单环境，库口令等变量不进子进程。 测试：新包 internal/dingtalkdiscovery（fixture 用真实 dws 输出形状）：paging 约束、 截断提示、一类失败不连带、全部失败→ErrUnavailable、子进程环境；httpapi 侧 401/501/503/500 与不泄漏内部错误；OpenAPI 契约（400/503 组件）通过。前端 189 条 + tsc 干净。 面板实测：知识库（18）/钉盘（7）都列出来，已有三条钉钉来源自动标「已是来源」； 勾选「视觉文档」→ 加入为来源 → 新来源 sc-8a4be5b8293d1c9a048c3c7e9b194155（dingtalk，enabled） + source.catalog.refresh 已完成。
3962 lines
86 KiB
YAML
3962 lines
86 KiB
YAML
{
|
||
"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/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}/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"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|