Files
knowledge-governance/docs/library-acceptance-matrix.md
T
姚章浩 7b8cc0384b
build / build (push) Successful in 1m19s
feat(library): 生产发布授权与同步/恢复编排,worker 接线
为什么:同步入口此前只会拒绝;授权、预备份、四类写入、验证与失败恢复都没有代码。
本轮把编排与授权实现出来,真实生产执行仍按授权闸口关闭。

- internal/libraryrelease:预备份 → 数据库/资源/索引/Wiki → 验证 → 失败恢复;
  授权过期/目标不符/快照不符/参数变化在动生产前拒绝;恢复失败单独上报。
- 迁移 000067 library_release_authorizations(目标+快照+参数摘要+有效期,可撤销)。
- POST/GET /api/v1/library/authorizations 与 /{id}/revoke,仅管理员签发,5–1440 分钟。
- worker library.sync 接编排:先闸口再授权,阶段落库,只有编排成功才标成功。
- 生产目标适配器未配置时显式失败(不返回零值状态),预备份存储同。
- overview 返回授权状态,页面"生产保护与恢复"显示签发人与有效期。
- 验收矩阵区分"已实现·隔离测试通过"与"真实执行未授权"。
2026-10-28 15:11:27 +08:00

9.0 KiB
Raw Blame History

整库同步验收矩阵(真实证据对照)

对应 docs/library-sync-acceptance.md 的 30 个验收项。状态只写实际发生的事:

  • 已实现·已验证:有代码 + 本机真实数据或真实归档/真实 PostgreSQL 跑过的证据,或既有 CI 检查覆盖。
  • 已实现·未验证:代码与测试在位,但还缺真实业务环境的执行证据(例如需要隔离生产栈)。
  • 阻塞(需授权/环境):实现所需的动作属于生产写入、生产读取或生产恢复,当前授权明确禁止。
  • 未实现:还没有代码,界面按"未接入/未知"显示,不冒充完成。

A06(内容、问答、引用图片效果、性能报告)已被用户取消,本矩阵不含该项,也不再作为封版门槛。

状态口径(严格区分四件事):

  • 已实现·已验证:代码 + 本机真实归档/真实 PostgreSQL 或既有 CI 的实跑证据。
  • 已实现·隔离测试通过:代码 + 单元/集成测试(注入假生产目标),没有真实生产执行。
  • 已实现·未验证:代码在位但缺真实环境证据。
  • 未实现 / 真实执行未授权:前者是代码缺口,后者是权限缺口,两者不混用。
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 每次生产写入前完整预备份,失败零写入 internal/libraryrelease(prebackup 阶段)+ library_versions.production_prebackup + gate 已实现·隔离测试通过·真实执行未授权 编排测试:预备份失败→零写入;读不到生产当前状态→零写入。真实预备份需生产读取凭据(未授权)
B02 资源在测试侧删除后仍可恢复 归档内容寻址 blob(library_versions + librarysnapshot 内容去重) 已实现·未验证 归档不依赖测试临时对象;跨版本去重 55,309,693 字节;尚未做"测试侧删除后从归档恢复"的实测
B03 每版保存完整 Wiki 与引用关联并校验 library_snapshot 的 wiki 部件 + 摘要 已实现·已验证 真实快照含 31 页 Wiki 与逐页摘要,manifest 记录数量/字节
S01 数据库/资源/索引/Wiki 真实落地并校验 internal/libraryrelease.Run(四类阶段 + verify)+ worker library.sync 已实现·隔离测试通过·真实执行未授权 测试覆盖:四类按序写入、阶段失败→恢复、验证失败→恢复;生产目标适配器未配置时显式失败
S02 生产不再解析/Embedding/生成 Wiki 编排只对 Stage 提交归档快照 id,不做解析/嵌入/生成 已实现·未验证 代码层面没有解析/嵌入调用;真实生产写入未执行,不能声称已验证
S03 一致生效与失败补偿边界 — 未实现 跨 PG/ES/资源的一致切点与可见性保护未实现
S04 各阶段失败/超时/重启可追溯可恢复 library_jobs/library_job_stages + ReconcileLibraryJobs 已实现·已验证 阶段与错误持久化;worker 启动清理"队列已无对应作业"的孤儿并写明恢复责任,避免永久占锁
S05 幂等与互斥(多 worker 安全) library_jobs_idempotency、library_jobs_active 唯一索引 已实现·已验证 真实 PostgreSQL 上验证:同目标第二个在飞作业被拒;同键同 digest 重放复用;同键换 digest 冲突
R01 版本恢复整套生产知识状态 libraryrelease 失败路径调用 Target.Restore(backup);抽屉恢复入口仍禁用 已实现(失败自动恢复)·独立恢复未实现 恢复编排与幂等由测试覆盖;"按版本手动恢复"入口仍未接线,不能声称可用
R02 恢复失败显式异常、不回退测试库 Outcome.State=rollback_failed + 独立阶段记录 已实现·隔离测试通过 测试断言恢复失败与同步失败可区分,且不触碰测试库
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 保留策略(数量/天数) internal/libraryretention;LIBRARY_RETENTION_VERSIONS/DAYS 已实现·已验证(单测+真实归档) 未设置=0 时按"全部保留",不编默认值;设置了才生成候选
D02 占用测量 internal/librarysnapshot/usage.go;系统设置→存储管理 已实现·已验证 版本数/跨版本去重内容/blob 表观与分配/未引用/清单;真实两份清单 55,309,693 字节
D03 依赖保护 libraryretention.Build 的 Protected/ProtectedBy 已实现·已验证 真实归档上 2 个版本都因"最近测试封存"受保护;受保护版本永不进入候选
D04 清理预览 libraryretention.Build 的 Candidates/ReclaimPreviewBytes;GET /library/storage 已实现·已验证 真实归档:策略 keep=1 时仍 0 候选(两版均受保护);回收预览只计独占字节
D05 容量门禁 libraryretention.CheckCapacity + sync gate 已实现·已验证(单测+真实数据) 预算未设置→阻断并说明;超预算→阻断并给出预计字节
D06 测试残留 归档未引用 blob 统计(UnreferencedBlobs/Bytes) 已实现·已验证 真实归档未引用 blob 为 0;这只是口径,不等于扫描过所有测试残留
D07 实际回收 — 阻塞(需清理授权) 自动清理默认关闭,不提供删除动作

差异比对(本轮新增)

internal/librarydiff 以稳定文档 ID 为身份、以排除 updated_at/updated_by 后的整行摘要为内容, 比较两份归档快照的 knowledges 行数组,输出新增/更新/撤销。真实归档上验证: 对内快照 4 篇对空集为"新增 4",反向为"撤销 4",缺失快照返回原因而不是空差异。 生产权威版本建立后即可直接给出生产→测试差异;在生产版本未知时页面保持"未接入"。

未通过项如何阻断

  • POST /api/v1/library/syncs:闸口关闭、缺恢复演练证据、生产端点未配置、生产权威版本未知、 目标快照无预备份——任一成立即 503 并逐条列原因,不创建作业。
  • 页面"启动同步"按同一 gate 禁用,title 与卡片列出全部缺项;不存在"点了才失败"的假按钮。
  • 封存缺项(结清检查不通过、契约不符、导出校验失败)一律阻断封版,不改状态蒙混。