feat(library): 整库版本/作业持久化与状态读取契约,生产同步默认拒绝
build / build (push) Failing after 17s

- 新增 library_versions:测试封存、生产生效、生产预备份三类分开登记,
  生产生效版本唯一(旧版本必须先 supersede),测试快照不能顶替生产版本
- 新增 library_jobs + library_job_stages:业务作业身份、阶段、错误与恢复说明,
  分项计数用 NULL 表示"总量未知";互斥与幂等由数据库唯一索引保证
- 新增 GET /api/v1/library/overview、/jobs、/jobs/{id};POST /syncs 闸口未齐
  返回 503 缺项且不建作业
- 封存作业落库:先建业务作业再入队,worker 推进 export 阶段并登记 test_sealed
- 发布管理读真实状态:生产未知不再顶替、差异 unknown、启动同步按缺项禁用、
  同步明细/四类分项来自持久阶段;阶段勾选只认当前作业证据
- 准备信息标注封存时间与范围,不声称实时测试库已就绪
This commit is contained in:
姚章浩
2026-10-28 13:58:51 +08:00
parent 58d0483d44
commit dc9e827656
14 changed files with 1902 additions and 126 deletions
+167
View File
@@ -898,6 +898,173 @@
}
}
},
"/api/v1/library/overview": {
"get": {
"tags": [
"Runtime"
],
"operationId": "getLibraryOverview",
"summary": "整库状态:测试封存 / 生产生效 / 生产预备份三类版本分开返回,差异未接线时为 unknown,并给出启动同步的缺项",
"parameters": [
{
"name": "scope",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"internal",
"external"
]
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"description": "整库版本登记存储不可用"
}
}
}
},
"/api/v1/library/jobs": {
"get": {
"tags": [
"Runtime"
],
"operationId": "listLibraryJobs",
"summary": "列出该目标最近的整库作业(测试封存与生产同步分开,含阶段与结果;重启后仍可读)",
"parameters": [
{
"name": "scope",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"internal",
"external"
]
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/api/v1/library/jobs/{id}": {
"get": {
"tags": [
"Runtime"
],
"operationId": "getLibraryJob",
"summary": "读取单个整库作业的阶段、计数、错误与恢复说明",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"404": {
"description": "作业不存在"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/api/v1/library/syncs": {
"post": {
"tags": [
"Runtime"
],
"operationId": "startLibrarySync",
"summary": "启动生产同步:闸口、生产恢复演练证据、生产权威版本或本次预备份缺一即拒绝,且不创建作业",
"parameters": [
{
"name": "X-Governance-Action",
"in": "header",
"required": false,
"schema": {
"const": "library-sync"
}
}
],
"responses": {
"202": {
"description": "已创建同步作业(互斥与幂等由数据库唯一索引保证)"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"409": {
"description": "该目标已有在飞同步作业,或同一幂等键对应不同请求"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"description": "闸口或证据未齐,返回具体缺项且不创建作业"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"scope",
"target_snapshot_id"
],
"properties": {
"scope": {
"type": "string",
"enum": [
"internal",
"external"
]
},
"target_snapshot_id": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/v1/library/snapshots/{id}": {
"get": {
"tags": [