From dc9e8276560d2db57d048dbd62e1d7a95fb3023a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Wed, 28 Oct 2026 13:58:51 +0800 Subject: [PATCH] =?UTF-8?q?feat(library):=20=E6=95=B4=E5=BA=93=E7=89=88?= =?UTF-8?q?=E6=9C=AC/=E4=BD=9C=E4=B8=9A=E6=8C=81=E4=B9=85=E5=8C=96?= =?UTF-8?q?=E4=B8=8E=E7=8A=B6=E6=80=81=E8=AF=BB=E5=8F=96=E5=A5=91=E7=BA=A6?= =?UTF-8?q?=EF=BC=8C=E7=94=9F=E4=BA=A7=E5=90=8C=E6=AD=A5=E9=BB=98=E8=AE=A4?= =?UTF-8?q?=E6=8B=92=E7=BB=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 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、启动同步按缺项禁用、 同步明细/四类分项来自持久阶段;阶段勾选只认当前作业证据 - 准备信息标注封存时间与范围,不声称实时测试库已就绪 --- CHANGELOG.md | 15 + api/openapi.yaml | 167 ++++++ cmd/worker/main.go | 64 +++ internal/governance/library_flow.go | 117 ++++ internal/httpapi/library_capture.go | 51 ++ internal/httpapi/library_flow.go | 337 ++++++++++++ internal/httpapi/library_flow_test.go | 230 ++++++++ internal/httpapi/server.go | 14 + internal/platform/postgres/library_jobs.go | 276 ++++++++++ .../migrations/000066_library_flow.down.sql | 3 + .../migrations/000066_library_flow.up.sql | 57 ++ web/src/ReleaseTargets.test.tsx | 105 +++- web/src/ReleaseTargets.tsx | 504 ++++++++++++++---- web/src/librarySnapshots.ts | 88 ++- 14 files changed, 1902 insertions(+), 126 deletions(-) create mode 100644 internal/governance/library_flow.go create mode 100644 internal/httpapi/library_flow.go create mode 100644 internal/httpapi/library_flow_test.go create mode 100644 internal/platform/postgres/library_jobs.go create mode 100644 internal/platform/postgres/migrations/000066_library_flow.down.sql create mode 100644 internal/platform/postgres/migrations/000066_library_flow.up.sql diff --git a/CHANGELOG.md b/CHANGELOG.md index d1f758e..0b94860 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## 开发快照 snapshot/v0.1.114 - 2026-10-28 + +### Added + +- 整库版本与持久作业:新增 `library_versions`(test_sealed / production_effective / production_prebackup 三类分开登记,生产生效版本唯一)、`library_jobs`(业务作业身份、阶段、错误与恢复说明)与 `library_job_stages`(分项计数,NULL 表示总量未知)。互斥与幂等由数据库唯一索引保证,不依赖前端禁用或单 worker。 +- 读接口:`GET /api/v1/library/overview`(三类版本 + 差异 + 作业 + 启动缺项)、`GET /api/v1/library/jobs`、`GET /api/v1/library/jobs/{id}`。 +- 写接口:`POST /api/v1/library/syncs`,闸口、生产恢复演练证据、生产权威版本、本次预备份缺一即 503 并逐条给出原因,且**不创建**作业。 +- 封存作业落库:发起封存先建业务作业(同一目标只能一个在飞),worker 推进 export 阶段、成功登记 test_sealed 版本、失败同时记录阶段与作业状态。 +- 发布管理改为读取真实状态:生产当前来自生产生效版本(没有就显示未知)、目标来自测试封存、差异未接线保持 unknown、启动同步按缺项禁用、同步明细与四类分项来自持久阶段。 + +### Fixed + +- 没有当前作业时不再把历史测试封存当作「固定测试版本」已完成:阶段勾选只来自当前作业的阶段证据,并提示「已有测试封存(历史)/ 本次作业尚未开始」。 +- 准备信息注明依据哪次封存快照与范围,明确「不代表实时测试库已就绪」,没有放宽任何完整性检查。 + ## 开发快照 snapshot/v0.1.113 - 2026-10-28 ### Changed diff --git a/api/openapi.yaml b/api/openapi.yaml index 1739157..1aa291e 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -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": [ diff --git a/cmd/worker/main.go b/cmd/worker/main.go index bb7e53d..4b7272e 100644 --- a/cmd/worker/main.go +++ b/cmd/worker/main.go @@ -3,11 +3,13 @@ package main import ( "context" "encoding/json" + "errors" "fmt" "log" "os" "os/signal" "path/filepath" + "strings" "syscall" "time" @@ -29,6 +31,9 @@ import ( // libraryCaptureJobType is shared with the API which enqueues it. const libraryCaptureJobType = "library.capture" +// librarySyncJobType 是生产同步作业的队列类型;与封存严格分开,状态不共用。 +const librarySyncJobType = "library.sync" + func main() { ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM) defer stop() @@ -144,15 +149,74 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st if err := json.Unmarshal(job.Payload, &payload); err != nil || (payload.Scope != "internal" && payload.Scope != "external") || payload.CaptureJob == "" { return fmt.Errorf("invalid library capture payload") } + // 持久作业:页面读的是这里写的阶段与结果,worker 重启后仍能如实展示。 + libraryJobID := "libseal-" + payload.CaptureJob + startedAt := time.Now().UTC() + if advanceErr := store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobRunning, "export", "", "", "", "", startedAt); advanceErr != nil { + log.Printf("library seal job %s cannot be advanced: %v", libraryJobID, advanceErr) + } + if stageErr := store.UpdateLibraryStage(ctx, libraryJobID, "export", "running", nil, nil, nil, nil, + "主机侧正在暂停写入者、导出并恢复", startedAt); stageErr != nil { + log.Printf("library seal job %s stage update failed: %v", libraryJobID, stageErr) + } result, err := libraryagent.Capture(ctx, agentConfig, payload.Scope, payload.CaptureJob) + finishedAt := time.Now().UTC() if err != nil { + // 导出失败时阶段与作业都要留痕;恢复责任在 agent,不会因为作业失败而假装来源已恢复。 + _ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, err.Error(), finishedAt) + _ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", err.Error(), + "agent 已执行恢复检查;确认来源 healthy 后可重试同一作业号", "", "", finishedAt) log.Printf("library capture failed scope=%s capture_job=%s: %v", payload.Scope, payload.CaptureJob, err) return err } + // 封存产物成版本记录:只登记"测试封存",绝不写成生产生效版本。 + versionErr := store.RecordLibraryVersion(ctx, governance.LibraryVersion{ + ID: "libver-" + payload.Scope + "-" + result.SnapshotID, Scope: payload.Scope, + Kind: governance.LibraryVersionTestSealed, SnapshotID: result.SnapshotID, SourceJobID: libraryJobID, + Evidence: map[string]any{"capture_job": payload.CaptureJob, "replay": result.Replay, + "requested_by": payload.RequestedBy, "agent_result": json.RawMessage(result.Payload)}, + CreatedBy: payload.RequestedBy, CreatedAt: finishedAt, + }) + if versionErr != nil { + log.Printf("library seal job %s cannot record version: %v", libraryJobID, versionErr) + } + _ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "succeeded", nil, nil, nil, nil, + "已封存快照 "+result.SnapshotID, finishedAt) + _ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobSucceeded, "export", "", "", + result.SnapshotID, "", finishedAt) log.Printf("library capture completed scope=%s capture_job=%s snapshot=%s replay=%v requested_by=%s", payload.Scope, payload.CaptureJob, result.SnapshotID, result.Replay, payload.RequestedBy) return nil } + // 生产同步:唯一入口在 API(闸口未齐不建作业)。这里仍实现执行器, + // 但默认 fail-closed:没有闸口证据就明确失败,绝不向生产写入半个字节。 + handlers[librarySyncJobType] = func(ctx context.Context, job jobs.Job) error { + var payload struct { + LibraryJobID string `json:"library_job_id"` + Scope string `json:"scope"` + TargetSnapshotID string `json:"target_snapshot_id"` + } + if err := json.Unmarshal(job.Payload, &payload); err != nil || payload.LibraryJobID == "" { + return fmt.Errorf("invalid library sync payload") + } + now := time.Now().UTC() + reasons := make([]string, 0, 3) + if !config.ProductionReleaseRequestsEnabled { + reasons = append(reasons, "生产写入闸口关闭") + } + if !config.ProductionBackupRestoreVerified { + reasons = append(reasons, "没有已核验的生产恢复演练证据") + } + // 生产写入适配与预备份实现之前,执行链本身就是缺项:直接拒绝而不是空转。 + reasons = append(reasons, "生产预备份与写入适配尚未实现") + message := "生产同步执行链未接通:" + strings.Join(reasons, ";") + _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobRunning, "prebackup", "", "", "", "", now) + _ = store.UpdateLibraryStage(ctx, payload.LibraryJobID, "prebackup", "failed", nil, nil, nil, nil, message, now) + _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", message, + "未对生产执行任何写入,无需恢复", "", "", now) + log.Printf("library sync refused job=%s scope=%s: %s", payload.LibraryJobID, payload.Scope, message) + return errors.New(message) + } // A crash can leave the source writer stopped: recover before taking work, // and keep the failure visible instead of pretending the worker is ready. go func() { diff --git a/internal/governance/library_flow.go b/internal/governance/library_flow.go new file mode 100644 index 0000000..7870c0d --- /dev/null +++ b/internal/governance/library_flow.go @@ -0,0 +1,117 @@ +package governance + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "time" +) + +// 整库版本与作业的领域类型:与队列(jobs)分开——队列负责租约与重试, +// 这里负责业务身份、阶段与结果,重启后仍能如实展示。 + +type LibraryVersionKind string + +const ( + // LibraryVersionTestSealed 是测试库封存产物:只证明一份完整测试版本被封存, + // 不代表生产生效,也不代表做过生产恢复演练。 + LibraryVersionTestSealed LibraryVersionKind = "test_sealed" + // LibraryVersionProductionEffective 是生产当前权威版本:只有生产验证通过并 + // 记录证据后才能写入,测试快照不能顶替它。 + LibraryVersionProductionEffective LibraryVersionKind = "production_effective" + // LibraryVersionProductionPrebackup 是每次生产写入前的独立预备份。 + LibraryVersionProductionPrebackup LibraryVersionKind = "production_prebackup" +) + +type LibraryJobKind string + +const ( + LibraryJobSeal LibraryJobKind = "seal" + LibraryJobSync LibraryJobKind = "sync" +) + +type LibraryJobState string + +const ( + LibraryJobPending LibraryJobState = "pending" + LibraryJobRunning LibraryJobState = "running" + LibraryJobSucceeded LibraryJobState = "succeeded" + LibraryJobFailed LibraryJobState = "failed" + LibraryJobCancelled LibraryJobState = "cancelled" +) + +// ErrLibraryJobActive:同一目标同一类作业已有在飞作业(数据库级互斥)。 +var ErrLibraryJobActive = errors.New("library job already active for this target") + +// ErrLibraryJobIdempotencyConflict:同一幂等键对应了不同的请求体。 +var ErrLibraryJobIdempotencyConflict = errors.New("library job idempotency key reused with a different request") + +type LibraryStage struct { + Stage string `json:"stage"` + State string `json:"state"` + // Total/Completed/BytesTotal/BytesDone 为 nil 表示该维度没有可靠数据, + // 界面必须显示"未知",不得当 0 或据此算百分比。 + Total *int64 `json:"total"` + Completed *int64 `json:"completed"` + BytesTotal *int64 `json:"bytes_total"` + BytesDone *int64 `json:"bytes_done"` + Detail string `json:"detail"` + UpdatedAt time.Time `json:"updated_at"` +} + +type LibraryJob struct { + ID string `json:"id"` + Scope string `json:"scope"` + Kind LibraryJobKind `json:"kind"` + State LibraryJobState `json:"state"` + Stage string `json:"stage"` + IdempotencyKey string `json:"-"` + RequestDigest string `json:"request_digest"` + QueueJobID string `json:"queue_job_id"` + SnapshotID string `json:"snapshot_id"` + TargetSnapshotID string `json:"target_snapshot_id"` + Actor string `json:"actor"` + Error string `json:"error"` + Recovery string `json:"recovery"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` + FinishedAt *time.Time `json:"finished_at"` + Stages []LibraryStage `json:"stages"` +} + +type LibraryVersion struct { + ID string `json:"id"` + Scope string `json:"scope"` + Kind LibraryVersionKind `json:"kind"` + SnapshotID string `json:"snapshot_id"` + VersionLabel string `json:"version_label"` + SourceJobID string `json:"source_job_id"` + Evidence map[string]any `json:"evidence"` + CreatedBy string `json:"created_by"` + CreatedAt time.Time `json:"created_at"` + SupersededAt *time.Time `json:"superseded_at"` +} + +// LibraryRequestDigest 绑定一次请求的确切含义:同键不同体必须被拒绝,而不是 +// 复用旧作业。只覆盖会影响执行结果的字段;actor 不参与摘要。 +func LibraryRequestDigest(scope string, kind LibraryJobKind, payload map[string]any) (string, error) { + canonical := map[string]any{"scope": scope, "kind": string(kind), "payload": payload} + raw, err := json.Marshal(canonical) + if err != nil { + return "", err + } + sum := sha256.Sum256(raw) + return hex.EncodeToString(sum[:]), nil +} + +// SyncStages 是生产同步作业的固定阶段顺序:先备份并核验恢复条件,再写生产, +// 最后验证;失败时走恢复而不是把作业标成功。 +func SyncStages() []string { + return []string{"prebackup", "database", "resources", "index", "wiki", "verify", "rollback"} +} + +// SealStages 是封存作业的阶段:导出是原子操作,没有分项进度。 +func SealStages() []string { + return []string{"export"} +} diff --git a/internal/httpapi/library_capture.go b/internal/httpapi/library_capture.go index 2cac99c..08e7217 100644 --- a/internal/httpapi/library_capture.go +++ b/internal/httpapi/library_capture.go @@ -3,12 +3,14 @@ package httpapi import ( "context" "encoding/json" + "errors" "fmt" "net/http" "regexp" "strings" "time" + "knowledge-governance/internal/governance" "knowledge-governance/internal/jobs" ) @@ -62,6 +64,39 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config return } now := time.Now().UTC() + // 业务作业先建:互斥由 library_jobs 的唯一索引保证,这样不会出现"队列里排着两个封存"。 + // 队列投递失败或请求冲突时把业务作业取消,不留下永远 pending 的占位。 + libraryJobID := "libseal-" + captureJob + createdSealJob := false + if store, ok := libraryStore(config); ok { + digest, digestErr := governance.LibraryRequestDigest(request.Scope, governance.LibraryJobSeal, + map[string]any{"capture_job": captureJob}) + if digestErr == nil { + sealJob, reusedSeal, sealErr := store.CreateLibraryJob(r.Context(), governance.LibraryJob{ + ID: libraryJobID, Scope: request.Scope, Kind: governance.LibraryJobSeal, + IdempotencyKey: "library.seal:" + captureJob, RequestDigest: digest, Actor: requestedBy, + }, governance.SealStages(), now) + switch { + case errors.Is(sealErr, governance.ErrLibraryJobActive): + writeJSON(w, http.StatusConflict, map[string]any{ + "code": "library_seal_active", "error": "该目标已有在飞的封存作业,等它结束再发起", + }) + return + case errors.Is(sealErr, governance.ErrLibraryJobIdempotencyConflict): + writeJSON(w, http.StatusConflict, map[string]any{ + "code": "library_seal_scope_conflict", "error": "同一作业号已按另一个范围封存", + }) + return + case sealErr != nil: + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot create seal job"}) + return + case !reusedSeal: + createdSealJob = true + default: + libraryJobID = sealJob.ID + } + } + } requestedID := fmt.Sprintf("library-capture-%s-%d", request.Scope, now.UnixNano()) // The idempotency key is the capture job id: the same logical capture must map // to one queue row. Binding the scope into the key would silently create a @@ -76,9 +111,18 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config IdempotencyKey: "library.capture:" + captureJob, }, now) if err != nil || job == nil { + if store, ok := libraryStore(config); ok && createdSealJob { + _ = store.CancelLibraryJob(r.Context(), libraryJobID, "队列投递失败,未开始封存", now) + } writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot enqueue capture job"}) return } + if store, ok := libraryStore(config); ok { + if attachErr := store.AttachLibraryQueueJob(r.Context(), libraryJobID, job.ID, now); attachErr != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot attach capture job"}) + return + } + } // Enqueue returns the existing row for a reused key. Answer from that row, not // from the current request: a reused job id with another scope must be refused // instead of being reported as a job for the new scope. @@ -87,7 +131,13 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config CaptureJob string `json:"capture_job"` RequestedBy string `json:"requested_by"` } + cancelSeal := func(reason string) { + if store, ok := libraryStore(config); ok && createdSealJob { + _ = store.CancelLibraryJob(r.Context(), libraryJobID, reason, now) + } + } if err = json.Unmarshal(job.Payload, &stored); err != nil || stored.CaptureJob != captureJob { + cancelSeal("请求冲突,未开始封存") writeJSON(w, http.StatusConflict, map[string]any{ "code": "library_capture_conflict", "error": "该作业号已被另一个封存请求占用", "existing_scope": stored.Scope, "requested_scope": request.Scope, @@ -95,6 +145,7 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config return } if stored.Scope != request.Scope { + cancelSeal("同一作业号已按另一个范围投递") writeJSON(w, http.StatusConflict, map[string]any{ "code": "library_capture_scope_conflict", "error": "同一作业号已按另一个范围投递", "existing_scope": stored.Scope, "requested_scope": request.Scope, diff --git a/internal/httpapi/library_flow.go b/internal/httpapi/library_flow.go new file mode 100644 index 0000000..07e1810 --- /dev/null +++ b/internal/httpapi/library_flow.go @@ -0,0 +1,337 @@ +package httpapi + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net/http" + "strings" + "time" + + "knowledge-governance/internal/governance" +) + +// 整库版本/状态/差异读取契约 + 生产同步的 fail-closed 入口。 +// +// 三类版本严格分开,不能互相顶替: +// - 测试封存(archive 里的 sealed 产物)——只证明测试库有一份完整版本; +// - 生产当前生效(library_versions.kind=production_effective)——必须有生产验证证据; +// - 生产预备份(kind=production_prebackup)——每次生产写入前的独立备份。 +// 生产未建立权威版本时返回 unknown,不拿最新测试快照冒充。 + +type libraryVersionView struct { + ID string `json:"id"` + Kind string `json:"kind"` + SnapshotID string `json:"snapshot_id"` + VersionLabel string `json:"version_label"` + SourceJobID string `json:"source_job_id"` + Evidence map[string]any `json:"evidence"` + CreatedBy string `json:"created_by"` + CreatedAt time.Time `json:"created_at"` + SupersededAt *time.Time `json:"superseded_at,omitempty"` +} + +type libraryKnownView struct { + State string `json:"state"` // known | unknown + Version *libraryVersionView `json:"version,omitempty"` + Reason string `json:"reason,omitempty"` +} + +type libraryDiffView struct { + State string `json:"state"` // unknown | computed + Reason string `json:"reason,omitempty"` + Added []any `json:"added"` + Updated []any `json:"updated"` + Removed []any `json:"removed"` +} + +type libraryGateView struct { + SyncAllowed bool `json:"sync_allowed"` + Reasons []string `json:"reasons"` +} + +type libraryOverview struct { + Scope string `json:"scope"` + TestSealed *librarySnapshotView `json:"test_sealed,omitempty"` + TestSealedReason string `json:"test_sealed_reason,omitempty"` + Production libraryKnownView `json:"production"` + Prebackup libraryKnownView `json:"prebackup"` + Diff libraryDiffView `json:"diff"` + Job *governance.LibraryJob `json:"job,omitempty"` + Jobs []governance.LibraryJob `json:"jobs"` + Gate libraryGateView `json:"gate"` + CaptureAvailable bool `json:"capture_available"` + CaptureReason string `json:"capture_reason,omitempty"` + Now time.Time `json:"now"` +} + +type libraryJobStore interface { + CreateLibraryJob(ctx context.Context, job governance.LibraryJob, stages []string, now time.Time) (governance.LibraryJob, bool, error) + LibraryJob(ctx context.Context, id string) (governance.LibraryJob, error) + ListLibraryJobs(ctx context.Context, scope string, limit int) ([]governance.LibraryJob, error) + RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error + LibraryVersions(ctx context.Context, scope string, limit int) ([]governance.LibraryVersion, error) + UpdateLibraryStage(ctx context.Context, jobID, stage, state string, total, completed, bytesTotal, bytesDone *int64, detail string, now time.Time) error + AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error + AttachLibraryQueueJob(ctx context.Context, jobID, queueJobID string, now time.Time) error + CancelLibraryJob(ctx context.Context, jobID, reason string, now time.Time) error +} + +func libraryStore(config Config) (libraryJobStore, bool) { + store, ok := config.Store.(libraryJobStore) + return store, ok +} + +func scopeFromQuery(r *http.Request) (string, error) { + scope := strings.TrimSpace(r.URL.Query().Get("scope")) + if scope == "" { + scope = "internal" + } + if scope != "internal" && scope != "external" { + return "", errors.New("scope must be internal or external") + } + return scope, nil +} + +func libraryVersionViewOf(item governance.LibraryVersion) libraryVersionView { + return libraryVersionView{ID: item.ID, Kind: string(item.Kind), SnapshotID: item.SnapshotID, + VersionLabel: item.VersionLabel, SourceJobID: item.SourceJobID, Evidence: item.Evidence, + CreatedBy: item.CreatedBy, CreatedAt: item.CreatedAt, SupersededAt: item.SupersededAt} +} + +// librarySyncGate 只依据真实存在的证据判断能不能写生产:闸口、生产端点、 +// 生产权威版本、目标快照的预备份。任何一项缺失都给出具体原因,不默认放行。 +func librarySyncGate(config Config, production libraryKnownView, prebackup libraryKnownView, target string) libraryGateView { + gate := libraryGateView{SyncAllowed: false, Reasons: []string{}} + if !config.ProductionReleaseRequestsEnabled { + gate.Reasons = append(gate.Reasons, "生产写入闸口关闭(PRODUCTION_RELEASE_REQUESTS_ENABLED=false)") + } + if !config.ProductionBackupRestoreVerified { + gate.Reasons = append(gate.Reasons, "没有已核验的生产恢复演练证据(PRODUCTION_BACKUP_RESTORE_VERIFIED=false)") + } + if strings.TrimSpace(config.ProductionWeKnoraBaseURL) == "" { + gate.Reasons = append(gate.Reasons, "生产端点未配置,无法核验生产当前版本") + } + if production.State != "known" { + gate.Reasons = append(gate.Reasons, "生产当前权威版本未知,不能启动写入") + } + if target == "" { + gate.Reasons = append(gate.Reasons, "还没有可同步的测试封存版本") + } + if prebackup.State != "known" { + gate.Reasons = append(gate.Reasons, "本次目标快照还没有生产预备份") + } + gate.SyncAllowed = len(gate.Reasons) == 0 + return gate +} + +func libraryOverviewHandler(w http.ResponseWriter, r *http.Request, config Config) { + scope, err := scopeFromQuery(r) + if err != nil { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()}) + return + } + store, ok := libraryStore(config) + if !ok { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, + "reason": "版本登记存储不可用"}) + return + } + now := time.Now().UTC() + overview := libraryOverview{Scope: scope, Jobs: []governance.LibraryJob{}, Now: now, + CaptureAvailable: strings.TrimSpace(config.LibraryAgentSocket) != "", + Gate: libraryGateView{Reasons: []string{}}, + Diff: libraryDiffView{State: "unknown", Reason: "生产与测试的文档级差异读取未接线", Added: []any{}, Updated: []any{}, Removed: []any{}}} + if !overview.CaptureAvailable { + overview.CaptureReason = "主机侧封存 agent 未接线" + } + + // 测试封存来自归档:它只是测试侧事实。 + snapshots, snapErr := readLibrarySnapshots(config.LibraryArchiveRoot) + if snapErr != nil { + overview.TestSealedReason = "归档不可读" + } else if !snapshots.Available { + overview.TestSealedReason = snapshots.Reason + } else { + for index := range snapshots.Snapshots { + if snapshots.Snapshots[index].Scope == scope { + overview.TestSealed = &snapshots.Snapshots[index] + break + } + } + if overview.TestSealed == nil { + overview.TestSealedReason = "还没有该目标的测试封存" + } + } + + // 生产生效 / 预备份 / 作业来自持久登记。 + versions, err := store.LibraryVersions(r.Context(), scope, 50) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"}) + return + } + overview.Production = libraryKnownView{State: "unknown", Reason: "还没有生产验证通过的生效版本记录"} + overview.Prebackup = libraryKnownView{State: "unknown", Reason: "本次目标快照还没有生产预备份"} + target := "" + if overview.TestSealed != nil { + target = overview.TestSealed.SnapshotID + } + for index := range versions { + item := versions[index] + view := libraryVersionViewOf(item) + switch item.Kind { + case governance.LibraryVersionProductionEffective: + if item.SupersededAt == nil { + overview.Production = libraryKnownView{State: "known", Version: &view} + } + case governance.LibraryVersionProductionPrebackup: + // 只有与目标快照绑定的预备份才算"这次同步前的备份"。 + if target != "" && item.SnapshotID == target { + overview.Prebackup = libraryKnownView{State: "known", Version: &view} + } + } + } + + recent, err := store.ListLibraryJobs(r.Context(), scope, 20) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library jobs"}) + return + } + overview.Jobs = recent + for index := range recent { + if recent[index].State == governance.LibraryJobPending || recent[index].State == governance.LibraryJobRunning { + overview.Job = &recent[index] + break + } + } + if overview.Job == nil && len(recent) > 0 { + overview.Job = &recent[0] + } + + overview.Gate = librarySyncGate(config, overview.Production, overview.Prebackup, target) + writeJSON(w, http.StatusOK, overview) +} + +func libraryJobsHandler(w http.ResponseWriter, r *http.Request, config Config) { + scope, err := scopeFromQuery(r) + if err != nil { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()}) + return + } + store, ok := libraryStore(config) + if !ok { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, "reason": "版本登记存储不可用", "jobs": []any{}}) + return + } + items, err := store.ListLibraryJobs(r.Context(), scope, 20) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library jobs"}) + return + } + writeJSON(w, http.StatusOK, map[string]any{"available": true, "jobs": items}) +} + +func libraryJobDetailHandler(w http.ResponseWriter, r *http.Request, config Config) { + store, ok := libraryStore(config) + if !ok { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, "reason": "版本登记存储不可用"}) + return + } + id := strings.TrimSpace(r.PathValue("id")) + if id == "" { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": "job id required"}) + return + } + job, err := store.LibraryJob(r.Context(), id) + if err != nil { + writeJSON(w, http.StatusNotFound, map[string]any{"available": false, "reason": "作业不存在"}) + return + } + writeJSON(w, http.StatusOK, map[string]any{"available": true, "job": job}) +} + +// librarySyncEnqueue 是生产同步的唯一入口:闸口未齐时**不建作业**,直接说明缺项。 +// 这样按钮永远不会假接通,也不会留下一个永远失败的空作业。 +func librarySyncEnqueue(w http.ResponseWriter, r *http.Request, config Config) { + if r.Method != http.MethodPost { + writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "method not allowed"}) + return + } + store, ok := libraryStore(config) + if !ok { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"code": "library_sync_unavailable", "reasons": []string{"版本登记存储不可用"}}) + return + } + var request struct { + Scope string `json:"scope"` + Target string `json:"target_snapshot_id"` + } + if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&request); err != nil { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"}) + return + } + if request.Scope != "internal" && request.Scope != "external" { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": "scope must be internal or external"}) + return + } + overview := libraryOverview{Scope: request.Scope} + versions, err := store.LibraryVersions(r.Context(), request.Scope, 50) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"}) + return + } + overview.Production = libraryKnownView{State: "unknown"} + overview.Prebackup = libraryKnownView{State: "unknown"} + for index := range versions { + item := versions[index] + if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil { + view := libraryVersionViewOf(item) + overview.Production = libraryKnownView{State: "known", Version: &view} + } + if item.Kind == governance.LibraryVersionProductionPrebackup && request.Target != "" && item.SnapshotID == request.Target { + view := libraryVersionViewOf(item) + overview.Prebackup = libraryKnownView{State: "known", Version: &view} + } + } + gate := librarySyncGate(config, overview.Production, overview.Prebackup, request.Target) + if !gate.SyncAllowed { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{ + "code": "library_sync_blocked", "reasons": gate.Reasons, + "production": overview.Production, "prebackup": overview.Prebackup, + }) + return + } + + // 走到这里说明闸口与证据都齐了才真正建作业;互斥与幂等由数据库索引保证。 + digest, err := governance.LibraryRequestDigest(request.Scope, governance.LibraryJobSync, + map[string]any{"target_snapshot_id": request.Target}) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot digest request"}) + return + } + actor := "" + if identity, ok := sessionFrom(r.Context()); ok { + actor = identity.Username + } + now := time.Now().UTC() + jobID := fmt.Sprintf("libsync-%s-%d", request.Scope, now.UnixNano()) + job, reused, err := store.CreateLibraryJob(r.Context(), governance.LibraryJob{ + ID: jobID, Scope: request.Scope, Kind: governance.LibraryJobSync, + IdempotencyKey: "library.sync:" + request.Scope + ":" + request.Target, RequestDigest: digest, + TargetSnapshotID: request.Target, Actor: actor, + }, governance.SyncStages(), now) + if errors.Is(err, governance.ErrLibraryJobActive) { + writeJSON(w, http.StatusConflict, map[string]any{"code": "library_sync_active", "error": "该目标已有在飞的同步作业"}) + return + } + if errors.Is(err, governance.ErrLibraryJobIdempotencyConflict) { + writeJSON(w, http.StatusConflict, map[string]any{"code": "library_sync_conflict", "error": "同一幂等键对应了不同的请求"}) + return + } + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot create library sync job"}) + return + } + writeJSON(w, http.StatusAccepted, map[string]any{"job": job, "reused": reused}) +} diff --git a/internal/httpapi/library_flow_test.go b/internal/httpapi/library_flow_test.go new file mode 100644 index 0000000..c53844d --- /dev/null +++ b/internal/httpapi/library_flow_test.go @@ -0,0 +1,230 @@ +package httpapi + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "knowledge-governance/internal/governance" +) + +// 生产闸口与整库状态契约的针对性测试:不做数据库集成,只验证 +// "证据不齐就不建作业" 与 "三类版本不互相顶替" 这两条硬规则。 + +// 复用既有 fakeJobStore 提供 Store 的其余方法,只覆盖整库作业这几个。 +type fakeLibraryStore struct { + fakeJobStore + versions []governance.LibraryVersion + jobs []governance.LibraryJob + createN int + lastJob governance.LibraryJob + lastState governance.LibraryJobState +} + +func (f *fakeLibraryStore) CreateLibraryJob(_ context.Context, job governance.LibraryJob, _ []string, _ time.Time) (governance.LibraryJob, bool, error) { + f.createN++ + f.lastJob = job + return job, false, nil +} + +func (f *fakeLibraryStore) LibraryJob(_ context.Context, id string) (governance.LibraryJob, error) { + return governance.LibraryJob{ID: id}, nil +} + +func (f *fakeLibraryStore) ListLibraryJobs(_ context.Context, scope string, _ int) ([]governance.LibraryJob, error) { + result := make([]governance.LibraryJob, 0, len(f.jobs)) + for _, job := range f.jobs { + if job.Scope == scope { + result = append(result, job) + } + } + return result, nil +} + +func (f *fakeLibraryStore) RecordLibraryVersion(_ context.Context, version governance.LibraryVersion) error { + f.versions = append(f.versions, version) + return nil +} + +func (f *fakeLibraryStore) LibraryVersions(_ context.Context, scope string, _ int) ([]governance.LibraryVersion, error) { + result := make([]governance.LibraryVersion, 0, len(f.versions)) + for _, version := range f.versions { + if version.Scope == scope { + result = append(result, version) + } + } + return result, nil +} + +func (f *fakeLibraryStore) UpdateLibraryStage(_ context.Context, _, _, _ string, _, _, _, _ *int64, _ string, _ time.Time) error { + return nil +} + +func (f *fakeLibraryStore) AdvanceLibraryJob(_ context.Context, _ string, state governance.LibraryJobState, _, _, _, _, _ string, _ time.Time) error { + f.lastState = state + return nil +} + +func (f *fakeLibraryStore) AttachLibraryQueueJob(_ context.Context, _, _ string, _ time.Time) error { + return nil +} + +func (f *fakeLibraryStore) CancelLibraryJob(_ context.Context, _, _ string, _ time.Time) error { + f.lastState = governance.LibraryJobCancelled + return nil +} + +func TestLibrarySyncGateRequiresEveryPieceOfEvidence(t *testing.T) { + known := libraryKnownView{State: "known", Version: &libraryVersionView{ID: "v1"}} + cases := []struct { + name string + config Config + production libraryKnownView + prebackup libraryKnownView + target string + allowed bool + reason string + }{ + { + name: "default installation is closed", + config: Config{}, + production: libraryKnownView{State: "unknown"}, + prebackup: libraryKnownView{State: "unknown"}, + target: "snap-1", + allowed: false, + reason: "生产写入闸口关闭", + }, + { + name: "flags on but restore evidence missing", + config: Config{ProductionReleaseRequestsEnabled: true, + ProductionWeKnoraBaseURL: "http://prod.invalid"}, + production: known, + prebackup: known, + target: "snap-1", + allowed: false, + reason: "没有已核验的生产恢复演练证据", + }, + { + name: "everything present", + config: Config{ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true, + ProductionWeKnoraBaseURL: "http://prod.invalid"}, + production: known, + prebackup: known, + target: "snap-1", + allowed: true, + }, + } + for _, testCase := range cases { + t.Run(testCase.name, func(t *testing.T) { + gate := librarySyncGate(testCase.config, testCase.production, testCase.prebackup, testCase.target) + if gate.SyncAllowed != testCase.allowed { + t.Fatalf("sync_allowed = %v, want %v (%v)", gate.SyncAllowed, testCase.allowed, gate.Reasons) + } + if testCase.reason != "" { + joined := strings.Join(gate.Reasons, "|") + if !strings.Contains(joined, testCase.reason) { + t.Fatalf("reasons %v missing %q", gate.Reasons, testCase.reason) + } + } + }) + } +} + +// 闸口关闭时 POST /api/v1/library/syncs 必须直接拒绝,并且**不创建**作业: +// 不能留下一个永远失败的空作业,也不能让按钮看起来接通了。 +func TestLibrarySyncEnqueueRefusesWithoutCreatingJob(t *testing.T) { + store := &fakeLibraryStore{} + config := Config{Store: store} + request := httptest.NewRequest(http.MethodPost, "/api/v1/library/syncs", + strings.NewReader(`{"scope":"internal","target_snapshot_id":"snap-1"}`)) + recorder := httptest.NewRecorder() + librarySyncEnqueue(recorder, request, config) + if recorder.Code != http.StatusServiceUnavailable { + t.Fatalf("status = %d, want 503", recorder.Code) + } + if store.createN != 0 { + t.Fatalf("created %d jobs while gate is closed", store.createN) + } + var body struct { + Code string `json:"code"` + Reasons []string `json:"reasons"` + } + if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil { + t.Fatalf("decode body: %v", err) + } + if body.Code != "library_sync_blocked" || len(body.Reasons) == 0 { + t.Fatalf("unexpected refusal body: %s", recorder.Body.String()) + } +} + +// 即使闸口打开,缺少与目标快照绑定的预备份也必须拒绝。 +func TestLibrarySyncEnqueueRequiresPrebackupForTarget(t *testing.T) { + store := &fakeLibraryStore{versions: []governance.LibraryVersion{{ + ID: "ver-prod-1", Scope: "internal", Kind: governance.LibraryVersionProductionEffective, + SnapshotID: "prod-snap", VersionLabel: "prod-2026.10", CreatedAt: time.Now().UTC(), + }}} + config := Config{Store: store, ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true, + ProductionWeKnoraBaseURL: "http://prod.invalid"} + request := httptest.NewRequest(http.MethodPost, "/api/v1/library/syncs", + strings.NewReader(`{"scope":"internal","target_snapshot_id":"snap-1"}`)) + recorder := httptest.NewRecorder() + librarySyncEnqueue(recorder, request, config) + if recorder.Code != http.StatusServiceUnavailable { + t.Fatalf("status = %d, want 503", recorder.Code) + } + if !strings.Contains(recorder.Body.String(), "预备份") { + t.Fatalf("refusal must name the missing prebackup: %s", recorder.Body.String()) + } + if store.createN != 0 { + t.Fatalf("created %d jobs without a prebackup", store.createN) + } +} + +// 三类版本必须分开读:production_effective 才是生产当前,测试封存不能顶替。 +func TestLibraryOverviewKeepsVersionKindsSeparate(t *testing.T) { + now := time.Now().UTC() + store := &fakeLibraryStore{versions: []governance.LibraryVersion{ + {ID: "ver-test", Scope: "internal", Kind: governance.LibraryVersionTestSealed, SnapshotID: "snap-1", CreatedAt: now}, + {ID: "ver-prod", Scope: "internal", Kind: governance.LibraryVersionProductionEffective, + SnapshotID: "prod-snap", VersionLabel: "prod-2026.10", CreatedAt: now}, + {ID: "ver-backup-other", Scope: "internal", Kind: governance.LibraryVersionProductionPrebackup, + SnapshotID: "other-snap", CreatedAt: now}, + }} + config := Config{Store: store, LibraryArchiveRoot: t.TempDir()} + request := httptest.NewRequest(http.MethodGet, "/api/v1/library/overview?scope=internal", nil) + recorder := httptest.NewRecorder() + libraryOverviewHandler(recorder, request, config) + if recorder.Code != http.StatusOK { + t.Fatalf("status = %d: %s", recorder.Code, recorder.Body.String()) + } + var body struct { + Production libraryKnownView `json:"production"` + Prebackup libraryKnownView `json:"prebackup"` + Diff struct { + State string `json:"state"` + } `json:"diff"` + Gate struct { + SyncAllowed bool `json:"sync_allowed"` + } `json:"gate"` + } + if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil { + t.Fatalf("decode overview: %v", err) + } + if body.Production.State != "known" || body.Production.Version == nil || body.Production.Version.ID != "ver-prod" { + t.Fatalf("production must be the effective version, got %+v", body.Production) + } + // 预备份只对匹配目标快照的那一份生效;这里目标为空(归档不可用),所以是未知。 + if body.Prebackup.State != "unknown" { + t.Fatalf("prebackup must stay unknown without a matching target snapshot: %+v", body.Prebackup) + } + if body.Diff.State != "unknown" { + t.Fatalf("diff must be unknown until the comparison is wired, got %q", body.Diff.State) + } + if body.Gate.SyncAllowed { + t.Fatal("gate must stay closed") + } +} diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go index 2913cc5..f75846e 100644 --- a/internal/httpapi/server.go +++ b/internal/httpapi/server.go @@ -405,6 +405,20 @@ func NewHandler(config Config) (http.Handler, error) { mux.HandleFunc("GET /api/v1/library/captures", func(w http.ResponseWriter, r *http.Request) { libraryCaptureJobs(w, r, config) }) + // 整库状态:测试封存 / 生产生效 / 生产预备份 三类版本 + 差异 + 持久作业。 + mux.HandleFunc("GET /api/v1/library/overview", func(w http.ResponseWriter, r *http.Request) { + libraryOverviewHandler(w, r, config) + }) + mux.HandleFunc("GET /api/v1/library/jobs", func(w http.ResponseWriter, r *http.Request) { + libraryJobsHandler(w, r, config) + }) + mux.HandleFunc("GET /api/v1/library/jobs/{id}", func(w http.ResponseWriter, r *http.Request) { + libraryJobDetailHandler(w, r, config) + }) + // 生产同步唯一入口:闸口未齐不建作业,返回缺项而不是假 Accepted。 + mux.HandleFunc("POST /api/v1/library/syncs", func(w http.ResponseWriter, r *http.Request) { + librarySyncEnqueue(w, r, config) + }) // 全部 main 提交时间线(读本库缓存,不直接打 Gitea) mux.HandleFunc("GET /api/v1/version-history", func(w http.ResponseWriter, r *http.Request) { versionHistoryList(w, r, config) diff --git a/internal/platform/postgres/library_jobs.go b/internal/platform/postgres/library_jobs.go new file mode 100644 index 0000000..957366d --- /dev/null +++ b/internal/platform/postgres/library_jobs.go @@ -0,0 +1,276 @@ +package postgres + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "time" + + "github.com/jackc/pgx/v5" + "github.com/jackc/pgx/v5/pgconn" + + "knowledge-governance/internal/governance" +) + +// 整库作业与版本:队列(jobs)负责租约重试,本文件负责业务身份、阶段与结果。 +// 互斥与幂等都由数据库唯一索引保证,不依赖前端或单 worker 部署。 + +func (s *Store) CreateLibraryJob(ctx context.Context, job governance.LibraryJob, stages []string, now time.Time) (governance.LibraryJob, bool, error) { + request := job.RequestDigest + if request == "" { + return governance.LibraryJob{}, false, errors.New("library job requires a request digest") + } + rawRequest, err := json.Marshal(map[string]any{"digest": request, "kind": string(job.Kind), "scope": job.Scope}) + if err != nil { + return governance.LibraryJob{}, false, err + } + var id string + err = s.db.QueryRow(ctx, ` +INSERT INTO library_jobs (id, scope, kind, state, stage, idempotency_key, request_digest, request, + queue_job_id, snapshot_id, target_snapshot_id, actor, error, recovery, created_at, updated_at) +VALUES ($1,$2,$3,'pending','',$4,$5,$6,$7,$8,$9,$10,'','',$11,$11) +ON CONFLICT (idempotency_key) DO NOTHING +RETURNING id`, + job.ID, job.Scope, string(job.Kind), job.IdempotencyKey, request, rawRequest, + job.QueueJobID, job.SnapshotID, job.TargetSnapshotID, job.Actor, now.UTC()).Scan(&id) + if err != nil { + var pgErr *pgconn.PgError + if errors.As(err, &pgErr) && pgErr.Code == "23505" { + if pgErr.ConstraintName == "library_jobs_active" { + return governance.LibraryJob{}, false, governance.ErrLibraryJobActive + } + } + if !errors.Is(err, pgx.ErrNoRows) { + return governance.LibraryJob{}, false, fmt.Errorf("create library job: %w", err) + } + // 幂等键已存在:必须返回**已存**作业,并核对请求体是否一致。 + existing, loadErr := s.libraryJobByKey(ctx, job.IdempotencyKey) + if loadErr != nil { + return governance.LibraryJob{}, false, loadErr + } + if existing.RequestDigest != request { + return existing, false, governance.ErrLibraryJobIdempotencyConflict + } + return existing, true, nil + } + for _, stage := range stages { + if _, err := s.db.Exec(ctx, ` +INSERT INTO library_job_stages (job_id, stage, state, detail, updated_at) +VALUES ($1,$2,'pending','',$3) +ON CONFLICT (job_id, stage) DO NOTHING`, id, stage, now.UTC()); err != nil { + return governance.LibraryJob{}, false, fmt.Errorf("create library job stage: %w", err) + } + } + created, err := s.LibraryJob(ctx, id) + return created, false, err +} + +func (s *Store) libraryJobByKey(ctx context.Context, key string) (governance.LibraryJob, error) { + var id string + if err := s.db.QueryRow(ctx, `SELECT id FROM library_jobs WHERE idempotency_key=$1`, key).Scan(&id); err != nil { + if errors.Is(err, pgx.ErrNoRows) { + return governance.LibraryJob{}, errors.New("library job idempotency key not found") + } + return governance.LibraryJob{}, fmt.Errorf("load library job by key: %w", err) + } + return s.LibraryJob(ctx, id) +} + +func (s *Store) LibraryJob(ctx context.Context, id string) (governance.LibraryJob, error) { + var job governance.LibraryJob + var kind, state string + var finished *time.Time + if err := s.db.QueryRow(ctx, ` +SELECT id, scope, kind, state, stage, idempotency_key, request_digest, queue_job_id, snapshot_id, + target_snapshot_id, actor, error, recovery, created_at, updated_at, finished_at +FROM library_jobs WHERE id=$1`, id).Scan(&job.ID, &job.Scope, &kind, &state, &job.Stage, &job.IdempotencyKey, + &job.RequestDigest, &job.QueueJobID, &job.SnapshotID, &job.TargetSnapshotID, &job.Actor, &job.Error, + &job.Recovery, &job.CreatedAt, &job.UpdatedAt, &finished); err != nil { + if errors.Is(err, pgx.ErrNoRows) { + return governance.LibraryJob{}, err + } + return governance.LibraryJob{}, fmt.Errorf("load library job: %w", err) + } + job.Kind, job.State, job.FinishedAt = governance.LibraryJobKind(kind), governance.LibraryJobState(state), finished + stages, err := s.libraryStages(ctx, id) + if err != nil { + return governance.LibraryJob{}, err + } + job.Stages = stages + return job, nil +} + +func (s *Store) libraryStages(ctx context.Context, id string) ([]governance.LibraryStage, error) { + rows, err := s.db.Query(ctx, ` +SELECT stage, state, total, completed, bytes_total, bytes_done, detail, updated_at +FROM library_job_stages WHERE job_id=$1 ORDER BY updated_at, stage`, id) + if err != nil { + return nil, fmt.Errorf("load library job stages: %w", err) + } + defer rows.Close() + result := make([]governance.LibraryStage, 0, 7) + for rows.Next() { + var stage governance.LibraryStage + if err := rows.Scan(&stage.Stage, &stage.State, &stage.Total, &stage.Completed, &stage.BytesTotal, + &stage.BytesDone, &stage.Detail, &stage.UpdatedAt); err != nil { + return nil, fmt.Errorf("scan library job stage: %w", err) + } + result = append(result, stage) + } + return result, rows.Err() +} + +// ListLibraryJobs 返回某目标最近的作业(按创建时间倒序),供页面在重启后恢复展示。 +func (s *Store) ListLibraryJobs(ctx context.Context, scope string, limit int) ([]governance.LibraryJob, error) { + if limit < 1 || limit > 50 { + return nil, errors.New("library job list limit out of range") + } + rows, err := s.db.Query(ctx, `SELECT id FROM library_jobs WHERE scope=$1 ORDER BY created_at DESC, id DESC LIMIT $2`, scope, limit) + if err != nil { + return nil, fmt.Errorf("list library jobs: %w", err) + } + defer rows.Close() + ids := make([]string, 0, limit) + for rows.Next() { + var id string + if err := rows.Scan(&id); err != nil { + return nil, fmt.Errorf("scan library job id: %w", err) + } + ids = append(ids, id) + } + if err := rows.Err(); err != nil { + return nil, err + } + result := make([]governance.LibraryJob, 0, len(ids)) + for _, id := range ids { + job, err := s.LibraryJob(ctx, id) + if err != nil { + return nil, err + } + result = append(result, job) + } + return result, nil +} + +// UpdateLibraryStage 只改调用方给了值的维度:nil 表示"这一维还没有可靠数据", +// 保持 NULL,绝不写成 0。 +func (s *Store) UpdateLibraryStage(ctx context.Context, jobID, stage, state string, total, completed, bytesTotal, bytesDone *int64, detail string, now time.Time) error { + tag, err := s.db.Exec(ctx, ` +UPDATE library_job_stages SET + state = CASE WHEN $3='' THEN state ELSE $3 END, + total = COALESCE($4, total), + completed = COALESCE($5, completed), + bytes_total = COALESCE($6, bytes_total), + bytes_done = COALESCE($7, bytes_done), + detail = CASE WHEN $8='' THEN detail ELSE $8 END, + updated_at = $9 +WHERE job_id=$1 AND stage=$2`, jobID, stage, state, total, completed, bytesTotal, bytesDone, detail, now.UTC()) + if err != nil { + return fmt.Errorf("update library stage: %w", err) + } + if tag.RowsAffected() != 1 { + return errors.New("library stage not found") + } + return nil +} + +// AttachLibraryQueueJob 把队列作业号写到已建的业务作业上(两步创建,避免先入队后才发现互斥冲突)。 +func (s *Store) AttachLibraryQueueJob(ctx context.Context, jobID, queueJobID string, now time.Time) error { + tag, err := s.db.Exec(ctx, `UPDATE library_jobs SET queue_job_id=$2, updated_at=$3 WHERE id=$1`, jobID, queueJobID, now.UTC()) + if err != nil { + return fmt.Errorf("attach library queue job: %w", err) + } + if tag.RowsAffected() != 1 { + return errors.New("library job not found") + } + return nil +} + +func (s *Store) CancelLibraryJob(ctx context.Context, jobID, reason string, now time.Time) error { + return s.AdvanceLibraryJob(ctx, jobID, governance.LibraryJobCancelled, "", reason, "", "", "", now) +} + +func (s *Store) AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error { + finished := any(nil) + if state == governance.LibraryJobSucceeded || state == governance.LibraryJobFailed || state == governance.LibraryJobCancelled { + finished = now.UTC() + } + tag, err := s.db.Exec(ctx, ` +UPDATE library_jobs SET + state=$2, + stage = CASE WHEN $3='' THEN stage ELSE $3 END, + error = CASE WHEN $4='' THEN error ELSE $4 END, + recovery = CASE WHEN $5='' THEN recovery ELSE $5 END, + snapshot_id = CASE WHEN $6='' THEN snapshot_id ELSE $6 END, + target_snapshot_id = CASE WHEN $7='' THEN target_snapshot_id ELSE $7 END, + updated_at=$8, + finished_at=COALESCE($9, finished_at) +WHERE id=$1`, jobID, string(state), stage, message, recovery, snapshotID, targetSnapshotID, now.UTC(), finished) + if err != nil { + return fmt.Errorf("advance library job: %w", err) + } + if tag.RowsAffected() != 1 { + return errors.New("library job not found") + } + return nil +} + +// RecordLibraryVersion 写入一个版本记录。生产生效版本必须先把旧的 supersede 掉, +// 否则唯一索引会拒绝——这正是"不许两个生效版本并存"的保证。 +func (s *Store) RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error { + evidence, err := json.Marshal(version.Evidence) + if err != nil { + return fmt.Errorf("encode library version evidence: %w", err) + } + tx, err := s.db.Begin(ctx) + if err != nil { + return fmt.Errorf("begin library version: %w", err) + } + defer func() { _ = tx.Rollback(ctx) }() + if version.Kind == governance.LibraryVersionProductionEffective { + if _, err := tx.Exec(ctx, ` +UPDATE library_versions SET superseded_at=$2 +WHERE scope=$1 AND kind='production_effective' AND superseded_at IS NULL`, version.Scope, version.CreatedAt.UTC()); err != nil { + return fmt.Errorf("supersede library version: %w", err) + } + } + if _, err := tx.Exec(ctx, ` +INSERT INTO library_versions (id, scope, kind, snapshot_id, version_label, source_job_id, evidence, created_by, created_at) +VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9) +ON CONFLICT (id) DO NOTHING`, + version.ID, version.Scope, string(version.Kind), version.SnapshotID, version.VersionLabel, + version.SourceJobID, evidence, version.CreatedBy, version.CreatedAt.UTC()); err != nil { + return fmt.Errorf("record library version: %w", err) + } + return tx.Commit(ctx) +} + +func (s *Store) LibraryVersions(ctx context.Context, scope string, limit int) ([]governance.LibraryVersion, error) { + if limit < 1 || limit > 100 { + return nil, errors.New("library version limit out of range") + } + rows, err := s.db.Query(ctx, ` +SELECT id, scope, kind, snapshot_id, version_label, source_job_id, evidence, created_by, created_at, superseded_at +FROM library_versions WHERE scope=$1 ORDER BY created_at DESC, id DESC LIMIT $2`, scope, limit) + if err != nil { + return nil, fmt.Errorf("list library versions: %w", err) + } + defer rows.Close() + result := make([]governance.LibraryVersion, 0, limit) + for rows.Next() { + var item governance.LibraryVersion + var kind string + var evidence []byte + if err := rows.Scan(&item.ID, &item.Scope, &kind, &item.SnapshotID, &item.VersionLabel, &item.SourceJobID, + &evidence, &item.CreatedBy, &item.CreatedAt, &item.SupersededAt); err != nil { + return nil, fmt.Errorf("scan library version: %w", err) + } + item.Kind = governance.LibraryVersionKind(kind) + if len(evidence) > 0 { + _ = json.Unmarshal(evidence, &item.Evidence) + } + result = append(result, item) + } + return result, rows.Err() +} diff --git a/internal/platform/postgres/migrations/000066_library_flow.down.sql b/internal/platform/postgres/migrations/000066_library_flow.down.sql new file mode 100644 index 0000000..eb49552 --- /dev/null +++ b/internal/platform/postgres/migrations/000066_library_flow.down.sql @@ -0,0 +1,3 @@ +DROP TABLE IF EXISTS library_job_stages; +DROP TABLE IF EXISTS library_jobs; +DROP TABLE IF EXISTS library_versions; \ No newline at end of file diff --git a/internal/platform/postgres/migrations/000066_library_flow.up.sql b/internal/platform/postgres/migrations/000066_library_flow.up.sql new file mode 100644 index 0000000..2209476 --- /dev/null +++ b/internal/platform/postgres/migrations/000066_library_flow.up.sql @@ -0,0 +1,57 @@ +-- 整库版本与作业:把"测试封存 / 生产生效 / 生产预备份"三种版本与持久作业分开记录。 +-- 现有 jobs 表是队列与租约;这里记录业务身份、阶段与结果,重启后仍可读。 +CREATE TABLE library_versions ( + id VARCHAR(64) PRIMARY KEY, + scope VARCHAR(16) NOT NULL CHECK (scope IN ('internal','external')), + kind VARCHAR(24) NOT NULL CHECK (kind IN ('test_sealed','production_effective','production_prebackup')), + snapshot_id VARCHAR(64) NOT NULL DEFAULT '', + version_label VARCHAR(64) NOT NULL DEFAULT '', + source_job_id VARCHAR(64) NOT NULL DEFAULT '', + evidence JSONB NOT NULL DEFAULT '{}'::jsonb, + created_by VARCHAR(128) NOT NULL DEFAULT '', + created_at TIMESTAMPTZ NOT NULL, + superseded_at TIMESTAMPTZ +); +CREATE INDEX library_versions_scope_kind ON library_versions(scope, kind, created_at DESC, id DESC); +-- 每个目标只有一个"当前生产生效版本";写入新版本时旧的必须先被 supersede。 +CREATE UNIQUE INDEX library_versions_effective ON library_versions(scope) + WHERE kind = 'production_effective' AND superseded_at IS NULL; + +CREATE TABLE library_jobs ( + id VARCHAR(64) PRIMARY KEY, + scope VARCHAR(16) NOT NULL CHECK (scope IN ('internal','external')), + kind VARCHAR(16) NOT NULL CHECK (kind IN ('seal','sync')), + state VARCHAR(16) NOT NULL CHECK (state IN ('pending','running','succeeded','failed','cancelled')), + stage VARCHAR(32) NOT NULL DEFAULT '', + idempotency_key VARCHAR(255) NOT NULL, + request_digest VARCHAR(64) NOT NULL, + request JSONB NOT NULL DEFAULT '{}'::jsonb, + queue_job_id VARCHAR(64) NOT NULL DEFAULT '', + snapshot_id VARCHAR(64) NOT NULL DEFAULT '', + target_snapshot_id VARCHAR(64) NOT NULL DEFAULT '', + actor VARCHAR(128) NOT NULL DEFAULT '', + error TEXT NOT NULL DEFAULT '', + recovery VARCHAR(255) NOT NULL DEFAULT '', + created_at TIMESTAMPTZ NOT NULL, + updated_at TIMESTAMPTZ NOT NULL, + finished_at TIMESTAMPTZ +); +CREATE UNIQUE INDEX library_jobs_idempotency ON library_jobs(idempotency_key); +-- 同一目标同一类作业只能有一个在飞:互斥由数据库保证,不依赖前端或单 worker 部署。 +CREATE UNIQUE INDEX library_jobs_active ON library_jobs(scope, kind) + WHERE state IN ('pending','running'); +CREATE INDEX library_jobs_recent ON library_jobs(scope, created_at DESC, id DESC); + +CREATE TABLE library_job_stages ( + job_id VARCHAR(64) NOT NULL REFERENCES library_jobs(id) ON DELETE CASCADE, + stage VARCHAR(32) NOT NULL, + state VARCHAR(16) NOT NULL DEFAULT 'pending' CHECK (state IN ('pending','running','succeeded','failed','skipped')), + -- NULL 表示"总量未知":绝不能当成 0,也不据此算百分比。 + total BIGINT, + completed BIGINT, + bytes_total BIGINT, + bytes_done BIGINT, + detail TEXT NOT NULL DEFAULT '', + updated_at TIMESTAMPTZ NOT NULL, + PRIMARY KEY (job_id, stage) +); \ No newline at end of file diff --git a/web/src/ReleaseTargets.test.tsx b/web/src/ReleaseTargets.test.tsx index 3c5b552..42db40f 100644 --- a/web/src/ReleaseTargets.test.tsx +++ b/web/src/ReleaseTargets.test.tsx @@ -1,7 +1,13 @@ import { renderToStaticMarkup } from 'react-dom/server' import { describe, expect, it, vi } from 'vitest' import { ReleaseTargetsView } from './ReleaseTargets' -import type { LibraryCaptureJob, LibrarySnapshot, LibrarySnapshotList } from './librarySnapshots' +import type { + LibraryCaptureJob, + LibraryJobRecord, + LibraryOverview, + LibrarySnapshot, + LibrarySnapshotList, +} from './librarySnapshots' const internalSnapshot: LibrarySnapshot = { snapshot_id: 'f992d64ea45bf737a0721a465b5aef2b150ef7757157eb84f3aaf8b6972d98f9', @@ -67,11 +73,69 @@ const page: LibrarySnapshotList = { capture_reason: '', } +// 真实接口形状:生产段未知、闸口未开、没有持久作业。 +const overview: LibraryOverview = { + scope: 'internal', + test_sealed: internalSnapshot, + production: { state: 'unknown', reason: '还没有生产验证通过的生效版本记录' }, + prebackup: { state: 'unknown', reason: '本次目标快照还没有生产预备份' }, + diff: { + state: 'unknown', + reason: '生产与测试的文档级差异读取未接线', + added: [], + updated: [], + removed: [], + }, + jobs: [], + gate: { + sync_allowed: false, + reasons: [ + '生产写入闸口关闭(PRODUCTION_RELEASE_REQUESTS_ENABLED=false)', + '没有已核验的生产恢复演练证据(PRODUCTION_BACKUP_RESTORE_VERIFIED=false)', + '生产当前权威版本未知,不能启动写入', + '本次目标快照还没有生产预备份', + ], + }, + capture_available: true, + now: '2026-10-28T03:40:00Z', +} + +const persistedSeal: LibraryJobRecord = { + id: 'libseal-lib-internal-20261028T033457', + scope: 'internal', + kind: 'seal', + state: 'running', + stage: 'export', + request_digest: 'd'.repeat(64), + queue_job_id: 'library-capture-internal-1', + snapshot_id: '', + target_snapshot_id: '', + actor: 'yaozhanghao', + error: '', + recovery: '', + created_at: '2026-10-28T03:34:50Z', + updated_at: '2026-10-28T03:34:55Z', + finished_at: null, + stages: [ + { + stage: 'export', + state: 'running', + total: null, + completed: null, + bytes_total: null, + bytes_done: null, + detail: '主机侧正在暂停写入者、导出并恢复', + updated_at: '2026-10-28T03:34:55Z', + }, + ], +} + type ViewProps = Parameters[0] const base: ViewProps = { page, jobs: [], + overview, loading: false, error: null, notice: null, @@ -102,20 +166,41 @@ describe('ReleaseTargetsView(确认稿布局)', () => { expect(html).not.toContain('对外知识库 · 尚无') }) - it('未接入项显示“未接入”,不用 0 / 无变化冒充', () => { + it('未接入项显示“未接入/未知”,不用 0 / 无变化冒充', () => { const html = render() expect(html).toContain('生产当前') + // 生产没有权威版本时必须写未知,不能拿测试快照顶替 + expect(html).toContain('未知(尚未建立权威版本)') + expect(html).toContain('尚无记录 · 生产与测试的文档级差异读取未接线') expect(html).toContain('未接入') - expect(html).toContain('尚无记录 · 变更清单来自生产与测试版本对比') }) - it('“启动同步”保持禁用并说明原因,不把封存当成同步', () => { + it('“启动同步”保持禁用并逐条说明缺项,不把封存当成同步', () => { const html = render() expect(html).toMatch(/]*class="rel-primary"[^>]*disabled/) - expect(html).toContain('生产同步未接线') + expect(html).toContain('生产写入闸口关闭') + expect(html).toContain('没有已核验的生产恢复演练证据') + expect(html).toContain('本次目标快照还没有生产预备份') expect(html).toContain('封存测试版本') }) + it('没有当前作业时不把历史封存当成阶段完成', () => { + const html = render() + // 阶段条第一段必须是 idle(○),"✓" 只允许出现在准备清单,不出现在阶段条 + const stageBar = html.slice(html.indexOf('aria-label="作业阶段"'), html.indexOf('rel-steps-note')) + expect(stageBar).not.toContain('✓') + expect(stageBar).toContain('本次作业尚未开始') + expect(html).toContain('已有测试封存') + expect(html).toContain('没有当前作业证据时不会把历史封存当作阶段完成') + }) + + it('准备信息注明快照时间与范围,不声称实时测试库已就绪', () => { + const html = render() + expect(html).toContain('依据 10/28 11:34 封存的测试库全库快照,不代表实时测试库已就绪') + expect(html).toContain('同一份封存快照,不是实时 Wiki 队列状态') + expect(html).toContain('封存时的逐项校验和,重新封存才会更新') + }) + it('版本与快照抽屉按 scope 列出全部历史并区分测试封存/不可直接恢复', () => { const html = render({ drawerOpen: true, expandedSnapshot: internalSnapshot.snapshot_id }) expect(html).toContain('版本与快照') @@ -135,8 +220,11 @@ describe('ReleaseTargetsView(确认稿布局)', () => { }) it('同步中布局显示四类数据卡与明细,且不编造百分比', () => { - const html = render({ jobs: [runningJob] }) - expect(html).toContain('正在封存测试版本') + const html = render({ + jobs: [runningJob], + overview: { ...overview, job: persistedSeal, jobs: [persistedSeal] }, + }) + expect(html).toContain('测试库封存作业') expect(html).toContain('数据库 · 文档与分块') expect(html).toContain('原文件 · 图片 · 附件') expect(html).toContain('检索索引 · 向量') @@ -146,6 +234,9 @@ describe('ReleaseTargetsView(确认稿布局)', () => { expect(html.match(/[1-9]\d*%/g) ?? []).toEqual(['100%']) expect(html).toContain('文件传输 100% ≠ 作业完成') expect(html).toContain('不编造百分比') + // 没有真实总量时只写"未知总量",不画百分比 + expect(html).toContain('未知总量') + expect(html).toContain('主机侧正在暂停写入者、导出并恢复') }) it('无权限时不给封存入口,未接线时说明通道状态', () => { diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx index de451da..0b96d4d 100644 --- a/web/src/ReleaseTargets.tsx +++ b/web/src/ReleaseTargets.tsx @@ -2,12 +2,16 @@ import { useCallback, useEffect, useState } from 'react' import { enqueueLibraryCapture, fetchLibraryCaptures, + fetchLibraryOverview, fetchLibrarySnapshots, formatBytes, scopeLabel, type LibraryCaptureJob, + type LibraryJobRecord, + type LibraryOverview, type LibrarySnapshot, type LibrarySnapshotList, + type LibraryStageRow, } from './librarySnapshots' import { useOptionalAuth } from './auth' import './releaseTargets.css' @@ -57,6 +61,10 @@ interface ScopeView { history: LibrarySnapshot[] activeJob?: LibraryCaptureJob lastJob?: LibraryCaptureJob + // 持久作业与三类版本:来自 /api/v1/library/overview,重启后仍可读。 + overview?: LibraryOverview | null + job?: LibraryJobRecord + syncJob?: LibraryJobRecord } interface ViewProps { @@ -74,28 +82,44 @@ interface ViewProps { pendingCapture: boolean canCapture: boolean canWrite: boolean + overview: LibraryOverview | null now: number onRefresh: () => void onCapture: () => void } -function scopeView(page: LibrarySnapshotList | null, jobs: LibraryCaptureJob[], scope: Scope): ScopeView { +function scopeView( + page: LibrarySnapshotList | null, + jobs: LibraryCaptureJob[], + scope: Scope, + overview: LibraryOverview | null, +): ScopeView { const history = (page?.snapshots ?? []).filter((item) => item.scope === scope) const scoped = jobs.filter((job) => job.scope === scope) + const persisted = overview?.jobs ?? [] + const job = + overview?.job ?? persisted.find((item) => item.state === 'pending' || item.state === 'running') ?? persisted[0] return { scope, snapshot: history[0], history, activeJob: scoped.find((job) => ACTIVE_STATES.includes(job.state)), lastJob: scoped[0], + overview, + job, + syncJob: persisted.find((item) => item.kind === 'sync'), } } const scopeName = (scope: Scope) => (scope === 'internal' ? '对内知识库' : '对外知识库') function statusOf(view: ScopeView) { - if (view.activeJob) return { text: '封存中', tone: 'blue' as const } - if (view.snapshot) return { text: '已有封存', tone: 'green' as const } + const job = view.job + if (job && (job.state === 'running' || job.state === 'pending')) { + return { text: job.kind === 'seal' ? '封存中' : '同步中', tone: 'blue' as const } + } + if (view.overview?.production.state === 'known') return { text: '生产已记录版本', tone: 'green' as const } + if (view.overview?.test_sealed || view.snapshot) return { text: '已有封存', tone: 'green' as const } return { text: '尚无封存', tone: 'gray' as const } } @@ -103,27 +127,110 @@ const jstate = (state?: string) => state === 'failed' ? '封存失败,可在版本与快照里查看原因' : state ? '封存已完成,生产段未接入' : '尚无作业' // 五个阶段对应原稿:固定测试版本 → 备份生产 → 同步数据与 Wiki → 生产验证 → 新版本生效。 -// 只有第一段有真实实现;其余按"未接入"显示,不画成进行中或已完成。 +// 勾选只能来自**当前这次作业**的阶段证据;历史封存记录不代表本次作业推进过, +// 所以没有作业时全部是"本次作业尚未开始",不再把旧快照打勾。 +function stageOf(job: LibraryJobRecord | undefined, name: string): LibraryStageRow | undefined { + return job?.stages.find((item) => item.stage === name) +} + +function worstState(rows: LibraryStageRow[]): 'succeeded' | 'running' | 'failed' | 'pending' { + if (rows.some((row) => row.state === 'failed')) return 'failed' + if (rows.some((row) => row.state === 'running')) return 'running' + if (rows.length > 0 && rows.every((row) => row.state === 'succeeded' || row.state === 'skipped')) return 'succeeded' + return 'pending' +} + +type StepState = 'done' | 'live' | 'fail' | 'idle' + +function toState(value: 'succeeded' | 'running' | 'failed' | 'pending'): StepState { + return value === 'succeeded' ? 'done' : value === 'running' ? 'live' : value === 'failed' ? 'fail' : 'idle' +} + +function jobStateText(job: LibraryJobRecord): string { + const map: Record = { + pending: '排队中', + running: '执行中', + succeeded: '已完成', + failed: '失败', + cancelled: '已取消', + } + return map[job.state] ?? job.state +} + function StageBar({ view }: { view: ScopeView }) { - const sealed = Boolean(view.snapshot) - const capturing = Boolean(view.activeJob) - const stages = [ + const job = view.job + const sealJob = job?.kind === 'seal' ? job : undefined + const syncJob = job?.kind === 'sync' ? job : undefined + + let first: { state: StepState; hint: string } + if (sealJob) { + const exportStage = stageOf(sealJob, 'export') + first = { + state: toState( + sealJob.state === 'succeeded' ? 'succeeded' : sealJob.state === 'failed' ? 'failed' : 'running', + ), + hint: + sealJob.state === 'succeeded' + ? `本次作业已封存 ${stamp(sealJob.finished_at ?? exportStage?.updated_at ?? sealJob.updated_at)}` + : sealJob.state === 'running' + ? '本次封存执行中' + : sealJob.state === 'pending' + ? '已排队,等待 worker' + : '本次封存未完成', + } + } else if (syncJob) { + first = { state: 'done', hint: '已绑定的测试版本' } + } else { + first = { state: 'idle', hint: '本次作业尚未开始' } + } + + const prebackup = syncJob ? stageOf(syncJob, 'prebackup') : undefined + const dataStages = syncJob + ? ['database', 'resources', 'index', 'wiki'] + .map((name) => stageOf(syncJob, name)) + .filter((row): row is LibraryStageRow => Boolean(row)) + : [] + const verifyStage = syncJob ? stageOf(syncJob, 'verify') : undefined + + const stages: { label: string; state: StepState; hint: string }[] = [ + { label: '固定测试版本', ...first }, { - label: '固定测试版本', - state: capturing ? 'live' : sealed ? 'done' : 'idle', - hint: capturing ? '封存执行中' : sealed ? `最近封存 ${stamp(view.snapshot!.created_at)}` : '尚未封存', + label: '备份生产', + state: prebackup ? toState(worstState([prebackup])) : 'idle', + hint: prebackup + ? prebackup.state === 'succeeded' + ? '已完成生产预备份' + : prebackup.state === 'running' + ? '正在备份生产' + : prebackup.state === 'failed' + ? '预备份失败' + : '未开始' + : '未接入', + }, + { + label: '同步数据与 Wiki', + state: dataStages.length > 0 ? toState(worstState(dataStages)) : 'idle', + hint: dataStages.length > 0 ? '按数据库 / 资源 / 索引 / Wiki 分项上报' : '未接入', + }, + { + label: '生产验证', + state: verifyStage ? toState(worstState([verifyStage])) : 'idle', + hint: verifyStage ? (verifyStage.state === 'succeeded' ? '校验通过' : '未完成') : '未接入', + }, + { + label: '新版本生效', + state: syncJob && syncJob.state === 'succeeded' ? 'done' : 'idle', + hint: syncJob && syncJob.state === 'succeeded' ? '生产已生效' : '未接入', }, - { label: '备份生产', state: 'idle', hint: '未接入' }, - { label: '同步数据与 Wiki', state: 'idle', hint: '未接入' }, - { label: '生产验证', state: 'idle', hint: '未接入' }, - { label: '新版本生效', state: 'idle', hint: '未接入' }, ] return ( <>
    {stages.map((stage, index) => (
  1. - {stage.state === 'done' ? '✓' : stage.state === 'live' ? '●' : '○'} + + {stage.state === 'done' ? '✓' : stage.state === 'live' ? '●' : stage.state === 'fail' ? '!' : '○'} + {stage.label} {stage.hint} {index < stages.length - 1 ? → : null} @@ -131,15 +238,27 @@ function StageBar({ view }: { view: ScopeView }) { ))}

- {capturing - ? '封存是停写入者后的原子导出,没有分项进度上报;导出完成后才会出现新版本。' - : '运行时展开各类数据的数量、字节进度及 Wiki 快照进度;不把提交成功当作版本生效。'} + {job + ? `作业 ${job.id} · ${job.kind === 'seal' ? '测试封存' : '生产同步'} · ${jobStateText(job)}${ + job.error ? ` · ${job.error}` : '' + }` + : view.snapshot + ? `已有测试封存 ${stamp(view.snapshot.created_at)}(历史记录),但本次作业尚未开始;没有当前作业证据时不会把历史封存当作阶段完成。` + : '本次作业尚未开始。'}

) } -function ChangeTable() { +function ChangeTable({ diff }: { diff: LibraryOverview['diff'] }) { + const computed = diff.state === 'computed' + const rows = computed + ? [ + ...diff.added.map((item) => ({ action: '新增', item })), + ...diff.updated.map((item) => ({ action: '更新', item })), + ...diff.removed.map((item) => ({ action: '删除', item })), + ] + : [] return (
@@ -147,7 +266,7 @@ function ChangeTable() {

本次变更

整库版本同步,不单独勾选文件

- 未接入 + {computed ? `${rows.length} 条` : '未接入'} @@ -157,34 +276,71 @@ function ChangeTable() { - - - + {rows.length === 0 ? ( + + + + ) : ( + rows.map((row, index) => ( + + + + + )) + )}
- 尚无记录 · 变更清单来自生产与测试版本对比,这项数据还没有接入 -
+ {computed + ? '生产与测试版本没有文档差异' + : `尚无记录 · ${diff.reason || '变更清单来自生产与测试版本对比,这项数据还没有接入'}`} +
{row.action}{typeof row.item === 'string' ? row.item : JSON.stringify(row.item)}
) } -function ProtectionCard({ onOpen }: { onOpen: () => void }) { +function ProtectionCard({ + production, + prebackup, + gate, + onOpen, +}: { + production: LibraryOverview['production'] + prebackup: LibraryOverview['prebackup'] + gate: LibraryOverview['gate'] + onOpen: () => void +}) { + const backupKnown = prebackup.state === 'known' && prebackup.version return (