package governance import ( "crypto/sha256" "encoding/hex" "encoding/json" "errors" "time" ) // 整库版本与作业的领域类型:与队列(jobs)分开——队列负责租约与重试, // 这里负责业务身份、阶段与结果,重启后仍能如实展示。 type LibraryVersionKind string const ( // LibraryVersionTestSealed 是测试库封存产物:只证明一份完整测试版本被封存, // 不代表生产生效,也不代表做过生产恢复演练。 LibraryVersionTestSealed LibraryVersionKind = "test_sealed" // LibraryVersionProductionEffective 是生产当前权威版本:只有生产验证通过并 // 记录证据后才能写入,测试快照不能顶替它。 LibraryVersionProductionEffective LibraryVersionKind = "production_effective" // LibraryVersionProductionPrebackup 是每次生产写入前的独立预备份。 LibraryVersionProductionPrebackup LibraryVersionKind = "production_prebackup" ) type LibraryJobKind string const ( LibraryJobSeal LibraryJobKind = "seal" LibraryJobSync LibraryJobKind = "sync" // LibraryJobRestore 是按指定整库版本恢复:与同步分开,授权与阶段也独立。 LibraryJobRestore LibraryJobKind = "restore" ) type LibraryJobState string const ( LibraryJobPending LibraryJobState = "pending" LibraryJobRunning LibraryJobState = "running" LibraryJobSucceeded LibraryJobState = "succeeded" LibraryJobFailed LibraryJobState = "failed" LibraryJobCancelled LibraryJobState = "cancelled" ) // ErrLibraryJobActive:同一目标同一类作业已有在飞作业(数据库级互斥)。 var ErrLibraryJobActive = errors.New("library job already active for this target") // ErrLibraryJobIdempotencyConflict:同一幂等键对应了不同的请求体。 var ErrLibraryJobIdempotencyConflict = errors.New("library job idempotency key reused with a different request") type LibraryStage struct { Stage string `json:"stage"` State string `json:"state"` // Total/Completed/BytesTotal/BytesDone 为 nil 表示该维度没有可靠数据, // 界面必须显示"未知",不得当 0 或据此算百分比。 Total *int64 `json:"total"` Completed *int64 `json:"completed"` BytesTotal *int64 `json:"bytes_total"` BytesDone *int64 `json:"bytes_done"` Detail string `json:"detail"` UpdatedAt time.Time `json:"updated_at"` } type LibraryJob struct { ID string `json:"id"` Scope string `json:"scope"` Kind LibraryJobKind `json:"kind"` State LibraryJobState `json:"state"` Stage string `json:"stage"` IdempotencyKey string `json:"-"` RequestDigest string `json:"request_digest"` QueueJobID string `json:"queue_job_id"` SnapshotID string `json:"snapshot_id"` TargetSnapshotID string `json:"target_snapshot_id"` Actor string `json:"actor"` Error string `json:"error"` Recovery string `json:"recovery"` CreatedAt time.Time `json:"created_at"` UpdatedAt time.Time `json:"updated_at"` FinishedAt *time.Time `json:"finished_at"` Stages []LibraryStage `json:"stages"` } type LibraryVersion struct { ID string `json:"id"` Scope string `json:"scope"` Kind LibraryVersionKind `json:"kind"` SnapshotID string `json:"snapshot_id"` VersionLabel string `json:"version_label"` SourceJobID string `json:"source_job_id"` Evidence map[string]any `json:"evidence"` CreatedBy string `json:"created_by"` CreatedAt time.Time `json:"created_at"` SupersededAt *time.Time `json:"superseded_at"` } // LibraryRequestDigest 绑定一次请求的确切含义:同键不同体必须被拒绝,而不是 // 复用旧作业。只覆盖会影响执行结果的字段;actor 不参与摘要。 // LibraryVersionID 生成版本记录 ID:library_versions.id 是 varchar(64), // 用完整快照 ID 拼会超长(真实踩过),所以用稳定短摘要——同样的输入永远得到同一个 ID, // 收尾重试因此是幂等的。 func LibraryVersionID(kind LibraryVersionKind, scope, snapshotID string) string { sum := sha256.Sum256([]byte(string(kind) + "|" + scope + "|" + snapshotID)) return "libver-" + string(kind)[:0] + hex.EncodeToString(sum[:])[:16] } // QueueJobIDFor 生成队列作业 ID:jobs.id 是 varchar(36), // 直接用业务作业 ID 加后缀会超长(真实踩过),所以用固定长度摘要。 func QueueJobIDFor(libraryJobID string) string { sum := sha256.Sum256([]byte(libraryJobID)) return "q" + hex.EncodeToString(sum[:])[:32] } func LibraryRequestDigest(scope string, kind LibraryJobKind, payload map[string]any) (string, error) { canonical := map[string]any{"scope": scope, "kind": string(kind), "payload": payload} raw, err := json.Marshal(canonical) if err != nil { return "", err } sum := sha256.Sum256(raw) return hex.EncodeToString(sum[:]), nil } // SyncStages 是生产同步作业的固定阶段顺序:先备份并核验恢复条件,再写生产, // 最后验证;失败时走恢复而不是把作业标成功。 func SyncStages() []string { // finalize 是收尾:登记生产生效版本。登记失败不得报成功,所以它是独立阶段。 return []string{"prebackup", "database", "resources", "index", "wiki", "verify", "finalize", "rollback"} } // SealStages 是封存作业的阶段:导出是原子操作,没有分项进度。 func SealStages() []string { return []string{"export"} } // LibraryReleaseAuthorization 是生产发布授权:绑定目标、快照、参数摘要与有效期。 type LibraryReleaseAuthorization struct { ID string `json:"id"` Scope string `json:"scope"` SnapshotID string `json:"snapshot_id"` ParamsDigest string `json:"params_digest"` AuthorizedBy string `json:"authorized_by"` ExpiresAt time.Time `json:"expires_at"` RevokedAt *time.Time `json:"revoked_at,omitempty"` CreatedAt time.Time `json:"created_at"` } // ValidAt 只在未撤销且未过期时为真;参数摘要由调用方显式比对。 func (a LibraryReleaseAuthorization) ValidAt(now time.Time) bool { return a.RevokedAt == nil && now.Before(a.ExpiresAt) }