98294b9583
build / build (push) Failing after 24s
why:审计 19 项(12 P1 / 7 P2)来自同一批根因,逐点试错会把协议撕成十几份:
· 意图与执行混为一谈(F01/F15):`library.sync:<scope>:<快照>` 是终身幂等键,
A→B→A 的第三次发布拿到第一次的历史成功作业,什么都不做;
· 版本行既是实体又是事件(F02/F09):主键只由 (kind,scope,快照) 决定、写入是
upsert,第二个作业覆盖 `source_job_id`/`evidence`/`created_at`;
· 接管没有代次(F13):两个 worker 都能认领同一 pending 作业,失租的旧执行还能
写业务状态、释放别人的维护锁;
· 早退与终态没有统一政策(F03/F04/F05/F06):半写窗口的前置检查失败会重新开门、
服务起不来也照样开入口、journal 终态后收尾不可重建、恢复成功不回写 current;
· 数据身份与准入各写一套(F07/F08/F14/F17):接管丢了复用语义、全库搬运不改
location_hash、通用入口可造 library.* 作业、目标模型从没被问过;
· 存储/容量/UI/CI 判据各自为政(F10/F11/F12/F16/F18/F19)。
what:按批准的一套协议集中实施(详见 handoffs/release-consolidated-implementation/
current-contract.md):
· operation(一次明确意图)/ attempt(epoch 代次)/ 不可变版本事件 / current 指针;
治理库迁移 76,只动治理库,不碰 WeKnora Schema/源码/镜像;
· 所有业务状态、阶段、版本事件、维护锁写入带 epoch 守卫(失租代次写不进去);
心跳失租立刻取消 handler;
· 半写窗口早退保持关闭;服务未全部健康绝不开入口;journal 终态可从持久事实重建
收尾;恢复成功登记 recovery 事件并推进 current;
· worker 在动维护前核对业务行/kind/scope/队列关联;通用入口拒绝 library.*;
· 全库搬运重算 location_hash 并与文档级导入共用实现;接管消费写集合的复用决定;
发布前核目标实时模型契约、容量门禁前置;
· 存储保护闭包改为全量依赖、类型只认显式登记、保护未知则不出可删候选;
· 页面核 HTTP 状态与结构、恢复纳入轮询、Wiki 差异覆盖标题/摘要/父级。
how:`make verify` rc=0(16 项必需检查全绿,含 go test 全量与前端 485 例);
`go vet ./...` rc=0;`npx tsc -p tsconfig.json --noEmit` rc=0;逐项负例见各包测试
(F03/F04/F08/F12/F13/F14/F16/F18/F19 都有先红后绿记录)。
未执行:治理库迁移到任何已有库、真实 PG/ES/S3/WeKnora 集成、故障注入、部署。
133 lines
6.0 KiB
Go
133 lines
6.0 KiB
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 用队列作业 ID 作为执行者身份;缺失时退回业务作业 ID
|
||
// (手工/测试路径没有队列身份,但至少不会与他人共用)。
|
||
func libraryQueueOwner(job jobs.Job, libraryJobID string) string {
|
||
if job.ID != "" {
|
||
return job.ID
|
||
}
|
||
return libraryJobID
|
||
}
|