package libraryrelease import ( "context" "crypto/sha256" "encoding/hex" "encoding/json" "errors" "fmt" "sort" "time" ) // WriteSetVersion 是写集合台账的格式版本。读到的版本不认识就拒绝恢复: // 宁可保持维护,也不要用一份"格式变了但看起来还能读"的记录去删目标数据。 const WriteSetVersion = 1 // WriteSetRow 是台账里的一行:本次发布明确要写的精确身份 + 写前状态。 // // 为什么需要"写前状态":恢复不能在目标里按"没人引用"推断残渣。历史孤儿资源、 // 同租户另一个知识库暂未绑定的资源、被多个知识库共享的资源,都满足"没人引用", // 但它们不是这次作业写的,删掉就是数据丢失(快照里没有这些行,恢复不回来)。 // 只有写前不存在、且由本次写进去的行才允许清理。 type WriteSetRow struct { Table string `json:"table"` ID string `json:"id"` // Existing 表示写前目标里已经有这一行(属于目标自己的数据,恢复一律不许删)。 Existing bool `json:"existing"` // Owner 是写前该行的归属("/"),不存在时为空。 Owner string `json:"owner,omitempty"` // Reused 表示这一行虽然写前就在目标里、却不在预备份范围内,但已经用 // "持久作业/快照证据 + 整行内容 + 对象字节"证明与本次要写的内容完全一致, // 因此本次既不重写它、也不在恢复时清理它。 // // 不能只因为"它没被任何绑定/正文引用"就当成自己的:历史孤儿、同租户另一个 // 知识库暂未绑定的资源同样满足"没人引用",覆盖或删除同样是数据丢失。 Reused bool `json:"reused,omitempty"` // ReuseEvidence 是可复用证据文档的摘要(reuse/.json),独立于写集合, // 防止把这次推断伪装成历史台账。 ReuseEvidence string `json:"reuse_evidence,omitempty"` } // WriteSetPlan 是调用方在写第一笔之前交给目标的信息:绑定作业、目标、预备份与快照, // 以及预备份时刻的整实例证据。 type WriteSetPlan struct { JobID string Target string BackupSnapshotID string TargetSnapshotID string Universe map[string]TableFingerprint // PriorSnapshots 是治理库里"这个目标的持久来源":成功同步过的快照,以及这个 // 目标自己的预备份。资源复用必须沿它把来源追到真实登记过的快照,而不是按 // "目标里没人引用"推断归属。 PriorSnapshots []PriorSnapshot } // 复用来源的两种合法类别。 const ( // PriorSnapshotSync:这个目标成功同步过这份快照(且登记了生效版本)。 PriorSnapshotSync = "sync" // PriorSnapshotPrebackup:这份快照是从这个目标自己身上拍的预备份,把它写回去 // 就是回到本目标的历史状态。 PriorSnapshotPrebackup = "prebackup" ) // PriorSnapshot 是一次**已登记**的来源:作业身份 + 快照身份 + 来源类别。 // 只有它也含有同一个资源 ID、且行内容完全一致,才允许把目标里那行当作 // "本次写入的等价物"。 type PriorSnapshot struct { JobID string `json:"job_id"` SnapshotID string `json:"snapshot_id"` Kind string `json:"kind"` FinishedAt time.Time `json:"finished_at,omitempty"` } // WriteSet 是"这一次发布的写集合 + 写前整实例内容证据",内容寻址、可校验、 // 与 job/target/backup 绑定。恢复只读它,不读目标现状去推断。 type WriteSet struct { Version int `json:"version"` JobID string `json:"job_id"` Target string `json:"target"` TenantID uint64 `json:"tenant_id"` KnowledgeBaseID string `json:"knowledge_base_id"` BackupSnapshotID string `json:"backup_snapshot_id"` TargetSnapshotID string `json:"target_snapshot_id"` CreatedAt time.Time `json:"created_at"` Rows []WriteSetRow `json:"rows"` Universe map[string]TableFingerprint `json:"universe"` // Digest 是对除本字段外全部内容的 sha256:落盘文件名与治理库里的引用都用它, // 记录被改一个字节就对不上。 Digest string `json:"digest"` } // Seal 把行序规范化为可复现的顺序并写入摘要。调用方在落盘与登记之前必须先 Seal。 // 排序在这里落地(而不是只在算摘要时排),否则落盘字节与摘要覆盖的内容不一致。 func (w *WriteSet) Seal() error { sort.Slice(w.Rows, func(i, j int) bool { if w.Rows[i].Table != w.Rows[j].Table { return w.Rows[i].Table < w.Rows[j].Table } return w.Rows[i].ID < w.Rows[j].ID }) digest, err := w.computeDigest() if err != nil { return err } w.Digest = digest return nil } // CanonicalBytes 是不含摘要字段的规范字节:摘要覆盖的就是它,落盘文件另外 // 带上摘要本身(便于自描述),读回时用同一份规范字节重新推导。 func (w WriteSet) CanonicalBytes() ([]byte, error) { copied := w copied.Digest = "" rows := make([]WriteSetRow, len(w.Rows)) copy(rows, w.Rows) // 行序不影响语义但影响摘要:两边都按 (table,id) 排序才能算出同一个值。 sort.Slice(rows, func(i, j int) bool { if rows[i].Table != rows[j].Table { return rows[i].Table < rows[j].Table } return rows[i].ID < rows[j].ID }) copied.Rows = rows raw, err := json.Marshal(copied) if err != nil { return nil, fmt.Errorf("编码写集合失败: %w", err) } return raw, nil } func (w *WriteSet) computeDigest() (string, error) { raw, err := w.CanonicalBytes() if err != nil { return "", err } sum := sha256.Sum256(raw) return hex.EncodeToString(sum[:]), nil } // Verify 校验摘要与必备身份。缺任一身份都必须失败:没有绑定就没有"这份记录属于 // 这个作业/目标/预备份"的证明,拿它去删目标数据无法追责。 func (w *WriteSet) Verify() error { if w.Version != WriteSetVersion { return fmt.Errorf("写集合记录版本 %d 不受支持(当前 %d)", w.Version, WriteSetVersion) } if w.JobID == "" || w.BackupSnapshotID == "" || w.TargetSnapshotID == "" { return errors.New("写集合记录缺少作业/预备份/快照绑定") } if w.TenantID == 0 || w.KnowledgeBaseID == "" { return errors.New("写集合记录缺少目标范围身份") } if len(w.Universe) == 0 { return errors.New("写集合记录缺少整实例内容证据") } if w.Digest == "" { return errors.New("写集合记录没有摘要") } for _, row := range w.Rows { if row.Reused && !row.Existing { return fmt.Errorf("写集合记录把 %s/%s 标成可复用却不是写前已存在行", row.Table, row.ID) } if row.Reused && row.ReuseEvidence == "" { return fmt.Errorf("写集合记录把 %s/%s 标成可复用却没有证据摘要", row.Table, row.ID) } } digest, err := w.computeDigest() if err != nil { return err } if digest != w.Digest { return errors.New("写集合记录摘要不符(内容被改动或截断)") } return nil } // CreatedIDs 返回"本次新建"的精确身份(写前不存在的行)。恢复只允许删这些。 func (w WriteSet) CreatedIDs(table string) []string { ids := make([]string, 0, 8) for _, row := range w.Rows { if row.Table == table && !row.Existing { ids = append(ids, row.ID) } } sort.Strings(ids) return ids } // ExistingIDs 返回写前已存在的身份(用于恢复后复核"目标自己的行都还在")。 func (w WriteSet) ExistingIDs(table string) []string { ids := make([]string, 0, 8) for _, row := range w.Rows { if row.Table == table && row.Existing { ids = append(ids, row.ID) } } sort.Strings(ids) return ids } // ReusedIDs 返回本次"证明可复用、因此既不重写也不清理"的精确身份。 // 它与 CreatedIDs 互斥,恢复清理一律不看这里(复用行必须原样保留)。 func (w WriteSet) ReusedIDs(table string) []string { ids := make([]string, 0, 8) for _, row := range w.Rows { if row.Table == table && row.Reused { ids = append(ids, row.ID) } } sort.Strings(ids) return ids } // UniverseDigest 是整实例证据的摘要,随台账一起登记,便于独立核对。 func (w WriteSet) UniverseDigest() string { if len(w.Universe) == 0 { return "" } tables := make([]string, 0, len(w.Universe)) for table := range w.Universe { tables = append(tables, table) } sort.Strings(tables) type pair struct { Count int64 `json:"count"` Digest string `json:"digest"` } ordered := make([]pair, 0, len(tables)) for _, table := range tables { ordered = append(ordered, pair{Count: w.Universe[table].Count, Digest: w.Universe[table].Digest}) } raw, err := json.Marshal(struct { Tables []string `json:"tables"` Values []pair `json:"values"` }{Tables: tables, Values: ordered}) if err != nil { return "" } sum := sha256.Sum256(raw) return hex.EncodeToString(sum[:]) } // WriteSetPlanner 由能访问目标与归档的实现提供:它在写第一笔之前算出写集合、 // 拒绝跨范围 ID 冲突,并把记录落盘。失败即"一笔都不许写"。 type WriteSetPlanner interface { PlanWriteSet(ctx context.Context, plan WriteSetPlan) (WriteSet, error) } // WriteSetAdopter 让"计划已经存在"的执行也能带上复用语义(F07)。 // // 触发场景:首次 planner 证明某些 resources 可复用 → 写集合落盘 → 进程中断 → 接管时用 // **新进程/新 target** 继续。写集合已存在,planner 因此被跳过;如果执行目标不消费这份 // 计划,它会按"没有复用"重新 upsert 资源行并重传对象——账本说"共享对象没动",实际却 // 重写了共享对象。必须显式接管计划,而不是重新按半写现状计划一遍。 type WriteSetAdopter interface { AdoptWriteSet(set WriteSet) error } // WriteSetObserver 让调用方在写第一笔之前把写集合摘要持久化到治理库。 // 失败同样意味着"一笔都不许写":没有可追溯的写集合,恢复就只能靠推断。 type WriteSetObserver interface { WriteSetPlanned(ctx context.Context, set WriteSet) error }