fix: improve import, evidence indexing and material-scoped grading

Preserve document revisions and evidence, harden indexing and export behavior, add explicit material selection and direct-folder import, validate model JSON schemas with safe error messages, and retain student selection while loading scoring data.

docs/OPTIMIZATION_2026-10-12.md

@@ -0,0 +1,46 @@
+# 2026-10-12 解析与评分可靠性优化
+
+后续记录：第二轮新增迁移 `0008`，同源重建改为创建独立文档修订，保留旧页面和片段；最新验证及升级说明见 [2026-10-13 优化说明](OPTIMIZATION_2026-10-13.md)。本文件保留第一轮的结果和验证范围。
+
+本轮基于 `29c95ce` 的失败用例修复源码。用户提供的 PDF、处理资产和详细日志保留在仓库外的隔离测试目录，不提交到 Git。未连接或修改正式业务环境。
+
+## 行为变化
+
+- 摘要标题可位于页首报告标题之后；摘要与目录不参与内容评分。
+- 切块按实际小节拆分并沿用跨页章节路径，避免同页所有内容被标为最后一个小节。混合页正文块具有独立来源类型，评分和引用不再用整页目录标签覆盖它。
+- PDF 解析补充限定区域的三线表识别，保留原页文字、图像、边框位置及推断告警。推断列边界仍可能切分表头或跨列文本，教师应核对原页，不能把检测到表格等同于全部单元格准确。
+- 封面标签支持中文字符之间的空白。无法识别材料类型时仍要求教师确认。
+- 原始未解析字符保持不变，页面记录质量告警，包含异常字符的正文片段被标为 `unknown` 并排除出自动内容检索；引文校验也拒绝未解析字符。项目材料详情显示文字和表格解析提醒。没有猜测符号或用低分替代质量问题。
+- 规则接口支持对象式证据目标，校验目标标识、用途和页面权限，目标标识随规则持久保存。旧字符串形式继续可读。
+- 内容正分必须有合法内容引文，未知目标被拒绝。同一片段可关联多个目标；选取候选时先保留目标覆盖，再填充剩余预算。
+- 文档范围、文档就绪状态、索引版本和旧片段过滤在候选上限之前执行；指定课程公共文档也使用正确范围。ASCII 关键词按完整词匹配，重复词不额外增加关键词分。
+- 评分项返回 `null` 时记录原始不足原因；最后一个评分项复核后重新计算批次状态。教师在模型请求期间完成的复核优先保留，PDF 和 Excel 保留合法 `0` 分。
+- 索引与评分共用 `submissions.py`，从评分模块移出解析与文件锁。索引重建修复错误导入，复用已保存解析结果并覆盖已保存的课程页面；还有待处理文档时不会标为完成。
+- 文件内容变化时旧文档被标为 `superseded`，保留历史页面和引用。新解析图像使用文件内容哈希目录，避免覆盖旧引用图像。已退休索引不参与检索和待重建统计。
+- 会话引用优先使用精确片段链接，普通页号不会关联另一份文档的同页。会话显示来源类型、结构用途及历史引用标签。
+- 结果查询合并逐评分项的证据查询并预取来源页面；会话界面按需加载。修复构建依赖 `source-map-js` 已知告警，依赖锁文件只更新该包至 1.2.2。
+
+## 索引与升级
+
+迁移 `0007` 仅对新文档的索引版本默认值设为 `4`；现有文档不会被自动宣称已重建。当前分类器版本为 `4`，证据政策版本为 `2`。
+
+升级前应备份数据库及处理资产，在专用 PostgreSQL/pgvector 环境演练迁移和重建，等待旧评分/索引任务排空后再更新服务。旧政策批次的结果和复核保持可读；带旧政策快照的批次不继续按新政策重试，应创建新批次。
+
+迁移后，通过 `/api/knowledge/stale/{course_version_id}` 查看待重建文档，再调用 `/api/knowledge/reindex/{course_version_id}` 并跟踪任务结果。源文件变化或缺少规范页面时会明确报告剩余项。重建优先复用缓存，旧缓存不会自动补出新的三线表结构；本轮三线表改进在新解析材料上验证。
+
+本轮没有执行正式迁移、重建或部署。SQLite 新库升级、默认值降级及再次升级的测试不等于 PostgreSQL 数据恢复演练；`0007` 降级也不会恢复旧切块内容。
+
+## 验证范围
+
+新增 `backend/tests/test_optimization.py` 覆盖解析政策、规则接口至批次快照、混合页检索至证据校验、文档范围/版本过滤、复核状态、零分导出、历史引用保留、缓存重建、迁移默认值及文件锁。数据库测试使用隔离 SQLite、确定性嵌入和模型替身，明确不代替 PostgreSQL/pgvector 或真实模型验证。
+
+另实际执行本机可运行的原有测试、前端 TypeScript/生产构建和 Chromium 浏览器测试。用户提供的 17 页 PDF 完整解析、渲染并核对：摘要分类、封面字段、小节标签、三张结果表及原页定位已复验；19 个原始异常字符仍保留并受到质量政策约束。没有生成真实模型成绩。
+
+详细命令、数量、构建大小、失败修复过程和 PDF 前后对比见本地隔离测试目录中的最新优化报告。真实 PostgreSQL、Redis/RQ 故障恢复、真实 BGE-M3/OCR/评分模型、LibreOffice 与实际 PDF 导出仍需在目标容器环境验证。前端仍有主包体积警告，按需加载改善入口拆分，不代表默认会话页总下载量或响应时间已经下降。
+
+## 本地验证记录（2026-10-13 核对）
+
+- 后端：35 项新增回归用例与 19 项可在本机执行的原有用例合计 `53 passed, 1 skipped`；跳过项需要 LibreOffice。原有完整数据库套件没有执行，Windows 符号链接权限相关用例未纳入本轮通过数量。
+- 真实 PDF：重新运行当前源码解析与检查，`18 passed`。相比基线，摘要从正文中分离，封面字段可提取，表格从 1 张增至 4 张（封面表加 3 张结果表），切块从 41 个变为 56 个。源文件 SHA256 与 17 张渲染页图保持一致。异常字符检查验收的是保留、告警和排除受损证据，不能解读为 19 个异常字符已修复。
+- 前端：TypeScript 和生产构建通过；使用模拟接口的 Chromium 测试 `3 passed`，手机截图在禁用动画后核对。依赖审计本轮记录为 0 项漏洞。
+- 两台已配置远端的 SSH 连接在建立阶段被关闭，没有新增远端数据库、模型或部署验证。源码修改仍为本地未提交状态；详细日志和含个人信息的测试材料在仓库外保存。