Files
knowledge-governance/internal/releaseadapter/v071/library_export.go
T
姚章浩 1a0f99e346
build / build (push) Successful in 1m44s
fix(release): 修复发布管理F01-F11资源闭包与状态呈现
F01:捕获、写前镜像、指纹和恢复后内容校验共用按目标精确绑定的资源闭包:
从已限定范围的 resource_bindings 与正文 handle 一次提取,再按索引取资源,
不再对每个租户资源扫描全部正文表。无绑定正文引用仍保留,缺失资源仍失败。

F02/F03:恢复验证使用 capture/verify/canary/restore/finalize 自己的阶段,登记
证据不再叫新版本生效;顶部优先在飞作业;已验证且 API reason 为空时不再同屏
显示未读到状态,报告可展开。

F04-F11:显示实际目标实例/项目/库;运行中主按钮查看当前任务并禁止重复启动;
快照历史默认已登记、可筛选分页并定位所选;无真实下次计划时显示未读取;各
scope 独立 overview;新操作清旧通知;存储行按文档/分块/资源/绑定及 Wiki
页面/目录/日志分项。高影响恢复验证/恢复增加一次影响确认。

验证:隔离 PG 20k 无关资源夹具旧扫描 683ms→新导出 41ms,资源 ID 闭包相等;
Go/前端全量及 make verify 17 项通过。未部署、未做 8088 UI 验收。
2026-11-05 12:50:11 +08:00

203 lines
10 KiB
Go

package v071
import (
"context"
"encoding/json"
"errors"
"github.com/jackc/pgx/v5"
)
type librarySnapshotDB interface {
BeginTx(context.Context, pgx.TxOptions) (pgx.Tx, error)
}
// ExportLibrary reads one PostgreSQL MVCC snapshot, including empty Wiki tables.
// It does not certify semantic quality, freeze Elasticsearch/objects, or authorize
// publication. Those require a separately verified, complete library version.
func ExportLibrary(ctx context.Context, db librarySnapshotDB, identity PostgresIdentity) (PostgresSnapshot, error) {
return ExportLibraryWithReleases(ctx, db, identity, nil)
}
// ExportLibraryWithReleases 与 ExportLibrary 相同,但允许调用方带上精确解除的死信
// 指纹(只影响死信这一项判定,其余结算条件不变)。
func ExportLibraryWithReleases(ctx context.Context, db librarySnapshotDB, identity PostgresIdentity, released []string) (PostgresSnapshot, error) {
if db == nil || identity.TenantID == 0 || !validSearchIdentifier(identity.KnowledgeBaseID) || identity.KnowledgeID != "" {
return PostgresSnapshot{}, errors.New("invalid library snapshot scope")
}
tx, err := db.BeginTx(ctx, pgx.TxOptions{IsoLevel: pgx.RepeatableRead, AccessMode: pgx.ReadOnly})
if err != nil {
return PostgresSnapshot{}, errors.New("begin library snapshot")
}
defer tx.Rollback(context.WithoutCancel(ctx))
var version int
var dirty bool
if err := tx.QueryRow(ctx, `SELECT version,dirty FROM schema_migrations LIMIT 1`).Scan(&version, &dirty); err != nil || version != 74 || dirty {
return PostgresSnapshot{}, errors.New("source library schema contract mismatch")
}
var graph bool
if err := tx.QueryRow(ctx, `SELECT COALESCE((indexing_strategy->>'graph_enabled')::boolean,false) FROM knowledge_bases WHERE tenant_id=$1 AND id=$2 AND deleted_at IS NULL`, identity.TenantID, identity.KnowledgeBaseID).Scan(&graph); err != nil {
return PostgresSnapshot{}, errors.New("source library unavailable")
}
if graph {
return PostgresSnapshot{}, errors.New("Neo4j graph snapshot is not supported")
}
var unsettled, pending, failed int64
if err := tx.QueryRow(ctx, librarySettlementSQL, identity.TenantID, identity.KnowledgeBaseID).Scan(&unsettled, &pending, &failed); err != nil {
return PostgresSnapshot{}, errors.New("read library settlement")
}
if unsettled != 0 || pending != 0 || failed != 0 {
if failed != 0 && unsettled == 0 && pending == 0 {
rows, rowsErr := sourceDeadLetterRows(ctx, tx, identity.TenantID, identity.KnowledgeBaseID)
if rowsErr != nil {
return PostgresSnapshot{}, rowsErr
}
if releasedErr := requireReleased(rows, released); releasedErr != nil {
return PostgresSnapshot{}, releasedErr
}
} else {
return PostgresSnapshot{}, errors.New("library has unfinished or failed processing; semantic acceptance is still required after settlement")
}
}
if err := verifyLibraryRelationalClosure(ctx, tx, identity, false); err != nil {
return PostgresSnapshot{}, err
}
exporter := PostgresExporter{db: tx}
var snapshot PostgresSnapshot
snapshot.Catalog, _, err = captureMigrationCatalog(ctx, tx)
if err != nil {
return PostgresSnapshot{}, err
}
if err = validateMigrationCatalog(snapshot.Catalog); err != nil {
return PostgresSnapshot{}, err
}
for _, entry := range libraryContentQueries {
rows, err := exporter.queryRows(ctx, entry.sql, identity.TenantID, identity.KnowledgeBaseID)
if err != nil {
return PostgresSnapshot{}, err
}
snapshot.Tables = append(snapshot.Tables, newTableSnapshot(entry.name, rows))
}
// Resources can be owned by a document/chunk or only referenced in body text.
// The latter includes Wiki manual pages, which document bundles used to miss.
var bodies []json.RawMessage
for _, table := range snapshot.Tables {
if table.Name == "resource_bindings" || table.Name == "knowledge_tag_relations" {
continue
}
bodies = append(bodies, table.Rows...)
}
handles, err := libraryResourceHandles(bodies)
if err != nil {
return PostgresSnapshot{}, err
}
resources, err := scopedResourceRows(ctx, &exporter, identity, false, bodies,
snapshot.Table("resource_bindings").Rows)
if err != nil {
return PostgresSnapshot{}, err
}
resourceIDs, resourceHandles := map[string]bool{}, map[string]bool{}
for _, raw := range resources {
var row struct {
ID string `json:"id"`
Handle string `json:"handle"`
TenantID uint64 `json:"tenant_id"`
}
if json.Unmarshal(raw, &row) != nil || row.ID == "" || row.TenantID != identity.TenantID || resourceIDs[row.ID] || resourceHandles[row.Handle] {
return PostgresSnapshot{}, errors.New("invalid library resource identity")
}
resourceIDs[row.ID] = true
resourceHandles[row.Handle] = true
}
for _, handle := range handles {
if !resourceHandles[handle] {
return PostgresSnapshot{}, errors.New("library references an unavailable resource")
}
}
for _, raw := range snapshot.Table("resource_bindings").Rows {
var row struct {
ResourceID string `json:"resource_id"`
}
if json.Unmarshal(raw, &row) != nil || !resourceIDs[row.ResourceID] {
return PostgresSnapshot{}, errors.New("library binding references an unavailable resource")
}
}
ids := make([]string, 0, len(resourceIDs))
for id := range resourceIDs {
ids = append(ids, id)
}
if err := verifyLibraryResourceOwners(ctx, tx, ids); err != nil {
return PostgresSnapshot{}, err
}
snapshot.Tables = append(snapshot.Tables, newTableSnapshot("resources", resources))
if err = tx.Commit(ctx); err != nil {
return PostgresSnapshot{}, errors.New("commit library snapshot")
}
return snapshot, nil
}
// Deleted document retract/finalize tasks are scoped to the KB, not a live
// knowledge row. Never join them to only non-deleted documents. Dead letters
// have no resolution marker in this schema, so presence blocks automatically.
const librarySettlementSQL = `SELECT
(SELECT count(*) FROM knowledges WHERE tenant_id=$1 AND knowledge_base_id=$2 AND 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 WHERE tenant_id=$1 AND ((scope='knowledge_base' AND scope_id=$2) OR (scope='knowledge' AND scope_id IN (SELECT id FROM knowledges WHERE tenant_id=$1 AND knowledge_base_id=$2)))),
(SELECT count(*) FROM task_dead_letters WHERE tenant_id=$1 AND ((scope='knowledge_base' AND scope_id=$2) OR (scope='knowledge' AND scope_id IN (SELECT id FROM knowledges WHERE tenant_id=$1 AND knowledge_base_id=$2))))`
var libraryContentQueries = []struct{ name, sql string }{
{"knowledges", `SELECT to_jsonb(k) FROM knowledges k WHERE k.tenant_id=$1 AND k.knowledge_base_id=$2 AND k.deleted_at IS NULL ORDER BY k.id`},
{"chunks", `SELECT to_jsonb(c) FROM chunks c JOIN knowledges k ON k.id=c.knowledge_id AND k.tenant_id=c.tenant_id AND k.knowledge_base_id=c.knowledge_base_id WHERE k.tenant_id=$1 AND k.knowledge_base_id=$2 AND k.deleted_at IS NULL AND c.deleted_at IS NULL ORDER BY c.id`},
{"knowledge_tags", `SELECT to_jsonb(t) FROM knowledge_tags t WHERE t.tenant_id=$1 AND t.knowledge_base_id=$2 AND t.deleted_at IS NULL ORDER BY t.id`},
{"knowledge_tag_relations", `SELECT to_jsonb(r) FROM knowledge_tag_relations r JOIN knowledges k ON k.id=r.knowledge_id JOIN knowledge_tags t ON t.id=r.tag_id AND t.tenant_id=k.tenant_id AND t.knowledge_base_id=k.knowledge_base_id WHERE k.tenant_id=$1 AND k.knowledge_base_id=$2 AND k.deleted_at IS NULL AND t.deleted_at IS NULL ORDER BY r.knowledge_id,r.tag_id`},
{"resource_bindings", `SELECT to_jsonb(b) FROM resource_bindings b WHERE b.tenant_id=$1 AND ((b.owner_type='knowledge' AND EXISTS (SELECT 1 FROM knowledges k WHERE k.id=b.owner_id AND k.tenant_id=$1 AND k.knowledge_base_id=$2 AND k.deleted_at IS NULL)) OR (b.owner_type='chunk' AND EXISTS (SELECT 1 FROM chunks c JOIN knowledges k ON k.id=c.knowledge_id AND k.tenant_id=c.tenant_id AND k.knowledge_base_id=c.knowledge_base_id WHERE c.id=b.owner_id AND c.tenant_id=$1 AND c.knowledge_base_id=$2 AND c.deleted_at IS NULL AND k.deleted_at IS NULL))) ORDER BY b.id`},
{"wiki_pages", `SELECT to_jsonb(w) FROM wiki_pages w WHERE w.tenant_id=$1 AND w.knowledge_base_id=$2 AND w.deleted_at IS NULL ORDER BY w.id`},
{"wiki_folders", `SELECT to_jsonb(w) FROM wiki_folders w WHERE w.tenant_id=$1 AND w.knowledge_base_id=$2 AND w.deleted_at IS NULL ORDER BY w.id`},
{"wiki_page_issues", `SELECT to_jsonb(w) FROM wiki_page_issues w WHERE w.tenant_id=$1 AND w.knowledge_base_id=$2 AND w.deleted_at IS NULL ORDER BY w.id`},
{"wiki_log_entries", `SELECT to_jsonb(w) FROM wiki_log_entries w WHERE w.tenant_id=$1 AND w.knowledge_base_id=$2 ORDER BY w.id`},
}
// F01: resources were previously selected by an OR over a per-row EXISTS that
// re-scanned every body table, so a small KB in a large tenant paid for all
// unrelated resources. The caller now extracts the exact binding ids and body
// handles first; both are indexed identities, never filename guesses.
const libraryResourcesSQL = `SELECT to_jsonb(r) FROM resources r
WHERE r.tenant_id=$1 AND ($4::boolean OR r.deleted_at IS NULL)
AND (r.id=ANY($2::text[]) OR r.handle=ANY($3::text[]))
ORDER BY r.id`
// scopedResourceRows is the single F01 read path: binding ids and body handles
// are extracted once from already scoped rows, then both are resolved through
// indexed resource identities. The old per-resource EXISTS/position filter
// rescanned every body table for every tenant resource.
func scopedResourceRows(ctx context.Context, exporter *PostgresExporter, identity PostgresIdentity,
includeDeleted bool, bodies, bindings []json.RawMessage) ([]json.RawMessage, error) {
handles, err := libraryResourceHandles(bodies)
if err != nil {
return nil, err
}
ids, err := libraryBindingResourceIDs(bindings)
if err != nil {
return nil, err
}
return exporter.queryRows(ctx, libraryResourcesSQL, identity.TenantID, ids, handles, includeDeleted)
}
// libraryBindingResourceIDs reads the exact resource ids owned by the already
// scoped resource_bindings rows. It does not infer ownership from names.
func libraryBindingResourceIDs(rows []json.RawMessage) ([]string, error) {
seen := map[string]bool{}
ids := make([]string, 0, len(rows))
for _, raw := range rows {
var row struct {
ResourceID string `json:"resource_id"`
}
if err := json.Unmarshal(raw, &row); err != nil || row.ResourceID == "" {
return nil, errors.New("invalid scoped resource binding")
}
if !seen[row.ResourceID] {
seen[row.ResourceID] = true
ids = append(ids, row.ResourceID)
}
}
return ids, nil
}