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']