diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b94860..e71245d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/cmd/worker/main.go b/cmd/worker/main.go index 4b7272e..958a0ca 100644 --- a/cmd/worker/main.go +++ b/cmd/worker/main.go @@ -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 diff --git a/docs/library-acceptance-matrix.md b/docs/library-acceptance-matrix.md new file mode 100644 index 0000000..6e4b9a0 --- /dev/null +++ b/docs/library-acceptance-matrix.md @@ -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 与卡片列出全部缺项;不存在"点了才失败"的假按钮。 +- 封存缺项(结清检查不通过、契约不符、导出校验失败)一律阻断封版,不改状态蒙混。 \ No newline at end of file diff --git a/docs/release-ledger.md b/docs/release-ledger.md new file mode 100644 index 0000000..57b914c --- /dev/null +++ b/docs/release-ledger.md @@ -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)镜像与数据始终为原样。 \ No newline at end of file diff --git a/internal/httpapi/library_flow.go b/internal/httpapi/library_flow.go index 07e1810..ebc2169 100644 --- a/internal/httpapi/library_flow.go +++ b/internal/httpapi/library_flow.go @@ -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) } diff --git a/internal/librarydiff/diff.go b/internal/librarydiff/diff.go new file mode 100644 index 0000000..a53051e --- /dev/null +++ b/internal/librarydiff/diff.go @@ -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 +} diff --git a/internal/librarydiff/diff_test.go b/internal/librarydiff/diff_test.go new file mode 100644 index 0000000..88c018d --- /dev/null +++ b/internal/librarydiff/diff_test.go @@ -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") + } +} diff --git a/internal/platform/postgres/library_jobs.go b/internal/platform/postgres/library_jobs.go index 957366d..4d60746 100644 --- a/internal/platform/postgres/library_jobs.go +++ b/internal/platform/postgres/library_jobs.go @@ -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") diff --git a/web/src/ReleaseTargets.test.tsx b/web/src/ReleaseTargets.test.tsx index 5aab8dd..51a357c 100644 --- a/web/src/ReleaseTargets.test.tsx +++ b/web/src/ReleaseTargets.test.tsx @@ -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 封存的测试库全库快照,不代表实时测试库已就绪') diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx index 080a626..d758599 100644 --- a/web/src/ReleaseTargets.tsx +++ b/web/src/ReleaseTargets.tsx @@ -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 + 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'] }) { {computed ? `${rows.length} 条` : '未接入'} + {computed && diff.base_snapshot && diff.target_snapshot ? ( +

+ 生产 {diff.base_snapshot.slice(0, 12)} → 测试 {diff.target_snapshot.slice(0, 12)} +

+ ) : null} @@ -286,7 +305,7 @@ function ChangeTable({ diff }: { diff: LibraryOverview['diff'] }) { rows.map((row, index) => ( - + )) )} diff --git a/web/src/librarySnapshots.ts b/web/src/librarySnapshots.ts index c02349d..e0b2396 100644 --- a/web/src/librarySnapshots.ts +++ b/web/src/librarySnapshots.ts @@ -247,6 +247,9 @@ export interface LibraryDiff { added: unknown[] updated: unknown[] removed: unknown[] + /** 这次比对用的两个整库版本(生产 → 测试),避免把历史差异当成当前。 */ + base_snapshot?: string + target_snapshot?: string } export interface LibraryStageRow { diff --git a/web/src/releaseTargets.css b/web/src/releaseTargets.css index c6c452a..f766f4c 100644 --- a/web/src/releaseTargets.css +++ b/web/src/releaseTargets.css @@ -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; +}
{row.action}{typeof row.item === 'string' ? row.item : JSON.stringify(row.item)}{diffLabel(row.item)}