package v071 import ( "context" "encoding/json" "errors" "fmt" "log" "strings" "github.com/jackc/pgx/v5" ) // wikiReplaceScope 描述一次库级 wiki 替换的真实作用域,以及它是否被降级。 // // 背景:WeKnora 的 wiki 图谱与页面同表(wiki_pages,节点/边靠 slug + in_links // / out_links 表达),旧的"整库 DELETE + 灌包"在**共享真实知识库**上会把其他 // 文档的页面和 agent 手写页一起抹掉(2026-10-08 生产演练的现场)。 // // 现在的判定规则: // // - 目标页的 source_refs 形如 "|",只有引用的知识 // 全部属于"本包覆盖的知识集合"时,这一页才归本包管(InScope); // - 引用了包外知识的页是外来页(Foreign),永不删除; // - 完全没有 source_refs/chunk_refs 的页(index/log、agent 手写页)永不删除; // - 外来页与包内页同 slug 时无法安全处理 → 拒绝发布(fail-closed)。 // // 目标库没有外来页时("镜像库 → 原件"前提成立)仍走整库替换,行为与旧实现一致; // 只要出现外来页就降级为"只替换包内页集",其余页面一行不动。 type wikiReplaceScope struct { InScope int // 包内知识拥有、会被删除重建的页 Foreign int // 引用了包外知识的页,永不删除 ForeignReferencingIn int // 外来页中仍引用本包知识的页(只摘引用,不动正文) Untouched int // 无引用来源的页(index/log/agent),永不触碰 SkippedLibraryPages int // 降级时被跳过的库级页(index/log 不能由部分快照重写) Degraded bool // 目标库存在外来页 → 只替换本包页集 } func (scope wikiReplaceScope) summary() string { return fmt.Sprintf("in_scope=%d foreign=%d foreign_ref_stripped=%d untouched=%d skipped_library=%d degraded=%t", scope.InScope, scope.Foreign, scope.ForeignReferencingIn, scope.Untouched, scope.SkippedLibraryPages, scope.Degraded) } // targetWikiRef 是目标库现存 wiki 页面的归属信息。 type targetWikiRef struct { ID string Slug string SourceRefs []string ChunkRefs []string } const targetWikiRefsSQL = ` SELECT id, slug, COALESCE(source_refs, '[]'::jsonb), COALESCE(chunk_refs, '[]'::jsonb) FROM wiki_pages WHERE tenant_id = $1 AND knowledge_base_id = $2 AND deleted_at IS NULL` // packageWikiOwners 返回本包 wiki 快照覆盖的知识 id 集合:快照里 knowledges // 行的 id,加上所有页面 source_refs 的归属。 // // 镜像库对原件发布时这个集合是整个库(几百上千篇),单文档包发布时它只有一篇 // ——所以同一套判定既能保住"整库替换"的镜像语义,又能在共享库上自动收敛。 func packageWikiOwners(snapshot PostgresSnapshot) (map[string]bool, error) { owners := map[string]bool{} if tablePresent(snapshot, "knowledges") { for _, raw := range snapshot.Table("knowledges").Rows { var row struct { ID string `json:"id"` } if json.Unmarshal(raw, &row) != nil || !validSearchIdentifier(row.ID) { return nil, errors.New("invalid package knowledge row") } owners[row.ID] = true } } if tablePresent(snapshot, "wiki_pages") { for _, raw := range snapshot.Table("wiki_pages").Rows { page, err := decodeWikiRow(raw) if err != nil { return nil, err } for _, reference := range stringList(page["source_refs"]) { if owner := referenceOwner(reference); owner != "" { owners[owner] = true } } } } if len(owners) == 0 { return nil, errors.New("package wiki snapshot carries no owning knowledge") } return owners, nil } // referenceOwner 取 source_refs 条目的知识 id:"|"。 func referenceOwner(reference string) string { if index := strings.Index(reference, "|"); index > 0 { reference = reference[:index] } if !validSearchIdentifier(reference) { return "" } return reference } // classifyTargetWikiPages 判定目标库里每一页的归属(纯函数,便于单测)。 // 返回作用域、将被替换的包内 slug,以及"仍引用本包知识的外来页"。 func classifyTargetWikiPages(pages []targetWikiRef, owners map[string]bool) (wikiReplaceScope, []string, []targetWikiRef) { scope := wikiReplaceScope{} inScopeSlugs := make([]string, 0, len(pages)) foreignReferencingIn := make([]targetWikiRef, 0) for _, page := range pages { if page.Slug == "" || (!validSearchIdentifier(page.ID)) { // 结构异常的页按外来页处理:不删、不改。 scope.Foreign++ continue } if len(page.SourceRefs) == 0 && len(page.ChunkRefs) == 0 { scope.Untouched++ continue } if len(page.SourceRefs) == 0 { // 只有 chunk_refs(chunk UUID 不带知识 id)时无法归属 → 按外来页处理。 scope.Foreign++ continue } pageOwners := make([]string, 0, len(page.SourceRefs)) mine, malformed := 0, false for _, reference := range page.SourceRefs { owner := referenceOwner(reference) if owner == "" { malformed = true break } pageOwners = append(pageOwners, owner) if owners[owner] { mine++ } } if malformed { scope.Foreign++ continue } if mine == len(pageOwners) { scope.InScope++ inScopeSlugs = append(inScopeSlugs, page.Slug) continue } scope.Foreign++ if mine > 0 { scope.ForeignReferencingIn++ foreignReferencingIn = append(foreignReferencingIn, page) } } scope.Degraded = scope.Foreign > 0 return scope, inScopeSlugs, foreignReferencingIn } // replaceWiki 是发布 / 撤权 / 回滚共用的 wiki 通道:先判定归属,再按作用域写入。 // 必须在已经持有 knowledge base 维度 advisory lock 的事务里调用。 func (importer *PostgresImporter) replaceWiki(ctx context.Context, tx pgx.Tx, identity PostgresIdentity, snapshot PostgresSnapshot) (wikiReplaceScope, error) { tables, hasWiki := wikiSnapshotRows(snapshot) if !hasWiki { // 老包 / 未启用 wiki 的库:不动目标 wiki。 return wikiReplaceScope{}, nil } pageRows := snapshot.Table("wiki_pages").Rows folderRows := snapshot.Table("wiki_folders").Rows bundleSlugs := make([]string, 0, len(pageRows)) for _, raw := range pageRows { var row struct { Slug string `json:"slug"` } if json.Unmarshal(raw, &row) != nil || row.Slug == "" { return wikiReplaceScope{}, errors.New("invalid package wiki page slug") } bundleSlugs = append(bundleSlugs, row.Slug) } folderIDs := make([]string, 0, len(folderRows)) for _, raw := range folderRows { var row struct { ID string `json:"id"` } if json.Unmarshal(raw, &row) != nil || row.ID == "" { return wikiReplaceScope{}, errors.New("invalid package wiki folder id") } folderIDs = append(folderIDs, row.ID) } owners, err := packageWikiOwners(snapshot) if err != nil { return wikiReplaceScope{}, err } targetPages, err := loadTargetWikiRefs(ctx, tx, identity) if err != nil { return wikiReplaceScope{}, err } scope, inScopeSlugs, foreignReferencingIn := classifyTargetWikiPages(targetPages, owners) // 外来页与包内会写入的页同 slug:两边正文不同、又都不该被覆盖 → 拒绝发布。 bundleRefBearing := make(map[string]bool, len(bundleSlugs)) for _, raw := range pageRows { page, err := decodeWikiRow(raw) if err != nil { return scope, err } if len(stringList(page["source_refs"])) == 0 && len(stringList(page["chunk_refs"])) == 0 { continue } slug, _ := page["slug"].(string) bundleRefBearing[slug] = true } if slug, collided := wikiSlugCollision(targetPages, inScopeSlugs, bundleRefBearing); collided { return scope, fmt.Errorf("目标知识库的 wiki 页 %s 由其他文档或人工维护,发布包无法安全覆盖,已拒绝发布(%s)", slug, scope.summary()) } if scope.Degraded { // 降级:只摘掉外来页上对本包知识的引用(正文不动,避免破坏库级合成结果)。 if err := stripForeignWikiRefs(ctx, tx, identity, foreignReferencingIn, owners, chunkIDSet(snapshot)); err != nil { return scope, err } if len(inScopeSlugs) > 0 { if _, err := tx.Exec(ctx, ` DELETE FROM wiki_pages WHERE tenant_id = $1 AND knowledge_base_id = $2 AND slug = ANY($3::text[]) `, identity.TenantID, identity.KnowledgeBaseID, inScopeSlugs); err != nil { return scope, errors.New("clear in-scope target wiki pages") } } if len(folderIDs) > 0 { if _, err := tx.Exec(ctx, ` DELETE FROM wiki_folders WHERE tenant_id = $1 AND knowledge_base_id = $2 AND id = ANY($3::text[]) `, identity.TenantID, identity.KnowledgeBaseID, folderIDs); err != nil { return scope, errors.New("clear package target wiki folders") } } filteredPages := make([]json.RawMessage, 0, len(pageRows)) for _, raw := range pageRows { page, err := decodeWikiRow(raw) if err != nil { return scope, err } if len(stringList(page["source_refs"])) == 0 && len(stringList(page["chunk_refs"])) == 0 { // index/log 是库级聚合页,部分快照重写会毁掉目标库自己的聚合。 scope.SkippedLibraryPages++ continue } filteredPages = append(filteredPages, raw) } if err := insertSnapshotRows(ctx, tx, newTableSnapshot("wiki_folders", folderRows)); err != nil { return scope, err } if err := insertSnapshotRows(ctx, tx, newTableSnapshot("wiki_pages", filteredPages)); err != nil { return scope, err } log.Printf("release wiki replace scope %s (只替换包内页集,目标库其余页面未改动)", scope.summary()) return scope, nil } // 无外来页:镜像库对原件的正常路径,整库替换(与旧行为一致), // 但保留"无引用来源且不在包内"的页面(agent 手写页等)。 if _, err := tx.Exec(ctx, ` DELETE FROM wiki_pages WHERE tenant_id = $1 AND knowledge_base_id = $2 AND ((COALESCE(source_refs, '[]'::jsonb) <> '[]'::jsonb) OR (COALESCE(chunk_refs, '[]'::jsonb) <> '[]'::jsonb) OR slug = ANY($3::text[])) `, identity.TenantID, identity.KnowledgeBaseID, bundleSlugs); err != nil { return scope, errors.New("clear target wiki pages") } if _, err := tx.Exec(ctx, ` DELETE FROM wiki_folders AS folder WHERE folder.tenant_id = $1 AND folder.knowledge_base_id = $2 AND (folder.id = ANY($3::text[]) OR NOT EXISTS (SELECT 1 FROM wiki_pages AS page WHERE page.knowledge_base_id = folder.knowledge_base_id AND page.folder_id = folder.id AND page.deleted_at IS NULL)) `, identity.TenantID, identity.KnowledgeBaseID, folderIDs); err != nil { return scope, errors.New("clear target wiki folders") } for _, table := range tables { if err := insertSnapshotRows(ctx, tx, table); err != nil { return scope, err } } log.Printf("release wiki replace scope %s", scope.summary()) return scope, nil } func loadTargetWikiRefs(ctx context.Context, tx pgx.Tx, identity PostgresIdentity) ([]targetWikiRef, error) { rows, err := tx.Query(ctx, targetWikiRefsSQL, identity.TenantID, identity.KnowledgeBaseID) if err != nil { return nil, errors.New("read target wiki page ownership") } defer rows.Close() pages := make([]targetWikiRef, 0) for rows.Next() { var page targetWikiRef var sourceRefs, chunkRefs []byte if err := rows.Scan(&page.ID, &page.Slug, &sourceRefs, &chunkRefs); err != nil { return nil, errors.New("read target wiki page ownership") } if json.Unmarshal(sourceRefs, &page.SourceRefs) != nil || json.Unmarshal(chunkRefs, &page.ChunkRefs) != nil { // 非数组结构(异常行)按"无法归属"处理:不删、不改。 page.SourceRefs = nil page.ChunkRefs = []string{""} } pages = append(pages, page) } if rows.Err() != nil { return nil, errors.New("read target wiki page ownership") } return pages, nil } // stripForeignWikiRefs 在外来页上只摘掉本包知识的引用,正文一行不改。 func stripForeignWikiRefs(ctx context.Context, tx pgx.Tx, identity PostgresIdentity, pages []targetWikiRef, owners map[string]bool, removedChunks map[string]bool) error { for _, page := range pages { keptSources := make([]string, 0, len(page.SourceRefs)) for _, reference := range page.SourceRefs { if !owners[referenceOwner(reference)] { keptSources = append(keptSources, reference) } } keptChunks := make([]string, 0, len(page.ChunkRefs)) for _, reference := range page.ChunkRefs { if !removedChunks[reference] { keptChunks = append(keptChunks, reference) } } if len(keptSources) == len(page.SourceRefs) && len(keptChunks) == len(page.ChunkRefs) { continue } encodedSources, _ := json.Marshal(keptSources) encodedChunks, _ := json.Marshal(keptChunks) if _, err := tx.Exec(ctx, ` UPDATE wiki_pages SET source_refs = $3::jsonb, chunk_refs = $4::jsonb, updated_at = NOW() WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL `, page.ID, identity.TenantID, string(encodedSources), string(encodedChunks)); err != nil { return errors.New("strip package wiki references from shared target page") } } return nil } // wikiSlugCollision 找"包内会写入的页 slug 已被目标库外来页占用"的第一个 slug。 // 命中时两侧正文不同、又都不该被覆盖,只能拒绝发布(fail-closed)。 // // bundleRefBearing 是包内**携带引用**的页 slug:只有这些页在降级路径上会真正 // 写入;包内的库级页(index/log)会被跳过,因此不构成占用。 func wikiSlugCollision(pages []targetWikiRef, inScopeSlugs []string, bundleRefBearing map[string]bool) (string, bool) { inScope := make(map[string]bool, len(inScopeSlugs)) for _, slug := range inScopeSlugs { inScope[slug] = true } for _, page := range pages { if !bundleRefBearing[page.Slug] || inScope[page.Slug] { continue } return page.Slug, true } return "", false } func chunkIDSet(snapshot PostgresSnapshot) map[string]bool { ids := map[string]bool{} if !tablePresent(snapshot, "chunks") { return ids } for _, raw := range snapshot.Table("chunks").Rows { var row struct { ID string `json:"id"` } if json.Unmarshal(raw, &row) == nil && row.ID != "" { ids[row.ID] = true } } return ids }