knowledge-governance/internal/releaseadapter/v071/document_export.go

package v071

import (
	"context"
	"errors"
	"strings"
	"time"

	"knowledge-governance/internal/releasebundle"
	releaseworkflow "knowledge-governance/internal/workflows/release"
)

type postgresSnapshotExporter interface {
	Export(ctx context.Context, identity PostgresIdentity) (PostgresSnapshot, error)
}

type searchSnapshotExporter interface {
	Export(ctx context.Context, identity SearchIdentity) (SearchSnapshot, error)
}

type objectSnapshotExporter interface {
	Export(ctx context.Context, snapshot PostgresSnapshot) (ObjectSnapshot, error)
}

type DocumentExporterConfig struct {
	Contract       targetContractInspector
	Postgres       postgresSnapshotExporter
	Search         searchSnapshotExporter
	Objects        objectSnapshotExporter
	TenantID       uint64
	EmbeddingModel string
	Now            func() time.Time
}

type DocumentExporter struct {
	config DocumentExporterConfig
}

type DocumentBundle struct {
	Manifest releasebundle.Manifest
	Postgres PostgresSnapshot
	Search   SearchSnapshot
	Objects  ObjectSnapshot
}

func (bundle *DocumentBundle) ReleaseManifest() releasebundle.Manifest {
	if bundle == nil {
		return releasebundle.Manifest{}
	}
	return bundle.Manifest
}

func NewDocumentExporter(config DocumentExporterConfig) (*DocumentExporter, error) {
	if config.Contract == nil || config.Postgres == nil || config.Search == nil || config.Objects == nil || config.TenantID == 0 ||
		!validSearchIdentifier(config.EmbeddingModel) || config.Now == nil {
		return nil, errors.New("invalid v0.7.1 document exporter configuration")
	}
	return &DocumentExporter{config: config}, nil
}

func (exporter *DocumentExporter) Export(ctx context.Context, item releaseworkflow.PlanItem) (releaseworkflow.ExportedBundle, error) {
	if !validDocumentPlan(item) {
		return nil, errors.New("invalid document release plan")
	}
	sourceContract, err := exporter.config.Contract.Contract(ctx, item)
	if err != nil || sourceContract.WeKnoraVersion != releasebundle.WeKnoraVersionV071 ||
		sourceContract.MigrationVersion != releasebundle.WeKnoraMigrationV071 || sourceContract.TenantID != exporter.config.TenantID ||
		sourceContract.KnowledgeBaseID != item.TestKnowledgeBaseID || sourceContract.RetrieverEngine != "elasticsearch_v8" ||
		sourceContract.EmbeddingModel != exporter.config.EmbeddingModel || sourceContract.EmbeddingDimension != releasebundle.EmbeddingDimensionV071 {
		return nil, errors.New("source WeKnora release contract mismatch")
	}
	postgresSnapshot, err := exporter.config.Postgres.Export(ctx, PostgresIdentity{
		TenantID: exporter.config.TenantID, KnowledgeBaseID: item.TestKnowledgeBaseID, KnowledgeID: item.KnowledgeID,
	})
	if err != nil {
		return nil, errors.New("export PostgreSQL document snapshot")
	}
	searchSnapshot, err := exporter.config.Search.Export(ctx, SearchIdentity{
		TenantID: exporter.config.TenantID, KnowledgeBaseID: item.TestKnowledgeBaseID, KnowledgeID: item.KnowledgeID,
	})
	if err != nil {
		return nil, errors.New("export Elasticsearch document snapshot")
	}
	if len(searchSnapshot.Documents) == 0 || !validLowerSHA256(searchSnapshot.MappingSHA256) || !validLowerSHA256(searchSnapshot.DocumentsSHA256) {
		return nil, errors.New("Elasticsearch document snapshot is incomplete")
	}
	if searchSnapshot.MappingSHA256 != sourceContract.ElasticsearchMappingSHA256 {
		return nil, errors.New("source Elasticsearch mapping contract mismatch")
	}
	objectSnapshot, err := exporter.config.Objects.Export(ctx, postgresSnapshot)
	if err != nil {
		return nil, errors.New("export object document snapshot")
	}
	if !validLowerSHA256(objectSnapshot.SHA256) {
		return nil, errors.New("object document snapshot is incomplete")
	}
	// 库级 wiki 快照与本文档同一个发布单元：检索（PG/ES/OSS）和 wiki 一起进生产。
	// 撤权（delete）时剥掉该文档在 wiki 里的贡献，避免生产 wiki 继续引用已撤权的文档。
	if wikiExporter, ok := exporter.config.Postgres.(wikiSnapshotExporter); ok {
		removingKnowledgeID := ""
		if item.Action == "delete" {
			removingKnowledgeID = item.KnowledgeID
		}
		wikiTables, err := wikiExporter.ExportWiki(ctx, PostgresIdentity{
			TenantID: exporter.config.TenantID, KnowledgeBaseID: item.TestKnowledgeBaseID, KnowledgeID: item.KnowledgeID,
		}, removingKnowledgeID)
		if err != nil {
			// 例如源端 wiki 未收敛，直接透出面向运营的中文原因。
			return nil, err
		}
		postgresSnapshot.Tables = append(postgresSnapshot.Tables, wikiTables...)
	}
	tables := make([]releasebundle.TableDigest, 0, len(postgresSnapshot.Tables))
	for _, table := range postgresSnapshot.Tables {
		if !validReleaseTable(table.Name) || table.RowCount != len(table.Rows) || !validLowerSHA256(table.SHA256) {
			return nil, errors.New("PostgreSQL document snapshot is incomplete")
		}
		tables = append(tables, releasebundle.TableDigest{Name: table.Name, RowCount: table.RowCount, SHA256: table.SHA256})
	}
	manifest, err := releasebundle.Seal(releasebundle.Manifest{
		FormatVersion: releasebundle.FormatVersionV1, ExecutionID: item.ReleaseExecutionID,
		PublicationID: item.PublicationID, SourceItemVersionID: item.SourceItemVersionID,
		SourceRevision: item.SourceRevision, ParseRevision: item.ParseRevision, ReleaseRevision: item.ReleaseRevision,
		CreatedAt: exporter.config.Now().UTC(),
		Contract: releasebundle.Contract{
			WeKnoraVersion: sourceContract.WeKnoraVersion, MigrationVersion: sourceContract.MigrationVersion,
			TenantID: sourceContract.TenantID, KnowledgeBaseID: sourceContract.KnowledgeBaseID, KnowledgeID: item.KnowledgeID,
			RetrieverEngine: sourceContract.RetrieverEngine, EmbeddingModel: sourceContract.EmbeddingModel,
			EmbeddingDimension: sourceContract.EmbeddingDimension, ElasticsearchMappingSHA256: sourceContract.ElasticsearchMappingSHA256,
		},
		Tables: tables,
		Search: releasebundle.SearchDigest{DocumentCount: len(searchSnapshot.Documents), SHA256: searchSnapshot.DocumentsSHA256},
		Assets: releasebundle.AssetDigest{ObjectCount: len(objectSnapshot.Objects), TotalBytes: objectSnapshot.TotalBytes, SHA256: objectSnapshot.SHA256},
	})
	if err != nil {
		return nil, errors.New("seal v0.7.1 document release bundle")
	}
	return &DocumentBundle{Manifest: manifest, Postgres: postgresSnapshot, Search: searchSnapshot, Objects: objectSnapshot}, nil
}

func validDocumentPlan(item releaseworkflow.PlanItem) bool {
	for _, value := range []string{item.ReleaseExecutionID, item.PublicationID, item.SourceItemVersionID,
		item.TestKnowledgeBaseID, item.KnowledgeID} {
		if !validSearchIdentifier(value) {
			return false
		}
	}
	for _, value := range []string{item.SourceRevision, item.ParseRevision, item.ReleaseRevision} {
		if value == "" || len(value) > 128 || value != strings.TrimSpace(value) || strings.ContainsAny(value, "\x00\r\n\t/?#\\") {
			return false
		}
	}
	return item.DecidedVisibility == "internal" || item.DecidedVisibility == "external"
}

func validReleaseTable(name string) bool {
	switch name {
	case "knowledges", "chunks", "knowledge_tags", "knowledge_tag_relations", "resources", "resource_bindings",
		"wiki_pages", "wiki_folders":
		return true
	default:
		return false
	}
}

var _ releaseworkflow.BundleExporter = (*DocumentExporter)(nil)