Files
knowledge-governance/internal/releaseadapter/v071/document_export.go
T
姚章浩 fba2713b4e
build / build (push) Successful in 1m54s
feat(library): 发布写入支持 WeKnora 0.9.0 schema 134
整库发布写入路径原先按 0.7.1 的固定表集合工作:0.9.0 没有 wiki_log_entries,
Current/清理/编目/整实例指纹都会在不存在表上失败,跨版本闸门也因快照丢掉
SchemaVersion 而失效(未知版本被当作 74)。

改为在装配时解析目标 profile,表集合与清理顺序按解析结果;快照复制与范围改写
带上 SchemaVersion/Profile;跨版本发布显式拒绝并同时点名两个版本。单文档发布包
仍只支持 0.7.1,但改为明确拒绝并说明原因。

本机隔离验证:真实 0.9.0 schema 源库→导出→封存→写入干净 134 目标→逐表核对→
写前镜像回滚;74→134 拒绝与 134 缺表不报错两个负例通过。make verify 17 项全绿。
2026-11-16 20:42:23 +08:00

174 lines
7.5 KiB
Go

package v071
import (
"context"
"errors"
"fmt"
"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) {
// 单文档发布包是 0.7.1 契约:读到的库是别的版本时必须说清楚原因,
// 而不是和"租户/模型不对"共用一句泛化错误。
return nil, fmt.Errorf("single-document release supports only v0.7.1 (74): source library declares %s (%d), so its rows and index documents must go through the library-level publish path",
sourceContract.WeKnoraVersion, sourceContract.MigrationVersion)
}
if err != nil || 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)