Files
knowledge-governance/internal/governance/library_flow.go
T
姚章浩 ac3b395102
build / build (push) Successful in 1m21s
fix(library): 对齐真实 WeKnora Schema + 入口级真实服务验收
为什么:候选环境改用真实 WeKnora 表结构后,暴露出多处"按猜的列名/形状"的假设,
以及若干 varchar 长度、对象定位符、空索引基线问题,导致真实链路跑不通。

- knowledge_tag_relations 无 tenant_id/KB 列 → 归属走父表;resources 作用域=绑定+chunk 引用。
- 写入顺序按真实外键;无代理键表用内容摘要核对。
- 队列作业 ID / 版本记录 ID 改固定长度摘要(列宽 varchar(36)/varchar(64))。
- 对象定位符拆 storage://<backend>/oss://<bucket>/<key>;provider 可配置。
- 空索引基线全链路一致(Current/Export/Backup/Archive),非空仍严格比对映射。
- finalize 阶段:版本登记失败不报成功;崩溃接管复用已持久化预备份。
- 迁移 000069:同一目标的 sync/restore 跨 kind 互斥。
2026-10-28 17:53:43 +08:00

153 lines
6.3 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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)
}