WiseGrade/docs/OPTIMIZATION_2026-10-13.md

2026-10-13 历史引用保护与索引失败恢复

后续记录：本日实际 PDF 入库与检索发现并修复无点线目录条目的权限问题。最新索引版本为 5，迁移为 0009；见 PDF 实流程说明。本文件保留第二轮的结果和验证范围。

同一文件重建索引时，原实现会删除旧片段并覆盖规范页面，历史会话中的片段 ID 可能失效；将文件恢复为过去的内容时还会复用并改写旧文档。第二轮将重建、材料类别变化和恢复旧内容都处理为新文档修订，历史来源仅标记为 superseded，保留原页、片段与成绩引用。无需重建的当前索引仍直接复用。

行为与性能变化

• 新迁移 0008 增加 knowledge_documents.revision，替换原有同源唯一约束，允许同一文件哈希保留多份历史修订。现有记录以修订 1 保留，页面与片段 ID 不变。重建结果包含原 document_id 与 replacement_document_id，便于审计。修订号用于区分同源索引，不替代源文件 SHA256 或索引算法版本。
• 公共资料重建与课程入库使用同一个课程文件锁，取得锁后重新读取文档状态。重叠任务不会再次重建已被替代的旧快照。本机双线程测试覆盖这一情形，不能代替跨主机或 PostgreSQL 任务并发验收。
• 索引任务在数据库写入失败后先回滚，再重新读取任务并保存失败状态及已得到的结果。课程资料逐份入库也在失败后回滚，后续资料与结构化课程资料仍能继续处理。
• 成绩结果和历史会话在读取时根据文档退休状态显示历史引用标记。保存的成绩引文、消息内容、引用 URL 和 JSON 不改写。会话按文档集合批量查询退休状态，成绩沿用已有批量预取。
• 知识库列表批量统计片段数；26 份文档的回归场景从 27 次查询降至 2 次。当前版本但状态失败的文档也明确需要重建；已退休文档不作为待重建项。

验证记录

本轮新增 9 项回归，优化回归累计 44 项；与上轮选择的 19 项本机可执行原有用例合计 62 passed, 1 skipped。LibreOffice 用例继续跳过，Windows 符号链接权限用例不纳入通过数量。完整 PostgreSQL 测试套件没有运行。

新增检查覆盖：原页面和片段保留、恢复旧哈希及材料类别变化、数据库事务失败的任务状态、课程部分写入失败、成绩和会话的历史标签、已有记录的迁移与有损降级拦截、失败重建后重试、双任务公共资料重建、知识库列表查询数量及失败索引提示。原有数据库套件的重建用例已调整为新语义，仍需在专用 PostgreSQL 环境执行。

用户提供的真实 17 页 PDF 重新解析后的 18 passed，原件 SHA256 与 17 张渲染页图保持一致。保留此前的 19 个异常字符告警与受损证据过滤，没有生成真实模型成绩。

迁移测试包含新库完整升级、无历史修订时降级及再升级，也包含手工构造的 0007 同源唯一约束和已有文档/页面，再升级至 0008。创建同源修订后尝试降级会在结构修改前停止，两份文档和原页面均保留。这些测试使用 SQLite，未执行生产 PostgreSQL 迁移。

升级与验证边界

当前索引算法版本仍为 4，证据政策仍为 2，Alembic 最新迁移为 0008。更新服务前，应备份数据库和处理资产、排空旧任务，并在独立 PostgreSQL/pgvector 数据库演练 alembic upgrade head。不要将未升级的数据库直接交给包含 revision 字段的新服务。

0008 降级在存在同源历史修订时主动拒绝，不能通过删除历史来源绕过；需要完整回退时恢复升级前数据库及相匹配的处理资产备份。仅修改索引默认值或降级算法版本不会恢复此前已被删除的历史片段；本轮只能保护仍然存在及以后生成的来源。

保留历史修订会增加存储量，本轮不自动清理。真实 PostgreSQL/pgvector、Redis/RQ 重试与跨主机锁、真实嵌入和评分模型、实际 PDF 导出仍待目标环境验收。源代码修改仍为本地未提交状态，没有正式迁移、部署或推送。个人 PDF 和详细日志位于仓库外 .wisegrade-testing/round2，不提交到 Git。