From bf049cee1fe7e2ed6e96cc46d30b1784e563b061 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Wed, 28 Oct 2026 01:05:44 +0800 Subject: [PATCH] =?UTF-8?q?fix(snapshot):=20=E6=9A=82=E5=81=9C=E5=89=8D?= =?UTF-8?q?=E5=90=8E=E5=BC=BA=E5=88=B6=E6=A3=80=E6=9F=A5=E5=85=B1=E4=BA=AB?= =?UTF-8?q?=E6=BA=90=E5=85=A8=E5=BA=93=E4=BB=BB=E5=8A=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 7 ++++ docs/library-sync-acceptance.md | 2 +- .../releaseadapter/v071/library_capture.go | 6 +++ .../v071/library_capture_test.go | 21 ++++++---- .../v071/library_export_integration_test.go | 32 ++++++++++++++++ .../v071/library_export_test.go | 5 +++ .../v071/library_source_settlement.go | 38 +++++++++++++++++++ 7 files changed, 103 insertions(+), 8 deletions(-) create mode 100644 internal/releaseadapter/v071/library_source_settlement.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 8211441..bb853b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 开发快照 snapshot/v0.1.100 - 2026-10-28 + +### Fixed + +- 测试封存暂停共享写入服务前及暂停后,强制检查整个源数据库的解析状态、待处理任务和死信;其他库、其他租户及已删除或未知任务范围的未完成工作均阻断封存。 +- 保留部署侧入口与后台作业检查;数据库任务结清不代表 Wiki 语义验收通过。本次未清理死信、未暂停实际测试 WeKnora、未执行生产发布。 + ## 开发快照 snapshot/v0.1.99 - 2026-10-28 ### Fixed diff --git a/docs/library-sync-acceptance.md b/docs/library-sync-acceptance.md index c2fda01..1a08d32 100644 --- a/docs/library-sync-acceptance.md +++ b/docs/library-sync-acceptance.md @@ -101,4 +101,4 @@ 已新增 `internal/releaseadapter/v071/library_capture.go`,在源服务组互斥下串起预检、暂停、停后复检、PG/ES 导出、独立归档和恢复。协调测试使用 PG/服务控制夹具与 HTTP 搜索夹具,覆盖预检忙时零停止、暂停前后新增任务阻断、搜索失败恢复、旧作业重放不重新暂停、跨 scope 复用拒绝、归档丢失不返回成功;不把这组夹具当成实际业务知识库全链路验收。最终竞态回归、隔离 Docker 重跑与 `make verify` 均退出码 0,最终日志为同目录 `kg-freeze-docker-final.log`、`kg-library-freeze-final-verify.log`。 -**仍缺少的接线**:真实测试部署的全部写入者枚举及标签/健康契约、全源任务就绪检查的实际提供方、worker 调用捕获协调函数、启动恢复入口和持续恢复调度。单独的本地 Docker 控制器不能控制远端测试主机;远端场景需在测试主机运行受限执行器,不能向浏览器或普通 API 暴露 Docker socket。上述测试不能证明这些接线已完成,尚未暂停实际测试 WeKnora。 +**仍缺少的接线**:真实测试部署的全部写入者枚举及标签/健康契约、部署侧入口及后台作业就绪检查的实际提供方、worker 调用捕获协调函数、启动恢复入口和持续恢复调度。`CaptureLibrary` 已强制在暂停前后检查整个源数据库的解析、pending 与 dead-letter 状态(跨库、跨租户及未知/删除范围);此检查不能代替入口隔离与 Wiki 语义验收。单独的本地 Docker 控制器不能控制远端测试主机;远端场景需在测试主机运行受限执行器,不能向浏览器或普通 API 暴露 Docker socket。上述测试不能证明这些接线已完成,尚未暂停实际测试 WeKnora。 diff --git a/internal/releaseadapter/v071/library_capture.go b/internal/releaseadapter/v071/library_capture.go index 636a31f..8ba5c7b 100644 --- a/internal/releaseadapter/v071/library_capture.go +++ b/internal/releaseadapter/v071/library_capture.go @@ -28,6 +28,9 @@ func CaptureLibrary(ctx context.Context, freeze *libraryfreeze.Coordinator, arch return libraryfreeze.Result{}, errors.New("invalid library capture configuration") } result, err := freeze.RunPrepared(ctx, req.JobID, func(ctx context.Context) error { + if err := checkLibrarySourceSettlement(ctx, db); err != nil { + return err + } if err := sourceReady(ctx); err != nil { return err } @@ -36,6 +39,9 @@ func CaptureLibrary(ctx context.Context, freeze *libraryfreeze.Coordinator, arch _, err := ExportLibrary(ctx, db, req.Identity) return err }, func(ctx context.Context) (string, error) { + if err := checkLibrarySourceSettlement(ctx, db); err != nil { + return "", err + } if err := sourceReady(ctx); err != nil { return "", err } diff --git a/internal/releaseadapter/v071/library_capture_test.go b/internal/releaseadapter/v071/library_capture_test.go index fe96fea..275f2d3 100644 --- a/internal/releaseadapter/v071/library_capture_test.go +++ b/internal/releaseadapter/v071/library_capture_test.go @@ -15,10 +15,11 @@ import ( ) type captureWriter struct { - running atomic.Bool - db *libraryFixture - late bool - stops int + running atomic.Bool + db *libraryFixture + late bool + lateSource bool + stops int } func (c *captureWriter) Inventory(context.Context) ([]libraryfreeze.Service, error) { @@ -31,14 +32,20 @@ func (c *captureWriter) Stop(context.Context, string) error { if c.late { c.db.tx.pending = 1 } + if c.lateSource { + c.db.tx.sourcePending = 1 + } return nil } func (c *captureWriter) Start(context.Context, string) error { c.running.Store(true); return nil } func TestLibraryCaptureMaintenanceOwnsArchiveAndRestoresOnFailure(t *testing.T) { - for _, mode := range []string{"success", "initial-busy", "late-pending", "search-failure"} { + for _, mode := range []string{"success", "initial-busy", "late-pending", "search-failure", "other-library-busy", "other-library-late-pending"} { t.Run(mode, func(t *testing.T) { db := newLibraryFixture() - writer := &captureWriter{db: db, late: mode == "late-pending"} + writer := &captureWriter{db: db, late: mode == "late-pending", lateSource: mode == "other-library-late-pending"} + if mode == "other-library-busy" { + db.tx.sourcePending = 1 + } writer.running.Store(true) if mode == "initial-busy" { db.tx.pending = 1 @@ -98,7 +105,7 @@ func TestLibraryCaptureMaintenanceOwnsArchiveAndRestoresOnFailure(t *testing.T) if err == nil { t.Fatal("invalid candidate succeeded") } - if mode == "initial-busy" && writer.stops != 0 { + if (mode == "initial-busy" || mode == "other-library-busy") && writer.stops != 0 { t.Fatal("busy source stopped") } return diff --git a/internal/releaseadapter/v071/library_export_integration_test.go b/internal/releaseadapter/v071/library_export_integration_test.go index cd21f0f..808244b 100644 --- a/internal/releaseadapter/v071/library_export_integration_test.go +++ b/internal/releaseadapter/v071/library_export_integration_test.go @@ -54,6 +54,38 @@ func TestLibraryExportIsolatedPostgres(t *testing.T) { } } } + t.Run("whole source settlement", func(t *testing.T) { + if err := checkLibrarySourceSettlement(ctx, db); err != nil { + t.Fatal(err) + } + for _, tc := range []struct{ name, change, restore string }{ + {"other tenant document", `UPDATE knowledges SET parse_status='processing' WHERE id='other-scope'`, `UPDATE knowledges SET parse_status='completed' WHERE id='other-scope'`}, + {"other library pending", `INSERT INTO task_pending_ops VALUES(20000,'wiki:ingest','knowledge_base','other-library')`, `DELETE FROM task_pending_ops`}, + {"deleted scope pending", `INSERT INTO task_pending_ops VALUES(20000,'wiki:retract','knowledge','physically-deleted-doc')`, `DELETE FROM task_pending_ops`}, + {"unknown scope pending", `INSERT INTO task_pending_ops VALUES(20000,'unknown:task','unknown','unknown')`, `DELETE FROM task_pending_ops`}, + {"other tenant dead letter", `INSERT INTO task_dead_letters VALUES(20000,'document:process','knowledge_base','other-library')`, `DELETE FROM task_dead_letters`}, + } { + t.Run(tc.name, func(t *testing.T) { + if _, err := db.Exec(ctx, tc.change); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { + if _, err := db.Exec(ctx, tc.restore); err != nil { + t.Error(err) + } + }) + if _, err := ExportLibrary(ctx, db, scope); err != nil { + t.Fatalf("selected library unexpectedly busy: %v", err) + } + if err := checkLibrarySourceSettlement(ctx, db); err == nil { + t.Fatal("source maintenance allowed while another scope has unfinished work") + } + }) + } + if err := checkLibrarySourceSettlement(ctx, db); err != nil { + t.Fatalf("settled source did not recover: %v", err) + } + }) t.Run("MVCC concurrent update", func(t *testing.T) { wrapper := libraryHookDB{pool: db, hook: func() { if _, err := db.Exec(ctx, `UPDATE wiki_pages SET content='new-content' WHERE id='wiki-safe'`); err != nil { diff --git a/internal/releaseadapter/v071/library_export_test.go b/internal/releaseadapter/v071/library_export_test.go index b7501c7..4293d20 100644 --- a/internal/releaseadapter/v071/library_export_test.go +++ b/internal/releaseadapter/v071/library_export_test.go @@ -80,6 +80,7 @@ type libraryFixtureTx struct { pgx.Tx queries []string committed bool + sourcePending int64 pending, failed, unsettled int64 graph bool queryError bool @@ -111,6 +112,10 @@ type libraryFixtureRow struct { func (r libraryFixtureRow) Scan(dest ...any) error { switch { + case strings.Contains(r.sql, "library-source-settlement"): + *dest[0].(*int64) = r.d.unsettled + *dest[1].(*int64) = r.d.pending + r.d.sourcePending + *dest[2].(*int64) = r.d.failed case strings.Contains(r.sql, "schema_migrations"): *dest[0].(*int) = 74 *dest[1].(*bool) = false diff --git a/internal/releaseadapter/v071/library_source_settlement.go b/internal/releaseadapter/v071/library_source_settlement.go new file mode 100644 index 0000000..541a317 --- /dev/null +++ b/internal/releaseadapter/v071/library_source_settlement.go @@ -0,0 +1,38 @@ +package v071 + +import ( + "context" + "errors" + + "github.com/jackc/pgx/v5" +) + +// A maintenance window stops a shared writer, not a single KB. Check its entire +// source database, including other tenants, deleted scopes and unknown task +// scopes. Restricting this query to the selected KB can interrupt another job. +// This only establishes recorded processing settlement, never Wiki semantics or +// the absence of unrecorded/remote work; CaptureLibrary still requires the +// deployment's ingress and background-worker readiness callback. +func checkLibrarySourceSettlement(ctx context.Context, db librarySnapshotDB) error { + tx, err := db.BeginTx(ctx, pgx.TxOptions{IsoLevel: pgx.RepeatableRead, AccessMode: pgx.ReadOnly}) + if err != nil { + return errors.New("begin library source settlement") + } + defer tx.Rollback(context.WithoutCancel(ctx)) + var unsettled, pending, failed int64 + if err := tx.QueryRow(ctx, librarySourceSettlementSQL).Scan(&unsettled, &pending, &failed); err != nil { + return errors.New("read library source settlement") + } + if unsettled != 0 || pending != 0 || failed != 0 { + return errors.New("library source has unfinished or failed processing") + } + if err := tx.Commit(ctx); err != nil { + return errors.New("commit library source settlement") + } + return nil +} + +const librarySourceSettlementSQL = `SELECT /* library-source-settlement */ + (SELECT count(*) FROM knowledges WHERE deleted_at IS NULL AND (parse_status IS DISTINCT FROM 'completed' OR pending_subtasks_count IS NULL OR pending_subtasks_count<>0)), + (SELECT count(*) FROM task_pending_ops), + (SELECT count(*) FROM task_dead_letters)`