Files
knowledge-governance/internal/releaseadapter/v071/library_capture.go
T
姚章浩 c5e033dd0e
build / build (push) Failing after 15s
fix(library): 幂等重放、跨版本去重用量与契约复核
- 同作业号重跑读持久日志+已封存清单按首次请求重放(source_read=false,
  writers_stopped=false),换范围/绑定库或清单校验失败即拒绝
- 归档用量按跨版本去重统计内容字节,清单/未引用 blob/实际分配单列,
  不再用各版本 unique 之和冒充归档占用
- 冻结窗口内复核来源契约,不一致即中止;拒绝组外同镜像运行容器
- 补齐整库只读接口的 OpenAPI 契约
- 按用户确认取消 A06:文档/页面/接口不再把效果测试列为封版门槛
2026-10-28 12:01:09 +08:00

90 lines
4.0 KiB
Go

package v071
import (
"context"
"errors"
"time"
"knowledge-governance/internal/libraryfreeze"
"knowledge-governance/internal/librarysnapshot"
)
type LibraryCaptureRequest struct {
JobID, Scope string
Identity PostgresIdentity
Compatibility librarysnapshot.Compatibility
CreatedAt time.Time
MaxDocuments int
// VerifyContract, when set, runs inside the stopped window immediately before
// the export. The caller re-reads the source contract and returns an error if
// it differs from Compatibility, so a model/index change between the
// preflight read and the maintenance window cannot be sealed silently.
VerifyContract func(context.Context) error
}
// CaptureLibrary connects maintenance to the actual PG/PIT/object archive path.
// sourceReady is mandatory and must verify the whole writer group (both scopes,
// ingress and background jobs), not only this KB. It runs before stopping and
// again inside the stopped window. Deployment must establish that the group
// contains every source writer. This function does not certify Wiki semantics,
// approve a release, or give the worker any production credentials.
func CaptureLibrary(ctx context.Context, freeze *libraryfreeze.Coordinator, archive *librarysnapshot.Archive, db librarySnapshotDB, search *SearchExporter, objects ObjectReader, sourceReady func(context.Context) error, req LibraryCaptureRequest) (libraryfreeze.Result, error) {
if freeze == nil || archive == nil || db == nil || search == nil || objects == nil || sourceReady == nil || req.CreatedAt.IsZero() || req.MaxDocuments < 1 || req.Identity.TenantID == 0 || !validSearchIdentifier(req.Identity.KnowledgeBaseID) || req.Identity.KnowledgeID != "" || (req.Scope != "internal" && req.Scope != "external") {
return libraryfreeze.Result{}, errors.New("invalid library capture configuration")
}
result, err := freeze.RunPrepared(ctx, req.JobID, func(ctx context.Context) error {
if err := checkLibrarySourceSettlement(ctx, db); err != nil {
return err
}
if err := sourceReady(ctx); err != nil {
return err
}
// Check readiness before a maintenance window, then repeat the export inside
// that window: work can arrive between preflight and the graceful stop.
_, err := ExportLibrary(ctx, db, req.Identity)
return err
}, func(ctx context.Context) (string, error) {
if err := checkLibrarySourceSettlement(ctx, db); err != nil {
return "", err
}
if err := sourceReady(ctx); err != nil {
return "", err
}
if req.VerifyContract != nil {
if err := req.VerifyContract(ctx); err != nil {
return "", err
}
}
pg, err := ExportLibrary(ctx, db, req.Identity)
if err != nil {
return "", err
}
es, err := search.ExportLibrary(ctx, SearchIdentity{TenantID: req.Identity.TenantID, KnowledgeBaseID: req.Identity.KnowledgeBaseID}, req.MaxDocuments)
if err != nil {
return "", err
}
return ArchiveLibraryCandidate(ctx, archive, req.Scope, req.Identity, req.Compatibility, pg, es, objects, req.CreatedAt)
})
if err != nil {
return result, err
}
// A successful old operation is replayable only while its exact independent
// archive still verifies, and never under another KB/scope/model contract.
saved, err := archive.Load(result.SnapshotID)
if err != nil {
return libraryfreeze.Result{}, errors.New("captured library archive no longer verifies")
}
if saved.ValidationPolicy != librarysnapshot.ArtifactAcceptancePolicy {
return libraryfreeze.Result{}, errors.New("library capture validation policy conflicts with existing job")
}
if saved.Scope != req.Scope || saved.TenantID != req.Identity.TenantID || saved.KnowledgeBaseID != req.Identity.KnowledgeBaseID || saved.Compatibility != req.Compatibility || !saved.CreatedAt.Equal(req.CreatedAt) {
return libraryfreeze.Result{}, errors.New("library capture request conflicts with existing job")
}
for _, part := range saved.Parts {
if part.Kind == "index" && part.Count > int64(req.MaxDocuments) {
return libraryfreeze.Result{}, errors.New("replayed library exceeds requested document limit")
}
}
return result, nil
}