knowledge-governance/cmd/worker/library_writer.go

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"time"

	"knowledge-governance/internal/governance"
	"knowledge-governance/internal/jobs"
	postgresstore "knowledge-governance/internal/platform/postgres"
)

// libraryAttemptWriter 是"这一次执行代次"的写入口。
//
// 它嵌入完整 Store，只把**可变**入口换成带 epoch 守卫的实现（方法名相同，所以调用点
// 一行都不用改）。这样"谁能写业务状态/维护锁"只由这一个类型回答：handler 里拿到的
// 是 writer 而不是裸 Store，就不可能顺手绕过守卫去写。
//
// 为什么必须这样：失租的旧执行器和接管它的新代次用的是**同一个 job_id**。只加一个
// epoch 列而不让写路径读它，等于什么都没做（这正是 F13 的原始形态）。
type libraryAttemptWriter struct {
	*postgresstore.Store
	attempt governance.LibraryAttempt
}

// beginLibraryWriter 取得这个作业的执行权，返回带守卫的写入口。
// owner 用队列作业 ID：每一次投递是一个确定的执行者身份，重复投递是同一个身份（幂等），
// 不同投递互不覆盖（这正是"第二个 resumer 不能释放第一个的锁"需要的区分）。
func beginLibraryWriter(ctx context.Context, store *postgresstore.Store, jobID, owner string) (*libraryAttemptWriter, error) {
	job, err := store.LibraryJob(ctx, jobID)
	if err != nil {
		return nil, fmt.Errorf("读不到业务作业 %s：%w", jobID, err)
	}
	if job.OperationID == "" {
		// 迁移前的历史作业没有 operation：仍然取租约（防止双执行），但没有代次可守卫。
		log.Printf("library job %s has no operation id (pre-identity row): guarded writes fall back to lease only", jobID)
	}
	attempt, err := store.BeginLibraryAttempt(ctx, jobID, owner, 10*time.Minute, time.Now().UTC())
	if err != nil {
		return nil, err
	}
	return &libraryAttemptWriter{Store: store, attempt: attempt}, nil
}

func (w *libraryAttemptWriter) AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState,
	stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error {
	if err := w.checkJob(jobID); err != nil {
		return err
	}
	return w.Store.AdvanceLibraryJobGuarded(ctx, w.attempt, state, stage, message, recovery, snapshotID, targetSnapshotID, now)
}

func (w *libraryAttemptWriter) UpdateLibraryStage(ctx context.Context, jobID, stage, state string,
	total, completed, bytesTotal, bytesDone *int64, detail string, now time.Time) error {
	if err := w.checkJob(jobID); err != nil {
		return err
	}
	return w.Store.UpdateLibraryStageGuarded(ctx, w.attempt, stage, state, total, completed, bytesTotal, bytesDone, detail, now)
}

// RecordLibraryVersion 注入本次代次身份：事件登记因此也受 epoch 守卫。
func (w *libraryAttemptWriter) RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error {
	if version.OperationID == "" {
		version.OperationID = w.attempt.OperationID
	}
	if version.AttemptEpoch == 0 {
		version.AttemptEpoch = w.attempt.Epoch
	}
	version.AttemptOwner = w.attempt.Owner
	return w.Store.RecordLibraryVersion(ctx, version)
}

func (w *libraryAttemptWriter) SetLibraryMaintenanceIngress(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error {
	return w.Store.SetLibraryMaintenanceIngressGuarded(ctx, scope, ownerJobID, state, note, w.attempt, now)
}

func (w *libraryAttemptWriter) SetInstanceMaintenanceIngress(ctx context.Context, instance, ownerJobID, state, note string, now time.Time) error {
	return w.Store.SetInstanceMaintenanceIngressGuarded(ctx, instance, ownerJobID, state, note, w.attempt, now)
}

func (w *libraryAttemptWriter) UpdateLibraryMaintenanceState(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error {
	return w.Store.UpdateLibraryMaintenanceStateGuarded(ctx, scope, ownerJobID, state, note, w.attempt, now)
}

func (w *libraryAttemptWriter) UpdateInstanceMaintenanceState(ctx context.Context, instance, ownerJobID, state, note string, now time.Time) error {
	return w.Store.UpdateInstanceMaintenanceStateGuarded(ctx, instance, ownerJobID, state, note, w.attempt, now)
}

func (w *libraryAttemptWriter) ReleaseLibraryMaintenance(ctx context.Context, scope, ownerJobID string, now time.Time) error {
	return w.Store.ReleaseLibraryMaintenanceGuarded(ctx, scope, ownerJobID, w.attempt, now)
}

func (w *libraryAttemptWriter) ReleaseInstanceMaintenance(ctx context.Context, instance, ownerJobID string, now time.Time) error {
	return w.Store.ReleaseInstanceMaintenanceGuarded(ctx, instance, ownerJobID, w.attempt, now)
}

// finish 结束本次代次。失败只记日志：代次结束写不进去不该反过来把已经完成的数据收尾
// 判成失败（下一次接管会重新开始一个新代次，旧代次的残留状态由 active 唯一索引兜住）。
func (w *libraryAttemptWriter) finish(ctx context.Context, state governance.LibraryAttemptState, outcome string) {
	if w.attempt.OperationID == "" {
		return
	}
	if err := w.Store.FinishLibraryAttempt(ctx, w.attempt, state, outcome, time.Now().UTC()); err != nil &&
		!errors.Is(err, governance.ErrLibraryEpochStale) {
		log.Printf("library attempt %s#%d finish failed: %v", w.attempt.OperationID, w.attempt.Epoch, err)
	}
}

func (w *libraryAttemptWriter) checkJob(jobID string) error {
	if jobID != w.attempt.JobID {
		return fmt.Errorf("尝试用代次 %s#%d 写另一个作业 %s：拒绝（跨作业写入不是续作）",
			w.attempt.OperationID, w.attempt.Epoch, jobID)
	}
	return nil
}

// 编译期断言：writer 必须同时满足"成功收尾"与"阶段记录"两个存储面。
var (
	_ libraryMaintenanceStore = (*libraryAttemptWriter)(nil)
	_ libraryStageStore       = (*libraryAttemptWriter)(nil)
)

// libraryQueueOwner 构造**每一次投递**的执行者身份：worker + 队列作业 + 队列尝试序号。
//
// 不能用稳定的 queueJobID 单独当身份（父的复核项 R2）：同一个队列作业被重投时
// ID 不变，而执行者是新的——那样第二次投递会被误判成"同一次执行重复调用"，
// 直接复用上一代租约而不开新代次。加上 worker 与 attempt 之后：
//
//	· 同一次投递重复调用 ⇒ 身份相同 ⇒ 幂等复用；
//	· 换 worker 或换队列尝试 ⇒ 身份不同 ⇒ 必须开新代次（旧代次被结束，守卫立即失效）。
func libraryQueueOwner(workerID string, job jobs.Job, libraryJobID string) string {
	queueID := job.ID
	if queueID == "" {
		queueID = libraryJobID
	}
	worker := workerID
	if worker == "" {
		worker = "worker"
	}
	return fmt.Sprintf("%s#%s#%d", worker, queueID, job.Attempt)
}