knowledge-governance/internal/libraryrelease/release.go

// Package libraryrelease 是生产同步的执行编排：预备份 → 四类写入 → 验证 → 失败恢复。
//
// 它只编排顺序与责任，不自己连生产：目标读写由 Target 注入，备份由 BackupStore 注入，
// 授权由 Grant 描述。任何一步失败都不得标记成功；失败后必须尝试恢复原生产版本，
// 恢复失败要作为独立的、更严重的结论上报。
package libraryrelease

import (
	"context"
	"errors"
	"fmt"
	"time"
)

// Stage 是四类需要真实落地的数据；顺序即写入顺序。
type Stage string

const (
	StageDatabase  Stage = "database"
	StageResources Stage = "resources"
	StageIndex     Stage = "index"
	StageWiki      Stage = "wiki"
)

func Stages() []Stage { return []Stage{StageDatabase, StageResources, StageIndex, StageWiki} }

// Grant 是一次生产发布的授权：绑定确切目标与快照，带有效期与参数摘要。
// 参数一旦变化（例如换了目标快照）就必须重新授权，不能复用旧 grant。
type Grant struct {
	Target       string    `json:"target"`
	SnapshotID   string    `json:"snapshot_id"`
	ExpiresAt    time.Time `json:"expires_at"`
	ParamsDigest string    `json:"params_digest"`
	AuthorizedBy string    `json:"authorized_by"`
}

// Request 是一次待执行的生产同步。
type Request struct {
	// JobID 是这次发布的作业身份：写集合记录与预备份引用都绑定它，
	// worker 重启后凭它找回"这次写了什么"。
	JobID      string
	Target     string
	SnapshotID string
	// ParamsDigest 覆盖会影响生产结果的全部参数（目标、快照、排除范围等）。
	ParamsDigest string
	Grant        Grant
	Now          time.Time
	// PriorSnapshots 是这个目标的持久来源（成功同步过的快照 + 自己的预备份），
	// 由治理库提供。资源复用只认它作证据；为空时"目标里已有但不在预备份范围"
	// 的资源一律按冲突拒绝。
	PriorSnapshots []PriorSnapshot
}

// CurrentState 是生产当前整库的指纹，用于预备份与最终验证。
type CurrentState struct {
	Revision   string            `json:"revision"`
	Counts     map[string]int64  `json:"counts"`
	Digests    map[string]string `json:"digests"`
	CapturedAt time.Time         `json:"captured_at"`
}

// Expectation 是同步完成后生产应当具备的状态（来自测试封存）。
type Expectation struct {
	SnapshotID string
	Counts     map[string]int64
	Digests    map[string]string
}

// TableFingerprint 是一张知识域表在**整实例**上的行数与身份集合摘要（不限租户/
// 知识库）。恢复后必须与预备份时刻逐表一致：只比目标范围会让"写到范围外"的
// 残留被当成已恢复（真实事故：恢复报成功，目标仍多 67 行）。
type TableFingerprint struct {
	Count  int64  `json:"count"`
	Digest string `json:"digest"`
}

// BackupRef 指向一份可独立恢复的完整预备份。
type BackupRef struct {
	ID string `json:"id"`
	// SnapshotID 是预备份在归档里的快照身份：恢复必须按它回放，
	// 不能只记"备份路径"却不知道恢复到哪一份内容。
	SnapshotID string    `json:"snapshot_id"`
	Bytes      int64     `json:"bytes"`
	CreatedAt  time.Time `json:"created_at"`
	// Universe 是预备份时刻的整实例指纹，恢复后逐表比对。
	Universe map[string]TableFingerprint `json:"universe,omitempty"`
	// WriteSet 是本次发布的写集合与整实例内容证据。它在写第一笔之前就落盘并
	// 登记摘要；恢复必须按它清理，缺了它恢复要失败（不许降级成"跳过比对"）。
	WriteSet *WriteSet `json:"write_set,omitempty"`
	// Reused 表示"这是接管时复用上一次的预备份，没有重新备份"。
	// 崩溃接管绝不允许重新备份：那一刻目标已被写过，新备份会把半写状态当成
	// 可回滚基线，覆盖真正干净的那一份。外部要能区分"复用"与"重做"，
	// 所以复用必须显式落到版本证据里。
	Reused bool `json:"reused,omitempty"`
}

type Target interface {
	// Current 读取生产当前整库指纹；读不到就不能开始写入。
	Current(ctx context.Context) (CurrentState, error)
	// Apply 把一类数据写入生产；实现必须幂等或可回滚。
	Apply(ctx context.Context, stage Stage, snapshotID string) error
	// Verify 校验生产是否与期望一致。
	Verify(ctx context.Context, expect Expectation) error
	// Restore 把生产恢复到给定预备份。
	Restore(ctx context.Context, backup BackupRef) error
}

type BackupStore interface {
	// Prepare 创建独立完整预备份，并在返回前自检可恢复性。
	Prepare(ctx context.Context, snapshotID string, current CurrentState) (BackupRef, error)
}

// Recorder 把阶段状态写进持久作业，供页面恢复展示。
type Recorder interface {
	Stage(ctx context.Context, stage string, state string, detail string)
}

// BackupObserver 让调用方在预备份完成时立刻持久化快照身份：
// worker 被杀后重启必须能接管这份预备份，而不是重新备份覆盖它。
type BackupObserver interface {
	// 必须返回错误：预备份引用没能持久化时，worker 被杀就没有恢复基线，
	// 这种情况下一个字节都不许写目标。调用方据此直接失败。
	BackupPrepared(ctx context.Context, backup BackupRef) error
}

// FinalizeStages 是"写入完成之后的收尾"：先登记权威版本，再把作业标成功。
// 收尾失败不能报告整体成功，否则版本登记与作业状态会分叉。
func FinalizeStages() []string { return []string{"finalize"} }

type recorderFunc func(ctx context.Context, stage, state, detail string)

func (f recorderFunc) Stage(ctx context.Context, stage, state, detail string) {
	f(ctx, stage, state, detail)
}

// NoopRecorder 用于测试或不需要落库的调用。
type NoopRecorder struct{}

func (NoopRecorder) Stage(context.Context, string, string, string) {}

type Outcome struct {
	State    string    `json:"state"` // succeeded | failed | rolled_back | rollback_failed
	Backup   BackupRef `json:"backup"`
	FailedAt Stage     `json:"failed_at,omitempty"`
	Error    string    `json:"error,omitempty"`
	Rollback string    `json:"rollback,omitempty"`
	Recovery string    `json:"recovery,omitempty"`
	Finished time.Time `json:"finished"`
}

var (
	ErrGrantExpired      = errors.New("发布授权已过期")
	ErrGrantTarget       = errors.New("发布授权与目标不匹配")
	ErrGrantSnapshot     = errors.New("发布授权与快照不匹配")
	ErrGrantParams       = errors.New("发布参数与授权不一致")
	ErrBackupUnavailable = errors.New("无法创建可独立恢复的生产预备份")
)

// ValidateGrant 在动生产之前把授权核对清楚：目标、快照、参数摘要、有效期，
// 任一项不符都直接拒绝，不做"先写一半再说"。
func ValidateGrant(request Request) error {
	if request.Grant.Target != request.Target {
		return fmt.Errorf("%w：授权 %q，请求 %q", ErrGrantTarget, request.Grant.Target, request.Target)
	}
	if request.Grant.SnapshotID != request.SnapshotID {
		return fmt.Errorf("%w：授权 %q，请求 %q", ErrGrantSnapshot, request.Grant.SnapshotID, request.SnapshotID)
	}
	if request.Grant.ParamsDigest != request.ParamsDigest {
		return ErrGrantParams
	}
	now := request.Now
	if now.IsZero() {
		now = time.Now()
	}
	if request.Grant.ExpiresAt.IsZero() || !now.Before(request.Grant.ExpiresAt) {
		return ErrGrantExpired
	}
	return nil
}

// Run 执行完整链路。任何阶段失败都会尝试恢复；只有全部成功才返回 succeeded。
func Run(ctx context.Context, request Request, target Target, backups BackupStore, recorder Recorder) Outcome {
	outcome := Outcome{State: "failed", Finished: time.Now().UTC()}
	if recorder == nil {
		recorder = NoopRecorder{}
	}
	if err := ValidateGrant(request); err != nil {
		outcome.Error = err.Error()
		recorder.Stage(ctx, "prebackup", "failed", err.Error())
		return outcome
	}

	recorder.Stage(ctx, "prebackup", "running", "读取生产当前状态并创建预备份")
	current, err := target.Current(ctx)
	if err != nil {
		// 读不到生产当前状态就不能写：否则回滚目标都没有。
		outcome.Error = "读取生产当前状态失败：" + err.Error()
		recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
		return outcome
	}
	backup, err := backups.Prepare(ctx, request.SnapshotID, current)
	if err != nil {
		outcome.Error = fmt.Sprintf("%v：%v", ErrBackupUnavailable, err)
		recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
		return outcome
	}
	outcome.Backup = backup
	if observer, ok := recorder.(BackupObserver); ok {
		if err := observer.BackupPrepared(ctx, backup); err != nil {
			// 硬门禁：持久化失败 = 没有可恢复基线 = 绝不写目标。
			outcome.State = "failed"
			outcome.Error = "预备份已生成但引用无法持久化，未对生产执行任何写入：" + err.Error()
			outcome.Recovery = "预备份 " + backup.SnapshotID + " 已落盘，先修复治理库再重试"
			recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
			return outcome
		}
	}
	recorder.Stage(ctx, "prebackup", "succeeded", "预备份 "+backup.ID)

	// 写集合必须在第一笔写入之前落盘并登记：恢复只按"这次明确写了什么"清理，
	// 不按目标现状推断残渣（那会把历史孤儿/共享资源当成本次残留删掉）。
	existingPlan := backup.WriteSet != nil
	if backup.WriteSet == nil {
		if planner, ok := target.(WriteSetPlanner); ok {
			set, planErr := planner.PlanWriteSet(ctx, WriteSetPlan{JobID: request.JobID, Target: request.Target,
				BackupSnapshotID: backup.SnapshotID, TargetSnapshotID: request.SnapshotID, Universe: backup.Universe,
				PriorSnapshots: request.PriorSnapshots})
			if planErr != nil {
				outcome.State = "failed"
				outcome.Error = "写集合/冲突预检失败，未对生产执行任何写入：" + planErr.Error()
				recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
				return outcome
			}
			backup.WriteSet = &set
			outcome.Backup = backup
			if observer, ok := recorder.(WriteSetObserver); ok {
				if err := observer.WriteSetPlanned(ctx, set); err != nil {
					// 硬门禁：记录没落库 = 恢复时不知道写集合 = 一笔都不许写。
					outcome.State = "failed"
					outcome.Error = "写集合已落盘但引用无法持久化，未对生产执行任何写入：" + err.Error()
					recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
					return outcome
				}
			}
		}
	}

	// 计划已经存在（接管/恢复）时，执行目标必须**消费**它：把"这些资源已证明可复用"
	// 的决定装进去，写入阶段才会跳过共享对象。不能重新计划——那时目标已被写过，
	// 重新计划等于把半写现状当新基线（F07）。
	if existingPlan {
		if adopter, ok := target.(WriteSetAdopter); ok {
			if err := adopter.AdoptWriteSet(*backup.WriteSet); err != nil {
				outcome.State = "failed"
				outcome.Error = "无法接管已持久化的写集合，拒绝继续写目标：" + err.Error()
				recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
				return outcome
			}
		} else if _, plans := target.(WriteSetPlanner); plans {
			// 会写资源、却读不懂计划：继续写就会重写共享行/对象。
			outcome.State = "failed"
			outcome.Error = "目标实现无法消费已持久化的写集合，拒绝在失去复用语义的情况下写目标"
			recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
			return outcome
		}
	}

	for _, stage := range Stages() {
		recorder.Stage(ctx, string(stage), "running", "")
		if err = target.Apply(ctx, stage, request.SnapshotID); err != nil {
			return failAndRestore(ctx, outcome, target, recorder, stage, err)
		}
		recorder.Stage(ctx, string(stage), "succeeded", "")
	}

	recorder.Stage(ctx, "verify", "running", "")
	expect := Expectation{SnapshotID: request.SnapshotID, Counts: current.Counts, Digests: current.Digests}
	if err = target.Verify(ctx, expect); err != nil {
		return failAndRestore(ctx, outcome, target, recorder, "verify", err)
	}
	recorder.Stage(ctx, "verify", "succeeded", "")
	outcome.State = "succeeded"
	outcome.Finished = time.Now().UTC()
	return outcome
}

func failAndRestore(ctx context.Context, outcome Outcome, target Target, recorder Recorder, stage Stage, cause error) Outcome {
	outcome.FailedAt = stage
	outcome.Error = cause.Error()
	outcome.Finished = time.Now().UTC()
	recorder.Stage(ctx, string(stage), "failed", cause.Error())
	recorder.Stage(ctx, "rollback", "running", "恢复到预备份 "+outcome.Backup.ID)
	if restoreErr := target.Restore(ctx, outcome.Backup); restoreErr != nil {
		// 恢复失败比同步失败更严重：明确标出，不能当作普通失败吞掉。
		outcome.State = "rollback_failed"
		outcome.Rollback = "恢复失败：" + restoreErr.Error()
		recorder.Stage(ctx, "rollback", "failed", outcome.Rollback)
		return outcome
	}
	// "恢复工具跑完"不是"恢复完成"：必须再校验一次目标内容与预备份一致，
	// 否则页面会把半恢复状态报成已恢复（真实事故就是这样放开了维护）。
	if verifyErr := target.Verify(ctx, Expectation{SnapshotID: outcome.Backup.SnapshotID}); verifyErr != nil {
		outcome.State = "rollback_failed"
		outcome.Rollback = "恢复后校验失败（目标可能仍是半写状态）：" + verifyErr.Error()
		recorder.Stage(ctx, "rollback", "failed", outcome.Rollback)
		return outcome
	}
	outcome.State = "rolled_back"
	outcome.Rollback = "已恢复到预备份 " + outcome.Backup.ID + "，并逐表/索引/资源复核一致"
	recorder.Stage(ctx, "rollback", "succeeded", outcome.Rollback)
	return outcome
}