为什么:发布管理的差异一直显示"未接入",业务作业也可能因队列丢作业而永久占锁; 本轮把这两件做成真实实现,并把 30 个验收项与 CI/版本身份落成可审计文档。 - internal/librarydiff:稳定文档 ID + 排除易变列的整行摘要做增改撤销;overview 在 生产权威版本与测试封存都在时给出 computed 差异并标注两侧快照,缺一侧仍是 unknown。 - 发布管理"本次变更"列文档身份与比对版本;无差异时明确写"没有文档差异"。 - ReconcileLibraryJobs:worker 启动清理队列已无对应作业的孤儿,避免永久互斥。 - docs/library-acceptance-matrix.md 与 docs/release-ledger.md 固定证据与版本事实。
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 与卡片列出全部缺项;不存在"点了才失败"的假按钮。
|
||||
- 封存缺项(结清检查不通过、契约不符、导出校验失败)一律阻断封版,不改状态蒙混。
|
||||
@@ -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)镜像与数据始终为原样。
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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")
|
||||
|
||||
@@ -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 封存的测试库全库快照,不代表实时测试库已就绪')
|
||||
|
||||
@@ -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>
|
||||
))
|
||||
)}
|
||||
|
||||
@@ -247,6 +247,9 @@ export interface LibraryDiff {
|
||||
added: unknown[]
|
||||
updated: unknown[]
|
||||
removed: unknown[]
|
||||
/** 这次比对用的两个整库版本(生产 → 测试),避免把历史差异当成当前。 */
|
||||
base_snapshot?: string
|
||||
target_snapshot?: string
|
||||
}
|
||||
|
||||
export interface LibraryStageRow {
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user