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 集成、故障注入、部署。
153 lines
7.7 KiB
Go
153 lines
7.7 KiB
Go
package main
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"time"
|
|
|
|
"knowledge-governance/internal/governance"
|
|
"knowledge-governance/internal/libraryrelease"
|
|
postgresstore "knowledge-governance/internal/platform/postgres"
|
|
)
|
|
|
|
// libraryFailStore 是"失败出口"需要的写面:带代次守卫的失败收尾。
|
|
// 抽成接口是因为 writer 与裸 Store 都要能传进来(测试里常用裸 Store)。
|
|
type libraryFailStore interface {
|
|
AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error
|
|
UpdateLibraryMaintenanceState(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error
|
|
}
|
|
|
|
// prebackupAnchors 读"这次操作第一次拍下的那份额度":字节数与写集合摘要。
|
|
//
|
|
// 为什么必须读它而不是重新计算:接管/收尾续作都没有重新备份,手上只有已登记的事实;
|
|
// 重新用当前状态算一遍就等于把"这次用了多大一份基线、写了什么"换成猜的(F09 的现场
|
|
// 就是 backup_bytes 变成 0、writeset_digest 变空)。
|
|
func prebackupAnchors(ctx context.Context, store *postgresstore.Store, scope, jobID, backupSnapshot string) (map[string]any, error) {
|
|
version, found, err := store.LibraryVersionByRef(ctx, scope, governance.LibraryVersionProductionPrebackup, jobID, backupSnapshot)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("读不到预备份证据:%w", err)
|
|
}
|
|
if !found {
|
|
return nil, fmt.Errorf("预备份 %s 没有作业 %s 的证据行:拒绝用空锚点登记生效版本", backupSnapshot, jobID)
|
|
}
|
|
anchors := map[string]any{}
|
|
for _, key := range []string{"backup_bytes", "writeset_digest", "writeset_rows", "writeset_path",
|
|
"writeset_created_at", "backup_created_at", "index_mapping_sha256", "backup_reused"} {
|
|
if value, ok := version.Evidence[key]; ok && value != nil {
|
|
anchors[key] = value
|
|
}
|
|
}
|
|
return anchors, nil
|
|
}
|
|
|
|
// finalizeEvidence 构造"生效/恢复"事件的证据:以持久化锚点为底,补上本次动作与映射。
|
|
// 缺字节数或写集合摘要时返回错误——收尾可以补登记,但不能补出一份没有锚点的"成功"。
|
|
func finalizeEvidence(ctx context.Context, store *postgresstore.Store, scope, jobID, backupSnapshot,
|
|
targetSnapshot, action, mappingDigest string) (map[string]any, error) {
|
|
anchors, err := prebackupAnchors(ctx, store, scope, jobID, backupSnapshot)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
if _, ok := anchors["backup_bytes"]; !ok {
|
|
return nil, fmt.Errorf("预备份 %s 的证据里没有真实字节数:拒绝登记生效版本(会把 backup_bytes 洗成空)", backupSnapshot)
|
|
}
|
|
if digest, _ := anchors["writeset_digest"].(string); digest == "" {
|
|
return nil, fmt.Errorf("预备份 %s 的证据里没有写集合摘要:拒绝登记生效版本(恢复将无从按计划清理)", backupSnapshot)
|
|
}
|
|
evidence := map[string]any{"backup_snapshot": backupSnapshot, "action": action, "target_snapshot": targetSnapshot}
|
|
for key, value := range anchors {
|
|
evidence[key] = value
|
|
}
|
|
if mappingDigest != "" {
|
|
evidence["index_mapping_sha256"] = mappingDigest
|
|
}
|
|
return evidence, nil
|
|
}
|
|
|
|
// rebuildSuccessBoundary 从**持久事实**重建"内容已验证、只差收尾"的凭据。
|
|
//
|
|
// 触发场景(F05 路径一):journal 已 saved succeeded,但进程在 finishLibrarySuccess 之前
|
|
// 崩了。接管方再跑 RunWindow 会直接成功返回、不再执行 work;如果这里还依赖进程内
|
|
// pending 指针,作业就永远收不了尾(锁挂着、队列已完成、页面一直显示维护中)。
|
|
//
|
|
// 重建需要且只需要三件事:
|
|
// 1. 作业行里持久化的预备份身份(这次用的是哪份基线);
|
|
// 2. 那份预备份的证据行里有真实字节数与写集合摘要(首次锚点没被洗掉);
|
|
// 3. 生效事件存在,或可以被**幂等补登记**(不重写目标、不再 Apply)。
|
|
func rebuildSuccessBoundary(ctx context.Context, store *libraryAttemptWriter, recorder libraryStageRecorder,
|
|
payload libraryReleasePayload, previous governance.LibraryJob, kind governance.LibraryJobKind,
|
|
grant governance.LibraryReleaseAuthorization) (successBoundary, error) {
|
|
backup := previous.SnapshotID
|
|
if backup == "" {
|
|
return successBoundary{}, errors.New("窗口已成功,但作业行没有持久化预备份身份:无法证明内容基线")
|
|
}
|
|
action := string(kind)
|
|
if payload.FinalizeOnly {
|
|
action = "finalize_only"
|
|
}
|
|
if _, err := prebackupAnchors(ctx, store.Store, payload.Scope, payload.LibraryJobID, backup); err != nil {
|
|
return successBoundary{}, err
|
|
}
|
|
_, found, err := store.LibraryVersionByRef(ctx, payload.Scope, governance.LibraryVersionProductionEffective,
|
|
payload.LibraryJobID, payload.TargetSnapshotID)
|
|
if err != nil {
|
|
return successBoundary{}, fmt.Errorf("读不到生效事件:%w", err)
|
|
}
|
|
if !found {
|
|
recorder.Stage(ctx, "finalize", "running", "窗口已成功:补登记生效版本(不重写生产)")
|
|
evidence, evidenceErr := finalizeEvidence(ctx, store.Store, payload.Scope, payload.LibraryJobID, backup,
|
|
payload.TargetSnapshotID, action, recorder.mappingDigest)
|
|
if evidenceErr != nil {
|
|
return successBoundary{}, evidenceErr
|
|
}
|
|
if err := store.RecordLibraryVersion(ctx, governance.LibraryVersion{
|
|
ID: governance.LibraryVersionEventID(governance.LibraryVersionProductionEffective, payload.Scope, payload.TargetSnapshotID, store.attempt.OperationID),
|
|
Scope: payload.Scope, Kind: governance.LibraryVersionProductionEffective,
|
|
SnapshotID: payload.TargetSnapshotID, SourceJobID: payload.LibraryJobID, CreatedBy: grant.AuthorizedBy,
|
|
Evidence: evidence, CreatedAt: time.Now().UTC(),
|
|
}); err != nil {
|
|
return successBoundary{}, fmt.Errorf("补登记生效版本失败:%w", err)
|
|
}
|
|
recorder.Stage(ctx, "finalize", "succeeded", "已补登记生效版本(未重写生产)")
|
|
}
|
|
return successBoundary{Ready: true, Backup: backup, Target: payload.TargetSnapshotID,
|
|
FinishedAt: time.Now().UTC()}, nil
|
|
}
|
|
|
|
// recordRecoveryEvent 是"按预备份恢复成功"的持久事实(F06)。
|
|
//
|
|
// 它必须回答两件事,缺一不可:
|
|
// - 恢复出来的内容身份是什么(backup 快照 + 校验摘要);
|
|
// - current 现在指向它——旧实现只释放维护锁,于是物理内容已经是旧版,
|
|
// overview/diff/provenance 仍然宣称失败的新版本生效,后续操作拿错误基线做判断。
|
|
//
|
|
// 它是独立事件,不改写原来那条失败作业/失败版本;原失败事实保持不变。
|
|
func recordRecoveryEvent(ctx context.Context, store *libraryAttemptWriter, scope, jobID, backupSnapshot,
|
|
verifyDigest, note string) error {
|
|
if backupSnapshot == "" || verifyDigest == "" {
|
|
return errors.New("恢复事件缺少预备份身份或校验摘要:不能登记成恢复事实")
|
|
}
|
|
operationID := store.attempt.OperationID
|
|
evidence := map[string]any{
|
|
"backup_snapshot": backupSnapshot, "action": "recover", "verify_digest": verifyDigest,
|
|
"window_job": jobID, "note": note, "recovered_at": time.Now().UTC(),
|
|
}
|
|
// 首次锚点若存在,一并带上:恢复事件同样要能回答"这份基线多大、写集合是什么"。
|
|
if anchors, err := prebackupAnchors(ctx, store.Store, scope, jobID, backupSnapshot); err == nil {
|
|
for key, value := range anchors {
|
|
if _, exists := evidence[key]; !exists {
|
|
evidence[key] = value
|
|
}
|
|
}
|
|
}
|
|
return store.RecordLibraryVersion(ctx, governance.LibraryVersion{
|
|
ID: governance.LibraryVersionEventID(governance.LibraryVersionRecoveryVerified, scope, backupSnapshot,
|
|
operationID+"|"+jobID),
|
|
Scope: scope, Kind: governance.LibraryVersionRecoveryVerified, SnapshotID: backupSnapshot,
|
|
SourceJobID: jobID, CreatedBy: "worker", Evidence: evidence, CreatedAt: time.Now().UTC(),
|
|
})
|
|
}
|
|
|
|
var _ libraryrelease.Recorder = libraryStageRecorder{}
|