From 146ac832a2fc7cad1e68012f81f49b0545950c26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Fri, 6 Nov 2026 10:04:19 +0800 Subject: [PATCH] =?UTF-8?q?fix(library):=20=E4=BF=AE=E5=A4=8D=E5=B0=81?= =?UTF-8?q?=E5=AD=98=E7=BB=88=E6=80=81=E5=9B=9E=E5=86=99=E5=B9=B6=E5=A2=9E?= =?UTF-8?q?=E5=8A=A0=E7=B2=BE=E7=A1=AE=E6=A0=B8=E5=AF=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修复 varchar 状态参数在 AdvanceLibraryJob 的 42P08;worker 开始/终态写入失败 不再吞掉。新增管理员核对路由,仅在 completed capture queue、export succeeded、 精确 test_sealed 版本、来源身份和归档复核一致时,以条件更新修复仍为 pending/running 的同一作业;已有不同快照或并发失败/取消行拒绝覆盖。保留 第一因与历史记录,不重新封存、不产生快照、不写源或目标知识。 验证:真实 varchar DDL PG 路径、handler 负例/幂等、worker 注入、web 组件; umask022 与真实隔离 kg_library_test_* 下 Go 全量与 make verify 17 项通过。 --- CHANGELOG.md | 22 ++ api/openapi.yaml | 39 +++ .../library_capture_persistence_test.go | 96 ++++++ cmd/worker/main.go | 50 +++- internal/httpapi/auth.go | 5 + internal/httpapi/library_capture_reconcile.go | 213 ++++++++++++++ .../httpapi/library_capture_reconcile_test.go | 273 ++++++++++++++++++ internal/httpapi/library_flow_test.go | 18 +- internal/httpapi/server.go | 4 + .../library_capture_reconcile_pg_test.go | 97 +++++++ internal/platform/postgres/library_jobs.go | 100 ++++++- .../library_jobs_first_error_pg_test.go | 40 ++- .../platform/postgres/library_write_fence.go | 16 +- internal/platform/postgres/queue_sql.go | 8 + internal/platform/postgres/store.go | 15 + web/src/ReleaseTargets.test.tsx | 21 ++ web/src/ReleaseTargets.tsx | 73 ++++- web/src/librarySnapshots.ts | 31 ++ 18 files changed, 1082 insertions(+), 39 deletions(-) create mode 100644 cmd/worker/library_capture_persistence_test.go create mode 100644 internal/httpapi/library_capture_reconcile.go create mode 100644 internal/httpapi/library_capture_reconcile_test.go create mode 100644 internal/platform/postgres/library_capture_reconcile_pg_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 92a7898..e79a661 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,27 @@ # Changelog +## 开发快照 0.1.365(封存终态回写与精确核对) + +### Fixed + +- `AdvanceLibraryJob` / `AdvanceLibraryJobGuarded` / `UpdateLibraryStage` 对 + `varchar` 状态/阶段列的参数显式使用 `::text`,修复真实 DDL 下 + `SQLSTATE 42P08 inconsistent types deduced for parameter $2`;封存终态不再 + 因类型推断失败而停留在 pending。 +- worker 封存开始状态/阶段写入失败时不再吞错进入源导出;成功终态的 stage 与 + job 回写失败返回错误,不把队列 completed 当成业务成功。 +- 新增管理员 `POST /api/v1/library/jobs/{id}/reconcile-capture`:只接受 + completed `library.capture`、精确 job/scope/source 的 `test_sealed` 版本、 + export succeeded 阶段和归档完整复核;修复该作业终态并记录幂等审计操作。 + 不重新封存、不产生快照、不写源或目标知识,不改首因及其他历史记录。 + +### Tests + +- 真实 `varchar(16)/varchar(32)` DDL 的 pending→running→failed→succeeded、 + snapshot/finished_at 与第一因保留回归;`r3i-42p08-red.txt` / `r3i-42p08-green.txt`。 +- worker 持久化失败注入测试;capture reconcile 错 queue/stage/version/source/ + archive 与幂等正例。 + ## 开发快照 0.1.364(恢复保留错误的第一因分类;部署基线稳定性) ### Fixed diff --git a/api/openapi.yaml b/api/openapi.yaml index 56bfad5..d15d2f1 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -1368,6 +1368,45 @@ } } }, + "/api/v1/library/jobs/{id}/reconcile-capture": { + "post": { + "tags": [ + "Runtime" + ], + "operationId": "reconcileLibraryCapture", + "summary": "仅在 completed capture queue、精确 test_sealed 版本与归档复核一致时,修复该封存作业终态;不重新封存", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "已修复或已成功(幂等)" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "description": "需要管理员权限" + }, + "404": { + "description": "作业不存在" + }, + "409": { + "description": "队列/阶段/版本/归档证据不一致,拒绝修复" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, "/api/v1/library/restore-availability": { "get": { "tags": [ diff --git a/cmd/worker/library_capture_persistence_test.go b/cmd/worker/library_capture_persistence_test.go new file mode 100644 index 0000000..67aa202 --- /dev/null +++ b/cmd/worker/library_capture_persistence_test.go @@ -0,0 +1,96 @@ +package main + +import ( + "context" + "errors" + "strings" + "testing" + "time" + + "knowledge-governance/internal/governance" +) + +type capturePersistenceFake struct { + failAdvance error + failStage error + advanced []governance.LibraryJobState + stages []string +} + +func (f *capturePersistenceFake) AdvanceLibraryJob(_ context.Context, _ string, state governance.LibraryJobState, + _, _, _, _, _ string, _ time.Time) error { + f.advanced = append(f.advanced, state) + return f.failAdvance +} + +func (f *capturePersistenceFake) UpdateLibraryStage(_ context.Context, _, stage, state string, + _, _, _, _ *int64, _ string, _ time.Time) error { + f.stages = append(f.stages, stage+"/"+state) + return f.failStage +} + +// The handler must stop before touching the source when the starting state +// cannot be persisted. This is the failure injection that the old log-and-ignore +// path hid behind a completed queue row. +func TestBeginLibraryCaptureStopsOnAdvanceFailure(t *testing.T) { + store := &capturePersistenceFake{failAdvance: errors.New("injected advance failure")} + err := beginLibraryCaptureJob(context.Background(), store, "libseal-test", time.Now()) + if err == nil || !strings.Contains(err.Error(), "cannot be advanced") { + t.Fatalf("err=%v", err) + } + if len(store.advanced) != 1 || store.advanced[0] != governance.LibraryJobRunning { + t.Fatalf("advance calls=%v", store.advanced) + } + if len(store.stages) != 0 { + t.Fatalf("stage was written before advance failure: %v", store.stages) + } +} + +func TestBeginLibraryCaptureStopsOnStageFailure(t *testing.T) { + store := &capturePersistenceFake{failStage: errors.New("injected stage failure")} + err := beginLibraryCaptureJob(context.Background(), store, "libseal-test", time.Now()) + if err == nil || !strings.Contains(err.Error(), "stage cannot be advanced") { + t.Fatalf("err=%v", err) + } + if len(store.stages) != 1 || store.stages[0] != "export/running" { + t.Fatalf("stage calls=%v", store.stages) + } +} + +// Terminal persistence is two writes; either failure must be returned rather +// than turning the queue row into completed while the business job is pending. +func TestCompleteLibraryCaptureStopsOnStageFailure(t *testing.T) { + store := &capturePersistenceFake{failStage: errors.New("injected success stage failure")} + err := completeLibraryCaptureJob(context.Background(), store, "libseal-test", "snap-test", time.Now()) + if err == nil || !strings.Contains(err.Error(), "success stage cannot be persisted") { + t.Fatalf("err=%v", err) + } + if len(store.advanced) != 0 { + t.Fatalf("advance must not run after stage failure: %v", store.advanced) + } +} + +func TestCompleteLibraryCaptureStopsOnAdvanceFailure(t *testing.T) { + store := &capturePersistenceFake{failAdvance: errors.New("injected success advance failure")} + err := completeLibraryCaptureJob(context.Background(), store, "libseal-test", "snap-test", time.Now()) + if err == nil || !strings.Contains(err.Error(), "success terminal cannot be persisted") { + t.Fatalf("err=%v", err) + } + if len(store.stages) != 1 || store.stages[0] != "export/succeeded" { + t.Fatalf("stage calls=%v", store.stages) + } + if len(store.advanced) != 1 || store.advanced[0] != governance.LibraryJobSucceeded { + t.Fatalf("advance calls=%v", store.advanced) + } +} + +func TestCompleteLibraryCapturePersistsBothFacts(t *testing.T) { + store := &capturePersistenceFake{} + if err := completeLibraryCaptureJob(context.Background(), store, "libseal-test", "snap-test", time.Now()); err != nil { + t.Fatal(err) + } + if len(store.stages) != 1 || store.stages[0] != "export/succeeded" || + len(store.advanced) != 1 || store.advanced[0] != governance.LibraryJobSucceeded { + t.Fatalf("stages=%v advanced=%v", store.stages, store.advanced) + } +} diff --git a/cmd/worker/main.go b/cmd/worker/main.go index c65e784..af7e023 100644 --- a/cmd/worker/main.go +++ b/cmd/worker/main.go @@ -288,6 +288,41 @@ func run(ctx context.Context, getenv func(string) string) error { return worker.Run(ctx, config.PollInterval) } +type libraryCapturePersistence interface { + 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 +} + +// beginLibraryCaptureJob persists the starting state before any source +// operation. If either write fails the handler must return, so the queue cannot +// be reported completed while the business job is still pending. +func beginLibraryCaptureJob(ctx context.Context, store libraryCapturePersistence, jobID string, now time.Time) error { + if err := store.AdvanceLibraryJob(ctx, jobID, governance.LibraryJobRunning, "export", "", "", "", "", now); err != nil { + return fmt.Errorf("library seal job %s cannot be advanced: %w", jobID, err) + } + if err := store.UpdateLibraryStage(ctx, jobID, "export", "running", nil, nil, nil, nil, + "主机侧正在暂停写入者、导出并恢复", now); err != nil { + return fmt.Errorf("library seal job %s stage cannot be advanced: %w", jobID, err) + } + return nil +} + +// completeLibraryCaptureJob persists both terminal facts. A failed write must +// be returned (queue failed), not logged and ignored; the capture journal keeps +// replay idempotent, and the admin reconcile path can repair only after the +// exact queue/version/archive evidence is present. +func completeLibraryCaptureJob(ctx context.Context, store libraryCapturePersistence, jobID, snapshotID string, now time.Time) error { + if err := store.UpdateLibraryStage(ctx, jobID, "export", "succeeded", nil, nil, nil, nil, + "已封存快照 "+snapshotID, now); err != nil { + return fmt.Errorf("library seal job %s success stage cannot be persisted: %w", jobID, err) + } + if err := store.AdvanceLibraryJob(ctx, jobID, governance.LibraryJobSucceeded, "export", "", "", + snapshotID, "", now); err != nil { + return fmt.Errorf("library seal job %s success terminal cannot be persisted: %w", jobID, err) + } + return nil +} + func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[string]jobs.Handler, error) { handlers := map[string]jobs.Handler{ "demo": func(_ context.Context, job jobs.Job) error { @@ -349,12 +384,8 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st // 持久作业:页面读的是这里写的阶段与结果,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) + if beginErr := beginLibraryCaptureJob(ctx, store, libraryJobID, startedAt); beginErr != nil { + return beginErr } // 平台审计过的精确死信解除指纹:读取失败必须阻断(fail closed), // 不能因为存储不可用就静默按"没有解除"或"全部解除"处理。 @@ -412,10 +443,9 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st if versionErr != nil { return fmt.Errorf("library seal job %s cannot record version: %w", 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) + if completeErr := completeLibraryCaptureJob(ctx, store, libraryJobID, result.SnapshotID, finishedAt); completeErr != nil { + return completeErr + } 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 diff --git a/internal/httpapi/auth.go b/internal/httpapi/auth.go index 5e372f5..9bea0fd 100644 --- a/internal/httpapi/auth.go +++ b/internal/httpapi/auth.go @@ -148,6 +148,11 @@ func classifyRole(method, path string) string { if strings.HasPrefix(path, "/api/v1/backup-schedule") && method != http.MethodGet { return roleAdmin } + // 核对封存结果会把一个 pending 业务作业修成 succeeded;只允许管理员, + // 且 handler 仍要求 completed queue、精确版本和归档复核。 + if strings.HasPrefix(path, "/api/v1/library/jobs/") && strings.HasSuffix(path, "/reconcile-capture") { + return roleAdmin + } // 版本记录的同步会拉起一次对远端仓库的抓取(消耗网络与数据库写入), // 与"谁能改生产绑定"同级:读任何角色可看,同步只能管理员。 if strings.HasPrefix(path, "/api/v1/version-history") && method != http.MethodGet { diff --git a/internal/httpapi/library_capture_reconcile.go b/internal/httpapi/library_capture_reconcile.go new file mode 100644 index 0000000..b387033 --- /dev/null +++ b/internal/httpapi/library_capture_reconcile.go @@ -0,0 +1,213 @@ +package httpapi + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "strings" + "time" + + "knowledge-governance/internal/governance" + "knowledge-governance/internal/jobs" + "knowledge-governance/internal/librarysnapshot" +) + +// libraryCaptureReconciler is deliberately narrow: it repairs one business +// seal job only after the completed capture queue, the successful export stage, +// the exact test-sealed version and the archived bytes all agree. It never +// captures, freezes writers, creates snapshots, writes source/target content or +// changes historical failure evidence. +type libraryCaptureReconciler interface { + LibraryJob(ctx context.Context, id string) (governance.LibraryJob, error) + LibraryCaptureExportEvidence(ctx context.Context, jobID string) (string, string, error) + LibraryTestSealedVersionForJob(ctx context.Context, scope, jobID string) (governance.LibraryVersion, bool, error) + EnsureLibraryOperation(ctx context.Context, op governance.LibraryOperation) (governance.LibraryOperation, bool, error) + ReconcileLibraryCaptureTerminal(ctx context.Context, jobID, scope, queueJobID, snapshotID string, now time.Time) (bool, error) +} + +type libraryCaptureQueueReader interface { + QueueJob(ctx context.Context, id string) (jobs.Job, bool, error) +} + +func libraryCaptureReconcile(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 := config.Store.(libraryCaptureReconciler) + if !ok { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, + "reason": "封存作业核对存储不可用"}) + return + } + queueStore, ok := config.Store.(libraryCaptureQueueReader) + if !ok { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, + "reason": "队列精确读取不可用"}) + return + } + jobID := strings.TrimSpace(r.PathValue("id")) + if jobID == "" { + writeJSON(w, http.StatusBadRequest, map[string]string{"error": "job id required"}) + return + } + job, err := store.LibraryJob(r.Context(), jobID) + if err != nil { + writeJSON(w, http.StatusNotFound, map[string]any{"available": false, "reason": "作业不存在"}) + return + } + if job.Kind != governance.LibraryJobSeal { + conflict(w, "只有封存作业可以核对封存结果") + return + } + if job.State != governance.LibraryJobPending && job.State != governance.LibraryJobRunning && job.State != governance.LibraryJobSucceeded { + conflict(w, "作业已是失败/取消终态,不能改写成成功") + return + } + if job.QueueJobID == "" { + conflict(w, "作业没有关联队列号,不能证明封存完成") + return + } + captureJob := strings.TrimPrefix(job.ID, "libseal-") + if captureJob == "" || captureJob == job.ID { + conflict(w, "作业号不是封存作业身份") + return + } + queue, found, err := queueStore.QueueJob(r.Context(), job.QueueJobID) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read capture queue"}) + return + } + if !found { + conflict(w, "队列作业不存在,不能证明封存完成") + return + } + if queue.Type != libraryCaptureJobType || queue.State != jobs.StateCompleted { + conflict(w, "队列作业不是 completed 的 library.capture") + return + } + var payload struct { + Scope string `json:"scope"` + CaptureJob string `json:"capture_job"` + } + if err := json.Unmarshal(queue.Payload, &payload); err != nil || + payload.Scope != job.Scope || payload.CaptureJob != captureJob || + queue.IdempotencyKey != "library.capture:"+captureJob { + conflict(w, "队列作业的 scope/capture_job/幂等键与业务作业不一致") + return + } + stageState, _, err := store.LibraryCaptureExportEvidence(r.Context(), job.ID) + if err != nil || stageState != "succeeded" { + conflict(w, "导出阶段没有成功证据,不能修复终态") + return + } + version, found, err := store.LibraryTestSealedVersionForJob(r.Context(), job.Scope, job.ID) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read exact test-sealed version"}) + return + } + if !found || version.Kind != governance.LibraryVersionTestSealed || + version.Scope != job.Scope || version.SourceJobID != job.ID || version.SnapshotID == "" { + conflict(w, "没有与作业/scope 精确绑定的测试封存版本") + return + } + source := configuredLibrarySource(config, job.Scope) + sourceID, err := source.ID() + if err != nil { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, + "reason": "来源身份配置不完整,无法核对封存来源"}) + return + } + evidenceSource, _ := version.Evidence["source_id"].(string) + evidenceCapture, _ := version.Evidence["capture_job"].(string) + if evidenceSource != sourceID || evidenceCapture != captureJob { + conflict(w, "版本来源或 capture_job 与当前作业不一致") + return + } + if config.LibraryArchiveRoot == "" { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, + "reason": "未接线归档根,无法复核归档完整性"}) + return + } + archive, err := librarysnapshot.Open(config.LibraryArchiveRoot, 256*1024*1024) + if err != nil { + writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, + "reason": "归档不可读,不能确认封存完整"}) + return + } + defer archive.Close() + manifest, err := archive.Load(version.SnapshotID) + if err != nil { + conflict(w, "归档字节复核失败,不能修复作业") + return + } + if manifest.Scope != source.Scope || manifest.TenantID != source.TenantID || + manifest.KnowledgeBaseID != source.KnowledgeBaseID { + conflict(w, "归档清单来源身份与当前来源不一致") + return + } + if job.SnapshotID != "" && job.SnapshotID != version.SnapshotID { + conflict(w, "作业已有不同快照,不能覆盖") + return + } + if job.State == governance.LibraryJobSucceeded { + if job.SnapshotID != version.SnapshotID { + conflict(w, "作业已成功但快照与精确版本不一致") + return + } + writeJSON(w, http.StatusOK, map[string]any{ + "repaired": false, "already_succeeded": true, "job_id": job.ID, + "snapshot_id": version.SnapshotID, "queue_job_id": queue.ID, + "version_id": version.ID, + }) + return + } + actor := "" + if identity, ok := sessionFrom(r.Context()); ok { + actor = identity.Username + } + now := time.Now().UTC() + digest, err := governance.LibraryRequestDigest(job.Scope, governance.LibraryJobRecover, map[string]any{ + "kind": "capture_reconcile", "job_id": job.ID, "queue_job_id": queue.ID, + "snapshot_id": version.SnapshotID, "capture_job": captureJob, "stage": "export", + }) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot build reconcile audit digest"}) + return + } + opID := "libop-capture-reconcile-" + digest[:16] + op, _, err := store.EnsureLibraryOperation(r.Context(), governance.LibraryOperation{ + ID: opID, Scope: job.Scope, Kind: governance.LibraryJobRecover, + TargetSnapshotID: version.SnapshotID, RequestDigest: digest, + OperationKey: "capture-reconcile:" + job.ID, Actor: actor, CreatedAt: now, + }) + if errors.Is(err, governance.ErrLibraryOperationConflict) { + conflict(w, "同一核对键对应了不同证据,拒绝修复") + return + } + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot record reconcile audit"}) + return + } + updated, err := store.ReconcileLibraryCaptureTerminal(r.Context(), job.ID, job.Scope, job.QueueJobID, version.SnapshotID, now) + if err != nil { + writeJSON(w, http.StatusInternalServerError, map[string]any{ + "error": "cannot persist reconciled job terminal", "audit_operation_id": op.ID, + }) + return + } + if !updated { + conflict(w, "作业状态/身份在核对期间变化,拒绝覆盖") + return + } + writeJSON(w, http.StatusOK, map[string]any{ + "repaired": true, "already_succeeded": false, "job_id": job.ID, + "snapshot_id": version.SnapshotID, "queue_job_id": queue.ID, + "stage": "export", "version_id": version.ID, "audit_operation_id": op.ID, + }) +} + +func conflict(w http.ResponseWriter, reason string) { + writeJSON(w, http.StatusConflict, map[string]any{"available": false, "repaired": false, "reason": reason}) +} diff --git a/internal/httpapi/library_capture_reconcile_test.go b/internal/httpapi/library_capture_reconcile_test.go new file mode 100644 index 0000000..a5dfe6a --- /dev/null +++ b/internal/httpapi/library_capture_reconcile_test.go @@ -0,0 +1,273 @@ +package httpapi + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "net/http/httptest" + "testing" + "time" + + "knowledge-governance/internal/governance" + "knowledge-governance/internal/jobs" + "knowledge-governance/internal/librarysnapshot" +) + +func (f *fakeLibraryStore) QueueJob(_ context.Context, id string) (jobs.Job, bool, error) { + if f.queue == nil || f.queue.ID != id { + return jobs.Job{}, false, nil + } + return *f.queue, true, nil +} + +func (f *fakeLibraryStore) LibraryCaptureExportEvidence(_ context.Context, _ string) (string, string, error) { + return f.stageState, "", f.stageErr +} + +func (f *fakeLibraryStore) LibraryJobStage(_ context.Context, _, stage string) (string, string, error) { + if f.stageErr != nil { + return "", "", f.stageErr + } + if stage != "export" { + return "", "", errors.New("unexpected stage") + } + return f.stageState, "", nil +} + +func (f *fakeLibraryStore) LibraryTestSealedVersionForJob(_ context.Context, scope, jobID string) (governance.LibraryVersion, bool, error) { + if f.versionErr != nil { + return governance.LibraryVersion{}, false, f.versionErr + } + if f.sealedVersion == nil || f.sealedVersion.Scope != scope || f.sealedVersion.SourceJobID != jobID { + return governance.LibraryVersion{}, false, nil + } + return *f.sealedVersion, true, nil +} + +func reconcileFixture(t *testing.T) (*fakeLibraryStore, Config, governance.LibraryJob, []byte) { + t.Helper() + root := libraryFixtureRoot(t) + snapshotID := sealSharedVersions(t, root, 1, 4)[0] + archive, err := librarysnapshot.Open(root, 256*1024*1024) + if err != nil { + t.Fatal(err) + } + manifest, err := archive.Load(snapshotID) + archive.Close() + if err != nil { + t.Fatal(err) + } + config := Config{LibraryArchiveRoot: root, + LibrarySourceProject: "fixture-project", LibrarySourceApp: "fixture-app", + LibrarySourceTenantID: manifest.TenantID, LibrarySourceInternalKB: manifest.KnowledgeBaseID} + source := configuredLibrarySource(config, "internal") + sourceID, err := source.ID() + if err != nil { + t.Fatal(err) + } + job := governance.LibraryJob{ID: "libseal-cap-1", Scope: "internal", Kind: governance.LibraryJobSeal, + State: governance.LibraryJobPending, QueueJobID: "libcap-1"} + payload, _ := json.Marshal(map[string]string{"scope": "internal", "capture_job": "cap-1"}) + store := &fakeLibraryStore{ + jobs: []governance.LibraryJob{job}, + stageState: "succeeded", + queue: &jobs.Job{ID: "libcap-1", Type: libraryCaptureJobType, State: jobs.StateCompleted, + Payload: payload, IdempotencyKey: "library.capture:cap-1"}, + sealedVersion: &governance.LibraryVersion{ID: "libver-1", Scope: "internal", + Kind: governance.LibraryVersionTestSealed, SnapshotID: snapshotID, SourceJobID: job.ID, + Evidence: map[string]any{"source_id": sourceID, "capture_job": "cap-1"}}, + } + config.Store = store + return store, config, job, payload +} + +func (f *fakeLibraryStore) ReconcileLibraryCaptureTerminal(_ context.Context, jobID, scope, queueJobID, snapshotID string, _ time.Time) (bool, error) { + if f.reconcileDenied { + return false, nil + } + for index := range f.jobs { + if f.jobs[index].ID != jobID || f.jobs[index].Scope != scope || f.jobs[index].Kind != governance.LibraryJobSeal || + f.jobs[index].QueueJobID != queueJobID || (f.jobs[index].State != governance.LibraryJobPending && f.jobs[index].State != governance.LibraryJobRunning) || + (f.jobs[index].SnapshotID != "" && f.jobs[index].SnapshotID != snapshotID) { + return false, nil + } + f.jobs[index].State = governance.LibraryJobSucceeded + f.jobs[index].SnapshotID = snapshotID + f.lastState = governance.LibraryJobSucceeded + return true, nil + } + return false, nil +} +func runReconcile(t *testing.T, config Config, jobID string) *httptest.ResponseRecorder { + t.Helper() + req := httptest.NewRequest(http.MethodPost, "/api/v1/library/jobs/"+jobID+"/reconcile-capture", nil) + req.SetPathValue("id", jobID) + rec := httptest.NewRecorder() + libraryCaptureReconcile(rec, req, config) + return rec +} + +func TestLibraryCaptureReconcileRepairsExactCompletedCapture(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusOK { + t.Fatalf("code=%d body=%s", rec.Code, rec.Body.String()) + } + var body map[string]any + if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil { + t.Fatal(err) + } + if body["repaired"] != true || body["snapshot_id"] == "" || body["audit_operation_id"] == "" { + t.Fatalf("body=%v", body) + } + if store.lastState != governance.LibraryJobSucceeded { + t.Fatalf("advanced state=%s", store.lastState) + } + if len(store.operations) != 1 { + t.Fatalf("audit operations=%v", store.operations) + } +} + +func TestLibraryCaptureReconcileAlreadySucceededIsReadOnly(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + job.State = governance.LibraryJobSucceeded + job.SnapshotID = store.sealedVersion.SnapshotID + store.jobs[0] = job + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusOK { + t.Fatalf("code=%d body=%s", rec.Code, rec.Body.String()) + } + var body map[string]any + _ = json.Unmarshal(rec.Body.Bytes(), &body) + if body["already_succeeded"] != true || body["repaired"] != false || store.lastState != "" { + t.Fatalf("body=%v advanced=%q", body, store.lastState) + } +} + +func TestLibraryCaptureReconcileRejectsQueueNotCompleted(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.queue.State = jobs.StateRunning + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q body=%s", rec.Code, store.lastState, rec.Body.String()) + } +} + +func TestLibraryCaptureReconcileRejectsStageNotSucceeded(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.stageState = "failed" + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q", rec.Code, store.lastState) + } +} + +func TestLibraryCaptureReconcileRejectsWrongVersionSource(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.sealedVersion.Evidence["source_id"] = "other-source" + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q", rec.Code, store.lastState) + } +} + +func TestLibraryCaptureReconcileRejectsWrongCaptureJob(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.sealedVersion.Evidence["capture_job"] = "other-capture" + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q", rec.Code, store.lastState) + } +} + +func TestLibraryCaptureReconcileRejectsBadArchive(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.sealedVersion.SnapshotID = "missing-snapshot" + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q body=%s", rec.Code, store.lastState, rec.Body.String()) + } +} + +func TestLibraryCaptureReconcileRejectsFailedJob(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + job.State = governance.LibraryJobFailed + store.jobs[0] = job + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q", rec.Code, store.lastState) + } +} + +func TestLibraryCaptureReconcileIsIdempotent(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + first := runReconcile(t, config, job.ID) + if first.Code != http.StatusOK { + t.Fatalf("first code=%d body=%s", first.Code, first.Body.String()) + } + second := runReconcile(t, config, job.ID) + if second.Code != http.StatusOK { + t.Fatalf("second code=%d body=%s", second.Code, second.Body.String()) + } + var body map[string]any + _ = json.Unmarshal(second.Body.Bytes(), &body) + if body["already_succeeded"] != true || len(store.operations) != 1 { + t.Fatalf("body=%v ops=%v", body, store.operations) + } +} + +func TestLibraryCaptureReconcileRejectsMissingQueue(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.queue = nil + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q", rec.Code, store.lastState) + } +} + +func TestLibraryCaptureReconcileRejectsQueueScope(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.queue.Payload, _ = json.Marshal(map[string]string{"scope": "external", "capture_job": "cap-1"}) + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q", rec.Code, store.lastState) + } +} + +func TestLibraryCaptureReconcileRejectsMissingVersion(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.sealedVersion = nil + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q", rec.Code, store.lastState) + } +} + +func TestLibraryCaptureReconcileRejectsWrongScopeVersion(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.sealedVersion.Scope = "external" + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q", rec.Code, store.lastState) + } +} + +func TestLibraryCaptureReconcileRejectsDifferentExistingSnapshot(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + job.SnapshotID = "other-snapshot" + store.jobs[0] = job + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q body=%s", rec.Code, store.lastState, rec.Body.String()) + } +} + +func TestLibraryCaptureReconcileConditionalWriteRejectsConcurrentState(t *testing.T) { + store, config, job, _ := reconcileFixture(t) + store.reconcileDenied = true + rec := runReconcile(t, config, job.ID) + if rec.Code != http.StatusConflict || store.lastState != "" { + t.Fatalf("code=%d advanced=%q body=%s", rec.Code, store.lastState, rec.Body.String()) + } +} diff --git a/internal/httpapi/library_flow_test.go b/internal/httpapi/library_flow_test.go index 8face85..352232d 100644 --- a/internal/httpapi/library_flow_test.go +++ b/internal/httpapi/library_flow_test.go @@ -11,6 +11,7 @@ import ( "time" "knowledge-governance/internal/governance" + "knowledge-governance/internal/jobs" ) // 生产闸口与整库状态契约的针对性测试:不做数据库集成,只验证 @@ -37,6 +38,13 @@ type fakeLibraryStore struct { resumeOK bool resumeErr error resumeCalls []string + // capture reconciliation fixtures + queue *jobs.Job + stageState string + stageErr error + sealedVersion *governance.LibraryVersion + versionErr error + reconcileDenied bool } func (f *fakeLibraryStore) CreateLibraryJob(_ context.Context, job governance.LibraryJob, _ []string, _ time.Time) (governance.LibraryJob, bool, error) { @@ -127,8 +135,16 @@ func (f *fakeLibraryStore) UpdateLibraryStage(_ context.Context, _, _, _ string, return nil } -func (f *fakeLibraryStore) AdvanceLibraryJob(_ context.Context, _ string, state governance.LibraryJobState, _, _, _, _, _ string, _ time.Time) error { +func (f *fakeLibraryStore) AdvanceLibraryJob(_ context.Context, jobID string, state governance.LibraryJobState, _, _, _, snapshotID, _ string, _ time.Time) error { f.lastState = state + for index := range f.jobs { + if f.jobs[index].ID == jobID { + f.jobs[index].State = state + if snapshotID != "" { + f.jobs[index].SnapshotID = snapshotID + } + } + } return nil } diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go index 1e77aed..621d825 100644 --- a/internal/httpapi/server.go +++ b/internal/httpapi/server.go @@ -559,6 +559,10 @@ func NewHandler(config Config) (http.Handler, error) { mux.HandleFunc("POST /api/v1/library/jobs/{id}/resume", func(w http.ResponseWriter, r *http.Request) { libraryJobResume(w, r, config) }) + // 封存完成但终态回写失败时,只按已完成队列+精确版本+归档复核修复该作业。 + mux.HandleFunc("POST /api/v1/library/jobs/{id}/reconcile-capture", func(w http.ResponseWriter, r *http.Request) { + libraryCaptureReconcile(w, r, config) + }) // 生产同步唯一入口:闸口未齐不建作业,返回缺项而不是假 Accepted。 mux.HandleFunc("POST /api/v1/library/syncs", func(w http.ResponseWriter, r *http.Request) { librarySyncEnqueue(w, r, config) diff --git a/internal/platform/postgres/library_capture_reconcile_pg_test.go b/internal/platform/postgres/library_capture_reconcile_pg_test.go new file mode 100644 index 0000000..fcbbefd --- /dev/null +++ b/internal/platform/postgres/library_capture_reconcile_pg_test.go @@ -0,0 +1,97 @@ +package postgres + +import ( + "context" + "os" + "strings" + "testing" + "time" + + "github.com/jackc/pgx/v5/pgxpool" +) + +// This exercises the exact SQL used by the admin capture reconcile path with +// the real varchar/jsonb/timestamptz column shapes from the migration. Fake +// stores cannot catch parameter-type mistakes, as the 42P08 incident showed. +func TestCaptureReconcileExactPostgresPath(t *testing.T) { + dsn := os.Getenv("KG_LIBRARY_TEST_DATABASE_URL") + if dsn == "" { + t.Skip("requires explicitly isolated kg_library_test_ PostgreSQL database") + } + cfg, err := pgxpool.ParseConfig(dsn) + if err != nil || !strings.HasPrefix(cfg.ConnConfig.Database, "kg_library_test_") || os.Getenv("KG_LIBRARY_TEST_ISOLATED") != "1" { + t.Fatal("isolated database required") + } + cfg.MaxConns = 1 + cfg.ConnConfig.RuntimeParams["search_path"] = "pg_temp" + ctx := context.Background() + pool, err := pgxpool.NewWithConfig(ctx, cfg) + if err != nil { + t.Fatal(err) + } + defer pool.Close() + if _, err := pool.Exec(ctx, ` +CREATE TEMP TABLE library_jobs( + id varchar(64) PRIMARY KEY, scope varchar(16) NOT NULL, kind varchar(16) NOT NULL, + state varchar(16) NOT NULL, queue_job_id varchar(64) NOT NULL DEFAULT '', + stage varchar(32) NOT NULL DEFAULT '', snapshot_id varchar(64) NOT NULL DEFAULT '', + error text NOT NULL DEFAULT '', updated_at timestamptz NOT NULL, finished_at timestamptz); +CREATE TEMP TABLE library_job_stages( + job_id varchar(64) NOT NULL, stage varchar(32) NOT NULL, state varchar(16) NOT NULL, + detail text NOT NULL DEFAULT '', updated_at timestamptz NOT NULL, PRIMARY KEY(job_id,stage)); +CREATE TEMP TABLE library_versions( + id varchar(64) PRIMARY KEY, scope varchar(16) NOT NULL, kind varchar(24) NOT NULL, + snapshot_id varchar(64) NOT NULL DEFAULT '', version_label varchar(64) NOT NULL DEFAULT '', + source_job_id varchar(64) NOT NULL DEFAULT '', operation_id varchar(64) NOT NULL DEFAULT '', + attempt_epoch integer NOT NULL DEFAULT 0, evidence jsonb NOT NULL DEFAULT '{}'::jsonb, + created_by varchar(128) NOT NULL DEFAULT '', created_at timestamptz NOT NULL, + superseded_at timestamptz); +INSERT INTO library_jobs(id,scope,kind,state,queue_job_id,updated_at) + VALUES('libseal-cap-1','internal','seal','pending','libcap-1',now()); +INSERT INTO library_job_stages(job_id,stage,state,updated_at) + VALUES('libseal-cap-1','export','succeeded',now()); +INSERT INTO library_versions(id,scope,kind,snapshot_id,source_job_id,created_at) + VALUES('libver-1','internal','test_sealed','snap-1','libseal-cap-1',now());`); err != nil { + t.Fatal(err) + } + store := NewStore(pool) + state, _, err := store.LibraryCaptureExportEvidence(ctx, "libseal-cap-1") + if err != nil || state != "succeeded" { + t.Fatalf("export evidence state=%q err=%v", state, err) + } + version, found, err := store.LibraryTestSealedVersionForJob(ctx, "internal", "libseal-cap-1") + if err != nil || !found || version.SnapshotID != "snap-1" { + t.Fatalf("version found=%v snapshot=%q err=%v", found, version.SnapshotID, err) + } + now := time.Now().UTC() + updated, err := store.ReconcileLibraryCaptureTerminal(ctx, "libseal-cap-1", "internal", "libcap-1", "snap-1", now) + if err != nil || !updated { + t.Fatalf("conditional repair updated=%v err=%v", updated, err) + } + var gotState, gotScope, gotSnapshot string + var finished bool + if err := pool.QueryRow(ctx, `SELECT state, scope, snapshot_id, finished_at IS NOT NULL FROM library_jobs WHERE id='libseal-cap-1'`). + Scan(&gotState, &gotScope, &gotSnapshot, &finished); err != nil { + t.Fatal(err) + } + if gotState != "succeeded" || gotScope != "internal" || gotSnapshot != "snap-1" || !finished { + t.Fatalf("terminal state=%q scope=%q snapshot=%q finished=%v", gotState, gotScope, gotSnapshot, finished) + } + if updated, err := store.ReconcileLibraryCaptureTerminal(ctx, "libseal-cap-1", "internal", "libcap-1", "snap-1", now.Add(time.Second)); err != nil || updated { + t.Fatalf("second repair must be idempotent/false: updated=%v err=%v", updated, err) + } + if _, err := pool.Exec(ctx, `INSERT INTO library_jobs(id,scope,kind,state,queue_job_id,updated_at) + VALUES('libseal-failed','internal','seal','failed','libcap-2',now())`); err != nil { + t.Fatal(err) + } + if updated, err := store.ReconcileLibraryCaptureTerminal(ctx, "libseal-failed", "internal", "libcap-2", "snap-2", now); err != nil || updated { + t.Fatalf("failed row must not be repaired: updated=%v err=%v", updated, err) + } + if _, err := pool.Exec(ctx, `INSERT INTO library_jobs(id,scope,kind,state,queue_job_id,snapshot_id,updated_at) + VALUES('libseal-other','internal','seal','running','libcap-3','other',now())`); err != nil { + t.Fatal(err) + } + if updated, err := store.ReconcileLibraryCaptureTerminal(ctx, "libseal-other", "internal", "libcap-3", "snap-3", now); err != nil || updated { + t.Fatalf("different existing snapshot must not be overwritten: updated=%v err=%v", updated, err) + } +} diff --git a/internal/platform/postgres/library_jobs.go b/internal/platform/postgres/library_jobs.go index 11cb293..320c56d 100644 --- a/internal/platform/postgres/library_jobs.go +++ b/internal/platform/postgres/library_jobs.go @@ -205,12 +205,12 @@ func (s *Store) ListLibraryJobs(ctx context.Context, scope string, limit int) ([ 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, + state = CASE WHEN $3::text='' THEN state ELSE $3::text 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, + detail = CASE WHEN $8::text='' THEN detail ELSE $8::text END, updated_at = $9 WHERE job_id=$1 AND stage=$2`, jobID, stage, state, total, completed, bytesTotal, bytesDone, detail, now.UTC()) if err != nil { @@ -245,19 +245,20 @@ func (s *Store) AdvanceLibraryJob(ctx context.Context, jobID string, state gover } tag, err := s.db.Exec(ctx, ` UPDATE library_jobs SET - state=$2, - stage = CASE WHEN $3='' THEN stage ELSE $3 END, + state=$2::text, + stage = CASE WHEN $3::text='' THEN stage ELSE $3::text END, -- 失败重试不得把第一因覆盖成第二次“already exists”;成功时清除旧错误, - -- 但新的 failed 状态保留已记录的第一条失败原因。 + -- 但新的 failed 状态保留已记录的第一条失败原因。显式 ::text 让所有对 $2 + -- 的引用推导为同一类型;否则 varchar 列赋值与 CASE 文本比较会触发 42P08。 error = CASE - WHEN $2='succeeded' THEN '' - WHEN $4='' THEN error - WHEN $2='failed' AND error<>'' THEN error - ELSE $4 + WHEN $2::text='succeeded' THEN '' + WHEN $4::text='' THEN error + WHEN $2::text='failed' AND error<>'' THEN error + ELSE $4::text 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, + recovery = CASE WHEN $5::text='' THEN recovery ELSE $5::text END, + snapshot_id = CASE WHEN $6::text='' THEN snapshot_id ELSE $6::text END, + target_snapshot_id = CASE WHEN $7::text='' THEN target_snapshot_id ELSE $7::text END, updated_at=$8, finished_at=COALESCE($9, finished_at) WHERE id=$1`, jobID, string(state), stage, message, recovery, snapshotID, targetSnapshotID, now.UTC(), finished) @@ -270,6 +271,81 @@ WHERE id=$1`, jobID, string(state), stage, message, recovery, snapshotID, target return nil } +// LibraryCaptureExportEvidence is the exact export-stage evidence used by the +// admin capture reconciliation gate. It is a named method so callers do not +// drift into a "latest stage" or generic list query. +func (s *Store) LibraryCaptureExportEvidence(ctx context.Context, jobID string) (string, string, error) { + return s.LibraryJobStage(ctx, jobID, "export") +} + +// LibraryJobStage reads one exact stage row. The customer-visible job row is +// authoritative for state; this is the export-stage evidence used by the +// capture reconciliation gate. +func (s *Store) LibraryJobStage(ctx context.Context, jobID, stage string) (string, string, error) { + if jobID == "" || stage == "" { + return "", "", errors.New("library stage requires job and stage") + } + var state, detail string + err := s.db.QueryRow(ctx, `SELECT state, detail FROM library_job_stages WHERE job_id=$1 AND stage=$2`, jobID, stage).Scan(&state, &detail) + if errors.Is(err, pgx.ErrNoRows) { + return "", "", errors.New("library stage not found") + } + if err != nil { + return "", "", fmt.Errorf("read library stage: %w", err) + } + return state, detail, nil +} + +// LibraryTestSealedVersionForJob finds the immutable test-sealed version by +// exact (scope, source_job_id), never by "latest N". More than one row means +// the ledger is ambiguous and must be rejected instead of picking one. +func (s *Store) LibraryTestSealedVersionForJob(ctx context.Context, scope, jobID string) (governance.LibraryVersion, bool, error) { + if scope == "" || jobID == "" { + return governance.LibraryVersion{}, false, errors.New("test sealed version requires scope and job") + } + rows, err := s.db.Query(ctx, ` +SELECT id, scope, kind, snapshot_id, version_label, source_job_id, operation_id, attempt_epoch, + evidence, created_by, created_at, superseded_at +FROM library_versions +WHERE scope=$1 AND kind='test_sealed' AND source_job_id=$2 +ORDER BY created_at DESC, id DESC LIMIT 2`, scope, jobID) + if err != nil { + return governance.LibraryVersion{}, false, fmt.Errorf("read test sealed version for job: %w", err) + } + items, err := scanLibraryVersions(rows, 2) + if err != nil { + return governance.LibraryVersion{}, false, err + } + if len(items) > 1 { + return governance.LibraryVersion{}, false, fmt.Errorf("job %s has %d test-sealed rows; refuse to pick one", jobID, len(items)) + } + if len(items) == 1 { + return items[0], true, nil + } + return governance.LibraryVersion{}, false, nil +} + +// ReconcileLibraryCaptureTerminal is the only write allowed to repair a seal +// terminal during admin reconciliation. It is conditional on the exact job, +// scope, kind, queue/capture identity and an in-flight state; a concurrent +// failed/cancelled row or a different snapshot is never overwritten. +func (s *Store) ReconcileLibraryCaptureTerminal(ctx context.Context, jobID, scope, queueJobID, snapshotID string, now time.Time) (bool, error) { + if jobID == "" || scope == "" || queueJobID == "" || snapshotID == "" { + return false, errors.New("reconcile capture terminal requires job/scope/queue/snapshot") + } + tag, err := s.db.Exec(ctx, ` +UPDATE library_jobs +SET state='succeeded', stage='export', error='', snapshot_id=$4, + updated_at=$5, finished_at=$5 +WHERE id=$1 AND scope=$2 AND kind='seal' AND queue_job_id=$3 + AND state IN ('pending','running') + AND (snapshot_id='' OR snapshot_id=$4)`, jobID, scope, queueJobID, snapshotID, now.UTC()) + if err != nil { + return false, fmt.Errorf("reconcile capture terminal: %w", err) + } + return tag.RowsAffected() == 1, nil +} + // RecordLibraryVersion 写入一条**不可变版本事件**,并在需要时推进 current 指针。 // // 与旧实现的区别(F02/F09 的根因): diff --git a/internal/platform/postgres/library_jobs_first_error_pg_test.go b/internal/platform/postgres/library_jobs_first_error_pg_test.go index 929e2a4..3ef201a 100644 --- a/internal/platform/postgres/library_jobs_first_error_pg_test.go +++ b/internal/platform/postgres/library_jobs_first_error_pg_test.go @@ -33,13 +33,36 @@ func TestAdvanceLibraryJobPreservesFirstFailure(t *testing.T) { defer pool.Close() if _, err := pool.Exec(ctx, ` CREATE TEMP TABLE library_jobs( - id text primary key, state text, stage text, error text, recovery text, - snapshot_id text, target_snapshot_id text, updated_at timestamptz, finished_at timestamptz); -INSERT INTO library_jobs(id,state,stage,error) VALUES('libseal-retry','running','export','');`); err != nil { + id text primary key, state varchar(16) NOT NULL CHECK (state IN ('pending','running','succeeded','failed','cancelled')), + stage varchar(32) NOT NULL DEFAULT '', error text NOT NULL DEFAULT '', recovery varchar(255) NOT NULL DEFAULT '', + snapshot_id varchar(64) NOT NULL DEFAULT '', target_snapshot_id varchar(64) NOT NULL DEFAULT '', + updated_at timestamptz NOT NULL, finished_at timestamptz); +INSERT INTO library_jobs(id,state,stage,error,updated_at) VALUES('libseal-retry','pending','','',now()); +CREATE TEMP TABLE library_job_stages( + job_id text, stage varchar(32), state varchar(16), total bigint, completed bigint, + bytes_total bigint, bytes_done bigint, detail text, updated_at timestamptz, primary key(job_id,stage)); +INSERT INTO library_job_stages(job_id,stage,state,updated_at) VALUES('libseal-retry','export','pending',now());`); err != nil { t.Fatal(err) } store := NewStore(pool) now := time.Now().UTC() + if err := store.UpdateLibraryStage(ctx, "libseal-retry", "export", "running", nil, nil, nil, nil, "started", now); err != nil { + t.Fatalf("update stage with real varchar types: %v", err) + } + if stageState, _, err := store.LibraryJobStage(ctx, "libseal-retry", "export"); err != nil || stageState != "running" { + t.Fatalf("read stage state=%q err=%v", stageState, err) + } + if err := store.AdvanceLibraryJob(ctx, "libseal-retry", governance.LibraryJobRunning, "export", "", "", "", "", now); err != nil { + t.Fatal(err) + } + var state, stage string + var finished bool + if err := pool.QueryRow(ctx, `SELECT state, stage, finished_at IS NULL FROM library_jobs WHERE id='libseal-retry'`).Scan(&state, &stage, &finished); err != nil { + t.Fatal(err) + } + if state != "running" || stage != "export" || !finished { + t.Fatalf("running transition not persisted: state=%q stage=%q finished_null=%v", state, stage, finished) + } if err := store.AdvanceLibraryJob(ctx, "libseal-retry", governance.LibraryJobFailed, "export", "first validation failure", "", "", "", now); err != nil { t.Fatal(err) } @@ -47,18 +70,25 @@ INSERT INTO library_jobs(id,state,stage,error) VALUES('libseal-retry','running', t.Fatal(err) } var got string - if err := pool.QueryRow(ctx, `SELECT error FROM library_jobs WHERE id='libseal-retry'`).Scan(&got); err != nil { + var snap string + if err := pool.QueryRow(ctx, `SELECT state, error, finished_at IS NOT NULL, snapshot_id FROM library_jobs WHERE id='libseal-retry'`).Scan(&state, &got, &finished, &snap); err != nil { t.Fatal(err) } + if state != "failed" || !finished || snap != "" { + t.Fatalf("failed transition not persisted: state=%q finished=%v snapshot=%q", state, finished, snap) + } if got != "first validation failure" { t.Fatalf("first failure overwritten: %q", got) } if err := store.AdvanceLibraryJob(ctx, "libseal-retry", governance.LibraryJobSucceeded, "export", "", "", "snap-ok", "", now.Add(2*time.Second)); err != nil { t.Fatal(err) } - if err := pool.QueryRow(ctx, `SELECT error FROM library_jobs WHERE id='libseal-retry'`).Scan(&got); err != nil { + if err := pool.QueryRow(ctx, `SELECT state, error, snapshot_id, finished_at IS NOT NULL FROM library_jobs WHERE id='libseal-retry'`).Scan(&state, &got, &snap, &finished); err != nil { t.Fatal(err) } + if state != "succeeded" || !finished || snap != "snap-ok" { + t.Fatalf("succeeded transition not persisted: state=%q finished=%v snapshot=%q", state, finished, snap) + } if got != "" { t.Fatalf("success must clear old error, got %q", got) } diff --git a/internal/platform/postgres/library_write_fence.go b/internal/platform/postgres/library_write_fence.go index dba5b5a..1fe7081 100644 --- a/internal/platform/postgres/library_write_fence.go +++ b/internal/platform/postgres/library_write_fence.go @@ -57,12 +57,12 @@ func (s *Store) AdvanceLibraryJobGuarded(ctx context.Context, attempt governance } 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, + state=$2::text, + stage = CASE WHEN $3::text='' THEN stage ELSE $3::text END, + error = CASE WHEN $4::text='' THEN error ELSE $4::text END, + recovery = CASE WHEN $5::text='' THEN recovery ELSE $5::text END, + snapshot_id = CASE WHEN $6::text='' THEN snapshot_id ELSE $6::text END, + target_snapshot_id = CASE WHEN $7::text='' THEN target_snapshot_id ELSE $7::text END, updated_at=$8, finished_at=COALESCE($9, finished_at) WHERE id=$1 AND `+libraryFence("$1", 10, 11), @@ -82,12 +82,12 @@ func (s *Store) UpdateLibraryStageGuarded(ctx context.Context, attempt governanc 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, + state = CASE WHEN $3::text='' THEN state ELSE $3::text 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, + detail = CASE WHEN $8::text='' THEN detail ELSE $8::text END, updated_at = $9 WHERE job_id=$1 AND stage=$2 AND `+libraryFence("$1", 10, 11), attempt.JobID, stage, state, total, completed, bytesTotal, bytesDone, detail, now.UTC(), diff --git a/internal/platform/postgres/queue_sql.go b/internal/platform/postgres/queue_sql.go index e2c0c80..909e3f5 100644 --- a/internal/platform/postgres/queue_sql.go +++ b/internal/platform/postgres/queue_sql.go @@ -134,6 +134,14 @@ SELECT id FROM updated // One job type, newest first: a caller which needs "the recent jobs of MY type" // must not page the global queue (other traffic would hide its own rows). +const jobByIDSQL = ` +SELECT id, type, payload, state, priority, available_at, + lease_owner, lease_until, attempt, max_attempts, + last_error, idempotency_key, created_at, updated_at +FROM jobs +WHERE id = $1 +` + const listJobsByTypeSQL = ` SELECT id, type, payload, state, priority, available_at, lease_owner, lease_until, attempt, max_attempts, diff --git a/internal/platform/postgres/store.go b/internal/platform/postgres/store.go index 939fba1..ae10e5c 100644 --- a/internal/platform/postgres/store.go +++ b/internal/platform/postgres/store.go @@ -101,6 +101,21 @@ func (s *Store) Claim(ctx context.Context, workerID string, allowedTypes []strin // ListByType lists only the requested job type, so a busy queue cannot hide the // caller's own recent jobs behind unrelated traffic. +// QueueJob reads one queue row by exact id (no window / no type filter). +func (s *Store) QueueJob(ctx context.Context, id string) (jobs.Job, bool, error) { + if strings.TrimSpace(id) == "" { + return jobs.Job{}, false, errors.New("queue job id required") + } + job, err := scanJob(s.db.QueryRow(ctx, jobByIDSQL, id)) + if errors.Is(err, pgx.ErrNoRows) { + return jobs.Job{}, false, nil + } + if err != nil { + return jobs.Job{}, false, fmt.Errorf("read queue job: %w", err) + } + return *job, true, nil +} + func (s *Store) ListByType(ctx context.Context, jobType string, limit int) ([]jobs.Job, error) { if strings.TrimSpace(jobType) == "" || limit < 1 || limit > 200 { return nil, errors.New("list jobs by type requires a type and a bounded limit") diff --git a/web/src/ReleaseTargets.test.tsx b/web/src/ReleaseTargets.test.tsx index 04cfbec..ee11eb8 100644 --- a/web/src/ReleaseTargets.test.tsx +++ b/web/src/ReleaseTargets.test.tsx @@ -171,6 +171,9 @@ const base: ViewProps = { pendingCapture: false, canCapture: true, canWrite: true, + canReconcileCapture: false, + pendingReconcileCapture: '', + onReconcileCapture: vi.fn(), canRestore: false, sync: { canSign: false, pendingGrant: false, onGrant: vi.fn(), canStart: false, pending: false, onStart: vi.fn() }, baseline: { canStart: false, pending: false, onStart: vi.fn() }, @@ -723,6 +726,24 @@ describe('ReleaseTargetsView(确认稿布局)', () => { expect(html).not.toContain('已完成 0 / 0') }) + it('封存已完成但终态未回写时,管理员看到核对入口;工程师不显示', () => { + const reconciled: LibraryJobRecord = { + ...persistedSeal, + stages: [{ ...persistedSeal.stages[0], state: 'succeeded', detail: '已封存快照 f992d64ea45b' }], + } + const admin = render({ + canReconcileCapture: true, + onReconcileCapture: vi.fn(), + overview: { ...overview, job: reconciled, jobs: [reconciled] }, + }) + expect(admin).toContain('核对封存结果') + const engineer = render({ + canReconcileCapture: false, + overview: { ...overview, job: reconciled, jobs: [reconciled] }, + }) + expect(engineer).not.toContain('核对封存结果') + }) + it('封存作业只显示只读导出步骤,不冒充生产备份/同步/生效或目标维护', () => { const html = render({ jobs: [runningJob], diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx index f4edc70..14d338f 100644 --- a/web/src/ReleaseTargets.tsx +++ b/web/src/ReleaseTargets.tsx @@ -15,6 +15,7 @@ import { fetchLibraryOverview, fetchLibraryRestoreAvailability, fetchLibrarySnapshots, + reconcileLibraryCapture, formatBytes, scopeLabel, type LibraryCaptureJob, @@ -117,6 +118,10 @@ interface ViewProps { pendingCapture: boolean canCapture: boolean canWrite: boolean + // 管理员核对已完成 queue/精确版本/归档后修复 pending 封存作业终态。 + canReconcileCapture: boolean + pendingReconcileCapture: string + onReconcileCapture: (jobID: string) => void // 发布动作:签发授权(管理员)与启动同步是两个独立步骤,页面绝不自动签发。 sync: ReleaseSyncActions // 目标非空又没有生效版本时,唯一入口是"建立目标权威基线"(管理员)。 @@ -1081,14 +1086,28 @@ function ReadyBody({ ) } -function ProgressBody({ view, now, onOpen }: { view: ScopeView; now: number; onOpen: () => void }) { +function ProgressBody({ + view, + now, + onOpen, + canReconcileCapture, + pendingReconcileCapture, + onReconcileCapture, +}: { + view: ScopeView + now: number + onOpen: () => void + canReconcileCapture: boolean + pendingReconcileCapture: string + onReconcileCapture: (jobID: string) => void +}) { const job = view.job const sealJob = job?.kind === 'seal' ? job : undefined // 四类数据阶段对同步/恢复/基线都成立:分项读的是这份作业自己的阶段, // 不是"只有 sync 才有"。写死 sync 会让恢复作业的分项全显示"未接入"。 const dataJob = job && job.kind !== 'seal' ? job : undefined const running = job?.state === 'running' || job?.state === 'pending' - const stage = (name: string) => dataJob?.stages.find((item) => item.stage === name) + const stage = (name: string) => (dataJob ?? sealJob)?.stages.find((item) => item.stage === name) // F11: counts must belong to the snapshot this job actually used. A newly // sealed test version must not decorate an older sync/restore/verify job. @@ -1176,6 +1195,22 @@ function ProgressBody({ view, now, onOpen }: { view: ScopeView; now: number; onO {job?.recovery ? ` · 恢复:${job.recovery}` : ''}

+ {sealJob && + canReconcileCapture && + (sealJob.state === 'pending' || sealJob.state === 'running') && + stage('export')?.state === 'succeeded' ? ( +
+ 队列已完成、导出阶段已成功,但作业终态尚未回写。 + +
+ ) : null}
当前: @@ -1806,6 +1841,9 @@ export function ReleaseTargetsView(props: ViewProps) { pendingCapture, canCapture, canWrite, + canReconcileCapture, + pendingReconcileCapture, + onReconcileCapture, sync, baseline, verification, @@ -2046,7 +2084,14 @@ export function ReleaseTargetsView(props: ViewProps) { /> {active ? ( - onDrawer(true)} /> + onDrawer(true)} + canReconcileCapture={canReconcileCapture} + pendingReconcileCapture={pendingReconcileCapture} + onReconcileCapture={onReconcileCapture} + /> ) : ( (null) const [pendingCapture, setPendingCapture] = useState(false) + const [pendingReconcileCapture, setPendingReconcileCapture] = useState('') const [now, setNow] = useState(() => Date.now()) const load = useCallback(async (signal?: AbortSignal) => { @@ -2348,6 +2394,24 @@ export function ReleaseTargets() { } } + const reconcileCapture = async (jobID: string) => { + setPendingReconcileCapture(jobID) + setNotice(null) + try { + const result = await reconcileLibraryCapture(jobID) + setNotice( + result.already_succeeded + ? `封存作业 ${jobID} 已是成功终态,未重复写入` + : `已核对封存结果:${jobID} → ${result.snapshot_id.slice(0, 12)}(审计 ${result.audit_operation_id ?? '已记录'})` + ) + await load() + } catch (reconcileError) { + setNotice(reconcileError instanceof Error ? reconcileError.message : '核对封存结果失败') + } finally { + setPendingReconcileCapture('') + } + } + const recover = async (windowJobID: string) => { setNotice(null) try { @@ -2400,6 +2464,9 @@ export function ReleaseTargets() { pendingCapture={pendingCapture} canCapture={canCapture} canWrite={canWrite} + canReconcileCapture={role === 'admin'} + pendingReconcileCapture={pendingReconcileCapture} + onReconcileCapture={(jobID) => void reconcileCapture(jobID)} sync={{ canSign: canSignSync, pendingGrant: pendingSyncGrant, diff --git a/web/src/librarySnapshots.ts b/web/src/librarySnapshots.ts index 981bb96..8375b2f 100644 --- a/web/src/librarySnapshots.ts +++ b/web/src/librarySnapshots.ts @@ -385,6 +385,37 @@ export async function fetchLibraryCaptures(signal?: AbortSignal): Promise { + const response = await fetch(`/api/v1/library/jobs/${encodeURIComponent(id)}/reconcile-capture`, { + method: 'POST', + headers: { Accept: 'application/json' }, + }) + const value = (await response.json().catch(() => null)) as unknown + const body = record(value) ? value : {} + if (!response.ok) { + throw new Error(text(body.reason) || text(body.error) || `核对封存结果失败(HTTP ${response.status})`) + } + return { + repaired: body.repaired === true, + already_succeeded: body.already_succeeded === true, + job_id: text(body.job_id), + snapshot_id: text(body.snapshot_id), + queue_job_id: text(body.queue_job_id), + audit_operation_id: text(body.audit_operation_id), + reason: text(body.reason), + } +} export function formatBytes(bytes: number): string { if (!Number.isFinite(bytes) || bytes <= 0) return '0 B' const units = ['B', 'KB', 'MB', 'GB', 'TB']