Files
knowledge-governance/internal/releaseadapter/v071/document_target.go
T
姚章浩 ea6e56b304 feat(release): 文档发布会带上知识库 wiki 快照并支持撤权剥离
发布通道原来只有三条:PostgreSQL 关系行、Elasticsearch 分片、OSS 对象。
WeKnora 的 wiki 图谱是 wiki_pages 一张纯 PG 表(in_links/out_links 存 slug),
所以它不在任何通道里——撤权后生产 wiki 会一直留着已撤权文档的页面与引用。

本次新增第 5 条通道:库级 wiki 快照,挂在现有文档发布包里,检索与 wiki
同一个 release 单元(同一次执行、同一次校验、同一次回滚):

- 导出:ExportWiki 按 knowledge_base_id 全量读 wiki_pages/wiki_folders;
  收敛门禁(库内无解析中/合成中文档)不满足直接失败并给中文原因;
  未启用 wiki 且无 wiki 行的库不参与同步(生产 wiki 保持原样)。
- 撤权:item.Action == "delete" 时在导出端剥离该文档的 wiki 贡献
  (source_refs/chunk_refs 去条目、无引用页面整页不带、摘死链、清 parent_slug、
  无页面引用的空文件夹及其祖先一并去掉),使“源端仍在只停止发布”和
  “源端删除”两种情况收敛到同一结果。
- 导入:库级 replace-by-kb(同一事务内 DELETE by kb 后灌入快照,文件夹先于页面),
  新增 ReplaceWiki 供撤权路径使用(文档行只 disable,wiki 整体替换)。
- 校验:VerifyWiki 用生产 WeKnora wiki API 比对页面 slug 集合,撤权时额外断言
  生产 wiki 不再引用被撤权文档。

驱动与验收:新增 cmd/release-channel-e2e(复用发布 worker 真实代码路径,
支持 publish/withdraw/rollback),scripts/wiki_e2e_test5.sh、
scripts/wiki_e2e_newkb.sh 两套端到端脚本;证据见
docs/WIKI_CO_TRANSPORT_ACCEPTANCE.md。
2026-09-30 10:54:07 +08:00

235 lines
9.7 KiB
Go

package v071
import (
"context"
"errors"
"knowledge-governance/internal/releasebundle"
releaseworkflow "knowledge-governance/internal/workflows/release"
)
type documentArchive interface {
Save(bundle *DocumentBundle) error
Load(releaseRevision string) (*DocumentBundle, error)
}
type targetContractInspector interface {
Contract(ctx context.Context, item releaseworkflow.PlanItem) (releasebundle.TargetContract, error)
}
type postgresDocumentTarget interface {
Replace(ctx context.Context, identity PostgresIdentity, snapshot PostgresSnapshot) error
Disable(ctx context.Context, identity PostgresIdentity) error
// ReplaceWiki 只应用库级 wiki 快照:撤权/回滚路径上文档行不能重灌,
// 但 wiki 必须整体替换成目标版本的快照。
ReplaceWiki(ctx context.Context, identity PostgresIdentity, snapshot PostgresSnapshot) error
}
type searchDocumentTarget interface {
Replace(ctx context.Context, identity SearchIdentity, snapshot SearchSnapshot) (SearchSnapshot, error)
Disable(ctx context.Context, identity SearchIdentity) error
}
type objectDocumentTarget interface {
Stage(ctx context.Context, releaseRevision string, snapshot ObjectSnapshot) (ObjectStage, error)
Promote(ctx context.Context, stage ObjectStage) error
}
type ProductionVerifier interface {
Verify(ctx context.Context, item releaseworkflow.PlanItem, bundle *DocumentBundle) error
VerifyDisabled(ctx context.Context, item releaseworkflow.PlanItem) error
// VerifyWiki 校验生产端 wiki 与包内快照一致(老包/未启用 wiki 时跳过)。
VerifyWiki(ctx context.Context, item releaseworkflow.PlanItem, bundle *DocumentBundle) error
}
type DocumentTargetConfig struct {
Archive documentArchive
Contract targetContractInspector
Postgres postgresDocumentTarget
Search searchDocumentTarget
Objects objectDocumentTarget
Verifier ProductionVerifier
}
type DocumentTarget struct {
config DocumentTargetConfig
}
func NewDocumentTarget(config DocumentTargetConfig) (*DocumentTarget, error) {
if config.Archive == nil || config.Contract == nil || config.Postgres == nil || config.Search == nil || config.Objects == nil || config.Verifier == nil {
return nil, errors.New("v0.7.1 document target dependencies are required")
}
return &DocumentTarget{config: config}, nil
}
func (target *DocumentTarget) Contract(ctx context.Context, item releaseworkflow.PlanItem) (releasebundle.TargetContract, error) {
contract, err := target.config.Contract.Contract(ctx, item)
if err != nil {
return releasebundle.TargetContract{}, errors.New("inspect target release contract")
}
return contract, nil
}
func (target *DocumentTarget) Prepare(ctx context.Context, item releaseworkflow.PlanItem, exported releaseworkflow.ExportedBundle) (releaseworkflow.PreparedChange, error) {
bundle, ok := exported.(*DocumentBundle)
if !ok || validateDocumentBundle(bundle) != nil || bundle.Manifest.ReleaseRevision != item.ReleaseRevision {
return releaseworkflow.PreparedChange{}, errors.New("invalid v0.7.1 target bundle")
}
if err := target.config.Archive.Save(bundle); err != nil {
return releaseworkflow.PreparedChange{}, errors.New("archive v0.7.1 target bundle")
}
previousRevision := item.PreviousProductionRevision
if previousRevision == "" {
previousRevision = "absent"
} else if previousRevision != "absent" {
if _, err := target.config.Archive.Load(previousRevision); err != nil {
return releaseworkflow.PreparedChange{}, errors.New("prior release bundle is unavailable")
}
}
if _, err := target.config.Objects.Stage(ctx, bundle.Manifest.ReleaseRevision, bundle.Objects); err != nil {
return releaseworkflow.PreparedChange{}, errors.New("stage v0.7.1 release assets")
}
return releaseworkflow.PreparedChange{PreviousRevision: previousRevision, ProductionRevision: bundle.Manifest.ReleaseRevision}, nil
}
func (target *DocumentTarget) Activate(ctx context.Context, item releaseworkflow.PlanItem, change releaseworkflow.PreparedChange) error {
bundle, err := target.config.Archive.Load(change.ProductionRevision)
if err != nil || bundle.Manifest.ReleaseRevision != item.ReleaseRevision {
return errors.New("load staged v0.7.1 release bundle")
}
stage, err := target.config.Objects.Stage(ctx, bundle.Manifest.ReleaseRevision, bundle.Objects)
if err != nil {
return errors.New("restage v0.7.1 release assets")
}
if err := target.config.Objects.Promote(ctx, stage); err != nil {
return errors.New("promote v0.7.1 release assets")
}
postgresIdentity, searchIdentity := targetIdentities(bundle.Manifest)
if err := target.config.Postgres.Replace(ctx, postgresIdentity, bundle.Postgres); err != nil {
return errors.New("activate v0.7.1 PostgreSQL release")
}
if _, err := target.config.Search.Replace(ctx, searchIdentity, bundle.Search); err != nil {
return errors.New("activate v0.7.1 Elasticsearch release")
}
return nil
}
func (target *DocumentTarget) Verify(ctx context.Context, item releaseworkflow.PlanItem, change releaseworkflow.PreparedChange) error {
bundle, err := target.config.Archive.Load(change.ProductionRevision)
if err != nil {
return errors.New("load v0.7.1 release for verification")
}
if err := target.config.Verifier.Verify(ctx, item, bundle); err != nil {
return errors.New("verify v0.7.1 production release")
}
if err := target.config.Verifier.VerifyWiki(ctx, item, bundle); err != nil {
return errors.New("verify v0.7.1 production wiki release")
}
return nil
}
func (target *DocumentTarget) Compensate(ctx context.Context, item releaseworkflow.PlanItem, change releaseworkflow.PreparedChange) error {
if change.PreviousRevision == "" || change.PreviousRevision == "absent" {
manifestBundle, err := target.config.Archive.Load(change.ProductionRevision)
if err != nil {
return errors.New("load failed first release bundle")
}
postgresIdentity, searchIdentity := targetIdentities(manifestBundle.Manifest)
if err := target.config.Postgres.Disable(ctx, postgresIdentity); err != nil {
return errors.New("disable failed first PostgreSQL release")
}
if err := target.config.Search.Disable(ctx, searchIdentity); err != nil {
return errors.New("disable failed first Elasticsearch release")
}
if err := target.config.Verifier.VerifyDisabled(ctx, item); err != nil {
return errors.New("verify disabled first release")
}
return nil
}
return target.restoreBundle(ctx, change.PreviousRevision)
}
func (target *DocumentTarget) Restore(ctx context.Context, item releaseworkflow.PlanItem, revision string) (string, error) {
if revision == "absent" {
current, err := target.config.Archive.Load(item.ReleaseRevision)
if err != nil {
return "", errors.New("load current release for disable")
}
postgresIdentity, searchIdentity := targetIdentities(current.Manifest)
if err := target.config.Postgres.Disable(ctx, postgresIdentity); err != nil {
return "", errors.New("disable current PostgreSQL release")
}
if err := target.config.Search.Disable(ctx, searchIdentity); err != nil {
return "", errors.New("disable current Elasticsearch release")
}
// 文档行只做 disable,但 wiki 要整体替换成撤权后的快照,
// 否则生产 wiki 会继续留着这条文档的页面与引用。
if hasWikiSnapshot(current.Postgres) {
if err := target.config.Postgres.ReplaceWiki(ctx, postgresIdentity, current.Postgres); err != nil {
return "", errors.New("apply withdrawn v0.7.1 wiki snapshot")
}
}
return "absent", nil
}
if err := target.restoreBundle(ctx, revision); err != nil {
return "", err
}
return revision, nil
}
func (target *DocumentTarget) VerifyRestored(ctx context.Context, item releaseworkflow.PlanItem, revision string) error {
if revision == "absent" {
if err := target.config.Verifier.VerifyDisabled(ctx, item); err != nil {
return errors.New("verify disabled production release")
}
current, err := target.config.Archive.Load(item.ReleaseRevision)
if err != nil {
return errors.New("load withdrawn v0.7.1 release for wiki verification")
}
if err := target.config.Verifier.VerifyWiki(ctx, item, current); err != nil {
return errors.New("verify withdrawn v0.7.1 wiki release")
}
return nil
}
bundle, err := target.config.Archive.Load(revision)
if err != nil {
return errors.New("load restored v0.7.1 release")
}
if err := target.config.Verifier.Verify(ctx, item, bundle); err != nil {
return errors.New("verify restored v0.7.1 release")
}
if err := target.config.Verifier.VerifyWiki(ctx, item, bundle); err != nil {
return errors.New("verify restored v0.7.1 wiki release")
}
return nil
}
func (target *DocumentTarget) restoreBundle(ctx context.Context, revision string) error {
bundle, err := target.config.Archive.Load(revision)
if err != nil {
return errors.New("load prior v0.7.1 release bundle")
}
stage, err := target.config.Objects.Stage(ctx, revision, bundle.Objects)
if err != nil {
return errors.New("stage prior v0.7.1 release assets")
}
if err := target.config.Objects.Promote(ctx, stage); err != nil {
return errors.New("promote prior v0.7.1 release assets")
}
postgresIdentity, searchIdentity := targetIdentities(bundle.Manifest)
if err := target.config.Postgres.Replace(ctx, postgresIdentity, bundle.Postgres); err != nil {
return errors.New("restore prior v0.7.1 PostgreSQL release")
}
if _, err := target.config.Search.Replace(ctx, searchIdentity, bundle.Search); err != nil {
return errors.New("restore prior v0.7.1 Elasticsearch release")
}
return nil
}
func targetIdentities(manifest releasebundle.Manifest) (PostgresIdentity, SearchIdentity) {
postgresIdentity := PostgresIdentity{TenantID: manifest.Contract.TenantID, KnowledgeBaseID: manifest.Contract.KnowledgeBaseID, KnowledgeID: manifest.Contract.KnowledgeID}
return postgresIdentity, SearchIdentity(postgresIdentity)
}
var _ releaseworkflow.SidecarTarget = (*DocumentTarget)(nil)