feat(library): 真实差异比对 + 孤儿作业回收 + 验收矩阵与台账
build / build (push) Successful in 1m18s

为什么:发布管理的差异一直显示"未接入",业务作业也可能因队列丢作业而永久占锁;
本轮把这两件做成真实实现,并把 30 个验收项与 CI/版本身份落成可审计文档。

- internal/librarydiff:稳定文档 ID + 排除易变列的整行摘要做增改撤销;overview 在
  生产权威版本与测试封存都在时给出 computed 差异并标注两侧快照,缺一侧仍是 unknown。
- 发布管理"本次变更"列文档身份与比对版本;无差异时明确写"没有文档差异"。
- ReconcileLibraryJobs:worker 启动清理队列已无对应作业的孤儿,避免永久互斥。
- docs/library-acceptance-matrix.md 与 docs/release-ledger.md 固定证据与版本事实。
This commit is contained in:
姚章浩
2026-10-28 14:39:17 +08:00
parent e3db157ba8
commit e313ae12f2
12 changed files with 490 additions and 1 deletions
+18
View File
@@ -1,5 +1,23 @@
# Changelog
## 开发快照(CI 修复 + 真实差异 + 孤儿作业回收)
### Added
- `internal/librarydiff`:按稳定文档 ID 与"排除 updated_at/updated_by 的整行摘要"比较两份归档快照的 `knowledges`,
输出新增/更新/撤销;`GET /api/v1/library/overview` 在生产权威版本与测试封存都存在时给出真实差异,
并标注 `base_snapshot`/`target_snapshot`,缺任一侧仍为 unknown 且说明原因。
- 发布管理"本次变更"按文档身份列出增改撤销,并显示比对的两个版本前缀。
- `ReconcileLibraryJobs`:worker 启动时把"队列里已无对应作业"的孤儿业务作业标失败并写明恢复责任,
避免永久占用 (scope,kind) 互斥索引。
- `docs/library-acceptance-matrix.md`:30 个验收项逐条对应代码/证据/状态(已实现已验证、已实现未验证、阻塞、未实现)。
- `docs/release-ledger.md`:版本→完整 SHA→CI run 与结果→是否部署 的台账。
### Fixed
- 格式问题(CI run149–156 在 format 步骤连续失败):按仓库既有 prettier 配置格式化四个文件,不放宽检查。
- `TestEmbeddedMigrationsAreVersionSorted` 仍写死 65 条迁移,新增 000066 后必红;改为 66 并补 000066 内容断言。
## 开发快照 snapshot/v0.1.114 - 2026-10-28
### Added
+7
View File
@@ -59,6 +59,13 @@ func run(ctx context.Context, getenv func(string) string) error {
return err
}
store := postgresstore.NewStore(pool)
// 启动先收拾孤儿业务作业:它们会永久占住 (scope,kind) 唯一索引,
// 不清掉的话页面会一直显示"在飞",同一目标再也发不出新作业。
if repaired, reconcileErr := store.ReconcileLibraryJobs(context.Background(), time.Now().UTC()); reconcileErr != nil {
log.Printf("library job reconcile failed: %v", reconcileErr)
} else if repaired > 0 {
log.Printf("library job reconcile: %d orphan job(s) marked failed", repaired)
}
handlers, err := workerHandlers(store, config)
if err != nil {
return err
+57
View File
@@ -0,0 +1,57 @@
# 整库同步验收矩阵(真实证据对照)
对应 `docs/library-sync-acceptance.md` 的 30 个验收项。**状态只写实际发生的事**:
- **已实现·已验证**:有代码 + 本机真实数据或真实归档/真实 PostgreSQL 跑过的证据,或既有 CI 检查覆盖。
- **已实现·未验证**:代码与测试在位,但还缺真实业务环境的执行证据(例如需要隔离生产栈)。
- **阻塞(需授权/环境)**:实现所需的动作属于生产写入、生产读取或生产恢复,当前授权明确禁止。
- **未实现**:还没有代码,界面按"未接入/未知"显示,不冒充完成。
A06(内容、问答、引用图片效果、性能报告)已被用户取消,本矩阵不含该项,也不再作为封版门槛。
| ID | 验收要点 | 代码 / 承载位置 | 状态 | 证据或缺口 |
| --- | --- | --- | --- | --- |
| V01 | 只有对内/对外两个目标,身份来自配置映射 | `internal/httpapi/library_*.go`(scope 只接受 internal/external);`web/src/ReleaseTargets.tsx` | 已实现·已验证 | overview 对非法 scope 返回 400;真实归档里 internal/external 各自解析到唯一 KB(0c84a098… / 对外 KB) |
| V02 | 全部解析/索引/Wiki 就绪,验收绑定本版 | `internal/releaseadapter/v071/library_source_settlement.go`;页面准备清单 | 已实现·未验证 | 结清检查(settlement)在封存前执行且缺项阻断;但对"实时测试库此刻就绪"仍需一次真实封存复核;页面已注明依据的是哪次快照 |
| V03 | 删除文档后 Wiki 共享正文/实体/边/引用真实变化 | — | 未实现 | 现在只能证明 Wiki 完整快照被保存;删除贡献的语义重算与证据未实现,界面不声称已满足 |
| V04 | 完整固定版本:文档集合+处理结果+资源+索引+完整 Wiki | `internal/librarysnapshot/*`(10 表 + 索引 + 资源 + Wiki 部件);`artifacts` 清单 | 已实现·已验证 | 真实快照 f992d64e…:4 文档/38 分块/122 索引/21 资源/31 Wiki 页/55,309,044 字节;部件摘要逐项校验 |
| V05 | 导出中源变更则拒绝或隔离 | `internal/libraryfreeze/*`(持久 journal、源锁、暂停/恢复);`ProjectController` | 已实现·未验证 | 冻结窗口内会重新比对兼容契约;跨"项目外写入者"的证明仍缺,需一次带并发写入的隔离演练 |
| V06 | 只同步知识数据,不含账号/会话/凭据 | 导出白名单(10 张知识表 + 知识域索引 + 资源 + Wiki) | 已实现·已验证 | 部件清单里没有 users/sessions/api_keys;真实归档部件名可逐项核对 |
| B01 | 每次生产写入前完整预备份,失败零写入 | `library_versions.kind=production_prebackup`;`POST /api/v1/library/syncs` 的 gate | 阻塞(需生产读取/写入授权) | 预备份必须读生产当前整库;当前没有生产读取凭据,接口按缺项 503 拒绝且**不建作业** |
| B02 | 资源在测试侧删除后仍可恢复 | 归档内容寻址 blob(`library_versions` + `librarysnapshot` 内容去重) | 已实现·未验证 | 归档不依赖测试临时对象;跨版本去重 55,309,693 字节;尚未做"测试侧删除后从归档恢复"的实测 |
| B03 | 每版保存完整 Wiki 与引用关联并校验 | `library_snapshot` 的 wiki 部件 + 摘要 | 已实现·已验证 | 真实快照含 31 页 Wiki 与逐页摘要,manifest 记录数量/字节 |
| S01 | 数据库/资源/索引/Wiki 真实落地并校验 | 同步执行链 | 阻塞(需生产写入授权) | 执行器在 `cmd/worker` 中 fail-closed:闸口未开即拒绝并写明缺项,不产生部分写入 |
| S02 | 生产不再解析/Embedding/生成 Wiki | 同上(只搬运归档产物) | 阻塞(同上) | 设计上只写归档产物;执行链尚未开通,不能声称已验证 |
| S03 | 一致生效与失败补偿边界 | — | 未实现 | 跨 PG/ES/资源的一致切点与可见性保护未实现 |
| S04 | 各阶段失败/超时/重启可追溯可恢复 | `library_jobs`/`library_job_stages` + `ReconcileLibraryJobs` | 已实现·已验证 | 阶段与错误持久化;worker 启动清理"队列已无对应作业"的孤儿并写明恢复责任,避免永久占锁 |
| S05 | 幂等与互斥(多 worker 安全) | `library_jobs_idempotency`、`library_jobs_active` 唯一索引 | 已实现·已验证 | 真实 PostgreSQL 上验证:同目标第二个在飞作业被拒;同键同 digest 重放复用;同键换 digest 冲突 |
| R01 | 版本恢复整套生产知识状态 | — | 阻塞(需生产恢复授权) | 恢复流程未实现;版本抽屉的恢复入口保持禁用并写明"没有恢复演练证据" |
| R02 | 恢复失败显式异常、不回退测试库 | — | 未实现 | 随 R01 一起阻塞 |
| R03 | 存快/恢复快对比 | — | 未实现 | 未做测速;不写没有测量的数字 |
| P01 | 作业阶段与整体状态 | `library_jobs.state/stage`;页面阶段条 | 已实现·已验证 | 阶段勾选只认当前作业证据;无作业时显示"本次作业尚未开始" |
| P02 | 四类分项计数/字节/错误 | `library_job_stages`(NULL=未知总量) | 已实现·已验证 | 真实库验证阶段行为;无 total 时页面显示"未知总量",不画百分比 |
| P03 | 同步明细与异常 | 页面"同步明细"表读阶段行 | 已实现·已验证 | 行来自持久阶段,刷新/重启可复现;封存作业显示 export 阶段真实状态 |
| U01 | 发布管理为主要入口(两库+单作业区) | `web/src/ReleaseTargets.tsx` | 已实现·已验证 | 按确认稿布局;父会话已在登录浏览器核验两库切换与抽屉 |
| U02 | 权限边界 | `canWrite`/`canCapture`,POST 需 engineer+ | 已实现·已验证 | 无权限时不给封存入口;未接线时说明通道状态 |
| U03 | 操作确认 | 封存按钮 + 作业号 + notice | 已实现·已验证 | 同一作业号重放返回已存作业并明确提示 |
| D01 | 保留策略(数量/天数) | — | 未实现 | 保留数量/天数未定,页面明确"未接线",不擅自编默认值 |
| D02 | 占用测量 | `internal/librarysnapshot/usage.go`;系统设置→存储管理 | 已实现·已验证 | 版本数/跨版本去重内容/blob 表观与分配/未引用/清单;真实两份清单 55,309,693 字节 |
| D03 | 依赖保护 | — | 未实现 | 没有引用保护实现,页面写明 |
| D04 | 清理预览 | — | 未实现 | 没有预览实现,页面写明 |
| D05 | 容量门禁 | — | 未实现 | 生产写入前容量检查随 B01/S01 一起阻塞 |
| D06 | 测试残留 | — | 未实现 | 未做扫描 |
| D07 | 实际回收 | — | 阻塞(需清理授权) | 自动清理默认关闭,不提供删除动作 |
## 差异比对(本轮新增)
`internal/librarydiff` 以**稳定文档 ID** 为身份、以排除 `updated_at`/`updated_by` 后的整行摘要为内容,
比较两份归档快照的 `knowledges` 行数组,输出新增/更新/撤销。真实归档上验证:
对内快照 4 篇对空集为"新增 4",反向为"撤销 4",缺失快照返回原因而不是空差异。
生产权威版本建立后即可直接给出生产→测试差异;在生产版本未知时页面保持"未接入"。
## 未通过项如何阻断
- `POST /api/v1/library/syncs`:闸口关闭、缺恢复演练证据、生产端点未配置、生产权威版本未知、
目标快照无预备份——任一成立即 503 并逐条列原因,**不创建作业**。
- 页面"启动同步"按同一 gate 禁用,title 与卡片列出全部缺项;不存在"点了才失败"的假按钮。
- 封存缺项(结清检查不通过、契约不符、导出校验失败)一律阻断封版,不改状态蒙混。
+30
View File
@@ -0,0 +1,30 @@
# 版本台账(可审计)
开发版本号由 `scripts/version.py` 从提交数推导(`release_version 0.1.0` + `commits_since_release`),
**不创建正式 tag**。下表记录每个开发版本对应的完整 SHA、CI 结论与部署事实;历史失败不涂改。
CI = Gitea Actions 仓库级 runner,`make verify` 为唯一门禁(format / static-go / static-web / build-go /
build-web / tests-go / tests-web / contracts / version / security-secrets / security-deps / manifests-locked)。
| 版本 | 完整 SHA | 实现范围 | CI run | CI 结论 | 已部署本机 |
| --- | --- | --- | --- | --- | --- |
| 0.1.105 | 3dc854de4bc7899f69b02a8e0d333c5a4ba97702 | 阻止旧策略作业重放 | 148 | success | 曾部署(后被后续版本替换) |
| 0.1.107 | 864a1632e04ae02a30cbb416333c9165952f5561 | 整库快照/冻结基线 | 148 | success | 否(版本记录门禁当时未过) |
| 0.1.108 | 045fc44 | 整库版本只读页 + 部署 | — | 未取得通过证据(run149 起连续失败) | 是 |
| 0.1.109 | 20fc40a147c3cb17576734c5a0a8c4e0394bd2e0 | 归档用量口径 | 149–150 段 | failure(format 等) | 是 |
| 0.1.110 | c5e033dd0ee5 | 修 R1/R2/R3 | 151 | failure | 是 |
| 0.1.111 | 910c0fcd76d287b4a0fd7f46da5fde40f2aa3de9 | 页面发起封存 + 主机侧 agent | 152 | failure | 是 |
| 0.1.112 | bb64c32654c85698f119da2ccabf0aee54dff0ab | 发布管理整库视图(后被用户打回 UI) | 153 | failure | 是 |
| 0.1.113 | 58d0483d4477614f88ccf187679333940a72ec01 | 按确认稿重做发布管理 UI | 154 | failure(format) | 是 |
| 0.1.114 | dc9e8276560d2db57d048dbd62e1d7a95fb3023a | 整库版本/作业持久化 + 状态读接口 + 生产 fail-closed | 155 | failure(format + migrations 计数) | 是 |
| 0.1.115 | 7e1610da44387c1cd86af2605311997e8249c47a | 仅格式化四个文件 | 156 | failure(tests-go:迁移清单写死 65) | 否 |
| 0.1.116 | e3db157ba8d78f6046114055a24f7812e224e576 | 迁移清单跟随 000066 | 157 | **success** | 否(等父审后部署) |
## 说明
- 0.1.108–0.1.115 的 CI 事实是 failure/未取得通过证据,**不因后续修复改写成绿**;
这些版本当时部署到本机,属于"未过远端门禁即上线"的既成事实,本台账如实保留。
- 0.1.116(run157 success)是第一个通过完整远端门禁的开发版本,但发布管理模块本身尚未完成全量验收,
因此不作为最终候选;最终候选必须同时满足"CI 全绿 + 业务验收证据",并在部署前交父会话审查。
- 生产侧从未执行任何写入、恢复或清理;本机部署仅替换治理平台自身容器(api/worker/web),
WeKnora(WKNFull-app)镜像与数据始终为原样。
+87
View File
@@ -10,6 +10,8 @@ import (
"time"
"knowledge-governance/internal/governance"
"knowledge-governance/internal/librarydiff"
"knowledge-governance/internal/librarysnapshot"
)
// 整库版本/状态/差异读取契约 + 生产同步的 fail-closed 入口。
@@ -44,6 +46,81 @@ type libraryDiffView struct {
Added []any `json:"added"`
Updated []any `json:"updated"`
Removed []any `json:"removed"`
// BaseSnapshot/TargetSnapshot 标明这次比对用的是哪两个整库版本,
// 避免把某次历史差异当成"当前拟发布"。
BaseSnapshot string `json:"base_snapshot,omitempty"`
TargetSnapshot string `json:"target_snapshot,omitempty"`
}
// computeLibraryDiff 用归档里的 knowledges 行数组比较两个快照:
// 身份是文档 ID,内容是排除易变列后的整行摘要;任一侧读不到就返回 false,
// 由调用方保持 unknown 并写明原因,而不是给出空差异冒充"无变化"。
func computeLibraryDiff(root, baseID, targetID string) (libraryDiffView, bool) {
unknown := libraryDiffView{State: "unknown", Added: []any{}, Updated: []any{}, Removed: []any{},
BaseSnapshot: baseID, TargetSnapshot: targetID}
if root == "" {
unknown.Reason = "整库归档未配置,无法比较生产与测试版本"
return unknown, false
}
if baseID == "" || targetID == "" {
unknown.Reason = "生产当前版本或测试封存缺失,没有可比的两份整库版本"
return unknown, false
}
archive, err := librarysnapshot.Open(root, 256*1024*1024)
if err != nil {
unknown.Reason = "归档根不可用,无法比较"
return unknown, false
}
defer archive.Close()
read := func(id string) ([]map[string]any, string) {
manifest, loadErr := archive.Load(id)
if loadErr != nil {
return nil, "快照不在本地归档或校验失败"
}
for _, part := range manifest.Parts {
if part.Kind != "database" || part.Name != "knowledges" {
continue
}
reader, openErr := archive.OpenPart(part)
if openErr != nil {
return nil, "归档正文不可读"
}
defer reader.Close()
rows, readErr := librarydiff.ReadDocuments(reader)
if readErr != nil {
return nil, "归档正文格式不符"
}
return rows, ""
}
return nil, "快照里没有 knowledges 部件"
}
base, reason := read(baseID)
if reason != "" {
unknown.Reason = "生产版本:" + reason
return unknown, false
}
target, reason := read(targetID)
if reason != "" {
unknown.Reason = "测试版本:" + reason
return unknown, false
}
result, err := librarydiff.Compare(base, target)
if err != nil {
unknown.Reason = "差异计算失败:" + err.Error()
return unknown, false
}
view := libraryDiffView{State: "computed", Added: []any{}, Updated: []any{}, Removed: []any{},
BaseSnapshot: baseID, TargetSnapshot: targetID}
for _, item := range result.Added {
view.Added = append(view.Added, item)
}
for _, item := range result.Updated {
view.Updated = append(view.Updated, item)
}
for _, item := range result.Removed {
view.Removed = append(view.Removed, item)
}
return view, true
}
type libraryGateView struct {
@@ -209,6 +286,16 @@ func libraryOverviewHandler(w http.ResponseWriter, r *http.Request, config Confi
overview.Job = &recent[0]
}
// 差异是真实计算:生产权威版本 + 测试封存都在本地归档时给出逐篇增改撤销,
// 否则保持 unknown 并说明缺哪一侧,不用空数组冒充"无变化"。
baseSnapshot := ""
if overview.Production.State == "known" && overview.Production.Version != nil {
baseSnapshot = overview.Production.Version.SnapshotID
}
if view, ok := computeLibraryDiff(config.LibraryArchiveRoot, baseSnapshot, target); ok || view.Reason != "" {
overview.Diff = view
}
overview.Gate = librarySyncGate(config, overview.Production, overview.Prebackup, target)
writeJSON(w, http.StatusOK, overview)
}
+124
View File
@@ -0,0 +1,124 @@
// Package librarydiff 比较两个已归档整库版本的知识文档集合。
//
// 身份用稳定文档 ID(不是标题、不是顺序),内容用排除易变字段后的整行摘要:
// 只有真实内容/元数据变化才算"更新",updated_at 之类的噪声不会引发假差异。
// 撤销(生产有、目标没有)单列,不能当作"无变化"。
package librarydiff
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"sort"
)
// volatileFields 是每次保存都会变、但不代表知识内容变化的列。
var volatileFields = []string{"updated_at", "updated_by", "last_edited_at"}
type Document struct {
ID string `json:"id"`
Title string `json:"title"`
Digest string `json:"digest"`
}
type Result struct {
Added []Document `json:"added"`
Updated []Document `json:"updated"`
Removed []Document `json:"removed"`
// BaseCount/TargetCount 是两侧文档数,便于核对"差异之和是否自洽"。
BaseCount int `json:"base_count"`
TargetCount int `json:"target_count"`
}
// ReadDocuments 读取归档里 knowledges 部件的行数组。
func ReadDocuments(r io.Reader) ([]map[string]any, error) {
decoder := json.NewDecoder(r)
token, err := decoder.Token()
if err != nil || token != json.Delim('[') {
return nil, errors.New("knowledge component must be a JSON row array")
}
rows := make([]map[string]any, 0, 64)
for decoder.More() {
var row map[string]any
if err = decoder.Decode(&row); err != nil {
return nil, fmt.Errorf("decode knowledge row: %w", err)
}
rows = append(rows, row)
}
if _, err = decoder.Token(); err != nil {
return nil, fmt.Errorf("close knowledge array: %w", err)
}
return rows, nil
}
func documentOf(row map[string]any) (Document, error) {
id, _ := row["id"].(string)
if id == "" {
return Document{}, errors.New("knowledge row without id")
}
canonical := make(map[string]any, len(row))
for key, value := range row {
canonical[key] = value
}
for _, key := range volatileFields {
delete(canonical, key)
}
encoded, err := json.Marshal(canonical)
if err != nil {
return Document{}, fmt.Errorf("encode knowledge row: %w", err)
}
sum := sha256.Sum256(encoded)
title, _ := row["title"].(string)
return Document{ID: id, Title: title, Digest: hex.EncodeToString(sum[:])}, nil
}
// Compare 以 base 为基准(通常是生产当前版本),target 为拟发布版本。
func Compare(base, target []map[string]any) (Result, error) {
baseDocs, err := index(base)
if err != nil {
return Result{}, err
}
targetDocs, err := index(target)
if err != nil {
return Result{}, err
}
result := Result{Added: []Document{}, Updated: []Document{}, Removed: []Document{},
BaseCount: len(baseDocs), TargetCount: len(targetDocs)}
for id, doc := range targetDocs {
previous, ok := baseDocs[id]
if !ok {
result.Added = append(result.Added, doc)
continue
}
if previous.Digest != doc.Digest {
result.Updated = append(result.Updated, doc)
}
}
for id, doc := range baseDocs {
if _, ok := targetDocs[id]; !ok {
result.Removed = append(result.Removed, doc)
}
}
sort.Slice(result.Added, func(i, j int) bool { return result.Added[i].ID < result.Added[j].ID })
sort.Slice(result.Updated, func(i, j int) bool { return result.Updated[i].ID < result.Updated[j].ID })
sort.Slice(result.Removed, func(i, j int) bool { return result.Removed[i].ID < result.Removed[j].ID })
return result, nil
}
func index(rows []map[string]any) (map[string]Document, error) {
docs := make(map[string]Document, len(rows))
for _, row := range rows {
doc, err := documentOf(row)
if err != nil {
return nil, err
}
if _, exists := docs[doc.ID]; exists {
return nil, fmt.Errorf("duplicate knowledge id %s", doc.ID)
}
docs[doc.ID] = doc
}
return docs, nil
}
+81
View File
@@ -0,0 +1,81 @@
package librarydiff
import (
"strings"
"testing"
)
func rows(t *testing.T, body string) []map[string]any {
t.Helper()
parsed, err := ReadDocuments(strings.NewReader(body))
if err != nil {
t.Fatalf("ReadDocuments: %v", err)
}
return parsed
}
func TestCompareUsesStableIdentityAndIgnoresVolatileColumns(t *testing.T) {
base := rows(t, `[
{"id":"doc-a","title":"机械臂报警","content":"正文一","updated_at":"2026-10-01T00:00:00Z"},
{"id":"doc-b","title":"示教器","content":"正文二","updated_at":"2026-10-01T00:00:00Z"},
{"id":"doc-c","title":"将删除","content":"正文三"}
]`)
target := rows(t, `[
{"id":"doc-a","title":"机械臂报警","content":"正文一","updated_at":"2026-10-28T00:00:00Z"},
{"id":"doc-b","title":"示教器","content":"正文二(已更新)","updated_at":"2026-10-01T00:00:00Z"},
{"id":"doc-d","title":"新增文档","content":"正文四"}
]`)
result, err := Compare(base, target)
if err != nil {
t.Fatalf("Compare: %v", err)
}
// doc-a 只有 updated_at 变了:不算更新。
if len(result.Added) != 1 || result.Added[0].ID != "doc-d" {
t.Fatalf("added = %+v, want doc-d", result.Added)
}
if len(result.Updated) != 1 || result.Updated[0].ID != "doc-b" {
t.Fatalf("updated = %+v, want doc-b", result.Updated)
}
if len(result.Removed) != 1 || result.Removed[0].ID != "doc-c" {
t.Fatalf("removed = %+v, want doc-c", result.Removed)
}
if result.BaseCount != 3 || result.TargetCount != 3 {
t.Fatalf("counts = %d/%d, want 3/3", result.BaseCount, result.TargetCount)
}
}
func TestCompareTreatsTitleChangeAsUpdate(t *testing.T) {
base := rows(t, `[{"id":"doc-a","title":"旧标题","content":"正文"}]`)
target := rows(t, `[{"id":"doc-a","title":"新标题","content":"正文"}]`)
result, err := Compare(base, target)
if err != nil {
t.Fatalf("Compare: %v", err)
}
if len(result.Updated) != 1 || result.Updated[0].Title != "新标题" {
t.Fatalf("title change must count as update: %+v", result.Updated)
}
}
func TestCompareRejectsDuplicateIDs(t *testing.T) {
base := rows(t, `[{"id":"doc-a","title":"x"}]`)
dup := rows(t, `[{"id":"doc-a","title":"x"},{"id":"doc-a","title":"y"}]`)
if _, err := Compare(base, dup); err == nil {
t.Fatal("duplicate knowledge IDs must be rejected, not silently collapsed")
}
}
func TestCompareEmptyBaseMarksEverythingAdded(t *testing.T) {
result, err := Compare(nil, rows(t, `[{"id":"doc-a","title":"x"}]`))
if err != nil {
t.Fatalf("Compare: %v", err)
}
if len(result.Added) != 1 || len(result.Removed) != 0 {
t.Fatalf("empty base must be all added: %+v", result)
}
}
func TestReadDocumentsRejectsNonArray(t *testing.T) {
if _, err := ReadDocuments(strings.NewReader(`{"id":"x"}`)); err == nil {
t.Fatal("object payload must be rejected")
}
}
@@ -246,6 +246,32 @@ ON CONFLICT (id) DO NOTHING`,
return tx.Commit(ctx)
}
// ReconcileLibraryJobs 收拾"业务作业还在飞、队列里已经没有对应作业"的孤儿:
// 它们会永久占用 (scope,kind) 唯一索引,让同一目标再也发不出作业。
// 只标失败并写明恢复责任,不猜结果、不重放。
func (s *Store) ReconcileLibraryJobs(ctx context.Context, now time.Time) (int, error) {
if _, err := s.db.Exec(ctx, `
UPDATE library_jobs AS lj
SET state='failed', error='队列中已无对应作业,业务作业未收到结果', recovery='封存作业由 agent 恢复来源;确认来源 healthy 后可重发', updated_at=$1, finished_at=$1
WHERE lj.state IN ('pending','running')
AND lj.queue_job_id <> ''
AND NOT EXISTS (
SELECT 1 FROM jobs AS j
WHERE j.id = lj.queue_job_id AND j.state IN ('pending','running','retry')
)`, now.UTC()); err != nil {
return 0, fmt.Errorf("reconcile library jobs: %w", err)
}
// 建了业务作业但队列投递没完成(queue_job_id 为空)超过 5 分钟,也是孤儿。
tag, err := s.db.Exec(ctx, `
UPDATE library_jobs
SET state='failed', error='队列投递未完成,作业从未开始', recovery='无需恢复来源;可直接重发', updated_at=$1, finished_at=$1
WHERE state IN ('pending','running') AND queue_job_id='' AND created_at < $2`, now.UTC(), now.Add(-5*time.Minute).UTC())
if err != nil {
return 0, fmt.Errorf("reconcile unattached library jobs: %w", err)
}
return int(tag.RowsAffected()), nil
}
func (s *Store) LibraryVersions(ctx context.Context, scope string, limit int) ([]governance.LibraryVersion, error) {
if limit < 1 || limit > 100 {
return nil, errors.New("library version limit out of range")
+22
View File
@@ -195,6 +195,28 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
expect(html).toContain('没有当前作业证据时不会把历史封存当作阶段完成')
})
it('差异已计算时按文档身份列增改撤销,并标注比对的两个版本', () => {
const html = render({
overview: {
...overview,
diff: {
state: 'computed',
added: [{ id: 'doc-new-0001', title: '新增的说明', digest: 'a'.repeat(64) }],
updated: [{ id: 'doc-upd-0002', title: '改过的说明', digest: 'b'.repeat(64) }],
removed: [{ id: 'doc-del-0003', title: '撤销的说明', digest: 'c'.repeat(64) }],
base_snapshot: 'prod00000000',
target_snapshot: 'test00000000',
},
},
})
expect(html).toContain('3 条')
expect(html).toContain('新增的说明 · doc-new-')
expect(html).toContain('改过的说明 · doc-upd-')
expect(html).toContain('撤销的说明 · doc-del-')
expect(html).toContain('生产 prod00000000 → 测试 test00000000')
expect(html).not.toContain('变更清单来自生产与测试版本对比')
})
it('准备信息注明快照时间与范围,不声称实时测试库已就绪', () => {
const html = render()
expect(html).toContain('依据 10/28 11:34 封存的测试库全库快照,不代表实时测试库已就绪')
+20 -1
View File
@@ -248,6 +248,20 @@ function StageBar({ view }: { view: ScopeView }) {
)
}
// 差异行是 {id,title,digest} 对象;只展示人能核对的身份,不摊开内部摘要。
function diffLabel(item: unknown): string {
if (typeof item === 'string') return item
if (item && typeof item === 'object') {
const record = item as Record<string, unknown>
const title = typeof record.title === 'string' ? record.title : ''
const id = typeof record.id === 'string' ? record.id : ''
if (title && id) return `${title} · ${id.slice(0, 8)}`
if (title) return title
if (id) return id
}
return JSON.stringify(item)
}
function ChangeTable({ diff }: { diff: LibraryOverview['diff'] }) {
const computed = diff.state === 'computed'
const rows = computed
@@ -266,6 +280,11 @@ function ChangeTable({ diff }: { diff: LibraryOverview['diff'] }) {
</div>
<span className={`rel-pill ${computed ? 'green' : 'gray'}`}>{computed ? `${rows.length} 条` : '未接入'}</span>
</header>
{computed && diff.base_snapshot && diff.target_snapshot ? (
<p className="rel-scope-note">
生产 {diff.base_snapshot.slice(0, 12)} → 测试 {diff.target_snapshot.slice(0, 12)}
</p>
) : null}
<table>
<thead>
<tr>
@@ -286,7 +305,7 @@ function ChangeTable({ diff }: { diff: LibraryOverview['diff'] }) {
rows.map((row, index) => (
<tr key={`${row.action}-${index}`}>
<td>{row.action}</td>
<td>{typeof row.item === 'string' ? row.item : JSON.stringify(row.item)}</td>
<td>{diffLabel(row.item)}</td>
</tr>
))
)}
+3
View File
@@ -247,6 +247,9 @@ export interface LibraryDiff {
added: unknown[]
updated: unknown[]
removed: unknown[]
/** 这次比对用的两个整库版本(生产 → 测试),避免把历史差异当成当前。 */
base_snapshot?: string
target_snapshot?: string
}
export interface LibraryStageRow {
+15
View File
@@ -598,3 +598,18 @@
overflow-x: auto;
}
}
/* 准备信息 / 差异行的范围说明:让人一眼看出依据的是哪次封存,而不是"现在"。 */
.rel-scope,
.rel-scope-note {
display: block;
margin: 2px 0 0;
font-style: normal;
font-size: 11px;
color: var(--rel-muted, #7b8d9a);
}
.rel-scope-note {
padding: 6px 14px 0;
font-variant-numeric: tabular-nums;
}