fix: harden knowledge lifecycle rollout

2026-08-03 16:00:45 +08:00
parent df77998e0c
commit 99e8c509d5
18 changed files with 709 additions and 156 deletions
@@ -330,11 +330,11 @@ POST /api/knowledge/quality/rollout/spaces/{knowledgeId}/generation-rollback

 审核包只提供风险、重复、冲突、质量问题和建议动作，不代替人工决定。低风险批量发布必须由人工显式发起、携带幂等 `batchKey`，逐项重新校验候选版本；`MEDIUM/HIGH/CRITICAL` 不进入批量发布。并发审核通过 `expectedVersionId` 拒绝已经换过候选版的陈旧操作。

-撤回是可恢复的在线下线：立即停用生产成员并排队删除当前 generation 的向量，但保留版本和片段供审计/回滚。物理清理只能针对已撤回资产，先生成影响快照，再进入 `PENDING -> APPROVED -> EXECUTING -> EXECUTED/FAILED`；申请人与批准/执行人必须不同，`legal_hold`、`PERMANENT` 或未到 `execute_after` 一律拒绝。保留期为 `TEMPORARY=7`、`STANDARD=90`、`REGULATED=365` 天。独占 OSS、MySQL 版本/片段/证据和对应向量按审计请求清理，`aihr_deletion_request` 永久保留为墓碑；`reconciliation-runs` 用于发现 MySQL、OSS 元数据、向量计数和 chunk 向量血缘漂移。
+撤回是可恢复的在线下线：立即停用生产成员并排队删除当前 generation 的向量，但保留版本和片段供审计/回滚。物理清理只能针对已撤回资产，先生成影响快照，再进入 `PENDING -> APPROVED -> EXECUTING -> EXECUTED/FAILED`；申请人与批准/执行人必须不同，`legal_hold`、`PERMANENT`、未到 `execute_after` 或活动 generation 仍包含该资产时一律拒绝。活动代次引用存在时，必须先构建并人工启用一个不含该资产的新代次。保留期为 `TEMPORARY=7`、`STANDARD=90`、`REGULATED=365` 天。执行过程先准备固定向量目标清单，再以可重试方式清理 legacy、全部治理代次和独占 OSS，最后在单个数据库事务内删除版本、片段和证据；任一外部或数据库步骤失败都记录为 `FAILED` 并允许重试。清理会重算受影响非活动代次的成员数和点数、清空旧 manifest、标记代次失效并解除失效候选指针，不能把已被清理破坏的旧代次用于回滚。`aihr_deletion_request` 永久保留为墓碑；`reconciliation-runs` 用于发现 MySQL、OSS 元数据、向量计数和 chunk 向量血缘漂移。

 历史补链使用迁移清单而不是无状态循环调用。每个 `migration-run` 冻结租户、可选知识空间、风险范围、dry-run、批大小和 manifest hash；`next` 只推进已持久化游标并记录批次证据。`LOW_RISK` 只扫描租户可验证 OSS 原件，`QUARANTINE_FIRST` 只扫描缺失原件且需要隔离的资料，`ALL` 扫描全部候选。失败附件进入显式 dead letter，最多按退避策略重试，不能因为单项失败回滚或隐藏仍由 LEGACY 服务的线上资料。正式任务必须提交 `verifiedDryRunId`，服务端只接受已完成且知识空间、风险范围、批大小完全一致的演练；管理端创建正式任务后仍需人工逐批推进，不会自动修改资料。

-空间发布固定为 `LEGACY -> SHADOW -> ENFORCED`。SHADOW 仍服务旧链路，候选 generation 在独立 collection/generation 中全量构建；管理端可记录真实问题的双链路对照。启用门禁要求候选 generation 为 `READY`、至少 20 个样本、Top1 一致率不低于 90%、Top5 平均重合率不低于 80%、治理结果空集率不高于 1%，且无覆盖缺口、开放关键问题或索引死信。旧 transition 接口不能直接进入 ENFORCED；只有人工使用最新 `PASSED` gate 调用 `activate` 才能切换。原 generation 保留 7 天回退窗口，回退后恢复 SHADOW。
+空间发布固定为 `LEGACY -> SHADOW -> ENFORCED`。SHADOW 仍服务旧链路，候选 generation 在独立 collection/generation 中全量构建；每个候选清单记录实际 embedding 模型、维度、成员数、点数和确定性 SHA-256，混用模型/维度或清单不完整会使 generation 失败，不能进入 `READY`。管理端可记录真实问题的双链路对照：旧链路结果来自当前线上召回，候选结果必须由 Qdrant 按租户、知识空间、生产数据集、已发布生命周期、人工可信级别和精确 generation 过滤；向量服务或模型失败时不写伪对照证据。启用门禁要求候选 generation 为 `READY`、至少 20 个样本、Top1 一致率不低于 90%、Top5 平均重合率不低于 80%、治理结果空集率不高于 1%，且无覆盖缺口、开放关键问题或索引死信。旧 transition 接口不能直接进入 ENFORCED；只有人工使用最新 `PASSED` gate 调用 `activate` 才能切换。原 generation 保留 7 天回退窗口；只有仍为 `RETIRED` 且未被物理清理失效的原代次可回退，回退后恢复 SHADOW。

 `publish` 必须带人工审核意见、用途、来源权威级别和来源版本。请求中的 `acceptedReasonCodes` 只能确认当前版本仍开放的软提示，服务端会再次统计开放问题，遗漏任何一项都拒绝发布；`HARD` 问题不能在发布动作中接受，必须修订原资料并生成新版本，或通过后续独立的显式纠错流程解决。规范性知识仅接受 `FORMAL_POLICY / COMPANY_POLICY / REGULATION / APPROVED_SOP` 且版本非空；同名已发布资料内容变化会产生 `VERSION_CONFLICT`，规范性知识必须再传 `supersedesAssetId`，服务端验证同租户、同来源名和旧资产仍已发布后，在同一事务内撤回旧版本并发布新版本。

@@ -29,8 +29,8 @@
 | 层级 | 当前状态 | 证据与边界 |
 |---|---|---|
 | 已实现 | 是 | 已有阶段一主功能；当前工作树另实现大喇叭投放控制、反馈转人工、正式学习任务/随机组卷、案例经验治理、原生异常恢复、上传容量门禁，以及数字资产兼容放量、版本、审核、向量代次、撤回/回滚、保留清理、历史迁移和影子启用全链路；接口事实见 [API_INTEGRATION.md](API_INTEGRATION.md) |
-| 本地自动化/API 验证 | 是 | 当前工作树管理端生产构建通过；后端完整测试 `851/851`，失败/错误/跳过均为 `0`；发布预检范围契约通过，生命周期迁移已在现有 MySQL 连续执行两次且资产数保持 `104`，未创建清理或迁移任务 |
-| 本地浏览器/视觉验证 | 部分 | `390×844` 已实际点击员工“今日/练/问”、大喇叭登录门禁和直通车登录门禁，无横向溢出或重叠；2026-08-03 已在当前工作树管理端登录并实际打开空间放量、迁移/清理、版本审核辅助和影子启用对话框，桌面布局无明显重叠或截断，未提交任何状态变更。窄屏管理端本轮未复核 |
+| 本地自动化/API 验证 | 是 | 当前工作树管理端定向 ESLint 与生产构建通过；后端完整测试 `855/855`，失败/错误/跳过均为 `0`；发布预检范围契约通过，生命周期迁移已在现有 MySQL 连续执行两次且资产数保持 `104`，未创建清理或迁移任务 |
+| 本地浏览器/视觉验证 | 部分 | `390×844` 已实际点击员工“今日/练/问”、大喇叭登录门禁和直通车登录门禁，无横向溢出或重叠；2026-08-03 已在当前工作树管理端登录并实际打开空间放量、迁移/清理、版本审核辅助和影子启用对话框，最新构建重启后再次复核桌面布局和对话框交互，无明显重叠或截断，未提交任何状态变更。窄屏管理端本轮未复核 |
 | 已部署 | 部分 | 2026-07-25 至 2026-07-31 的既有生产基线已部署；当前工作树的 `aihr_20260815_*` 至 `aihr_20260821_*` 生命周期迁移及对应后端、管理端均未部署，线上资料未发生本批变更 |
 | 生产基础验证 | 是 | 服务 `active`；根站、租户接口和移动首页 API 正常；媒体重试列/索引契约通过，4 个历史零片段任务均恢复为已完成且有片段/向量。当前未执行包含移动 H5 的完整包匹配 |
 | 生产完整业务验收 | 部分 | 公司消息已完成认证态全员文件消息和直通车闭环，单台 Android 标准基座已完成生产 ASR；训练写入、主管复盘、定向人群正反例、正式处理人绑定、其他真机媒体与严格试点窗口仍未完成 |
@@ -50,7 +50,8 @@
 - 执行顺序已经重新编排，不是把自动化辅助作为七阶段之外的平行项目：阶段 0 兼容层必须先落地，随后七阶段能力按依赖进入同一发布计划；系统先生成清单、风险、差异、影响和建议，人工只负责业务判断、异人批准和最终启用。
 - 既有资料默认继续由 `LEGACY` 服务。历史补链必须先创建固定范围的 dry-run，只有无失败完成且知识空间、风险范围、批大小完全匹配的演练，才能生成正式任务；正式任务仍需人工逐批推进，单项失败进入 dead letter，不中断旧读链路。
 - 新上传或修订只推进候选版本，生效版本继续提供检索；发布、撤回、回滚和 generation 切换均保留审计证据。日常删除语义为可恢复撤回，物理清理另受保留期、法务冻结、引用影响和异人控制约束。
- 生产启用固定为单空间 `LEGACY -> SHADOW -> ENFORCED`。SHADOW 期间构建隔离候选 generation 并记录真实问题对照；覆盖、索引、质量和样本门禁通过后，才允许人工确认启用，并保留七天 generation 回退窗口。
+- 生产启用固定为单空间 `LEGACY -> SHADOW -> ENFORCED`。SHADOW 期间构建隔离候选 generation，记录实际 embedding 模型、维度和确定性 manifest，并以当前线上召回和严格过滤候选 Qdrant 记录真实问题对照；检索失败不生成伪证据。覆盖、索引、质量和样本门禁通过后，才允许人工确认启用，并保留七天 generation 回退窗口。
+- 物理清理新增活动 generation 硬门禁：仍被当前代次包含的撤回资料必须先构建并启用排除该资料的新代次。清理按固定目标重试外部删除，再以单事务删除数据库链路；受影响非活动代次自动重算成员/点数、清空 manifest 并标记失效，已失效代次不能恢复为活动代次。
 - 本地浏览器仅执行只读查看和打开对话框。验收前后数据库均为资产 `104`、非活动删除状态 `0`、清理申请 `0`、迁移任务 `0`、影子样本 `0`、generation 启用 `0`；已有一个本地 SHADOW 空间保持不变。以上不能外推为生产部署或线上迁移完成。

 ### 2026-07-29 资料处理媒体恢复发布边界
@@ -180,9 +180,9 @@ mysql --default-character-set=utf8mb4 "$DB_NAME" < backend/script/sql/aihr_perso

 随后按 `20260808 -> 20260809 -> 20260810 -> 20260811 -> 20260812 -> 20260813 -> 20260814` 执行质量监控、人工术语修订、AI 案例来源、规则演进、处理批次、黄金集校准和隐私派生迁移。`20260811` 只增加规则草稿、状态审计、影子对照和抽样复核；`20260812` 只增加 `pipeline_run` 与自动生成待人工复核样本的调度，不启用规则执法，不改变任何资产生命周期。`20260814` 只增加独立脱敏正文、脱敏文件名、派生 hash、隐私状态、规则版本和复扫摘要字段，历史版本默认保持 `NOT_PROCESSED`，不得通过 SQL 伪造脱敏完成或自动获批。完整迁移后仍须最后执行排序规则兼容迁移。

-生命周期兼容发布继续按 `20260815 -> 20260816 -> 20260817 -> 20260818 -> 20260819 -> 20260820 -> 20260821` 执行：先建立按空间的 `LEGACY/SHADOW/ENFORCED` 兼容范围，再增加候选/生效双指针、审核辅助、不可变 generation 与回滚证据、保留和异人删除、历史迁移清单、影子指标与启用门禁。七个脚本均为增量结构迁移；不得在 SQL 阶段自动发布、撤回、删除或切换现有空间。迁移完成后所有空间仍应为 LEGACY 或保持迁移前显式模式，历史资料继续可见。生产发布必须先只读统计资产、版本、生产成员、fragment、OSS 和 Qdrant 数量并备份；先以单空间 dry-run 和 SHADOW 验证，达到门禁后由人工启用。正式迁移任务必须通过 `verified_dry_run_id` 绑定同知识空间、同风险范围、同批大小且无失败的已完成演练；创建正式任务不自动推进批次。任何补链失败都停留在迁移 dead letter，不得切断旧读路径。
+生命周期兼容发布继续按 `20260815 -> 20260816 -> 20260817 -> 20260818 -> 20260819 -> 20260820 -> 20260821` 执行。`20260815` 是七阶段共同依赖的阶段 0，不是平行的第八项：先建立按空间的 `LEGACY/SHADOW/ENFORCED` 兼容范围和只读基线，再增加候选/生效双指针、审核辅助、不可变 generation 与回滚证据、保留和异人删除、历史迁移清单、影子指标与启用门禁。七个脚本均为增量结构迁移；不得在 SQL 阶段自动发布、撤回、删除或切换现有空间。迁移完成后所有空间仍应为 LEGACY 或保持迁移前显式模式，历史资料继续可见。生产发布必须先只读统计资产、版本、生产成员、fragment、OSS 和 Qdrant 数量并备份；先以单空间 dry-run 和 SHADOW 验证，达到门禁后由人工启用。正式迁移任务必须通过 `verified_dry_run_id` 绑定同知识空间、同风险范围、同批大小且无失败的已完成演练；创建正式任务不自动推进批次。任何补链失败都停留在迁移 dead letter，不得切断旧读路径。系统负责生成范围清单、差异、风险、影响、候选 generation 和门禁证据，人工只保留业务事实裁决、异人审批、抽样复核和最终切换。

-生产物理删除不是部署步骤，也不得与 schema/JAR 发布同窗口批量执行。日常纠错只做 `withdraw`；`purge` 必须有业务/法务确认的保留分类、影响快照、异人批准和已到期 `execute_after`。发布后先运行 reconciliation 并处理不一致，再考虑清理。ENFORCED 启用后旧 generation 保留七天；窗口内指标恶化可从管理端回退上一代，超过窗口必须重新构建候选 generation 和重新通过门禁。
+生产物理删除不是部署步骤，也不得与 schema/JAR 发布同窗口批量执行。日常纠错只做 `withdraw`；`purge` 必须有业务/法务确认的保留分类、影响快照、异人批准和已到期 `execute_after`。活动 generation 仍包含该资产时，先构建并启用排除该资产的新 generation，系统不会允许直接清理；清理成功后，受影响的非活动代次会被自动重算并标记失效，不能再作为回滚目标。发布后先运行 reconciliation 并处理不一致，再考虑清理。ENFORCED 启用后旧 generation 保留七天；窗口内指标恶化且旧代次未失效时可从管理端回退，超过窗口或旧代次已失效时必须重新构建候选 generation 和重新通过门禁。

 8 月 1 日受控内部试点的正式来源注册是独立的业务数据变更，不随通用 schema 自动执行。先逐一核对附件 `id + doc_id`、原文件 SHA-256、发文号/版本、生效日期和适用范围，再由已授权负责人执行 `backend/script/sql/ops/aihr_20260730_aug1_formal_source_registry_mysql8.sql`。执行后必须只读确认恰好 10 条 `FORMAL_POLICY + APPROVED` 记录；任何缺失都保持无正式依据，不得把访谈、经验萃取、AI 生成内容或草稿补进白名单。

@@ -599,6 +599,8 @@ legacy preview（只读盘点）
 - 撤回后 MySQL 立即不可见，Qdrant 删除最终一致率 100%。
 - 黄金问题达到该批预设 Recall/MRR/nDCG 和无答案阈值。
 - 回滚只切换生产可见性/索引 generation，不删除原件、版本和审核证据。
+- 候选 generation 的 embedding 模型、维度、成员数、点数和 manifest hash 完整且一致；影子样本来自旧链路与严格过滤候选 Qdrant 的真实召回，检索失败不得生成比较证据。
+- 物理清理前活动 generation 不得仍含目标资产；清理后受影响非活动代次必须重算计数、清空 manifest 并失效，失效代次不得回滚。

 ## 16. 黄金集、测试与标定