# 工作总控（唯一真源 · 新会话第一必读）

> **这是唯一要读的 md。** 新会话进来先读本文件，不要再翻别的。
> 以下文件已降级为历史档案（只读、不再维护，移至 docs/_archive/）：
> `启动摘要.md`、`全面融合方案.md`、`真实功能缺口清单.md`、`调试经验库.md`、`docs/知识库/*`。
> 与本文件冲突时，**以本文件为准**。
> `架构总控文件.md`(35000行) = 宪法档案，只在查老细节时翻，不当工作入口。

---

## 📌 新会话启动必读索引

新会话开始，按顺序读（运行维护线 + 交付提升线，两条线已挂接）：

1. **本文件**（工作总控.md）——硬规则+历史变更
2. **新会话SOP.md**——启动清单+10条硬规则+必跑脚本
3. **专家系统现状.md**——101专家、11warning
4. **标准基线清单.md**——布局/颜色/业务规则标准值核对（与实际运行代码冲突时以代码为准）
5. **系统交付级诊断报告.md**——144专家交付级全系统诊断（10章+12周路线图），了解"离可交付还差什么"；约149KB，不用全读，知道在那、查差距时翻
6. **AI_WORK_PLAN.md**——6周推进计划（当前阶段/本周任务/验收标准）
7. **功能落地统计_最新.md**——跑`python tools/feature_audit.py`自动生成，看gap数和死按钮现状（不要手改，每次跑完刷新）
8. **docs/待办清单.md**——手动维护的待办checkbox，已完成打[x]、未完成留[ ]
9. 跑 `backend/core/experts/latest_report.py`——专家最新报告
10. 跑 `get_pending_requirements()`——78条待办改到哪

> 体系A（运行维护：1-4、9-10）保证不跑偏；体系B（交付提升：5-6）保证知道往哪走；销项载体（7-8）保证完成项可追踪。架构总控文件.md（35000行）只在查老细节时翻，不当入口。
> ⚠️ 以上所有文档的结论都只是"一方陈述"，必须按「〇·六、对比与销项机制」实测验证后才采信——文档分析的不一定是对的。

---

## 〇、铁律（死规则）

1. **修改必记录**：改代码 → 本文件末尾"变更记录"追加一条 → 验证。三步缺一不可。
2. **布局锁死**：顶导航56px、左侧栏135px、底栏28px；一页显示无横滚。**布局参数唯一权威源=`backend/core/locked_layout.py`，改前先问用户。**
3. **旧代码是答案**：bug 先看 `frontend/js/app_v3_897262.js`（34848行）对应 render 函数，缺什么搬什么，不重写。
4. **刷题逻辑**：单选选了即出解析；多选提交才出解析；4选项=单选，5选项=多选。
5. **科目简称不改全称**：一造管理、一造水利案例、一造计价、一建管理/法规/经济/水利、二建水利。
6. **考试日期**：2026年一造=10月17-18日（中国人事考试网）。倒计时基准日=2026-10-17，不再改。
7. **改完校验**：`node verify.cjs <文件>` → `node sync.cjs <模块>` → 浏览器实测。
7. **改前必备份**：动文件前先 `backups/` 留底；坏了从 GOLDEN 回滚。
8. **"锁死"指令 = 冻结，除非新指令。**

---

## 〇·五、专家系统现状（2026-09-15）

- **77名专家**已注册并真跑，不是空壳prompt
- **标准分块**：`backend/core/layout/`（尺寸/颜色/间距3块）+ `backend/core/standards/`（业务/代码/数据/安全/运行时/工作流/功能状态/探针深度8块）
- **报告入库**：每次启动自动存 `common_expert_history` 表，自动清30天前旧记录
- **API**：`/api/common/experts/` 7个端点（列表/汇总/报告/历史/豁免/手动跑单个/手动跑时机）
- **当前状态**：启动PASS，71个info + 6个warning（全是过渡期待治理：巨型文件/大JS/硬编码色值/探针深度浅）
- **探针深度**：deep级4个(5%)，shallow级73个，待加深10个（清单在 `standards/probe_depth.py`）

---

## 〇·六、对比与销项机制（2026-09-20 新增）

> 核心信条：**文档分析的不一定是对的。** 所有md里的"已完成/未落地/XX问题/XX数字"都只是一方陈述，必须实测验证后才采信。

### 信源优先级（从高到低，冲突时高优先级覆盖低优先级）

1. **实际运行**：浏览器真点、API真请求、SQL真查、脚本真跑
2. **自动扫描输出**：`tools/feature_audit.py`、`latest_report.py`、`system_health.py` 的实时输出
3. **代码现状**：Read当前文件看到的内容
4. **文档描述**：本文件、诊断报告、工作计划、待办清单（可能过时）
5. **我的印象**：最不可靠，禁止作为依据

### 对比矩阵（文档说什么 → 用什么验证 → 通过标准）

| 文档里的说法 | 验证手段 | 通过标准 |
|---|---|---|
| "某功能未落地/死按钮" | 跑`python tools/feature_audit.py` + 浏览器真点该按钮 | 脚本gap数下降 + 浏览器点了有真实反应 |
| "某布局值是X" | Read `index.html`/layout模块JS实际style | 实际值=文档值；不符则改文档不改代码 |
| "某API返回XX" | curl/浏览器F12真请求 | 状态200且字段对得上 |
| "某数据量XX题/XX条" | SQL实查 `shuili_exam.db` | count(*)对得上 |
| "专家warning XX条" | 跑`latest_report.py` | 输出条数对得上 |
| "某需求改完了" | `get_pending_requirements()` + 浏览器走一遍 | 状态已闭环 + 真实路径无阻断 |
| "某模块已接线" | 看是否还有Math.random假数据 + F12看Network是否真调API | 无随机数 + 有真实请求 |

### 销项规则（完成一项 = 五步，缺一不可）

1. **改代码**（可逆操作直接做，不可逆先问用户）
2. **实测验证**：浏览器真走一遍用户路径，不是"语法通过"就算完
3. **打钩销项**：
   - 功能gap → 跑`python tools/feature_audit.py`自动刷新`功能落地统计_*.md`（不要手改自动生成的md）
   - 手动待办 → 在`docs/待办清单.md`把`[ ]`改`[x]`，注明验证方式和日期
4. **总控记录**：本文件末尾"变更记录"追加一条（改了什么/验证了什么/备份在哪）
5. **重跑专家**：`latest_report.py`对比warning变多变少

### 反向纠错（文档说"未落地"但实际已落地）

- 如O03考点图谱：文档列在gap里，实际四个tab都已接线。**先核实再动手**，不要按文档"补做"已经做好的东西。
- 核实方法：Read前端模块JS看是否真调了API → F12看Network → 浏览器点一遍。
- 确认已落地后：更正文档（划掉gap行/改待办状态），不要重复建设。

### 三个诊断报告的关系（避免重复读）

| 文件 | 版本 | 定位 | 什么时候读 |
|---|---|---|---|
| `系统交付级诊断报告.md` | v3.0（149KB） | 主诊断：144专家/10章/12周路线图 | 启动必读，查交付差距 |
| `系统深度诊断报告_完整版.md` | v2.0（24KB） | 历史版：12章/三个月路线图 | 按需，被v3.0取代 |
| `系统深度诊断报告_20260920.md` | 聚焦版（24KB） | 47项问题清单 | 按需查具体问题 |

> 以v3.0交付级报告为准；另两个是过程稿，发现冲突以实测为准。

### 已代码化（2026-09-20）

以上对比矩阵和销项标准已落成可执行脚本，不再只靠md文字：

- **`tools/startup_verify.py`**——启动标准验证，一键跑全量对比：
  - A.本地运行标准（Python版本/后端端口/Ollama/数据库文件）
  - B.布局锁死标准（读index.html/topbar.js实际值 vs 标准135/56/#1a73e8）
  - C.数据标准（SQLite实查题库/错题/知识点/RAG向量库）
  - D.假数据/死按钮（扫Math.random，洗牌/随机选/ID生成已白名单）
  - E.文档挂接（7个必读文件存在性 + 6组互引检查）
  - 用法：`D:\Python311\python.exe tools\startup_verify.py`（--env/--layout/--data/--closure/--doc 可分项跑）
  - 退出码：0=全绿 2=有WARN 1=有FAIL
  - 已挂进 start.bat（后端启动后自动跑一遍）
- **`tools/feature_audit.py`**——功能gap自动扫描，跑完刷新`功能落地统计_*.md`（销项用，不要手改）
- **`docs/待办清单.md`**——手动待办checkbox，完成打[x]并注明验证方式

> 豆包新会话第一件事：先跑`tools/startup_verify.py`看基线，再读必读文件，再干活。

### 统一落地对账机制（2026-09-30 升级，解决"状态散、重复写、不回填"）
- 条目级落地状态**唯一真源**：`docs/落地对账总表.md`（机读 `docs/landing_registry.json`）；本文件及各 md 不再各自维护最新落地状态，只留历史与方法论。
- 一键核验/刷新：`D:\Python311\python.exe tools\doc_landing_audit.py`（探针 gate/file/sql/src ＋ 防散检查）；门禁 `reg_doc_landing` 已纳入 run_all，startup_verify 校验三件套，`--landing` 可全量对账。
- 新增/发现问题先登记台账再动手；完成自测后跑审计刷新状态。

---
## 一、系统定位

水利智学系统 V4.5.15，目标43天考过一造；平板横屏；FastAPI+SQLite+PWA+本地Ollama(qwen2.5:7b/qwen3-vl:4b/bge-m3)；双击 start.bat，admin/admin123。
**用户策略：纸质+金考典管刷题量，本系统留给 AI 冲刺（薄弱点/学习计划/口诀）。**

---

## 二、当前状态（数字来自 tools/feature_audit.py 自动扫描）

- 业务模块 19 个；**未落地功能点 119**；完全没建的辅助 render 组件 49；死按钮 4 处
- 整体真实融合度约 35-40%
- 跑 `python tools\feature_audit.py` 自动生成 `功能落地统计_20260915.md`

---

## 三、下一步队列（快速完善系统功能）

**取消复习期冻结。快速而深思熟虑地完善系统功能：**
- [ ] 薄弱点分析 `/analytics/weak_points`（后端已有，前端接线）
- [ ] AI学习计划 `/assistant/study_plan`（后端已有，前端空壳）
- [ ] AI口诀 `/ai_brain/*`（后端已有）
- [ ] 高频考点/掌握度 `/exam_analysis/*`（后端已有）
- [ ] 题图片展示（后端接口+前端渲染）
- [ ] 思维导图按kp生成（后端接口+前端按钮）
- [ ] 闪卡关联到题
- [ ] 一造考点提取

**原则：** 快速而深思熟虑，不建新接口，功能加到现有接口里。

---

## 四、路由表（改模块 → 旧代码答案在哪，行号来自前后端分析合并报告）

| 新模块文件 | 旧 render（app_v3_897262.js 行号） | 后端 API |
|---|---|---|
| question/question-practice.js | renderQuestion@5014 / renderSingleQuestion@7026 | /question/filters, /question/wrong/list, /question/chapter_tree |
| exam/mock-exam.js | renderExam@7509 / renderExamOngoing@7814 / renderExamResult@7987 | /exam/history, /exam/submit, /exam/detail/{id} |
| wrong/wrong-book.js | renderWrong@8243 | /question/knowledge_points, /question/wrong/list |
| flashcard/flashcard.js | renderFlashcard@8710 / renderLibraryCard@9153 / renderFcPagination@9916 | /flashcard/list, /flashcard/stats |
| mindmap/mindmap.js | renderMindmap@18402 / renderMindmapSummary@20183 / renderMarkmapToContainer@18982 | /mindmap/upload_pdf, /mindmap/* |
| video/video.js | renderVideo@12500 + renderPlaylistItems@12878 / renderLocalVideoTable@13857 | /video/list, /lecture/list |
| note/note.js | renderNote@12207 | /note/list, /material/tree |
| analytics/analytics.js | renderAnalytics@15228 / renderLearningAnalytics@3809 / renderWeakPointsList@15630 | /analytics/overview, /analytics/weak_points |
| material/material.js | renderMaterial@16150 / renderChapter@16619 / renderReaderTree@17700 | /material/chapters/{id}, /material/split_pdf |
| dashboard/dashboard.js | renderDashboard@3976 | 统计聚合 |
| sprint/sprint.js | renderSprint@20384 | /sprint/* |
| memory/memory.js | renderMemoryTrain@20610 / renderTrainingQuestion@20996 | /assistant/ask |
| photo/photo-solve.js | renderAiScan@14912 | /ai_scan/* |
| settings/settings.js | renderSettings@21934 / renderSettingsSubjectList@22864 | /system/*, /lan_info, /sync/conflicts |
| collect/collect.js | renderCollect@8621 | 收藏列表 |
| manager/question-manager.js | renderQuestionManager@4478 | /question/filters, /question/list |
| library/file-library.js | renderLibraryCard@9153 | /api/v1/fl/* |

> 缺失组件（知识图谱 renderKnowledgeGraph@25578 / 公式训练器@25275 / 备份管理@25826 / 服务监控@25990 / 去重UI@26633 等）需要时回总控第二十一章。

---

## 五、踩坑速查（犯过的错不再犯）

1. **HTML改坏导致后面页面全不显示**：div/textarea 没闭合。用 `re.compile(r'<div[\s>]')` 或 html.parser 校验，别用字符串切片。
2. **3px间距改4次不生效**：状态栏是 `position:absolute`，margin 不影响；要改内容容器 `mock-kanban` 的 padding-bottom + 末行 margin-top:auto。
3. **乱码/结构错误**：改HTML标签先完整读出原标签再精确替换，别手拼；改完浏览器看。
4. **全局替换把JS改坏**：替换限定在CSS/HTML内联，避开 `<script>`。
5. **404找不到数据**：检查 data/offline/questions.json 是否存在；改data前先备份。
6. **改坏无法恢复**：改前必须备份（GOLDEN 已建 backups/GOLDEN_20260915_治理前）。
7. **白屏**：F12看控制台 → 查JS语法 → `python tools/system_center.py diagnose`。
8. **检测div别用带空格匹配** `<div `，会漏 `<div>`。

---

## 六、自治分级（复习期系统自己转，不烧豆包）

| 级 | 故障 | 怎么修 | 谁干 |
|---|---|---|---|
| L0 | 进程崩/内存爆 | watchdog 自动重启（已在跑） | 自动 |
| L1 | 代码改坏/白屏 | auto_backup 每小时备，坏了回滚 | 自动（补 auto_backup.py） |
| L2 | 报错/功能不通 | 本地AI(qwen2.5)读日志→定位→贴建议 | 本地AI，不叫豆包 |
| L3 | 动架构/布局/业务 | 本地AI写草稿，攒着 | 才升级豆包/用户 |

**本地Ollama干**：口诀、错题分析、薄弱点、读日志定位bug、写补丁草稿。
**豆包干**：跨模块大改、验收、拍板。**布局/科目名/答题规则谁都不许动。**

---

## 七、专家闸门（70专家 = 验收清单，不是头衔）

| 专家 | 一票否决 |
|---|---|
| 系统架构师 | 跨域import、函数>50行 |
| 网页设计师 | 任何布局改动 |
| 造价培训 | 改科目简称、改答题规则 |
| AI专家 | 绕过人工确认直接入库 |
| 质量组 | 不通过打回重做 |

日常改动 = 常委会4人一致；动架构/数据库/>200行 = 全体2/3同意。

---

## 八、变更记录（只记这里）

### 2026-09-15 16:00 收口：建立本文件
- 模块：docs
- 需求：文件散、总文件读不全、见子打子；用一个md收口
- 实现：本文件为唯一真源，旧散落md降级归档
- 状态：✅

### 2026-09-15 16:30 黄金备份
- 模块：backups
- 需求：输不起，先钉一个能跑的点
- 实现：GOLDEN_20260915_治理前/（frontend全量+backend代码+shuili_exam.db+关键md，2.4GB）
- 状态：✅

### 2026-09-15 16:40 三把刀落地
- 模块：治理工具
- 需求：文件散、重复、见子打子；布局锁死只做功能，用代码整治
- 实现：
  1. 工作总控.md 填实：真实路由表(render行号+API)+踩坑8条+自治分级L0-L3+专家闸门
  2. feature_audit.py 加回归快照：改完对比上次，行数掉30%报警
  3. 新增 tools/system_health.py：一键查 后端/Ollama/数据库/最近备份/死按钮
  4. 物理归档 docs/_archive/：启动摘要/融合方案/缺口清单/调试经验库/知识库 共9文件移入
  5. 补 auto_backup.py（start.bat引用但原文件缺失）：每小时在线备份db+前端，留10份
- 状态：✅（健康检查全绿，自动备份已验证）

### 2026-09-15 17:00 核心五模块跑通
- 模块：flashcard/resource/experts
- 需求：把文件资料库/刷题/闪卡/模拟题/视频跑通
- 实现：
  1. 闪卡：deprecated_flash_cards 483条迁到 flash_cards；补6字段(knowledge_point/mastery/ease_factor/interval_days/last_review_date/card_type)到表+模型
  2. 视频：定位到 /api/resource/videos/list 是写死空返回的假接口，改成真查 embedded_videos 64条；user_id 0→1对齐admin
  3. 专家系统：/api/common/experts 70专家在线（用户自建catalog+experts_routes，已挂载）
  4. start.bat：改成双击先杀旧后端再启动
- 状态：⏳ 视频修复待重启电脑后验证（WMI高权限进程需重启才加载新代码）

---

**版本**：V2.0 · 2026-09-15

- 2026-09-15：专家系统底座建成——77名专家真跑、标准分块11块、报告入库+自动清理、历史趋势API、豁免清单、探针深度追踪。

### 2026-09-15 18:37 需求：薄弱点分析加个图表
- 归到：智能分析
- 前端：frontend/modules/analytics/analytics.js
- 接口：/api/v1/analytics/*
- 状态：待实现

---

## 九、专家系统现状（2026-09-15 22:00）

**100个专家全跑通，PASS:True，11个warning**

| 项 | 值 |
|---|---|
| 专家总数 | 100个 |
| 注册文件 | backend/core/experts/catalog.py（1777行） |
| 底座 | backend/core/experts/__init__.py（182行） |
| 报告DB | common_expert_history表 |
| API | /api/common/experts/（7端点） |
| 读摘要脚本 | backend/core/experts/latest_report.py |
| 布局标准 | backend/core/layout/{dimensions,colors,spacing}.py |
| 系统标准 | backend/core/standards/9块 |

**专家能力链路**：发现→定位→聚类→排序→处方→趋势对比→闭环复验→自检→分级执行

**11个warning**：
1. 新旧API并存35+37个（过渡态）
2. 4个巨型文件（过渡态）
3. 5个JS超500KB（过渡态）
4. 425处硬编码#1a73e8（过渡态）
5. RAG向量库0条embedding
6. 72个文件硬编码布局值（过渡态）
7. 探针深度14/100=14%
8. 7个用户报未挂功能
9. 11个文件原生alert（过渡态）
10. 8个空render函数
11. Ollama没起（start.bat已改自动起）

**硬规则**：改完代码必须重跑专家对比warning变化。

---

## 十、新会话启动SOP（豆包开机必做）

每次新对话第一任务，按顺序做：

### 第1步：读基线
- 读本文件（工作总控.md）
- 知道：100个专家、11个warning、布局锁死135px、主色#1a73e8

### 第2步：读专家最新报告
- 跑：D:\Python311\python.exe backend/core/experts/latest_report.py
- 知道：专家现在反对什么、warning变多变少

### 第3步：确认运行环境
- Ollama起着没（没起就 ollama serve）
- 后端起着没（没起就双击start.bat）

### 第4步：干活
- 用户报问题 → 先跑专家定位 → 改代码 → **改完必须重跑专家对比warning**

### 硬规则
1. 布局锁死（135px侧栏/56px顶栏/48px模块导航/28px底栏/#1a73e8主色）不许动
2. 改完代码必须重跑专家，对比warning变化
3. 不可逆操作（删表/清数据）必须先问用户
4. 可逆操作（建表/补render/灌数据）直接做

### 硬规则补3条（共7条）

5. **专家自己不能报错**——报问题前先验证是真问题，别把return HTML字符串当空render、别把flash_cards当flashcards、别拿V2.0旧值（160px/#3949ab）当现行标准
6. **实际运行代码 > tokens.css > 文档**——标准以跑起来的代码为准，文档过时了不怪代码
7. **标准分块不混入**——布局值在layout/，业务规则在standards/，改标准值只改对应文件，别写散

### git规则（第8条）

8. **项目有.git仓库但本机没装git CLI**——改代码前不用git commit，用backups/GOLDEN回滚机制。改坏了从backups/恢复，不靠git。

### git规则更新（2026-09-15 22:10）

8. **git已装**——改代码前先 git add . && git commit -m "改了什么"，改坏了 git checkout . 回滚。同时保留backups/GOLDEN双保险。

### 硬规则补2条（共10条）

9. **需求变更先读**——用户报问题/改需求，先查需求记录（需求记录#31~#78），知道这问题之前怎么记的、改到什么程度了
10. **改代码先读现状**——改任何文件前，先Read看现在长什么样，别凭记忆改；改完再重跑专家对比

---

## 十一、启动必读清单（豆包新会话第一件事）

新会话开始，按顺序全部读完，才开始干活：

### 必读文件
1. **工作总控.md**（本文件）——10条硬规则+专家现状+SOP
2. **架构总控文件.md**——细节问题查这个，不读35000行全文
3. **标准基线清单.md**——标准值核对

### 必跑脚本
4. **latest_report.py**——专家最新11个warning是什么
5. 确认Ollama起着没（没起就起）
6. 确认后端起着没（没起就双击start.bat）

### 必知事实
- 布局锁死：侧栏135px/顶栏56px/模块导航48px/底栏28px/主色#1a73e8
- 101个专家，PASS:True，11个warning
- 用户报48个问题#31~#78已录需求记录
- Python用D:\Python311\python.exe（系统python3.13没fastapi）
- 项目根：F:\水利智学系统\可运行版（解压即用，双击start.bat）

### 必读标准分块
7. backend/core/layout/dimensions.py——布局尺寸
8. backend/core/layout/colors.py——颜色
9. backend/core/standards/9块——业务规则/代码规则/数据质量/安全/运行时/工作流/功能状态/探针深度

**读完这些才开始干活，不跑偏。**

### 必跑脚本补1个
7. **查待办需求**——rom core.requirement_tracker import get_pending_requirements，78条待办，知道用户报的48个问题改到哪了

### 顶部工具弹窗统一靠右停靠（2026-09-16 新增，布局规范）
- 顶栏工具按钮（番茄专注钟/科学计算器/备考课表/背景音乐/帮助/安装APP/配色方案）点击 emit `topbar:tool-clicked`，由 `frontend/index.html` 主脚本统一分发到旧版全局函数（togglePomodoro / toggleCalculator / toggleExamSchedule / toggleMusic / showHelp / showPwaInstallGuide / toggleColorScheme）；theme 由 topbar 模块自处理。
- 弹窗统一加 class `tool-dock-right`：贴右侧（padding-right:16px）、顶栏下方（top:64px）、宽 340px、白底圆角16、右滑入动画；遮罩 rgba(0,0,0,.28)。
- 工具弹窗互斥：打开一个前先 remove 其他（pomodoroModal / examScheduleModal / calcModal）。
- 涉及面板：#pomodoroModal、#examScheduleModal（.modal-overlay）、#calcModal（.calc-modal）。

---

### 2026-09-17 23:30 智能分析前端接线（O02）
- 模块：analytics
- 需求：智能分析页面显示硬编码mock数据+随机正确率，需接真实API
- 实现：
  1. 给4个stat card加ID（statTotal/statAccuracy/statWrong/statExams）
  2. 给7个趋势图柱子加ID（trendBar0~6）
  3. 给动态分析卡加ID（dynStatusBadge/dynTotalAns/dynAccuracy/dynSuggestion/dynUpdateTime）
  4. 新增_api()方法：Bearer token认证 + AbortController 8秒超时
  5. 重写_loadRealStats()：调/api/v1/analytics/overview + study_trend?days=7 + weak_points
  6. 删除原来的随机正确率Math.random()
- 状态：✅已完成（API实测返回588题/41.8%/526错题/22次考试）
- 文件：frontend/modules/analytics/analytics.js
- 备份：backups/analytics.js.bak_20260917

---

### 2026-09-18 12:20 题库一造管理写闭环全线通 + 双内核路由竞态根治（commit de538d5）
- 目标：导入/识别→入库→题库列表→刷题（单选选后即出解析、多选提交才出解析、4选项=单选、5选项=多选）→今日待复习→错题本(加入复习)→我的收藏 整条链路无阻断、数据真实、真实浏览器点验。
- 后端（backend/modules/qb/service.py、routes.py）：
  1. record_answer 答错先 INSERT OR IGNORE 再 UPDATE 恢复（已掌握/曾软删题再答错回流）；答对更新 review_count/last_review_date（实测 wrong_questions 无 correct_streak 列，写它必500，已改用真实列）。
  2. 新增 POST /api/qb/wrong/{wrong_id}/review（reset_for_review，加入今日复习）。
  3. 错题/今日复习列表补返回 wrong_count/is_mastered/next_review_date/review_count（题目字段起始位 r[7:]）。
- 前端根因修复（解释长期"改了不生效/旧UI复活/Ctrl+F5仍旧"）：
  1. 双内核同页双写竞态：index.html renderPage 曾硬编码 question 走旧 app_v3 renderQuestion，与新版 QuestionPracticeModule 同写 #framework-content，冷启动旧UI覆盖新版；已删该旧回退特判，question 统一走新版。
  2. 侧边栏双订阅：framework.js 与 index.html 同时订阅 sidebar:navigate，renderPage 与 framework.load 双跑（同名模块双 init、别名 wrong→wrong-book 误报未注册）；已移除 framework.js 重复订阅，路由统一 renderPage 并登记 Framework._activeModule。
  3. P0：question-practice.js bindEvents 引用未声明的 aiExplainBtn/toFlashcardBtn（跨作用域 ReferenceError），进练习选项全点不动；已在 bindEvents 内补声明。
  4. page_size=200 触发后端 422（上限100）：wrong-book/collect/question 收藏加载中招列表为空；改为100并对 wrong/collect 分页循环拉全量。
  5. 新增今日复习模式 _startTodayReview()：消费 sessionStorage.todayReview，拉 /api/qb/wrong/today 到期错题直接进入复习刷题（修复用户#3 今日待复习点不开）；看板每日一练入口进题库自动弹窗（幂等，修双触发 toggle 关窗）。
- 真实浏览器点验：章节刷题新版（34章节、真实题数96/46/171…）；单选点错即着色+即时解析+同步后端；多选集合判分（答案AE选ABC：A/E绿、误选B/C红、提交才出解析）；错题本真实38题、字母集合高亮、薄弱章节TOP5真实聚合、加入复习不再报错（用户#7）；收藏☆→表格→系统统一确认框取消→归零（用户#31）；每日一练自动弹窗→15题真题；今日复习→38题到期错题；三模块切换控制台0报错。
- 数据还原：测试产生的 wrong_id 529/530 已软删，错题 total 回 baseline 36、今日复习36、收藏0。
- 遗留（独立任务）：①案例题 case_background/sub_questions 未结构化（渲染不崩但内容空、题干重复，属案例识别内核）；②复习题存在 PDF 识别串题脏选项（D/E 混入下一题文本）致5选项误判多选，属识别数据治理（不可逆，需备份+用户确认）；③真题年份下拉写死2023-2018缺2025、未按年份/题型筛选；④question-manager/mock-exam 待接线；⑤闪卡、思维导图为下一阶段。
- 文件：backend/modules/qb/service.py、backend/modules/qb/routes.py、frontend/core/framework.js、frontend/index.html、frontend/modules/question/question-practice.js、frontend/modules/wrong/wrong-book.js、frontend/modules/collect/collect.js
- 备份：backups/ 下 question-practice.js.bak_fixbtn/todayreview_*、index.html.bak_killoldq/daily/route_*、framework.js.bak_route_*、wrong-book.js.bak_wbpage_*、collect.js.bak_copage_*

---

## 2026-09-19-19 18:11 dashboard学习看板假数据融合修复（P0）

### 改动文件
1. rontend/modules/dashboard/dashboard.js（590行→640行）
2. ackend/api/v1/analytics.py（weak_points端点增强）

### dashboard.js 修复内容
- **删除Math.random假趋势**：L214 Math.floor(Math.random()*20)+5 随机7天做题数已删除，改为调 /api/v1/analytics/study_trend?days=7 获取真实答题记录
- **统计卡接真实API**：新增 /api/v1/analytics/overview 调用，累计答题/正确率/错题数优先用后端真实数据（实测614题/41.9%/536错），localStorage降级
- **章节掌握度修复**：原 masteryItems（硬编码30+i*12进度）设了但渲染用的是 state.mastery（永远0%），变量名不匹配。改为调 /api/v1/analytics/weak_points 按章节聚合真实正确率；后端未重启时从wrong_count推算
- **学习日历双数据源**：原来只读localStorage的today_stats，改为后端study_trend优先+localStorage兜底
- **AI建议空安全**：StorageService.answers.getAll()加了window.StorageService存在性检查
- Math.random计数：1→0

### analytics.py weak_points端点增强
- 原返回字段：chapter/knowledge_point/wrong_count（无正确率）
- 新增字段：total_answered/correct/accuracy
- SQL通过wrong_questions.question_id LEFT JOIN question_answer_logs，COALESCE章节名，按章节聚合
- 注意：后端进程权限较高无法从agent重启，需用户双击"重启后端.bat"生效；前端已有wrong_count推算fallback

### 验证
- node verify.cjs 语法通过
- node sync.cjs dashboard 已同步
- API实测：overview 614题/41.9%/536错/22次考试；study_trend 09-18有26题；weak_points 10条
- 备份：backups/dashboard.js.bak_20260919、backups/analytics.py.bak_20260919

### dashboard.js 追加修复（同日）
- **今日目标真实进度**：dailyGoals的current原来恒为0（0/1、0/25、0/20、0/5），改为从study_trend今日做题数、flashDue到期闪卡、wrongToday待复习错题填充（这两个变量原来取了却没用上）
- **AI阶段动态化**：原硬编码"强化阶段（剩余37天）"，改为按考试日2026-10-17动态计算：>60天基础/30-60强化/7-30冲刺/<7考前冲刺；记忆曲线建议按真实待复习数显示
- **中性占位**：构造函数初始值wrongCount:80→0、aiPlan假任务→"正在加载学习计划…"、"剩余37天"→"加载中…"，避免数据加载前闪现误导数字
- 最终行数669，Math.random=0，集成7个真实API端点

### analytics O03考点图谱核查结论（原误判为未迁移）
- 经走查，analytics.js四个tab均已接线：数据分析(_loadRealStats)、考点图谱(_loadPointMap调knowledge-graph三端点)、真题分析(_loadExamAnalysis调sprint/heatmap+exam_analysis)、大纲分析(_loadOutline)
- _switchTab切换时按activeTab调度对应加载方法，初始65%/25%/10%只是DOM占位会被真实题型分布覆盖
- 后端5端点实测全部200：knowledge-graph/overview(7.9KB)、key-points(8.8KB)、weak-points(1.3KB)、exam_analysis/overview、constant_points(5.4KB)
- 结论：O03实际已完成，迁移清单状态需更新

### 全模块mock终审
- 21个业务模块扫描完毕，剩余Math.random仅mock-exam.js(L78)、flashcard.js(L149/L721)的Fisher-Yates洗牌算法（随机题目/卡片顺序，合法非mock）
- memory.js三处硬编码经核查为教学内容（9种记忆法按钮/4个工具/8套考试专项填空题库，从旧代码迁移的静态内容）
- sprint.js硬编码数组经核查为初始占位，_loadRealStats直接更新DOM，4个后端端点实测正常

---

## 2026-09-19 323号文《水利工程设计概(估)算编制规定》全链条分析与入库

### 输入
- 桌面PDF：一造水利案例编规—《水利工程设计概(估)算编制规定》2024 323号文（252页/69.6MB，整页扫描JPEG+OCR文字层，文字可提取13.8万字，仅15页图表页）
- 水总〔2024〕323号工程部分，2025-04-01施行，替代水总〔2014〕429号

### 分析成果（产物目录：分析产物_323号文/）
1. 323号文_全文提取.txt（308KB/13.8万字，PyMuPDF sort=True提取）
2. 323号文_全链条思维导图.md（13947字，20个一级分支/69个三级节点/85+公式行）
   - 主线：基础单价→工程单价(8步取费)→六部分概算→工程部分静态投资→静态总投资→总投资
   - 覆盖：三阶段(匡算/估算/概算)、三大类工程、六部分、五大费用、基础单价(人工/材料/电风水/台时/砂石/混凝土)、建安单价取费、设备费、独立费用费率、预备费(基本+价差复利)、建设期融资利息、分年度投资资金流量、费率速查表、高频易错点
3. 323号文_全链条计算图.html（15.6KB自包含离线可视化，主色#1a73e8，金字塔计算链+8步取费+费用树+公式卡+费率表）
4. 323号文_压缩版.pdf（34.2MB，JPEG质量45+宽度1500重压缩，252页完整、文字层保留，满足资料库50MB上限；原件未改动）

### 系统入库（后端8000/admin）
- mind_maps id=194：全链条思维导图，subject=一造水利案例，map_type=knowledge（核心交付，已读回校验公式完整）
- mind_maps id=195：系统generate_from_pdf(material_id=49)自动生成，仅17节点目录骨架（验证系统可处理该扫描件，但深度远不如手工导图）
- course_materials id=49：压缩PDF，subject=一造水利案例（上传时被当前激活科目覆盖成"一建水利实务"，已UPDATE修正为一造水利案例），file_path=uploads/3460a12c95354663bcd8153e39762a76.pdf

### 关键结论/口径
- 利润7%、建筑业增值税9%、设备采购保管费率0.7%、材料采保其他材料2.5%、商品混凝土基价200元/m³
- 基本预备费费率：匡算18-20%/建议书15-18%/可研10-12%/初设5-8%
- 价差预备费 E=ΣFₙ[(1+P)^n−1]（基数资金流量表静态投资）；融资利息 S=Σ(年初借款本息累计+本年借款/2)×i
- 安装工程间接费基数=人工费（建筑=直接费）；材料补差/未计价材仅计税金
- 未改任何业务代码，仅向mind_maps/course_maps写入数据；PDF原件(桌面)未改动

### 2026-09-19 导图重构：按"总投资为根"费用分解树（id=194 v2）
- 用户纠偏：思维导图须以"水利工程总投资"为顶层根，融入项目组成六部分，最终落到费用构成，按编规章节深化到末梢（非计算流平铺）
- 新建 323号文_总投资费用分解思维导图.md（8652字，13个一级分支/45个二级/213个末梢列表项/54个公式）
  - 结构：总投资→静态总投资(四部分)→工程部分静态投资(六部分+基本预备费)→第一~六部分逐项(建筑/机电/金结/输水/施工临时/独立费用)→各部分费用构成末梢(建安费直接费三要素/其他直接费5项/间接费规费+企管费13项/设备费四项/独立费五项及子项)→计价支撑(工程单价8步、基础单价人材机电风水台时砂石混凝土)→分年度资金流量→三阶段
  - 基本预备费、价差预备费作为两个独立知识点节点（遵用户偏好）
- 生成 323号文_总投资费用分解思维导图.html（31KB，自包含可折叠横向树，20色一级分支，公式黄底等宽框，Edge headless截图验证渲染正常279节点，嵌套列表层级正确）
- POST /mindmap/save 更新 id=194 为 v2（标题"323号文·总投资费用分解树（末梢公式版）"，GET读回校验10个关键词全命中）；原全链条计算图HTML作为配套保留；id=195系统自动目录、168-182章节导图均未受影响

---

## 2026-09-20 323号文造价结构树·系统内交互页落地（map_type=cost_tree，零侵入）

### 交付物（全部为新增文件，未改动任何现有代码/布局/页面，遵守"布局锁死"）
- `frontend/pages/cost-tree.html`：独立交互页，访问 http://127.0.0.1:8000/static/pages/cost-tree.html （StaticFiles已递归挂载，无需注册路由）
- `frontend/lib/cost-tree.js`：水平结构树渲染器（cost-tree-v1），从库加载 content_json、失败回退内置种子；点节点手风琴弹卡、口诀就地编辑、一键存库；六部分/底座快捷跳转；sticky 顶栏；画布固定视口高度内双向滚动
- `frontend/data/cost-tree-seed.js`：内置种子（window.COST_TREE_SEED，离线/file:// 兜底）；`cost-tree-seed.json`：同源标准JSON（入库与备份）
- 数据模型：mind_maps id=196，map_type=cost_tree，subject=一造水利案例，chapter=编制规定323号文（工程部分），content_json 存结构化树，content_md 存190行大纲（兼容普通导图列表）；四元组(user+subject+chapter+map_type)覆盖更新、version自增

### 知识结构（经原文L534-863/L2806-3365/L3600-4669全量核准）
- 根=水利工程总投资；两条正交线：①项目组成线（静态总投资→工程部分静态→第一~六部分，按枢纽/引水/河道三类工程到建筑物/系统末级）②通用计价底座（建安费直间利税→工程单价8步→基础单价人材机风水电/台时/砂石/混凝土，全工程共用）
- 末级口径=建筑物/系统/费用要素；三级共性定额子目（土方/石方/混凝土/模板/钢筋/灌浆等）不挂具体建筑物，统一归底座（遵"土石方是共性共用"纠偏）
- 数字孪生到末级：设施4类（雨水情4站/安全监测6测+土建3件/通信网络/基础环境，青色实线入第一部分）＋设备平台软件9类（紫色虚线跨第二部分）
- 规模：190节点/147末级/81公式/40口诀；基本预备费、价差预备费为两个独立节点；关键费率（利润7%、增值税9%、采保0.7%、其他直接费/间接费/安全专项2.5%/其他临时/独立费各项/预备费分阶段）均入卡
- 交互：默认纯结构树；点带▸节点在正下方弹"公式黄区+口诀绿区"，同时刻只开一个、点空白或再点收起；每个可点节点预留口诀位，口诀 contenteditable 改完"保存口诀"POST /mindmap/save 持久化

### 验证（Playwright驱动系统Edge，非仅静态检查）
- 190节点全渲染、控制台0报错；顶栏常驻、根节点左中定位不挤压；点击手风琴(open恒=1)、弹卡公式/口诀、口诀contenteditable、编辑后dirty红点+保存钮变红、跳转底座/数孪定位均断言通过
- 持久化闭环：改口诀→save得v2且GET读回含改动→恢复原始→v3且读回复原（最终库内容=种子，id=196 v3）
- 零破坏：SQL确认 id=194(knowledge v2,8652字)/195、18条knowledge导图、总计127条记录完好；仅新增4文件+1条新map_type记录
- 注：本机 Edge 旧 --headless CLI 截图当前会出白屏（与页面无关），--headless=new / Playwright(channel=msedge)正常

### 待用户决策（未擅动）
- 系统内菜单/按钮入口会触及现有思维导图模块布局，按"布局锁死"暂不加，当前以独立URL访问；需要加入口时请示下
- 大量末级节点口诀仍为占位"（点击此处编写口诀）"，结构已全部预留可在线改；是否由AI按既有口诀风格批量拟全稿，待示下

### 2026-09-20 14:30 对照交付级诊断报告：实测勘误+批量标记+version接口

- 模块：docs/backend/data
- 需求：对照系统交付级诊断报告认真比对，不实的做标记，真问题深化推进
- 实现：
  1. **诊断报告加实测勘误表**：在报告开头插入6项勘误（艾宾浩斯已修/过时题实际44题/串题实际17题/重复题实际15题/同步属实/RAG属实），第八章差距表L890-891加行内标记
  2. **批量标记过时题**（UPDATE可逆）：PPP 1+BOT 14+特许经营4+选项缺失17 = is_outdated=1共45题
  3. **批量标记重复题**（UPDATE可逆）：4组同title，保留id小的，其余标is_duplicate=1（累计69题）
  4. **题库干净度**：可用干净题1004/1080（其余45过时+69重复已标记，刷题API过滤后不出现）
  5. **新增 /api/v1/system/version 端点**：返回app_version/题库总数/干净数/过时数/重复数/知识点数/最后更新时间，供移动端判断缓存是否过期
- 文件：系统交付级诊断报告.md、backend/api/v1/system.py、tools/_diag_p0.py、tools/_mark_p0.py、tools/_mark_empty.py、tools/_check_empty.py
- 状态：⏳ 后端需重启加载/version新端点（旧进程WMI高权限，agent杀不掉，需用户双击"重启后端.bat"）
- 验证标记：is_outdated=1=45题，is_duplicate=1=69题，干净题=1004

### 2026-09-20 15:10 造价结构树：模块入口(科目联动)+口诀全稿+基础单价电水风补全（id=196 v4）

- 模块：frontend/modules/mindmap、frontend/pages/cost-tree、frontend/lib/cost-tree、frontend/data/cost-tree-seed、frontend/sw.js
- 需求（用户三指令）：①思维导图模块加"🌳造价结构树"入口，切换到"一造水利案例"自动显示（本次唯一获授权布局改动），其余科目隐藏；②按现有口诀风格（缩字/数字，如"直间利税""基他间利差材税价"）批量拟全稿；③补全施工用电/用水/用风等基础单价编制（公式/构成），原"施工电水风价格"仅一个合并叶子未展开
- 实现：
  1. 入口：mindmap.js 加 _currentSubject()（读 Store.currentSubject/localStorage，默认一造管理）；render() 计算 isCostSubject=/水利案例/，工具栏条件渲染绿色按钮，点击 window.open('/static/pages/cost-tree.html')；modules 与 static/modules 两份 mindmap.js 已同步
  2. 缓存绕行（后端 WMI 高权限进程，taskkill/Stop-Process 均 Access denied、无法重启刷新 ?v= 指纹）：改后模块以**新文件名 mindmap.ct.js** 发布（新 URL 零 HTTP/SW 缓存、StaticFiles 实时读盘、免重启）；index.html 与 static/index.html L249 改引 mindmap.ct.js；sw.js CACHE_NAME bump 为 shuili-exam-v6-20260920-ct1、PRECACHE 同步换 mindmap.ct.js（activate 清旧壳缓存，KEEP 保留数据/视频/AI缓存）
  3. 种子整体重写（cost-tree-seed.js/.json）：末级二分——计费节点（有独立公式/费率，可点，必带 formula+非空口诀）与构成枚举末级（只列建筑物/系统/设备组成，不可点不弹卡）；主体8项建筑物/机电金结清单/数孪测点等纯枚举叶子上收计费逻辑到父节点；生产准备6项/科研勘测2项/其他直接费5项/人材机3项/间接费2项/单价8步3子项等独立费率知识点补 formula+口诀变可点
  4. 基础单价扩为8个可点末级：人工预算单价（表4-1 工区×等级×枢引河）、材料预算价格+材料基价（超限部分补差仅计税）、施工用电（电网连除两道损耗3~5%/4~7%+摊销0.04~0.05；柴油 K0.80~0.85、厂用电率3~5%、循环冷却水0.05~0.07；两部制容量电费列第五部分）、施工用水（K0.75~0.85、供水损耗6~10%、摊销0.04~0.05）、施工用风（比水多×60min、K0.70~0.85、损耗6~10%、摊销0.004~0.005、循环水0.007）、机械台时费（一类折修安/二类人燃料）、砂石（外购基价60）、混凝土材料（商混基价200、补差仅计税）
- 数据契约：cost-tree-v1（root/children，cls 配色，formula[]+koujue，按遍历路径 data-path 无手写id）；在线优先 GET 库 content_json、失败回退种子；保存整树 POST /mindmap/save，四元组覆盖 version+1
- 规模：**194节点/150末级/96公式节点/96口诀节点/0空口诀**；POST 覆盖 mind_maps **id=196 map_type=cost_tree version=4**，GET 读回 96=96、电水风/60min/材料基价/夜间口诀全命中
- 验证（Playwright 驱动系统 Edge，真实路径）：
  - 入口联动：管理科目进思维导图按钮=0；changeGlobalSubject('一造水利案例') 后重进思维导图按钮=1、文本"🌳 造价结构树"，点击新标签 URL 含 cost-tree.html、弹出页194节点；切回管理重进按钮=0；全程 pageerror=0
  - 造价树：.ct-cell=194、.ct-cell.has=96、.ct-k.empty=0；施工电/水/风/夜间施工增加费/材料基价卡片 open 且公式关键参数（高压3~5%、K0.75~0.85、60min、0.007、0.5%、补差）与口诀齐全；徽标"已载入系统数据(v4)"
  - node --check mindmap.ct.js 通过；HTTP 校验首页 served src=mindmap.ct.js?v=时间戳、不再引旧 mindmap.js、ct.js 返回200且含 mmCostTreeBtn/_currentSubject
- 零破坏：仅前端新增1文件(mindmap.ct.js)+改 mindmap（条件按钮+只读方法，原有导图/大纲/我的导图功能不变）+2处 index 引用+sw 版本；未动后端与 DB 结构；id=194/195、knowledge、章节导图等其他记录未触碰
- 访问：http://127.0.0.1:8000/static/pages/cost-tree.html ；系统内路径=思维导图模块 →（顶部科目切到"一造水利案例"）→ 工具栏"🌳造价结构树"
- 遗留：后端日后重启 APP_VERSION_TS 更新后，旧 mindmap.js?新指纹也会是新内容（ct.js 可保留）；用户旧标签若仍显旧，整页刷新一次，SW ct1 自动接管

---

## 2026-09-20 17:10 学习资料库删除功能修复（P0，用户报"大纲教材删不掉"）

- 模块：library（学习资料库 file-library.js）
- 需求：用户实测点删除按钮，"大纲教材8个还在"；单删/批删均无效且无报错
- 根因（三链全查实）：
  1. `window.api` 最终被旧代码 `app_v3_897262.js` 覆盖（L999，API+url 直拼，API='/api/v1'）；file-library.js 删除/上传/标签保存的 URL 带了 `/api/v1` 前缀 → 实际请求 `/api/v1/api/v1/fl/{id}` → **404**
  2. 404 被 app_v3 api 吞掉（不抛异常，返回 data）→ fetchData 不报错 → UI 误报"删除成功"但文件还在
  3. 加载列表用的 `/fl/list`（无前缀）拼接正确，所以列表正常显示、掩盖了删除路径错误
- 实现（统一去掉多余前缀，与列表调用一致）：
  1. deleteFile / batchDelete：文档 `/api/v1/fl/{id}` → `/fl/{id}`；视频 `/api/resource/videos/{id}` → `/video/{id}`（对齐后端 PUT/DELETE /api/v1/video/{vid}）
  2. deleteFolder：`/api/resource/{id}` → 按 id 类型走 `/fl/{id}` 或 `/video/{id}`
  3. 上传 `POST /api/v1/fl/upload` → `/fl/upload`
  4. 标签保存 PUT（单文件 L412 / 批量 L519）：`/api/v1/fl/{id}` → `/fl/{id}`
  5. fetchData 的 fetch fallback 分支：无 window.api 时补 `/api/v1` 前缀
  6. 版本指纹：index.html 与 static/index.html `file-library.js?v=20260919fl3` → `v=20260920fl4`；sw.js CACHE_NAME → shuili-exam-v6-20260920-fl4、PRECACHE 同步带新指纹（强制客户端拉新代码）
- 验证（浏览器实测 admin 真实路径）：
  - 上传测试 PDF → 列表可见 → 单文件删除 → showConfirm 确认 → **DELETE /api/v1/fl/509 200** → 列表自动刷新消失 → 库 is_deleted=1
  - 批量删除：勾选 → 按钮启用 → confirm → **DELETE /api/v1/fl/509 200** → 消失；控制台 0 报错
  - API 层：DELETE /fl/{id}、DELETE /video/{id}、PUT /fl/{id}(tags)、POST /fl/upload 全部 200
  - node --check 两份 file-library.js 通过；modules 与 static 两份哈希一致
  - 测试数据全部清理（记录+物理文件），库与修复前一致：fl 506、视频 64、大纲/教材 14 未删，用户数据零破坏
- 文件：frontend/modules/library/file-library.js、frontend/static/modules/library/file-library.js、frontend/index.html、frontend/static/index.html、frontend/sw.js
- 备份：backups/file-library.js.bak_deletefix_20260920_modules / _static
- 遗留（另题）：renameFile 文档重命名后端 fl 无 title 更新接口（PUT /fl/{id} 仅 Form 标签字段），重命名文档仍不可用，待用户确认是否补接口

## 2026-09-20 20:10 闪卡/题目批量删除 + 资料库文件夹删除（电脑版）

- 模块：flashcard.js、question-manager.js、file-library.js、data-service.js、index.html×2、sw.js
- 需求（用户指令）：闪卡批量删除、题目批量删除、学习资料库文件夹删除功能，只做电脑版
- 现状探查：
  1. 闪卡：卡片管理 tab 的 checkbox/删除按钮渲染了但**全无事件绑定**（死按钮）；后端 DELETE /api/v1/flashcard/{cid} 已存在
  2. 题目：有全选+单删，但无批量删除按钮；单删存在"删除后 this.render() 只重渲缓存、列表不刷新"的假成功 bug；后端 DELETE /api/v1/question/{qid} 软删除已存在
  3. 资料库：deleteFolder 函数与绑定已存在（上次删除修复时写好），但**文件夹分组标题行从未渲染删除按钮**（死代码）
- 实现：
  1. flashcard.js：工具栏加"🗑️ 批量删除"（id=fcBatchDel 默认 disabled）；表头全选 #fcSelectAll；行 checkbox .fc-row-chk[data-id]；单删按钮 .fc-del-btn[data-id]；新增 _fcUpdateBatchDel/_fcBatchDelete/_fcDeleteOne/_fcDeleteCards（循环 DELETE /api/v1/flashcard/{id}，成功清 DataService 缓存后 _loadRealCards 刷新）；**checkbox 与删除按钮的 click/change 均 stopPropagation**（行 onclick 会 re-render 丢勾选，实测踩坑修复）
  2. question-manager.js：工具栏加"🗑️ 批量删除"（id=qmBatchDelBtn 默认 disabled）；行 checkbox .qm-row-chk[data-id]；新增 _qmUpdateBatchDel/_qmBatchDelete/_qmDeleteIds（await 校验 res.ok&&data.success，失败 toast error，成功后 _loadRealQuestions(currentPage) 重新拉取）；**单删从"忽略结果+render()"改为 await 校验+重新拉取**（原实现删完列表不刷新）
  3. file-library.js：文件夹分组标题行操作列渲染"🗑️ 删文件夹"按钮（.fl-folder-delete-btn data-folder，onclick stopPropagation，绑定与 deleteFolder 复用上次修复），所有列文件夹均显示
  4. data-service.js：getFlashcards 的 apiFlashcardsCache 闭包缓存**删除/修改后永不失效**（clearCache 不清它）→ 新增 clearFlashcardsCache() 导出，flashcard 删除后调用，否则删完列表不刷新（实测踩坑修复）
  5. 指纹：flashcard.js→20260920fcbdel1、question-manager.js→20260920qmbdel1、file-library.js→20260920fl5、data-service.js→20260920bdel1；sw.js CACHE_NAME→shuili-exam-v6-20260920-bdel1；modules 与 static 两份哈希一致
- 验证（浏览器实测 admin 真实路径，测试数据已清理）：
  - 闪卡：勾选→按钮启用→confirm"确定删除选中的 N 张闪卡"→确定→DELETE 725→库 is_deleted=1→列表刷新消失（589 条）；取消路径不删
  - 题目：定位测试题 5954→勾选→按钮启用→confirm→确定→库 questions is_deleted=1→列表刷新消失
  - 文件夹：33 个文件夹标题行均渲染"删文件夹"按钮（33/33）；端到端删除验证未跑完（测试文件 509 已上传待归组删除）
  - node --check 全部通过；modules/static 哈希一致；API 列表正确过滤 is_deleted
- 文件：frontend/modules/{flashcard,manager,library}/*.js、frontend/core/data-service.js 及 static 对应副本、frontend/index.html、frontend/static/index.html、frontend/sw.js
- 备份：backups/*.bak_modules_20260920bdel、*.bak_20260920bdel
- 遗留：文件夹删除端到端验证（上传测试文件→归组测试文件夹→UI 删除→验证消失）待补；"清空"按钮仍无绑定（非本次需求，未动）

## 2026-09-20 20:40 平板无法访问诊断 + start.bat 统一网址显示

- 模块：start.bat（仅横幅显示，无业务逻辑改动）
- 需求（用户报）：平板访问 100.81.103.0 无法显示网页；后要求"统一网址，同一IP优先直连、Tailscale 兜底"
- 诊断结论（全部实测）：
  1. `100.81.103.0` 是电脑 **Tailscale 组网 IP**（tailscale status：cherry 100.81.103.0），平板 huawei-air=100.68.176.99
  2. 根因：检查时平板 Tailscale **offline（last seen 3h ago）**，故平板打不开；复查时已恢复 active（direct 192.168.0.38:37675 17ms，有流量）
  3. 电脑侧全部正常：uvicorn 监听 0.0.0.0:8000（main.py L971）、防火墙 python 入站 Allow（Private+Public）、本机经 100.81.103.0:8000 与 192.168.0.203:8000 均 HTTP 200
  4. Tailscale MagicDNS 已启用；电脑 WLAN IP 为 DHCP（192.168.0.203，会变）
- 结论（统一网址方案）：**统一用 http://100.81.103.0:8000**——Tailscale 在同一 WiFi 下自动 direct 直连（局域网优先已内置，实测 17ms），异地自动走 DERP 兜底；Tailscale IP 固定不随 DHCP 变。平板仅需保证 Tailscale 后台常驻
- 实现：start.bat 横幅增加 Tailscale IP 自动检测显示（for /f 调 tailscale.exe ip -4，GBK 写入，\t 转义坑已修）：`Unified: http://%TS_IP%:8000 (统一网址, 同一WiFi自动直连优先)`；cmd 临时 bat 实测输出 [OK] Unified: http://100.81.103.0:8000
- 备份：backups/start.bat.bak_20260920ts
- 遗留：平板端 Tailscale 电池优化需设"不限制"防掉线（用户侧操作）；192.168.0.203 局域网直连为备选（若 IP 变化需路由器 DHCP 绑定）


---

## 2026-09-20 三个问题修复/检测记录

### ① 磨耳朵"正在播报"状态文字错位（已修复）
- 根因：模块版 flashcard.js 中 mnemonicPlayStatus 位于卡片内部（fc2-body-back），与下方"下一个"按钮视觉混淆；且 updateDisplay 切卡时不清空状态文字，残留上一张卡的"正在播报：第 N 次 / 共 N 次"。
- 修复：①状态文字从卡片内移出，放到播报控制按钮上方独立成行（全宽、min-height 占位）；②updateDisplay 切卡时清空 mnemonicPlayStatus。
- 指纹：flashcard → v=20260920mnemonic1（index.html/static/index.html/sw.js 已同步）。
- 实测：状态文字 (30,377,480) 独立行位于按钮 (y=403) 上方，播放显示"正在播报：第 1 次 / 共 3 次"正常。

### ② 学习资料库重复文件检测（已检测，清理待用户确认）
- 全量扫描 backend/uploads（11616 文件/10.05GB）：990 组重复、浪费 0.44GB（大头 split_output 拆分zip 233MB、question_files 真题副本、syllabus、music）。
- 全量扫描 backend/data/files（1353 文件/2.79GB，资料库真实存储）：286 组重复、浪费 0.57GB（大头"其他/"与"考试类学习资料/"重复、视频讲义/与讲义目录重复、_nowm 多级去水印副本）。
- fl_file_library 对比：孤儿文件 1337 个（库无记录，含大量 _nowm/_nowm_nowm 副本）；悬空记录 484 条（file_path 含"一造培训资料/"前缀，实际文件在"2025-一造管理 蒋.莉莉/"等，路径失配）；库内同名记录 9 组。
- 报告：_dup_report.json（uploads）、_files_dup_report.json（data/files+fl对比）。

### ③ 顶部工具栏主题切换无效（已修复）
- 根因：framework.js _injectStyles 注入的 #framework-styles-v2 内联 style 把 body{background:#f5f7fa} 和 --bg/--card/--border 等变量硬编码在 body 级，后加载覆盖 style.min.css 的 [data-theme=dark] 规则 → --bg 计算值停在浅色，页面视觉不变。
- 修复：①framework.js body 硬编码背景改 var(--bg)、删除 body 级硬编码变量（tokens.css :root 已有）；②theme.js applyTheme 增加显式 CSS 变量注入（内联 element style 最高优先级，dark/浅色两套值），切换即生效。
- 指纹：theme.js/framework.js → v=20260920theme1，sw.js CACHE_NAME → shuili-exam-v6-20260920-theme1。
- 实测：切深色后 body rgb(15,23,42)、topbar rgb(30,41,59)、--bg #0f172a；切回浅色恢复 rgb(245,247,250)。视觉截图确认。

### 2026-09-21 08:00 对照诊断报告：刷题过滤+SM-2调度修复

- 模块：backend/modules/qb、backend/api/v1/system.py、data
- 需求：对照交付级诊断报告全面优化，已实现标记，深度不够继续优化
- 实现：
  1. **刷题API加过时/重复过滤**：service.py 3处+routes.py 1处查询条件加(is_outdated=0 OR is_outdated IS NULL)和(is_duplicate=0 OR is_duplicate IS NULL)，标记的45题过时+69题重复不再出现在刷题列表
  2. **SM-2调度修复**：record_answer答对分支之前只更新review_count不更新interval_days/next_review_date，导致568题全部堆在今日到期。补上SM-2间隔序列(1→3→7→15→30→掌握)，答对后自动推到未来复习日
  3. **568题错题SM-2初始化**：review_count=0→明天到期(563题)，review_count=1→3天后(2题)，review_count=2→7天后(1题)。今日到期从568→0
  4. **/version端点改raw SQL**：之前ORM模型没is_outdated字段导致500，改用sqlite3直接查，不依赖模型定义
- 文件：backend/modules/qb/service.py、backend/modules/qb/routes.py、backend/api/v1/system.py、tools/_check_sm2.py、tools/_init_sm2.py
- 状态：⏳ 后端需重启加载新代码（旧进程WMI高权限，agent杀不掉）
- 验证标记：今日到期=0题，明天=563题，可用干净题=1004/1080

### 2026-09-21 08:15 对照诊断报告：RAG灌库+同步bug修复

- 模块：RAG/sync/data
- 需求：继续深化推进诊断报告差距项
- 实现：
  1. **RAG向量库灌数据**：跑build_rag_index.py，464个教材文件全索引，产出26106个文档块，错误0。RAG从0条→26106块
  2. **同步API列名bug修复**：sync_records表实际列名是created_at，代码INSERT用create_time导致INSERT失败被except吞掉。push/pull返回200但sync_records永远=0。已修正
  3. **register-device路径**：实际端点是/api/sync/register-device（中划线），不是register_device（下划线）
- 文件：backend/modules/sync/routes.py、backend/tools/build_rag_index.py（已跑）
- 状态：⏳ 后端需重启加载sync routes修复+service.py过滤+SM-2调度
- 验证标记：RAG docs=26106，今日到期=0题，可用干净题=1004

### 2026-09-21 08:09 移动慢链路治理：SW API 限时竞速 + 视频预缓存链路门控
- 模块：PWA/离线（sw.js、offline-media-prefetch.js）
- 需求：Tailscale 已连但移动设备全程绕海外 DERP 中继（平板 sfo 408~660ms、手机 hkg ~510ms、未直连），移动瘦客户端在中继慢网下：①只读 API 走 network-first 且失败重试3次（0.7/1.4s），弱网/离线最坏十几秒才回缓存；②NetInfo 只判蜂窝，平板连 WiFi 但经中继也被当宽带，会硬缓存约8.3GB视频占满窄带。
- 实现：
  1. sw.js 同源 /api GET 改“网络3秒竞速+缓存即时回退”：AbortController 限时 NET_WAIT=3000ms，3s 内成功返回网络并写 DATA_CACHE；超时/失败有缓存立即返回（取消原3次长重试）；首装无缓存才再发一次不带超时耐心请求，仍失败回 503 offline JSON。写操作不拦截。
  2. offline-media-prefetch.js 新增 probeLinkQuality() 应用层链路门控：3 次 /api/common/health 取 RTT 中位数，RTT>120ms 直接判慢（不做吞吐、省流量）；合格再 Range 取样本视频前2.5MB 测吞吐，<2.5MB/s 判慢。慢链路只保证题库+教材PDF，跳过约8GB视频并底部提示一次；快链路才自动批量。切网重置重测；视频页单个“缓存此视频”不受门控。常量 RTT_FAST_MAX=120 / THROUGH_FAST_MIN=2.5MBps / PROBE_BYTES=2.5MB；暴露 window.offlineMediaPrefetch.probeLink。
- 文件：frontend/sw.js（当前 CACHE_NAME=shuili-exam-v6-20260921-ct2）、frontend/offline-media-prefetch.js；后端已重启 manual_restart DONE ok=True，APP_VERSION_TS=1789949176。
- 验证：node --check 通过；cherry 新 SW activated/controller=true、/sw.js 含 net-timeout；500ms 慢网 /api/qb/all 372ms 返回200/1080题；DATA_CACHE 的 qb/all 键含完整题；probeLink 桌面本地 hairpin RTT36ms、12.19MB/s、fast=true；startup_verify 26 PASS/0/0。桌面测试视频缓存已清、移动视口模拟已重置。
- 状态：⏳ 最终证据需真机（CDP 限速/offline 对 SW 独立 target 与本机 Tailscale hairpin 不稳定）：①飞行模式题库秒回缓存、未缓存端点回503且前端不当空数据；②中继下 probeLink 判慢跳过视频只缓存题库+PDF，同 WiFi 直连（RTT<50ms）后恢复全量视频缓存。
- 备注：中继根因=电脑对称NAT+路由器无UPnP；电脑WiFi=ChinaNet-BYHSK（192.168.0.203/23，网关192.168.1.1，UDP41641正常监听）。手机/平板连同一WiFi且路由器无AP隔离即可局域网直连；否则需路由器转发UDP41641或自建国内DERP。
### 2026-09-21 一造水利案例「造价结构树」升级为思维导图模块内嵌系统视图（全面测试通过）
- 模块：思维导图模块（mindmap）/ PWA 离线（sw.js）
- 需求：用户“将一造水利案例导图布局到系统里面、全面测试运行效果”。此前造价树（mind_maps id=196，map_type=cost_tree）只能由思维导图模块绿色按钮 window.open 独立标签页（自带蓝色顶栏、脱离系统 135px 侧栏/56px 顶栏外壳）。本轮要求内嵌为系统内视图、保留外壳、不再弹独立网页。
- 实现：
  1. mindmap 模块在节/章/科目 tab 后新增第 4 个 tab「🌳 造价结构树」，仅当前科目匹配 /水利案例/ 时渲染；绿色按钮保留，onclick 由 window.open 改为切到该内嵌 tab（tab 与按钮双入口均不开新窗）。
  2. 新增四方法：_renderCostTree()（蓝色工具条+操作提示+宿主 #mmCtHost；控件沿用 cost-tree.js 约定 id：#ctJump/#ctCollapse/#ctSave/#ctDirty(带 class ct-dirty)/#ctSrc/#ctOpenPage；内嵌 scoped style 让画布 flex 填满宿主，覆盖独立页 calc(100vh-176px) 口径，消除双重滚动）；_ensureCostTreeLib()（首次进入按需动态注入 /static/data/cost-tree-seed.js 与 /static/lib/cost-tree.js）；async _mountCostTree()（_costSeq 防竞态、切走即弃，CostTree.mount 在线读库、失败回退 seed，onStatus 写数据来源徽标）；_bindCostTreeEvents()（跳转 scrollTo、收起 collapseCards、↗新页开窗、保存 ctl.save()+CommonUtils.showToast，仅 dirty 可存）。
  3. render() 内容分发加 activeTab==='costtree' 分支并在 render 末尾触发 _mountCostTree；切回节/章/科目 tab 正常卸载造价树。
  4. 绕缓存发布（后端 APP_VERSION_TS 启动固定、资源 immutable、进程 WMI 高权限杀不掉无法重启刷新指纹）：最终版另存 mindmap.ct2.js 作为首页实际加载文件；modules/mindmap 下 mindmap.ct.js、mindmap.ct2.js、mindmap.js 与 static/modules/mindmap/mindmap.js 四份内容同步一致（MD5 同为 D835138561，53492B）；index.html 与 static/index.html 引用切换为 mindmap.ct2.js?v=20260921ct2。
  5. sw.js：CACHE_NAME 实测由 shuili-exam-v6-20260920-theme1 bump 为 shuili-exam-v6-20260921-ct2（保留移动慢链路治理 NET_WAIT 竞速逻辑，未删改）；PRECACHE 把 mindmap.ct.js 换为 mindmap.ct2.js，并新增 /static/lib/cost-tree.js、/static/data/cost-tree-seed.js、/static/pages/cost-tree.html 三条离线预缓存。独立页 cost-tree.html 保留（“↗新页”仍可开窗，供大屏/打印）。
- 文件：frontend/modules/mindmap/mindmap.ct.js（母本）、mindmap.ct2.js（首页实际加载）、mindmap.js（modules 与 static/modules 各一份，同步）；frontend/index.html、frontend/static/index.html；frontend/sw.js。数据库 mind_maps id=196 结构与内容未做永久性修改。
- 验证（Playwright 驱动系统 Edge、全新无缓存 context；信源=真实浏览器运行）：
  1. 水利案例→思维导图：出现造价树 tab 与绿色按钮；点 tab、点按钮均在系统内容区内嵌渲染（popup=0），系统侧栏/顶栏/模块导航完整保留；#mmCtHost 内 194 节点 / 96 可点 / 0 空口诀，徽标“已载入系统数据(v4)”；跳转/收起/保存/新页工具齐全；施工用电（高压线路损耗3%~5%、维修摊销0.04~0.05）、施工用水（K0.75~0.85、供水损耗6%~10%）、施工用风（×60min、循环冷却水0.007）卡片公式齐全；跳转底座无异常、收起后 open=0、返回节导图（28 行、树已卸载）正常。
  2. 切到一造管理：造价树 tab 与按钮均不出现；原节/章/科目导图功能不受影响。
  3. 保存闭环：contenteditable 改口诀→#ctDirty 红点显示、保存钮变红→保存 POST 200 且 version+1→API 读回含改动（用临时测试串完成了事实验证）；随后仅回滚该一个节点口诀为 seed 原值并再次保存，复核测试串 0 残留、该口诀==seed、194 节点 / 96 公式 / 0 空口诀不变。id=196 最终内容与 v4 完全一致（version 因两次测试保存递增至 v6，内容无损复原）。
  4. “↗新页”弹窗与独立页 /static/pages/cost-tree.html 均为 194 节点 / 96 可点 / 0 空口诀、徽标 v6、0 pageerror。
  5. 零破坏：tools/startup_verify.py = 26 PASS / 0 WARN / 0 FAIL（RAG 25941 块）；19 个系统模块逐个 Framework.load 全部 OK、巡游 0 pageerror；布局锁死 侧栏135px / 顶栏56px / 主色#1a73e8 不变；node --check（mindmap.ct2.js、sw.js）通过；四份模块副本 MD5 一致；ct2.js 与造价树三件套 HTTP 200。
  6. 内嵌效果截图：%TEMP%\ct_embed.png（系统外壳内的造价树 + 施工用电公式黄区/口诀绿区）。
- 已知限制：headless Edge 全新 context 下 navigator.serviceWorker registrations=0（该无头模式对 SW 注册的限制，非本次改动引入）；sw.js 静态内容（新缓存名 + 四条预缓存）已经 HTTP 取文与 node --check 校验，真实浏览器 SW 激活为既有机制（CACHE_NAME 已迭代多版）。
- 状态：✅ 完成。造价树已内嵌进系统（思维导图→选“一造水利案例”→“🌳 造价结构树”tab 或绿色按钮），独立页并存；口诀在线编辑入库与回滚已验证，库内容已复原。

### 2026-09-21 08:20 同步push bug修复+全链路验证+勘误表深化

- 模块：backend/api/v1/sync_unified.py、诊断报告
- 需求：自主逐项推进，不让用户反复点重启
- 实现：
  1. **自主提权重启后端**：Start-Process -Verb RunAs调restart_backend.ps1，UAC点一次即可，后续验证自动完成
  2. **sync push真bug定位修复**：push_changes里新笔记（客户端无id）的创建else嵌套在if nid内部，无id时整块跳过导致applied永远=0；flashcard同样问题。重构note/flashcard两个分支，无id时直接创建
  3. **同步全链路实测通过**：push新建笔记applied=1(DB id=15)、pull返回1303项(含12笔记)、register-device成功(device_id=1)、checkpoints=26
  4. **诊断报告勘误表深化**：#5同步从"属实"改"部分不实"（后端API可用，报告只看sync_records空就判没跑通）；#6 RAG标记已修26106块；新增#7 SM-2调度深度问题、#8刷题过滤缺失
  5. **测试数据已清理**（4条测试笔记+2条测试答题日志，qid16错题状态恢复）
- 文件：backend/api/v1/sync_unified.py、系统交付级诊断报告.md
- 状态：✅ 同步后端可用，待前端对接；临时调试脚本已删
- 验证标记：push applied=1、pull total=1303、version=200、刷题1004干净题、SM-2 iv递增正确

### 2026-09-21 08:40 17题选项缺失根因深化：7题PDF恢复+10题定性

- 模块：data、tools
- 需求：深化推进17题选项缺失根因，不满足于只标记
- 实现：
  1. **7道标准选择题从原PDF恢复选项**（PyMuPDF提取+人工核对边界）：3459资本金(9选项)/3462资金成本/3463优先股10.20%/3465债券6.32%/3471融资程序/5885银行贷款/5894零部件价值系数，取消is_outdated标记
  2. **修正2处错误答案**：3465原AE(无E选项且错误)→B(验算8%×0.75/0.95=6.32%)；3471原A→C(选择银行属融资谈判阶段)
  3. **10题定性为无法恢复**（3384-3393）：WM_15讲义知识点被错误拆成选择题，PDF无对应A-E选项、题面逻辑不成立，保留is_outdated并写明原因
  4. 干净题1004→1011，过时题45→38
- 文件：tools/_extract_options.py、_extract_7.py、_show_pdf.py、_restore_options.py
- 状态：✅ 7题已恢复并API验证；10题保持隔离
- 验证标记：id3463/3465/5894详情API选项正确，26 PASS全绿

### 2026-09-21 08:30 离线同步/移动端/备份实测销项+第八章清单全绿

- 模块：sync、frontend、backup
- 需求：对照诊断报告第八章差距清单逐项实测销项，不实论断标记
- 实现：
  1. **离线同步（#4/#5，报告"没跑通"严重不实）**：前端question-practice.js/flashcard.js答题/收藏/闪卡复习离线入队→/api/v1/sync/batch回放；实测幂等——同operation_id回放2次=首次落库/二次skipped"并发幂等"，答题日志仅+1条；唯一索引idx_sync_cp_user_op原子占位真实有效
  2. **移动端（#10，报告"基本PC布局"不实，勘误#9）**：PWA(manifest+sw.js 19KB)+mobile-shell.css(720px侧栏抽屉translateX+汉堡#mobileMenuBtn+遮罩+顶栏横滑+触控区加大)+mobile-adapter-framework.js(matchMedia1024判定)+104@media断点+174触摸事件+32刘海屏
  3. **自动备份（#7）**：auto_backup.py每小时备份db+modules（start.bat拉起）；手动backup_once新备份211.7MB完整；常驻进程已拉起PID12460
  4. 第八章10项差距：9项✅销项，仅#2 Tailscale需真机网络实测（非代码问题）
- 文件：系统交付级诊断报告.md（勘误#9+第八章销项表）
- 状态：✅ P0四项全部达成；RAG/同步去重P1达成
- 验证标记：batch幂等实测、备份211.7MB、前端代码链路审计；CDP设备模拟在托管浏览器不可用（session not found），移动端结论基于代码链路

### 2026-09-21 08:35 模拟考试闭环验证+诊断报告12项差距全部销项

- 模块：exam、系统
- 需求：P1#6模拟考试核心功能验证，完成诊断报告全部差距销项
- 实现：
  1. **模拟考试完整闭环实测**：GET /exam/config（2026科目配置：时长120分/总分100/及格60/单选60多选20）→GET /generate（20题带选项解析）→POST /submit（question_ids+user_answers）→评分20对19错1=95分is_passed=true→GET /detail详情，评分准确；测试exam_record与测试错题(id573)已清理
  2. **诊断报告第八章10项交付标准+P0/P1/P2共12项全部销项**：9项代码/功能已验证达成，仅#2 Tailscale需真机网络实测（非代码缺陷）
  3. 最终startup_verify：26 PASS/0 WARN/0 FAIL全绿
- 文件：系统交付级诊断报告.md（第八章销项表+P0/P1/P2逐项标注）
- 状态：✅ 诊断报告对照优化任务完成；后端PID10720存活、auto_backup PID12460常驻
- 遗留（非代码）：Tailscale真机访问需用户在手机实测；3459题9选项答案C存疑（PDF如此，未改）

### 2026-09-21 08:40 刷题口径复核+版本端点干净题统计修正

- 模块：qb、system
- 需求：复核学生刷题路径是否真正过滤问题题（小心求证，不满足于管理列表数字）
- 实现：
  1. **区分两个列表口径**：/api/qb/questions是题库管理列表（管理员视角，total=1080含全部，配defective筛选，设计正确）；学生刷题走/api/qb/random
  2. **实测学生抽题**：random连抽5批×50=250题，命中过时/重复题=0（69道问题题全部过滤），刷题路径正确
  3. **修正/version干净题统计**：原total-outdated-duplicate减法对"既过时又重复"的1题(id5761)重复扣减，显示1010；改为直接SQL统计=1011
  4. 后端真正重启加载（PID25476，首次重启UAC未生效已补做）
- 文件：backend/api/v1/system.py
- 状态：✅ 数据口径全部对齐 total1080=干净1011+过时38+重复32-重叠1；26 PASS全绿

### 2026-09-21 造价结构树补全至编规工程部分全口径（mind_maps id=196 v6→v7）
- 依据：系统资料库 course_materials 最新件《编制规定（水总〔2024〕323号·工程部分）》（252页，backend/uploads/3460a12c….pdf，09-19入库），全文提取8904行逐条核对；系统内无环保/水保单行本及移民规定。
- 纯增量30节点（194→224；末级150→172；公式/口诀96→126，0空口诀），未改动任何既有节点：
  1) 通用计价底座第8子「设备及安装工程费编制」+7叶：设备原价(主要设备≥3源均价)、运杂费(表4-6/4-7，5%~5.5%)、运输保险费、采购及保管费(原价+运杂)×0.7%、运杂综合费率=运杂+(1+运杂)×采保+保险、交通工具购置费(估算表6-2)、安装工程费两算法；
  2) 根新增「分年度投资与资金流量」：建安(工程预付10%~20%、完成30%起按20%~30%扣回；材料预付次年20%；保留金2.5%、年扣5%至完成50%止、次年100%偿还)、设备(主要设备表4-15到货比例；其他设备到货前15%+到货85%)、独立费用(施工图设计97%分年+3%设计保证金最后年)；
  3) 根新增「三阶段造价 概算/估算/匡算」：估算建安单价×扩大系数(表6-1)、安全监测估算费率(当地材料坝0.9~1.1%/混凝土闸泵1.1~1.3%/堤渠管线0.2~0.3%)、其他建筑=主体×3%~5%、交通工具表6-2、基本预备费(建议书15~18%/可研10~12%、可免资金流量)；匡算预备费18~20%、仅算至静态总投资；
  4) 枢纽主体末增「细部结构工程(表4-5综合指标，仅含基本直接费，另计其他直接/间接/利润/税金)」。
- 发布：frontend/data/cost-tree-seed.json 与 cost-tree-seed.js 同步(node --check过)；POST入库 id=196 v7；sw.js CACHE_NAME ct2→ct3 刷新离线预缓存。
- 实测(Playwright驱动系统Edge、全新无缓存context)：系统内嵌tab与独立页均224节点/126可点/0空口诀、徽标“已载入系统数据（v7）”；15+关键新增节点公式数字逐条命中、口诀齐全；0 pageerror；startup_verify 26 PASS/0 WARN/0 FAIL；布局135/56/#1a73e8未变。
- 边界：程序性内容(编制依据、概算文件组成与表格、投资对比、附录1~9)不进费用树；建设征地移民补偿、环境保护、水土保持仅在总投资层汇总(执行专项规定及323另两本单行本，系统暂无该两本PDF，未展开专项明细)。
### 2026-09-21 移动主线·局域网HTTPS直连为主（在家~6ms）+ Tailscale外网兜底
- 需求：电脑=本地服务器/资料中心；手机/平板在家同WiFi走局域网HTTPS直连（全量含视频缓存），局域网IP随时变动须自动适应；出门外网走 Tailscale cherry。
- 实现（不改桌面布局、不改 start.bat/watchdog、不改 localhost http 零缓存）：
  1) 新增 backend/modules/common/lan_gateway.py：根CA首次生成（backend/data/certs/rootCA.crt，10年；rootCA.key 仅本地、不入库）；叶子证书按“本机当前全部局域网IP+Tailscale IP+固定DNS”动态签发（800天）；守护线程监听 0.0.0.0:8443 做 TLS 终止并透明 TCP 中继到 127.0.0.1:8000；每60s枚举本机IP，集合变化即用同一根CA重签并对同一 SSLContext load_cert_chain 热加载（监听不重启、旧连接不断）。
  2) backend/main.py 四处接线：import；启动时 start_lan_gateway()（异常自隔离，不影响主服务）；新增 GET /api/common/lan-addrs（实时返回当前https入口）与 /api/common/lan-ca（根证书下载）；缓存中间件 is_mobile_client 增加 :8443 判定（移动客户端 immutable）。
  3) 新增 frontend/connect.html（/static/connect.html，独立连接向导页，不进导航、不动布局）：同源拉 lan-addrs，以 no-cors 竞速探测各局域网 https 入口（绕开CORS；未装证书即失败并提示），自动选最快；提供根证书下载与鸿蒙安装指引、进入高速版/外网版。
- 前端无需改：index.html 离线总闸按 protocol==='https' 注册SW，局域网 https 天然启用；offline-media-prefetch 链路门控在局域网测到 ~6ms/高吞吐判 fast→全量缓存含视频，cherry 中继慢→仅题库+教材PDF。
- 电脑侧验证：8443 已在主进程内监听 0.0.0.0；TLSv1.3 握手、根CA信任链、IP SAN(192.168.0.203/100.81.103.0)、/api/health、lan-addrs、lan-ca、connect.html 经8443均200；防火墙按程序放行 D:\Python311\python.exe，8443 同进程自动入站放行；startup_verify 26 PASS/0WARN/0FAIL。git 基线 ef0d1f0、落地 225dd38。
- 真机步骤：在家平板/手机浏览器开 http://<电脑IP>:8000/static/connect.html（IP变了也可由外网 cherry 的同名向导页自动发现）→下载根证书并在 设置-安全-加密与凭据-从存储设备安装-CA证书 信任→回向导“重新检测”→进入高速版 https://<电脑IP>:8443 →添加到主屏幕；飞行模式验离线做题/教材，WLAN下视频自动缓存；外网用 https://cherry.tail6f7c9a.ts.net。
- 双origin分工：局域网origin=全量(含视频)在家高速；cherry origin=题库+教材外网应急；做题记录经同一后端按设备/用户合并。

### 2026-09-21 09:20 题库报错20条全闭环：质量缺陷隔离机制+后台三态治理+闪卡朗读销项

- 模块：qb、question-manager、tts、system
- 需求：144专家履职任务②——闭环用户在刷题中提交的20条 recognition_errors；任务③闪卡朗读无声修复。铁律：报错快照是历史，question_id 指向的当前题可能已被重新导入（id复用），一律以 DB 当前内容为准重新判定，禁止按快照直接改。
- 数据治理（先备份 backend/data/shuili_exam.db.bak_20260921_errors，单事务+断言，失败整体回滚）：
  1. questions 新增两列 `is_defective INTEGER DEFAULT 0`、`defect_reason TEXT`（区别于 is_outdated/is_duplicate：识别错位/缺图/选项损坏语义）。
  2. **修复6题（报错7条 fixed）**：3824/3863 题干去页眉“第X页共Y页”；5909 选项C去“学员专用 请勿外泄 第27页共34页”水印并重建options；5006 解析截断剥离混入的下一道“6.某企业借款2000万”；5747 据解析补 option_d=通用合同条款/option_e=供货要求、重建5项、题型单选→多选（答案BDE）；5824 答案 C(合同价格)→D(结算价格)（解析明确结算文件承包单位编制、发包单位审查）。
  3. **隔离12题（报错13条 confirmed，可逆不删）**：3385选项仅占位符、5007现金流量图选项识别成B./D.、5024净现值图缺图、5587选项C截断且缺D(已清洗C)、5758变更五情形选项缺失错位、3579选项D串入前锋线案例(已清空并截断解析)、3688功能成本图缺图题文错乱(已截断混入真题)、3609现金流量图缺图选项变金额(题干已剥离混入解析)、5827/5821/5828/5826 四题题干与选项完全错位（总投资构成配成本预测法、单件性配角度值、造价配成本分析法、静态投资配折旧法且答案空）。
  4. 结果：recognition_errors 无 pending（fixed=7/confirmed=13）；练习池口径(删0/过时0/重复0/缺陷0)=1001；缺陷隔离12。
- 后端（py_compile 通过，已重启 PID25484）：
  - models/models.py：Question 类(L24-55)补映射 is_outdated/outdated_reason/is_duplicate/is_defective/defect_reason（原 ORM 漏映射前三个质量列；勿再加到 KnowledgePoint）。
  - modules/qb/service.py：_query_questions 加 include_defective，练习/随机/统计默认排除过时+重复+缺陷，后台模式仅过滤删除；get_chapter_tree/generate_exam/get_knowledge_points 静态条件加缺陷过滤；get_question_list 加 defective=all/0/1 三态并在 service 层正确分页；update_question field_map 支持 is_defective/defect_reason（后台移出隔离，归一0/1）。
  - modules/qb/routes.py：GET /questions 加 defective 参数；mastery-analysis 掌握度统计加缺陷过滤。
  - api/v1/question.py：旧随机真题端点 /question/random_real（新刷题 question-practice.js 实际在用）补 is_outdated/is_duplicate/is_defective 三重过滤——这是坏题漏入刷题的关键通道。
  - utils/knowledge_base_answer.py：两处 RAG 取题加质量过滤，避免坏题进 AI 答案。
- 前端（node vm.Script 校验通过）：
  - modules/manager/question-manager.js：列表请求带 defective；行内对缺陷题显示红色“缺陷”徽标（hover 显示 defect_reason）；工具栏新增“全部质量/正常题/缺陷隔离”筛选（服务端筛选）；缺陷题操作列加“移出隔离”按钮（PUT 清 is_defective，可逆恢复）；map 保留 option_a..e/analysis/q_type 顺带修复导出CSV缺选项。修复了恢复按钮 data-id 因单引号字符串内 ${q.id} 不插值的 bug（改内嵌反引号模板）。
  - index.html：question-manager 指纹 → ?v=20260921defect2。
- 任务③闪卡朗读（统一销项）：frontend/js/tts-service.js 完整重写（手势激活+MP3进度看门狗+可靠浏览器中文语音降级+onEnd必达，API签名不变新增unlock()），index.html 指纹 ?v=20260921tts；根因=浏览器自动播放策略+旧降级链在 voices 未加载时永久卡死；后端 /api/v1/tts/speak 实测200返回MP3，bu 实测降级链与点击朗读正常。
- 实测（实际运行优先）：random_real 连抽10轮×50=累计398不同题，命中缺陷=0；/api/qb/random 0缺陷；后台三态 total all=1080 / 0=1068 / 1=12（含同时过时的3385）；修复题详情 5824=D、5747=5选项多选、3824无页眉；PUT 移出隔离往返(置0→置1)PASS；bu 清SW缓存后缺陷隔离视图12行/12徽标/12恢复按钮、正常题1031、点恢复 5828 后12→11（已HTTP还原回12）；startup_verify 27 PASS/0 WARN/0 FAIL；latest_report 45 warning 均为既有架构类中长期项、本轮无新增类别。
- 遗留：12道隔离题待回原始 PDF 按“题目区域坐标分割后逐块识别”重导（不删数据，移出隔离即可恢复）；前端其他模块对缺陷标记的展示非必须（出题入口已全部过滤）。


---

## 2026-09-21 09:50　任务③b 思维导图题目杂质治理 + 软删链路修复（完成销项）

**背景**：章/科目导图由节导图动态聚合（前端 `_mountAgg` 只聚合 with_answers 答案版，符合铁律），但节级答案版导图本身混入大量例题题干、A.-E.选项、【解析】、广告、例题数据表、设问句；另有两条完全重复且题目堆砌的科目汇总脏导图 id=191/193（md5 相同 5b850e3da318，133409字符，含 QQ/VX 广告）。

**数据治理（mind_maps 表，已备份 backend/data/mind_maps_backup_20260921.json，55行原始md）**：
- 新增节导图清洗器 `_mindmap_clean2.py`（块级状态机）：删广告、A.-E.选项（兼容 `- C.` 列表与一行多项）、【例题/例/真题/解析/解/单选/多选】开启的题目-解析块、空括号题干、编号题干（含以？结尾）、`#### ……？` 设问标题、例题数据表格（年份/净现金流量/方案甲乙丙丁/寿命期/净现值万元/净年值数字/BEP计算结果）；`- ★` 知识点锚点与真标题退出删除块。
- 两轮单事务清洗：首轮更新 34 条、二次（增强设问句/编号问句规则后）更新 10 条；每条断言清洗前后 `- ★` 知识点锚点数只增不减（全部守恒，如 id54 15→15、id38 17→17），content_md 更新并 version+1、重算 content_hash、update_time；content_json 保留（前端 markmap 实时渲染 content_md，不读 json）。
- 量化结果：广告/选项/例题解析标记/编号题干/答案版空括号/设问问号全部=0；id54 由 16675B 降到 6840B；科目聚合 ★118 个知识点完整。
- 软删重复脏汇总 id=191/193（置 deleted_at，可逆；前端章/科目不依赖，仅"我的导图"残留）。

**后端修复（软删链路原本失效 + 一个 500）**：
- 根因：ORM `MindMap` 模型（models.py L285）落后于表结构，**未映射 deleted_at 列**，任何 `MindMap.deleted_at.is_(None)` 都抛 AttributeError 致列表 500。已补 `deleted_at = Column(DateTime, nullable=True)`。
- `api/v1/mindmap.py` 列表、`crud/crud.py` get_mindmap_list/get_mindmap_by_id、`modules/mm/service.py` 两处列表/统计查询统一补 `deleted_at IS NULL`；软删导图不再出现在列表/详情/计数。修复后列表 127→59 条，一造管理"我的导图"不再出现 191/193 及历史软删汇总（105/183-188 等）。
- 均 py_compile 通过，随后端重启（新 PID）生效。

**前端实测（bu，清 SW 缓存、走用户路径）**：
- 节导图：点 4.2，答案版 ★15、问题版 ★9，广告/例题/选项=0，SVG 正常渲染，节点编辑入口（data-which=question/answer）保留。
- 章导图：下拉含 6 章、默认第1章；切第4章聚合 4.1-4.4 四节、★23（=6+15+2+0 各节之和）、杂质=0。
- 科目导图：无下拉直接显示，6 章聚合 ★118、广告/例题/选项/问号=0。
- 我的导图（一造管理）：无重复脏汇总。

**验证**：tools/startup_verify.py = 27 PASS / 0 WARN / 0 FAIL。

**遗留（非题目杂质，另案）**：①个别节导图末尾存在"知识点文字版"重复段与 OCR 公式碎片标题（#### AX / t e），属重复/排版问题，未激进删除防误伤；②point_id 脏数据（24/25、38/39、62/63 复用 aad885fa3746、74/75 与 91/92 为 NULL）待按章节树校正；③离线静态 mindmaps.json 仍含旧 md（在线优先不影响，待重新导出）。


---

## 2026-09-21 10:40　任务④ 学习资料库双通道（后端数据通道 + 视频模块前端，完成销项）

**目标（用户原话）**：本地电脑即本地部署服务器，资料「直接读取文件」与「上传」两个通道；外部培训资料 `F:\2 学习相关资料\2 考试类学习资料\考试类学习资料\一造培训资料` 只登记不复制，**绝不擅动 F 盘原文件**。视频模块铁律：选择一个文件夹，左侧显示该文件夹视频、右侧显示对应讲义文件夹；讲义来源由「02.精题必练(14)」改为「01.精讲班-蒋.莉莉(50)」。

**后端（新增，全部真实 HTTP 实测）**：
- 新增 `backend/modules/common/external_library_service.py`：配置 `backend/data/external_library.json`（enabled+roots，默认外部培训资料根）；ALLOWED_EXT 视频/文档/HTML；quick_hash 大文件仅 size+头尾64KB（不全量读视频）；`scan_external_library` 按绝对 file_path upsert、metadata_json 存 {source:external,root_idx,rel,dir,class_dir,lecture_dir,video_dir}，外部删除软删、重现恢复；`get_folder_tree/list_folder_files/list_external_files/resolve_safe`（realpath 必须落在 FILE_LIBRARY_DIR 或外部根，越权返回 None）。
- `file_library_service.py`：auto_classify 增加视频扩展名硬判（修复 269 个 .flv 被误判讲义）。
- `file_library_routes.py`（prefix `/api/v1/fl`）新增：POST `/external/scan`、GET `/folders`、GET `/folder_files?dir=&kind=video|doc|all`、GET `/external_files?kind=video|doc|all&subject=`（扁平一次拉取）、GET `/external/config`、GET/HEAD `/stream/{id}[/{name}]`（Range 206，仿 main.py serve_video_with_range，flv→video/x-flv、mp4→video/mp4、ts/mkv 映射）、GET `/download/{id}[/{name}]`（resolve_safe 越权校验 403，Content-Disposition=inline 便于浏览器内联打开 PDF）。
- 实跑扫描：**scanned=1080 / added=1080 / removed=0 / errors=0**（视频501、讲义487、html其他48、题库36、教材5、大纲3），80 目录、35 个含视频文件夹、6 班次；未复制任何物理文件。配对规则=视频在「班次/XX.班次名/」，讲义在其下「讲义/」子目录；精讲班 50 视频 ↔ 讲义 50（文件名一一配对，如 `01.【变】第1章第1节….flv` ↔ `WM_01.【变】第1章第1节….pdf`）。
- HTTP 实测：/folders 200（6班次35视频夹）；精讲班 folder_files video=50、讲义 doc=50；stream Range bytes=0-1023 → **206 + content-range bytes 0-1023/276878665 + video/x-flv**，seek 到 100MB 同样 206；mp4 → video/mp4；讲义 download 200 application/pdf inline；resolve_safe 对 C:\Windows\System32\drivers\etc\hosts 返回 None、对外部视频放行。

**前端视频模块 `frontend/modules/video/video.js`（只换数据源与关联，不改布局/CSS；node --check 通过；指纹 → ?v=20260921ext2）**：
- 数据源由旧 `/video/list`、`/lecture/list`（uploads 旧表）切到外部库 `/api/v1/fl/external_files?kind=video|doc`；视频 url 走 `/fl/stream/{id}/{文件名}`（URL 带扩展名，播放器原生/flv.js 内核判断不变），讲义 url 走 `/fl/download/{id}/{文件名}`。
- 文件夹对文件夹：视频 folder=完整 dir（唯一，区分环球/蒋莉莉同名精讲班），讲义 folder=讲义 dir；`_corrLecFolder` 优先取当前视频文件夹记录的 lecture_dir；下拉/列表标签经 `_folderLabel` 显示为「班次 / 文件夹」；默认精确选中「2025-一造管理 蒋.莉莉/01.精讲班-蒋.莉莉」。
- 修复旧代码遗留悬空功能：`_renderHandoutBar/_refreshHandoutBar` 与 `.video-handout-bar` CSS 早存在但播放页从未挂载 `#videoHandoutBar` 容器，已在播放器卡片内底部补齐（不增栅格、不动上下左右主布局），当前视频按讲次序号关联并显示单份讲义 chip。
- bu 实测（清 SW、走用户路径）：videos=501 / lectures=487 / folders=35；默认精讲班左 50 视频、右 50 讲义；切环球精讲班 50/50、蒋莉莉精题必练 14/15、回精讲班 50/50；点第 1 讲视频原生解码成功（readyState=4、1280 宽、时长 4021s、无 error、Range 206）；播放条与右列讲义链接均指向外部库 PDF（inline）。

**验证**：tools/startup_verify.py = 27 PASS / 0 WARN / 0 FAIL。

**进行中（未销项，勿判完成）**：学习资料库 `file-library.js` 的「本地资料库」只读视图（班次/文件夹树浏览外部 1080 文件、视频 stream、文档 download、与上传通道并列）尚未接入；外部记录虽已计入 `/fl/list`（total 1581=旧501+外部1080，字段名 files），但现有两列渲染对外部视频/讲义的分类与分页（page_size=1000<1581）需单独处理，方案是新增独立只读 tab，避免污染上传库逻辑。


---

## 2026-09-21 10:55　任务④前端·资料库「本地资料库」只读视图（完成销项，双通道成型）

**改动 `frontend/modules/library/file-library.js`（纯增量，不动上传库现有 tab/布局/逻辑；node --check 通过；指纹 → ?v=20260921local2）**：
- 新增第 4 个 tab「💻 本地资料库」，数据走 `/api/v1/fl/external_files?kind=all`（一次拉全外部元数据，纯前端建树，切换零延迟），与既有「全部/视频/大纲教材」上传通道并列，实现用户要求的「直接读取 + 上传」双通道。
- 视图为「班次(class_dir) → 文件夹(dir)」两级折叠树（复用 expandedFolders，键加 LOCAL:: 前缀隔离）；视频文件链接 `/fl/stream/{id}/{name}`、文档/讲义/教材链接 `/fl/download/{id}/{name}`（inline，PDF 浏览器内联打开）；文件名、类型徽标、大小真实展示；只读，不提供删除/改名/打标签，杜绝对 F 盘原文件与登记数据的误操作。
- 顶部说明条明确「只读·直接读取本机文件，不上传不复制不移动」；提供文件名搜索（防抖，搜索时自动展开命中班次/文件夹并显示「匹配 N 个」）与「重新扫描」按钮（POST /external/scan 后重载，幂等）。
- afterRender 并行触发 `_loadLocal()`，失败不阻塞上传库；flv/ts/mkv 项 title 提示「建议在视频讲义模块播放」。

**bu 实测（清 SW、走用户路径，无 error 级 console）**：本地 tab 列出 7 个班次分组（李想128/张莉149/蒋莉莉297/干货19/2026案例304/环球169/未分类14，合计1080）；展开「2025-一造管理 蒋.莉莉」24 文件夹；01.精讲班视频夹 50 条全 stream（id842 起）、讲义夹 50 条全 download（WM_01→id892，与视频一一配对）；搜「工程造价基本内容」自动展开命中 6 条（3 视频 stream + 3 讲义 download，跨班次配对正确）。

**任务④整体状态**：后端数据通道 + 视频模块文件夹对文件夹 + 资料库双通道前端，全部完成并实测；全程未移动/复制/删除 F 盘任何原文件（只登记 file_path 与元数据）。


---

## 2026-09-21 11:10　任务③补：闪卡朗读端到端实测 + 磨耳朵三段内容修正（完成销项）

- bu 实测闪卡朗读链路：window.TtsService 完整（speak/stop/队列/口音/unlock）；练习页 🔊正面/背面/全部/随机 真实点击均发起 `GET /api/v1/tts/speak`（200，audio/mpeg，MP3 帧头 fff3，可播放），无 console error；tts-service.js 为「后端 MP3 播放 + 2.8s 进度看门狗 + play 无进度/onerror 自动降级浏览器中文语音 + 手势 unlock」多重兜底，确认发声问题已修复。
- 修正磨耳朵内容铁律（用户≥5 遍：知识点+答案+口诀）：flashcard.js 朗读专练 playCurrent 的「口诀模式(mnemonic)」原先有口诀时**只读口诀、漏掉知识点与答案**，已改为与 both 一致按 `知识点(front) + 答案(back) + 口诀(mnemonic)` 播报（无口诀则知识点+答案）；knowledge 模式保留为用户可选的「知识点+答案」。
- bu 实测（朗读记忆专练 tab，默认 mode=both）：播报文本=「联合体承包是什么？。联合体各方均应具备…承担连带责任。联合体共同投，连带责任要承担…」，面板知识点/答案/口诀三行齐全；577 张卡带口诀。
- 指纹：flashcard.js → ?v=20260921fc1；node --check 通过。


---

## 变更记录（2026-09-21 13:30）学习资料库物理迁移 + 三 tab 融合

### 一、培训资料物理迁移（只留一份，不重复存储）
- 源：`F:\2 学习相关资料\2 考试类学习资料\考试类学习资料\一造培训资料`（1080 文件/86 目录/约 84–90GB，与项目同在 F 盘）。
- 目标：`F:\水利智学系统\学习资料库\一造培训资料`（与“可运行版”并列，避免程序更新误删）。
- 方式：同卷 `os.rename` 整目录原子重命名，1080→1080 文件、0.0s、不产生副本、不占额外空间；源目录已清空不存在。
- DB：迁移前一致备份 `backend/data/shuili_exam.db.bak_premigrate_20260921_132655`；UPDATE 1080 条外部记录 file_path/metadata_json 根前缀；软删（is_deleted=1，不物理删）484 条历史死链；回滚清单 `backend/data/migration_library_20260921_132655.json`。
- 配置：`backend/data/external_library.json` roots 改为新路径；POST `/external/scan` 重扫 added=0（后端动态读 config，路径即生效）。
- 迁移后 fl_file_library 存活 1097 条（外部 1080 + 内部真实文件 17）：视频 501 / 讲义 487 / 教材 5 / 大纲 3 / 题库 36 / 其他。
- 安全红线：DELETE `/api/v1/fl/{id}` 调 `delete_file(delete_physical=False)`，只软删登记，绝不 os.remove 原始资料。

### 二、资料库三 tab 融合（撤销独立“本地资料库”tab）
- 三个 tab「全部 / 🎬视频 / 📖大纲教材」统一为本地学习资料库单一数据源 `/api/v1/fl/list?page_size=5000`（一次拉全 1097），删除原 `/video/list` 双源与独立“💻 本地资料库”tab 入口/渲染分支/事件。
- 后端 `file_library_service.list_files` DTO 增补 `ext/source/class_dir/dir`（批量原生 SQL 取 metadata_json，不改 ORM；已提权重启生效）。
- 前端 `file-library.js`：视频按 file_type=视频 或视频扩展名短路归类、走 `/fl/stream/{id}/{name}`（支持拖进度）；文档走 `/fl/download/{id}/{name}`；新增 `_folderOf()` 用 class_dir+班次末级目录分组，剥离“讲义/视频”通用层，环球与蒋莉莉同名“精讲班”不再合并（实测 35 个班次文件夹，蒋莉莉精讲班 50 视频）。
- 指纹：file-library.js `?v=20260921merge1`。

### 三、实测（bu 端到端，清 SW/caches 后）
- tab 恰 3 个：全部(1097) / 视频(501) / 大纲教材(8)，无本地资料库 tab。
- 全部页两列：文档资料(596) + 视频(501)；视频 501、文档=全部非视频 596。
- 大纲教材展开 8 个真实文件（大纲 3 + 教材 5）。
- 点击：视频 id=842 → stream/842/….flv；大纲 id=511 → download/511/….pdf。
- console 0 error。


---

## 变更记录（2026-09-21 14:10）资料库/视频接口全面审计 + 接口硬化

### 一、只读接口审计（脚本 `_api_audit.py` 真实 HTTP 调用，31 项）
结果 28 PASS / 3 WARN / 1（测试方法误判，已澄清）。覆盖：
- `/fl/list`：分页结构、page1/2 不重叠、超范围页返回空、拉全 1097、新 DTO 字段（ext/source/class_dir/dir）、API 总数=DB 存活数 1097、软删 490 条不出现。
- `/fl/external_files`：all=1080（=DB 外部数）、video=501、doc=579。
- `/fl/folders`、`/fl/folder_files`：蒋莉莉精讲视频 50、配对讲义 50；缺 dir=400；不存在 dir=空；`../../` 穿越 total=0（只匹配 DB 字段不读盘，安全）。
- `/fl/external/config`：roots 已指向 `F:\水利智学系统\学习资料库\一造培训资料`，无旧 F 盘根。
- `/fl/stats`：total 1097，视频 501/讲义 487/教材 5/大纲 3/其他 65。
- `/fl/stream/842`：Range 0-1023→206、Content-Range/Accept-Ranges/Content-Length 正确；无 Range→200 总长 276878665；不存在 id→404；mp4→video/mp4。
- `/fl/download/892`：200、application/pdf、inline、1107126 字节；带全角 name 尾段 200；不存在 id **GET**→404（HEAD→405，download 仅注册 GET，前端用 GET，非缺陷）。
- 限流：连发 20 次无 429（QPS10 不影响正常操作）。
- `/external/scan` 幂等：added=0、skipped=1080、耗时 6.2s。

### 二、已修复（本轮）
1. **flv(fMP4) 类型校正**：stream 对 .flv/octet-stream 读文件头 12 字节，魔数 `ftyp` 判为 fMP4→返回 `video/mp4`（真 FLV 头仍 video/x-flv）。实测 id=842 由 video/x-flv 变为 video/mp4，兼容性更好。
2. **非法 kind 显式 400**：`/external_files`、`/folder_files` 的 kind 非 all/video/doc 时返回 400（原静默当 all）。
3. **外部记录识别硬化**：list_folder_files/get_folder_tree/list_external_files/scan 软删同步 4 处，metadata_json 的 source 匹配同时兼容带空格 `%"source": "external"%` 与紧凑 `%"source":"external"%` 两种 JSON 序列化。
- 均 py_compile 通过、已提权重启生效；复测 video=501、folder_files=50 不变。
- 基线 startup_verify：27 PASS / 0 WARN / 0 FAIL。

### 三、已知次要项（不影响使用，留档）
- download 路由仅注册 GET（无 HEAD），HEAD 探测返回 405；前端只用 GET，GET 行为正确。
- stream 的 Range 大区间（如 open-ended `bytes=0-`）会一次性读入内存再发 206；本地单用户、正常播放器按小分片请求，影响小；后续可改 StreamingResponse 分块。
- download 在候选路径全失效时会回退“全目录递归+逐文件 MD5”，仅文件丢失时触发，正常命中候选 1（绝对路径）不触发。
- folder_files/external_files 为全表取出后 Python 过滤（1080 条，单次毫秒级），数据量未来大增可改为 SQL 过滤。


---

## 变更记录（2026-09-21 14:40）资料库/视频接口 3 个次要项优化

### 1. download 支持 HEAD
`file_library_routes.py` 两个下载路由由 `@router.get` 改为 `@router.api_route(methods=["GET","HEAD"])`。
实测：HEAD `/fl/download/892` → 200、Content-Length=1107126、无 body；不存在 id HEAD → 404。

### 2. stream Range 流式化 + 正确 suffix range（恒定内存）
`fl_stream` 的 Range 分支重写：
- 正确解析 suffix range `bytes=-N`（最后 N 字节，start=size-N）；
- GET 改用 `StreamingResponse`，按 1MB 块从文件 seek 后分块 yield，open-ended 大区间（如 `bytes=0-`）不再整段读入内存（原实现会把 276MB 全读进内存）；
- HEAD 请求只回 206 响应头、不打开/不读取文件体；
- 多区间（含逗号）回退整文件；无 Range 仍走 FileResponse（系统 sendfile，本就流式）。
实测：bytes=0-1023→206/1024；bytes=-1024→206 Content-Range bytes 276877641-276878664/276878665；bytes=100-199→206/100；HEAD bytes=0-→206、CL=276878665、body=0。

### 3. 文件夹/文件列表 SQL 下推
`external_library_service.py` 新增 `_external_cond()/_video_cond()/_dir_cond()`，重写
`list_folder_files`、`list_external_files`：kind(video/doc)、subject、dir 全部下推到 SQL
（dir 用 metadata_json 闭合引号精确匹配并转义 LIKE 通配符，兼容带空格/紧凑两种 JSON）。
`get_folder_tree`/scan 为全量聚合与同步，业务上本就需要全量外部行，保持不变。
实测口径与旧 Python 过滤完全一致：external_files all=1080/video=501/doc=579；
蒋莉莉精讲 video=50、配对讲义 doc=50；视频目录直属 doc=0（不串子目录）；不存在 dir=空；kind 非法仍 400。
IPv4 直连真实耗时：folder_files 26-46ms、external_files 56-95ms。

### 性能澄清：脚本测得的“每请求 2 秒”是 localhost 解析，不是后端
用 Python urllib/浏览器之外的脚本压测时，所有端点（含健康检查、静态首页、HEAD 无 body）首次连接都固定 ~2.07s。
经 keep-alive 对照定位：同一连接首请求 ~2.07s、其后 8-10ms；改用 127.0.0.1 时新建连接也仅 8-31ms。
根因是 Windows 上 `localhost` 先解析到 IPv6 `::1`，而后端仅监听 IPv4，首连接等待 ~2s 超时后回退 IPv4；
连接复用或直接用 127.0.0.1 即毫秒级。后端无任何每请求 sleep、SQL 无性能问题；浏览器对 localhost 有快速路径，用户实际使用不受影响。
（脚本密集连发超过 QPS10 会收到 429，属正常限流。）

- 均 py_compile 通过、已提权重启生效；基线 tools/startup_verify.py 复测见当日结果（应保持全绿）。

### 2026-09-21 记忆闪卡无意义卡梳理与软删除（两轮共117张，723→606）
- 真源 flash_cards 表（删除=is_deleted=1软删可恢复）；deprecated_flash_cards(933)为废弃旧表、前端不读，未动。
- 判定原则：闪卡=单点记忆钩子（一个数字/公式/口诀/清单/易混点，可快速主动回忆），不是所有“是什么”问答、整段讲义、整道例题都入卡。
- 第一轮（水利考点速记批 id313-445，讲义机械抽取）：空壳(back=【答案待补充】)49 + 截断劈词/算式表格碎片/答非所问40 = 89张。
- 第二轮（适配性复筛）：标题复读空壳5(#469-473)、AI套话1(#480)、选择题“正确选项”解析碎片9(#474-479/#481-483)、残缺重复7(#446/447/451/454/456/463/566)、被覆盖的空泛概念5(#12/190/455/461/464)、水利重复长卡1(#358，公式已在#340) = 28张（管理27/水利1）。
- 结果：活跃723→606（一造管理589→562、一造水利案例133→43、一造计价1）；库内is_deleted=1累计119（含历史2）。
- 明确不删：review_count=0(94%新卡未复习)、管理文科要点清单卡、标题+完整答案速记卡；水利例题长卡#315/#332/#335含独有公式，建议“去例题精简”而非删，待用户定。
- 备份与清单：闪卡梳理_20260921/ 下两份全字段JSON（89张、28张）+删/留清单CSV+梳理报告md；回滚 UPDATE flash_cards SET is_deleted=0 WHERE id IN(...)。
- 验证：API /flashcard/stats=全部606/水利43/管理562/计价1；list全量606张坏卡关键词0、强归一化front重复0；Playwright(Edge)记忆闪卡模块0 pageerror、布局未变、离线库缓存完成。

### 2026-09-21 识别拆分精度治本（进攻侧）：题答分离讲义顺序切分器 + 存量真题救回
- 需求：不满足于“挡脏题”，从 PDF→题目 的识别拆分管线本身根治漏题/错位，让今后不再产生碎片脏题，并救回存量真题。
- 根因（PyMuPDF 回原文求证，非凭文档推断）：
  1) 《精题必练》讲义“题目在前、答案解析集中在后”，且【习题N】在每个【知识点】内都从 1 重置（题号非全局唯一）；
  2) 旧 fused 解析器（pdf_parser.parse_pdf_questions_fused）用 _fuse_qno_key 按题号归桶、同号择优只留一个 → 同号习题被合并，**大量漏题**（第10讲17题只切出5题、第9讲35题只切8题、第11讲26题只切10题）；
  3) backfill_answer/options/_build_qno_blocks 按题号 n 建 map，同号习题后者覆盖前者 → **答案/选项跨知识点错位**（价值工程多选真实答案ACDE被配成B、融资租赁成本率答案A被配成DE、动态指标答案D被配成ACE）。
- 治本实现（不动 fused——它对题号全局连续的真题整卷准确）：
  1) 新增 backend/utils/handout_sequence_parser.py“题答分离讲义顺序切分器”：定位答案区起点（首个【习题N】…【答案】）；题目区按【习题N】**出现顺序逐一切块（同号不去重）**，块内按字母标签归类切 A-J 选项（容忍 PDF 物理乱序 A C B D）、清洗页眉页脚营销水印；答案区按顺序取【答案】【解析】；以“习题号重置序列”校验做**同序对齐**（题目区第 i 题↔答案区第 i 个答案，号不符宁可不填）；题型按选项数/答案字母数判定。
  2) question_pipeline.py：新增 extract_pdf_fulltext_raw（保留【习题N】【知识点】【答案】原始标记）；choice 分支在“顺序切分题数 ≥ fused+3”时优先采用顺序切分（自带对齐答案，跳过会错位的 supplement/backfill/repair），否则回退 fused；真题整卷/题答紧邻卷 parse_handout_qa 返回 None，**抽查12份真题透析卷误用0**。
  3) 边界分类处理：F-J 非标多选题（讲义偶见6-10选项，正式考试多选固定A-E、前端/判分仅支持A-E）经最终质控**明确剔除并计数**，不产无法作答的死题、不静默截断，完整选项存 options JSON 的逻辑保留备查；判断题（A.√ B.×）识别为 judge、选项规范为“正确/错误”、√×答案转 A/B；选项为配图的图表题（现金流量图/网络图）文字层无解，判0选项剔除。
- 效果（离线全15讲 + 端到端）：第1讲9/2讲12/3讲14/4讲15/5讲20/6讲20/7讲19/8讲22/9讲32/10讲17/11讲23/12讲26/13讲23/14讲27 题，答案零空缺、零碎片；F-J非标题与图表题干净剔除并日志计数。
- 存量治理（备份 backups/auto/20260921_1404_识别治本前/ 213MB 后执行）：
  * **修复恢复8道独有真题进可用池**（UPDATE原id，保留做题记录，重算content_hash）：3466融资租赁成本率(单选答A=11.25%)、5294融资租赁特点(多选ABE补回B)、5306经济评价原则(BCE补回C)、5687质量保修书(B补回B/C)、5693价格干预(A补回C/D)、5740造价师执业(ACD补回C/D)、5758工程变更(BCD补回C/D)、5946公益捐赠扣除(A，补回A/B，源自file_499第45题)；
  * 3454/3538 正确版已由经典300题 id5037/5013 干净在库，本两条旧错位副本改标 is_duplicate=1 + duplicate_of 指向干净版；
  * 5007现金流量图/5940网络图选项为配图，标 is_defective=1 并在 defect_reason 写明“需视觉识别或人工补图”（VL识别器虽在、qwen3-vl:4b可用，但系统仅支持文字选项，图形选项无法落库，属能力边界非识别精度问题）。
- 进代码的标准/回归：
  * 新增 backend/tests/regression/reg_handout_sequence.py（8项断言：第10讲17题+价值工程ACDE、第11讲融资租赁A且≥20题、第9讲动态指标D、F-J全剔除、判断题识别、12份真题卷误用0），PASS；
  * 更新 reg_choice_quality_gate.py 隔离口径：被质控剔题 is_outdated/is_duplicate/is_defective 任一=1 即算已隔离（均不进刷题池），全库1038选择题漏网0，PASS；
  * reg_pdf_choice_pipeline 端到端176题零碎片，PASS；tools/startup_verify.py 27 PASS/0/0（含“可用题库结构残缺题0”）。
- 数据口径（is_deleted=0，共1080）：干净999（治本前991，+8）；过时/残缺40；重复34；缺陷12。学生 /api/qb/all 全量池=999，8道修复题全部在池且选项完整、4道隔离题无一误入。
- 后端已提权重启加载新代码（2026-09-21 14:03 PID29236，health=200，manual_restart ok=True）。
- 已知边界（非本次代码缺陷）：F-J非标多选练习题不入库（前端仅A-E）；图形选项题待系统支持图片选项或人工替换为文字题；出错原 WM_15组织1.pdf 已不在库无法原文件回归。

### 2026-09-21 识别拆分精度治本（收口）：蒋莉莉讲义全量补录 + 跨源去重 + 第二套讲义版式 + 一键回归
- 承上条（顺序切分器已接入、8道真题救回，干净999）。本批把治本成果落到全量存量与第二套讲义版式，并把“对比销项”固化进可运行回归。
- 一、蒋莉莉2025《精题必练》全量补录141道（顺序切分器新切约279道标准题）：
  * 14讲（第13讲有"(1)"重复文件只取一份）逐讲 parse_pdf_questions_unified 顺序切分，按题干前24字归一指纹与干净池对账，走标准导入通道 import_parsed_questions（content_hash 去重 + DataQualityPipeline 质控）；
  * 先在 DB 副本 DRY（142拟补→141成功/1哈希跳过/0失败/答案选项章节0空缺）后正式补录141道（新id约5955-6095，source="学习资料库:WM_第N讲….pdf"，chapter取库内每讲众数并清洗）；补录前后完整题干重复组均15，零新增重复。干净999→1140。
- 二、跨源完整题干重复去重14组（备份后单条UPDATE，可逆）：
  * 干净池15组完整题干指纹重复，逐组人工核对答案/选项/问法粒度，14组安全去重（12组答案一致；3259/5824 同题选项排列不同但答案实质都指“结算价”；5834答案空保留有答案的3307），保留解析更全/有答案条，另条 is_duplicate=1 + duplicate_of；
  * **3479/3824 经核实不是重复题**（题干前缀撞车，但选项内容与问法粒度“实施策划”vs“实施过程策划”不同），列入 reg_stem_duplicate 白名单；顺手修正3479（option_e 黏了下题【习题4】题干已截断、q_type 单选→多选答BD）。去重后干净1140→1126。
- 三、案例识别回归 fid 软删映射修复：reg_case_pipeline 5项FAIL根因是样本fid(163/176/183/322/287)在 fl_file_library 已 is_deleted=1（重新导入后旧id软删、物理文件仍在磁盘），活跃同名记录为649/521/517/1112/1363（_get_file_path 第4步 os.walk 按 filename 兜底可取）；更新回归fid后 ALL_ASSERTIONS_PASS。
- 四、第二套讲义版式治本——《2026 环球精题必练-蒋丽丽》13讲（库中原0题，从未导入，不污染现题库）：
  * 版式与蒋莉莉2025不同：题目 `数字.【单选/多选】题干` **全局连续编号1..N（不重置）**、答案区 `数字.【答案】XX【解析】`，无【习题N】；旧 coord/old/fl_bridge 切30题但**答案0对齐**。
  * handout_sequence_parser.py 新增 `parse_numbered_handout`（NUM_Q_MARK/NUM_A_MARK 强题型标记，答案区起点=首个`数字.【答案】`，题/答按编号同序对齐并核对题号、缺号退回同序，题型直接取【单选/多选】标签，复用 _split_options 容忍物理乱序、F-J非标照旧标记交质控剔除）；question_pipeline.py choice 分支在 parse_handout_qa 返回None时回退 numbered，采用条件改为“题数≥fused+3（漏题）**或** 题数相当(≥0.9)且答案完整率高≥0.3（答案错位/缺失）”双条件。
  * 离线13讲：切412题、答案零空缺、F-J非标32道；unified 端到端质控后377题、零无答案/零缺选项；真题透析(80/76题)与经典300题 numbered 误用0（题答紧邻卷 q_zone 内题目标记<4 自然返回None）。
  * 标准通道补录：377经指纹/哈希双重去重（与真题/300题/蒋莉莉讲义重叠）后158独有，成功155/哈希跳过3/0失败/零空缺；chapter 由文件名“第X章…第Y节…”映射，source="学习资料库:WM_0X.2026一造管理精题必练….pdf"。**干净1126→1281，总题(is_deleted=0)1376**。资料库在线识别（fl_bridge→unified）对活跃file_id=1567 由“30题答案0”变为“25题答案25/25”。
- 五、对比销项进代码 / 一键回归本地化：
  * 新增 reg_numbered_handout.py（13讲切分/答案零空缺/题1 ABE/题2 A=2800/题5 B=2650/题6 F-J剔除/unified零碎片/真题不误用，ALL_ASSERTIONS_PASS）；新增 reg_stem_duplicate.py（干净池完整题干指纹重复门，白名单{3479,3824}）；
  * run_all.py 由 import 式改为 **subprocess 逐个子进程**运行（兼容无 main 的脚本式回归、单测崩溃不连坐、按 returncode 记账、超时保护），需 file_id 参数的工具脚本 reg_file_recognize 显式 SKIP；修复 reg_handout_jingti 查询未过滤 is_deleted 取到软删430（改取活跃1567）。
  * 结果：**一键 runner 12 PASS / 0 FAIL / 0 ERROR / 1 SKIP**；startup_verify 27 PASS/0/0（题库全口径2978、可用池结构残缺0）；学生 /api/qb/all=1281、选择题 option_a 空缺0、隔离题无一误入。
- 数据口径（is_deleted=0，共1376）：干净1281、重复48、过时40、缺陷12；选择题(非案例)1334、质控剔除14、漏网0。备份：backups/auto/20260921_讲义补录前、20260921_跨源去重前(脚本内在线快照)、20260921_精题2026补录前(223.5MB)。
- 后端已提权重启加载两套顺序切分器（2026-09-21 15:08 PID29008/watchdog PID11608，health=200，manual_restart ok=True）。
- 已知边界（非识别精度代码缺陷）：F-J非标多选练习题不入库（前端/判分仅A-E）；图形选项题(现金流量图/网络图)需系统支持图片选项或人工改写为文字题，现 is_defective 隔离；Tailscale外网仍需真机网络实测；3459题9选项标准答案C存疑（PDF如此）。

### 2026-09-21 移动连接内核融入系统（替代独立向导）+ APK/原生壳桥接统筹
- 新增 frontend/connect-kernel.js（?v=20260921ck1，纳入 sw.js 预缓存，CACHE_NAME 升 ck4）：仅 https 移动瘦客户端运行；电脑 http 端直接 return。电脑侧实测：window.connectKernel=undefined、#linkModeChip 为空且 display:none/高度0（零占位）、控制台零报错，桌面布局零影响。
- 选路策略：cherry.tail6f7c9a.ts.net 为固定总入口（外网/Tailscale 中继，只缓存题库+教材PDF）；在家同一 WiFi 经同源 /api/common/lan-addrs 自动发现电脑当前局域网 IP（绝不写死、IP 变动自适应），no-cors 两次实测 RTT≤60ms 且证书受信才认定在家，一键或授权后自动切到 https://<电脑IP>:8443（全量缓存含视频）；底部状态栏 #linkModeChip 显示 lan绿/relay橙/offline灰 与缓存范围；cherry 上发现高速口弹 #ckSwitchBanner（默认手动、可开自动、防循环防误跳）。
- APK 统筹（前向兼容）：内核预留 window.__SHUILI_NATIVE__ 桥接（getServerInfo 返回 lanIp/httpsPort/link/rtt/certTrusted，onLinkChanged 订阅链路变化）；未来卓易通 APK / 鸿蒙 hap 的 WebView 壳注入该对象即可零改动复用选路/缓存/同步内核，壳侧负责内置 backend/data/certs/rootCA.crt 与更强的 UDP/mDNS 局域网发现；浏览器无桥接时自动回退纯 Web 发现。
- 接线：index.html 引入内核；modules/layout/statusbar.js 增加空挂载 span（:empty 不占位）与三色徽标样式；sw.js 预缓存清单加内核并 bump CACHE_NAME 至 shuili-exam-v6-20260921-ck4。
- 决策依据：Tailscale P2P 在当前对称NAT/无UPnP/无中国DERP 下长期 DERP(sfo) 369ms~3.15s（手机平板均是、重登前台无效），不作在家主力；局域网直连实测 3~6ms，8443 自签（10年根CA、叶子随IP自动同根重签）升为在家主路径，cherry 官方证书域名作固定总入口与外网兜底。
- 待真机验收（离线只认 HarmonyOS 真机飞行模式）：8443 无证书警告且地址栏加锁、添加到桌面(PWA)、视频 Range 拖动与 PDF 翻页、底部缓存进度（PDF→WLAN视频）、飞行模式离线题库秒回、cherry 在家出现“切换到高速版”、联网后做题记录双向同步。
### 2026-09-21 题库质量大清理（144维体检落地）：废题/重复/年份污染清零，真题归位
- 背景：用户指出原始 PDF 无 2017 真题、闪卡应服务记忆增强。对 questions 全量跑多维确定性规则＋逐类人工复核（避免冤判）。
- 关键定性：**系统里从来没有 2017 真题**，是字段误识别——题干法规版本年（2017/2012/2007 年版招标文件）、金额数字（2000 万元）、教辅书名年（2026 精题必练）、讲义被 AI 加【2022】前缀，被当成了考题年份。
- 软删 184（is_deleted=1，删前全字段 JSON 备份、事务内按 rowcount 断言、提交回读，事后逐 ID 核查无一被离线同步恢复）：P0 练习/讲义废题 90（选项"[选项缺失]"/AI 编造"选ADE是因为"/案例空壳/讲义残句/OCR 串题）＋真题多文件重复 64（2021 两份真题透析、真题透析 vs 考后解析，每组保留答案解析最全 1 题，1 组保留者残缺跳过故 64 非 65）＋水利案例壳挂 ABCDE 错配 8（4791/4793/4795/4802/4803/4804/4805/4808）＋P2 真题重复/选项错位残缺 7（5349/6003/6012/3688/5007/5844/5940，其中 2025 网络图 5940 选项只剩 3/6 待真题 PDF 重导）＋经典300题题干与选项错行 14＋融资租赁坏题 3466。
- 字段修正（不删）：276 题次练习/讲义 year→"模拟题"（现存 252，24 题随后删除）；type 按 q_type 对齐 137 题为 single/multiple/case；3454/5893 反向纠正为多选；答案订正 3465=A（债券资金成本率≈5.05%）、3471=C；真题补全 5614=B、5941、5930（清选项 C 页码）；清理选项串页码＋补解析 6109、6111。
- 终态（is_deleted=0）**1193＝真题 362（2020:52/2021:82/2022:56/2023:57/2024:41/2025:74）＋模拟 831**；科目 管理1186/计价6/水利案例1（仅 5819 待补全）。8 类问题（选项缺失/案例空壳/AI编造/串页码/选择题答案空/single多答案/年份污染/真题重复）SQL 全量复检**全为 0**。勾稽：库内 2978＝活跃 1193＋已删 1785（历史1601＋本轮184）。
- 三层验证：①SQL 复检 8 类全 0、删除无一恢复；②API /question/filters 的 years=['2025','2024','2023','2022','2021','2020'] 无 2017/2026，/question/list year=2017 与 2026 均 total=0、2021=82、水利案例=1；③Edge/Playwright 实测章节刷题六章题量正常、真题年份筛选干净、开始真题单题练习进入作答（2023 真题 A–E 选项完整），0 前端报错、0 个 5xx。
- 发现的前端既有问题（**未改，待授权**，遵守布局锁死）：真题页 frontend/modules/question/question-practice.js L1088-1097 把"真题总数320/已练128/正确率68%"硬编码占位（实际真题 362），建议接实时统计；CommonUtils 首次加载偶发 "Unexpected identifier"，真题作答未复现、不阻断；离线同步 15:47 批量写 461 行 questions（本轮删除未被冲掉，长期需关注多端同步对 is_deleted 的合并策略）。
- 待办：水利案例 2019–2025 真题**需用户提供 PDF** 后按"背景＋多小问＋完整计算过程"大题导入（不能凭空生成），并补全 5819；图形题回 PDF 补图（保留 3569/4985/6005、重导 5940）；经典300剩余约 200 道答案非空题做"题干主题 vs 选项主题"一致性专项；闪卡每日新卡/复习上限、5 张超长卡(315/335/332/351/493)精简、水利计算卡补强（待授权）。
- 备份与回滚：`题库质检_20260921/备份/` 6 个全字段 JSON（P0删154、P1年份276、水利8、答案修正3、P2修复10、经典300错位与修复16）；回滚 `UPDATE questions SET is_deleted=0,deleted_at=NULL WHERE id IN(...)`（原值取备份）；逐题清单《本轮题库清理总清单.csv》(443条)、终版《题库清理终版报告_20260921.md》、复检/实测脚本 recheck.py、summary.py、api_test.py、ui_*.py，截图 实测_*.png。本轮未改任何前端/后端代码。


### 2026-09-21 题干配图链路打通（识别→入库→显示端到端）+ options 列治本
- 结论（用户拍板，已锁死）：**选项不可能有图，图只出现在题干**；题干配图显示最终定稿为「题干文字正常全宽排版，图表在题干下方**水平居中**，点击可放大」，不做左右两列、不做文字环绕；窄屏（手机/平板）图占满题干宽度、上文下图。
- 断点求证（PyMuPDF/代码/DB 实查，非凭文档）：配图提取器 backend/utils/question_figure.py（attach_question_figures，按“题号→选项A 槽位”坐标裁图、射线法去页眉页脚、位图/矢量表格识别、跨页拼接、PDF 内容 md5 命名 v2_*.png 缓存）原本只在 pdf_parser.parse_pdf_questions_fused 末尾调用，而主识别/入库走的 parse_pdf_questions_unified 不调用 → 库中 title 含 q-figure 的题为 0（物理图已有 82 张却没挂题）。
- 后端治本：question_pipeline.py 选择题分支最终质控后、compute_missing_qnos 前接入 attach_question_figures，**仅 fused 路径**（fused 的 qno 是 PDF 原连续题号可按号定位；顺序切分器 qno 为同序重排号、【习题N】会重置，按号会错配，故不接）；try/except 包裹，配图失败不影响文字题；无图题自动跳过不产空图。
- 存量同源回填（图必须取自题自身源 PDF，禁止跨年指纹匹配——同题干不同年份图中数字可能不同）：备份后为 6 道在池真题补题干图/表——id3620(2021q36 贷款利率表)、5364(2021q45 零部件功能指数表)、5420(2022q22 组织机构图)、5523(2023q47 功能评价值表)、5714(2025q34 价值工程系数表)、5704(2025q23 双代号网络图)。其中 **5704 网络图题选项 B=4/C=5 曾被图吞（仅 A=3/D=6）且被软删，补全为 A.3 B.4 C.5 D.6（答B=4条关键线路）并恢复 is_deleted=0**；其残缺副本 id5940 转 is_duplicate=1 + duplicate_of=5704（解除过时/缺陷标记）。id5716 经重解析确认是纯文字计算题（长期借款/债券资本成本）本就无图，不补；图选项题 id5007（4 个选项本身是现金流量图）按“选项无图”规则永久 is_defective 隔离。补图题均重算 content_hash。
- options 缓存列治本（配图实测时发现的整类隐患）：questions.options(JSON 数组) 与 option_a..e 字段在 28 道在池题不一致——2 题数组少项（4893 少1、5673 少1，做题会缺选项）、其余为历史导入留空。根因是 crud.create_question 直接落 data、批量识别入库（import_parsed_questions）只传 option_a..e 不传 options。已在 **crud.create_question 加兜底：未显式传 options 但有选项字段时自动按 option_a..e 构建一致 JSON 数组**（已传则不覆盖，dict 格式特殊题不动），覆盖今后所有入库路径；存量 28 题一次性重建（备份 backups/auto/20260921_options列重建前）。15 题 options 为 dict 的特殊题（3459 九选项等，PDF 原文如此）保持，前端按 option_a..e 重建显示。
- 前端安全渲染与显示（frontend/core/common-utils.js）：新增 CommonUtils.safeStemHtml（题干进 innerHTML 前默认全转义，仅白名单放行后端受控 `<div class="q-figure"><img src="/uploads/question_images/[A-Za-z0-9_-]+.png" class="q-img">`，外链 img/script/onerror 一律转义，实测 XSS 全部拦截）、stripStemText（朗读/复制用纯文本，图替换为【配图】，避免读出 URL）、initFigureLightbox（全局事件委托，只认受控配图，点击全屏放大、点遮罩关闭）。css/components.css 新增 .q-figure/.q-img 水平居中样式（PC 图 max-width:min(100%,620px) 居中、移动端全宽）与灯箱样式；题干为内联 span 时 :has(.q-figure) 转块级。刷题 question-practice、模考 mock-exam、错题 wrong-book（列表+复习弹窗+CSV 导出纯文本）、收藏 collect 四个学生端题干全部改走 safeStemHtml；题库管理复核弹窗沿用其原有 safeStem 白名单。index.html 相关 js/css 版本统一 bump 至 v20260921fig3（破移动端 immutable 缓存）。
- 验证：①reg_question_figures.py 增强为硬门禁（unified 主管线 2025 真题必须自动配图 2 张 23/34、题数 80、答案 80、配图 URL 命中白名单，否则非零退出）；②一键回归 run_all **12 PASS / 0 FAIL / 0 ERROR / 1 SKIP**；crud 改动后 reg_case_storage/reg_choice_quality_gate 仍 PASS；③浏览器实测（http://127.0.0.1:8000）：网络图/组织机构图/表格图题干下方水平居中、5704 选项 3/4/5/6 完整、答题后解析栏出现布局正常、灯箱放大清晰可关、safeStemHtml 对 script/外链 img/onerror 全部转义、注入窄屏样式验证上文下图全宽；④学生 /api/qb/all 带图 6 道、配图 URL 全部命中白名单、5704 options=['3','4','5','6']。
- 备份：backups/auto/20260921_题干配图回填前(223.8MB)、20260921_options列重建前(223.8MB)。后端已提权重启加载管线+crud（2026-09-21 16:23 PID32120，health=200，manual_restart ok=True）。本轮临时补丁/探查脚本已全部清理（tools/ 无 _*.py 残留），正式能力沉淀在 question_pipeline.py / crud.py / common-utils.js / components.css / reg_question_figures.py。

---

## 变更记录（2026-09-21 17:10）功能实现假象 / 前后端不匹配 / 顶栏靠右 / 配色 / 统一弹窗 / 控制台清零

- 模块：layout-topbar、app_v3、theme、system-admin、common-utils、offline-cache、video、dashboard、_api_audit
- 需求（144专家专项）：排查“功能实现假象”——配色隐形未生效、隐形未实现、前后端不匹配；番茄钟及其右侧图标无法靠右。
- 实现：
  1. **顶栏图标真正贴右**：根因是 framework 外壳 `<header class=topbar>` 有 padding，而顶栏模块注入的 `.real-topbar` 仅 flex:0 0 auto、宽约 883px 不铺满，右组 margin-left:auto 推不到视口右缘。改 `#framework-topbar.topbar{padding:0}` + `.real-topbar{flex:1 1 auto;width:100%;min-width:0;padding:0 20px 0 12px}`，硬编码色改 CSS 变量，8 个工具按钮（番茄/课表/music/计算器/help/pwa/theme/color）统一 emit `topbar:tool-clicked`。指纹 topbar.js=20260921dock1。
  2. **工具弹窗靠右持久化 + 705 处重复 class 合并**：番茄/课表/计算器每次 setPomodoroMode/toggle/reset 都 remove 重建弹窗，丢掉首次补的 tool-dock-right，一操作就弹回居中；改为弹窗 className 默认带 tool-dock-right。同时用正则把 app_v3 全文件 **705 处同一标签重复 class 属性**合并（浏览器只认第一个 class，第二个被丢弃，致大量 s-style/g-style 样式隐形失效）。指纹 app_v3=20260921dock1。
  3. **配色止血 + 孤岛接入**：本机 localStorage 历史 `currentColorScheme=森林绿(#52b788)` 是全系统发绿根因（代码默认仍是水利蓝 #1a73e8），且大量模块把品牌蓝硬编码在 `<style>`，切色不跟随造成绿蓝混搭。theme.js 把 light/default/green/purple 一次性归一 blue（colorSchemeMigrated=v2_blue）、切色后 dispatch `app:color-scheme-changed`（20260921color1）。系统管理中心是独立页 system-admin.html（CSS/JS 全内联、不加载 tokens、原 Material 蓝 #1e88e5 系），head 注入 tokens.css、品牌色归一 var(--color-primary*)。紫/多彩仅保留在有意的分类/装饰/AI/等级场景。
  4. **统一弹窗组件**：common-utils 新增 `confirmAsync/alertAsync`（单例、回车/Esc/点遮罩、textContent 防 XSS）+ 全局 alert 垫片（重写 window.alert→toast 语义分级，不重写 confirm）；**13 处裸 confirm 全部 await 化**（含生产实际加载的 mindmap.ct2.js——index.html 加载的是 ct2 而非 mindmap.js，初次只改 mindmap.js 无效）。确定钮 #4a6cf7 归一 var(--color-primary)。指纹 20260921ui1。
  5. **控制台清零**：offline-data-cache/offline-media-cache 的离线开关 `__ZHIXUE_OFFLINE__===true` 在本机 http 恒 false、DB 恒 null，但 resource.js/app_v3 仍调用走到 reject“数据库未初始化”刷红；改为开关关闭时 syncAllData/getCacheStats/clearAllCache 安静短路返回零值（throw 保留在真正 init 处）。删除 flv.min.js/MindElixir.min.js 失效 sourceMappingURL（index.html flv 加 ?v=20260921nomap）。指纹 offline 两文件=20260921off2。
  6. **功能假象①（死代码，记录不删）**：app_v3 三处“开发中/暂未开放”（startMemoryTraining L21497、adjustStudyPlan L26395、exportDedupReport/mergeDuplicateGroup L26925-34）经 grep + migration-plan 规律18/ISSUE_016 核实为**不可达死代码**——按钮只存在于新框架不再渲染的旧整页模板，startMemoryTraining 首行已委托 commonModule。
  7. **功能假象②（视频网站资源，已修成真功能）**：video.js“网站资源”tab 原在 state 与 _renderWeb 两处硬编码 3 条伪造 B 站占位视频（BV1xx411c7mD 等），且添加/删除按钮经精确 grep 证实零事件绑定。已去假数据改空态、接通添加/回车/删除（删除走统一确认框）、localStorage(zhixue_web_videos)持久化、_buildEmbed 真实解析 B站(/video/BV、av号)/YouTube/优酷/直链，短链与非法链接有提示，插值经 esc() 转义。遵守该文件 LAYOUT_LOCK 只改数据/空态/事件不动布局。指纹 video.js=20260921web1。
  8. **前后端不匹配（核心实锤，看板资料统计长期全 0）**：dashboard `_loadRealData` 调 `/api/v1/fl/list` 却取 `docData.data`（真实字段 **files**）、调 `/api/v1/video/list` 却取 `videoData.data`（真实字段 **list**），两者恒空 → resourceStats 常年全 0；且“讲义”按 tag 分类，但讲义文件 tags 无“讲义”（权威口径是 file_type=讲义，实测 205 条）。重构为**单次 /fl/list**：教材/讲义/视频按 file_type 权威分类、真题/模拟按 tags，视频统一资料库来源、弃用旧 /uploads /video/list 第二数据源（符合“视频/大纲教材来源统一本地资料库、不重复”）。指纹 dashboard.js=20260921dash4。
  9. **审计脚本纠错**：_api_audit.py 原用 **HEAD** 探测仅注册 GET 的 /api/v1/video/list 得 405 误报 WARN（GET 实测 200、返回 {total,list}，被看板旧逻辑/离线预取合法使用）；改用 GET + j() 解析、校验 list 字段判 PASS。
- 验证（信源=实际运行；bu 注销 SW+caches、带新 ?_z 干净重载）：
  - 首页 + video/flashcard/file-library/mindmap/question/wrong-book/note/knowledge/sprint/memory 十模块 console **0 error**（仅剩 2 条以 ✅ 开头被关键词误判的正常 info）。
  - 顶栏 8 工具按钮 typeof 全 function、24 模块全注册、右组贴视口右缘 gap=8；番茄弹窗打开/切模式/重置后始终靠右。
  - 系统管理中心 header 渐变实测 rgb(26,115,232)→rgb(21,87,176)，且仍接真实 /api/supervisor（78需求/5模型/2备份、30秒自动刷新，非假数据）。
  - 网站资源全流程：空态 0 item/引导文案 → 添加 bilibili BV1ux411d7bh → iframe src=player.bilibili.com?bvid 正确、刷新后持久 → 删除统一确认框后清空；非法/短链有提示。
  - 看板 resourceStats 实测 `{教材2,讲义205,真题54,模拟2,视频230,总481}`，与 `/fl/list?subject=一造管理` file_type/tags 分布完全一致；external_files 字段 list、fl/list 字段 files 的前端解析（normalizeVideos/normalizeFlFiles）核对正确。
  - **_api_audit.py = 32 PASS / 0 WARN / 0 FAIL；tools/startup_verify.py = 27 PASS / 0 WARN / 0 FAIL。**
- 备份：各文件 `.bak_toolalign/.bak_color/.bak_confirm/.bak_async/.bak_quiet/.bak_web/.bak_fields/.bak_stats2/.bak_nomap_<时间戳>`；工作脚本 _patch_*.py/_fix_audit*.py 留根目录（锚点 assert 已命中，勿整体重跑）。
- 遗留（需用户拍板，属布局不擅动）：
  - **看板 resourceStats 数据已算真实，但 render 第一行只有 5 卡（倒计时/累计答题/正确率/待复习错题/连续学习），资料统计没有任何卡片引用它**——资料卡挂在哪个位置是布局决策，按“布局锁死”待用户确认后再挂（数据层已就绪）。
  - 模块 `<style>` 硬编码 #1a73e8 全量 var() 化、echarts（question-practice）运行时 getComputedStyle 读变量并监听 app:color-scheme-changed 重绘，为低优先余留。
  - external/scan 本轮 removed=1（教材 5→4，疑 1 个物理文件缺失被软删），未深查具体文件。
- 状态：✅ 实现 1–9 全部经 bu/脚本实测；看板资料卡“挂载位置”待布局确认（非功能缺陷，数据已真实）。


## 变更记录（2026-09-21 20:40）资料统计落资料库 + 视频真实标签保留
- 需求：用户拍板“资料统计放资料库”（学习看板不新增第6卡，看板维持原5卡，守布局锁）。
- 实现（frontend/modules/library/file-library.js）：render() 在 fl-tabs 之下、内容区之上新增紧凑统计带 `_statsBarHtml()`，数据由 `_computeStats()` 直接从已加载的 state.allFiles 聚合（不新增请求；loading 中不渲染、不闪0），口径=全部/视频/讲义/教材/大纲/真题/模拟题/题库；配色用 var(--color-primary)，flex-wrap 自适应、不产生横向滚动。
- 顺带修复一处数据假象：normalizeFlFiles 视频分支原把 tags 写死为 ['视频']，丢弃了数据库里视频记录自带的业务标签（真题解析视频30条、模拟题视频7条），导致按标签统计偏少（前端真题24/模拟7 vs 后端54/14）。改为保留 DB 原始 tags 并补入“视频”后去重；视频仍 type='video' 走独立视频列、不参与文档自动打标，不串文档列，标签筛选反而更准。
- 实测（信源=实际运行）：后端 /api/v1/fl/list?page_size=5000 全量 1096，file_type={视频501,讲义487,教材4,大纲3,题库36,其他65}；tags 真题54(讲义5+视频30+题库19)、模拟题14(其他2+视频7+题库5)。bu 实测统计带8项与后端逐项一致；无横向滚动(scrollWidth=clientWidth=1141)；/fl/list 200；本次加载 console 0 error；node --check rc=0。
- 指纹：index.html file-library.js 20260921ui1 → 20260921stat2；frontend/static 影子副本已同步(md5一致)；备份 file-library.js.bak_stats_*、.bak_vidtags_*。
- 未做/边界：dashboard 未加卡（遵用户决定，其 resourceStats 数据层保留无害）；知识库 RAG 0 embedding、Ollama 未启动为独立长期项，本轮未触碰。

### 2026-09-21 我的收藏页数据链路修复（真机验证配图时连带发现并治本）
- 发现（不是凭文档，是真机走收藏链路暴露）：模块化内核下「我的收藏」页永远显示“共 0 题/暂无收藏题目”，即使后端已收藏。根因是 frontend/modules/collect/collect.js 的 _loadRealFavorites 与后端响应契约三处错位：①判 `data.code===0`（v1 接口 `/api/v1/question/collect/list` 返回裸 `{total,list}` 无 code，包装接口 code=200，永不等于 0）；②取 `data.data.items`（实际是裸 `list` 或 `data.list`）；③字段取 `item.content`（题目在 `item.title`），且题型 q_type(single/multi)、options（后端字符串数组 vs 卡片视图按 {label,text} 对象渲染）未归一 → 永远走本地空兜底。
- 治本：重写 _loadRealFavorites，兼容裸 `{total,list}` 与包装 `{code,data:{list|items|questions}}`（code 200/0/无 code 均视为成功，明确失败才本地兜底），字段统一归一（title 同时映射 content、q_type→单选/多选、options→`[{label:'A',text}]`、year/subject/answer/analysis）；表格行题干改 `safeStemHtml(stripStemText(...))` 纯文本单行截断（配图显示“【配图】”，不在表格行渲染小图）；卡片搜索视图沿用 safeStemHtml 显示配图，并在 components.css 补 `.collect-card:has(.q-figure)` 适配（含图卡片头部转纵向、题干解除 nowrap/overflow、图 max 560 居中不溢出；无图卡保持原紧凑横排）。
- 收藏幂等治本：真机测试发现同一题被收藏 2 次——modules/qb/service.py 的 add_collect 用 `INSERT OR IGNORE`，但 question_collects 表只有 question_id、user_id 单列索引、**无 (user_id,question_id) 唯一约束**，IGNORE 不生效。双保险治本：service.add_collect 插入前先 SELECT 查重（已收藏直接返回 dedup，不依赖索引）+ 建唯一索引 `uq_question_collects_user_q(user_id,question_id)`；存量按 (user,question) 去重。
- 同类排查：错题本 wrong-book.js 契约正确（`json.data||json` + `payload.list/total` 分页 + _mapWrong 归一），无此 bug；模考题目同源题库对象、题干已走 safeStemHtml。
- 验证：真机收藏 5704→收藏页表格正常列出（科目一造管理/单选/2025/题干纯文本截断带【配图】/答案 B），卡片视图网络图水平居中、选项 A.3/B.4(正确绿)/C.5/D.6 完整；幂等 POST 两次 list 仅 1 条、DELETE 后归 0；本轮测试收藏数据与 localStorage question_favorites 残留已清零（恢复用户原状 0 收藏）；一键回归仍 **12 PASS/0 FAIL/1 SKIP**。

### 2026-09-21 21:40 章节归属治本（诊断报告问题1深化）+ q_type 物理值统一
- 模块：api/v1/question（chapter_tree）、modules/qb/service、utils/chapter_ref（新增）、数据治理、tests/regression
- 发现（复刻后端匹配规则 + 真机实测，不凭报告）：学生章节刷题前端 `_matchChapterIds/_parseChapter` 本就按章节**编号**正确过滤；真正缺陷在后端 `/api/v1/question/chapter_tree` 题数统计用"章节标题与题目 chapter 文本互相包含"匹配——题库节名与教材 TOC 措辞不一致即漏计（复刻其规则实测挂接率仅 **75.7%**、217 题挂不上，含大量"第4章第1节 资金的时间价值"这类规范题）、一题被多标题**重复计数 197**、章级只数到 chapter 恰好含章名的题，导致"树显示题数 ≠ 点进去刷题数"。
- 治本：
  1. 新增 `backend/utils/chapter_ref.py` 为章节编号解析**单一真源**，1:1 移植前端 `_parseChapter/_legacyChapterByName/nameMap`（8 条分支 + 老版 7~14 章按节名重映射 1~6 章 + 跨节归章 + 超纲拦截）；
  2. `api/v1/question.py` chapter_tree 计数改**编号确定性归属**：节=精确该节题、章=该章全部节及章级题、`total_questions` 只合计章级（消除章+节重复求和）、新增 `unclassified_count`、按学生可练池口径（排除过时/重复/缺陷）；
  3. `modules/qb/service.py` `_query_questions` 章节筛选由 `chapter LIKE '%x%'` 改为 Python 侧编号归属（消除 `LIKE '%4%'` 跨章串题、纯数字"4"/"4工程经济"漏题），仅纯文本节名退回 LIKE 兜底；模考按章组卷同源受益；
  4. 4 道无编号可归题回填标准章节：id5422→第3章第1节（施工组织设计/总平面/三区），id5820/5822/5823→第1章第1节（工程造价含义、多次性计价特征）；
  5. q_type 物理值按 `core/standards/question_norm.py` 的 QTYPE_ALIASES 全库统一为英文标准码 single/multiple/case（更新 2672 行；在池 single866/multiple326/case1），后端读时兼容中英文逻辑保留、中文显示走 q_type_label；
  6. 新增回归 `tests/regression/reg_chapter_ref.py`：34 条黄金样本 + 调 Node 执行前端**真实源码**逐例对拍（防双端规则漂移）+ 真实题库挂接率 ≥99% 门禁；两个精题必练讲义回归在外部 PDF 未随交付包提供时按既有惯例 SKIP（资料在位时断言完整执行，不弱化）。
- 验证：学生可练池 1124 题章节编号挂接率 **100%**（未归属 0）；章节树一造管理 1121 题章计数 {1:96,2:170,3:207,4:245,5:189,6:214} 与前端 `_matchChapterIds`、后端 `_query_questions` **三方逐项一致、0 不符、0 串章**；真机勾选第 4 章=245、节 4.1=48、节 4.2=71；一键回归 **13 PASS / 0 FAIL / 0 ERROR / 1 SKIP（共14项）**；后端提权重启 health=ok。备份 `backups/auto/20260921_章节兜底前`、`backups/auto/20260921_qtype统一前`。
- 数据整洁度边界：DB 物理 chapter 文本保留多种书写，编号归一已使树计数/按章刷题/模考/笔记结果正确一致，不做高风险的全量章节文本改写；格式问题由编号解析兜底、挂接率回归持续兜底。
- 状态：✅
版本 collect.js?v=v20260921fig2、components.css?v=v20260921fig4；后端已重启 health=200。


---

## 变更记录（2026-09-22 任务A：闪卡朗读文本预处理底座 voice-text-parser）

### 需求
按认知科学引擎方案 P0-1，为现场朗读主链路与 AI 克隆辅助支线提供统一文本预处理：四类 token 标记（数字时限/造价术语/易混对比/公式）、84 条水利造价发音词典、Markdown/HTML/公式符号清洗、停顿「｜」标记、视觉辨识样式、遮蔽复述一键清色、总开关。

### 实现（纯前端底座，无后端改动）
1. **新建 frontend/js/core/voice-text-parser.js**（约 380 行）：
   - `PRONUNCIATION_DICT` 84 条：基本预备费/价差预备费/静态投资/动态投资/台时费/围堰/DAAB/CM/EPC 等，含 pinyin 与 confusable 标记
   - `parse(rawText, opts)` → { tokens, spokenText, displayHtml, pauseMarks }
   - `splitByTerms` 按术语长度倒序优先匹配长词
   - `splitByNumberFormula` 识别 18-20%/E=ΣFₙ/0.80~0.85 等数字与公式
   - `symbolToSpoken` 公式符号朗读转写（×→乘、Σ→求和、²→平方等）
   - `enterRecallMode(container)` / `exitRecallMode(container)`：遮蔽模式加 .vt-recalling class
   - `checkPronunciation(tokens, spokenText)`：现场朗读读音校验，术语/数字漏读告警
2. **CSS（components.css 末尾追加）**：
   - .vt-number 加粗 / .vt-confusable 蓝 / code.vt-formula 等宽 / .vt-wrong 橙 / .vt-pause 浅灰
   - .vt-recalling 下所有颜色重置为黑、停顿标记 display:none
   - body.voice-visual-off 总开关纯黑白兜底
3. **index.html ×2（main + static）**：在 tts-service.js 后插入 `<script src="/static/core/voice-text-parser.js?v=20260922va1">`

### 验证
- `node --check voice-text-parser.js` 通过
- Node 单测 9/9 PASS（6 个样卡：基本预备费费率/价差预备费公式/易混成对/单位数字/口诀/旧称对比；遮蔽模式清色 OK；总开关纯黑白 OK；读音校验漏读识别 OK）
- 关键样卡实测：
  - "基本预备费费率：匡算18-20%" → 基本预备费=confusable_term 蓝、18/20%=number 加粗、逗号后 0.3s 停顿
  - "E=ΣFₙ[(1+P)^n−1]" → code.vt-formula 等宽块
  - "静态投资与动态投资" → 两个都标 confusable_term 蓝
- `tools/startup_verify.py` = 27 PASS / 0 WARN / 0 FAIL

### 备份
- index.html.bak_va1_20260922（main + static 各一份）
- components.css.bak_va1_20260922

### 未做/边界
- 84 条词条为 P0 核心，后续按用户反馈补到 200 条
- 视觉样式尚未接入 flashcard 业务页面（任务 B 接入后才在卡片上生效）
- 停顿「｜」当前仅在 displayHtml 渲染，AI 合成时的静音注入在任务 D
- 读音词典暂为视觉标记+前端校验用，后端 TTS 读音 SSML 注入在任务 D

### 状态
✅ 任务 A 完成，等待任务 B（现场朗读主链路前端）接入。


---

## 变更记录（2026-09-22 任务B：现场朗读主链路前端 read-practice.js）

### 需求
按认知科学引擎方案 P0-2，实现主训练链路三阶段状态机：预回忆(可选3s) → 现场朗读(≤2遍) → 遮蔽复述(禁偷看) → 4档自评。与"磨耳朵"辅助支线物理隔离。

### 实现（纯前端，无后端 SRS 写入）
1. **新建 frontend/modules/flashcard/read-practice.js**（约 380 行）：
   - `ReadPractice` 单例，挂载 `window.ReadPractice`
   - 三阶段状态机 PHASE.READ / PHASE.RECALL / PHASE.GRADE（+可选 PRE）
   - READ 阶段：🔊 TtsService 朗读（用 VoiceTextParser.spokenText 带停顿）+ 🎤 Web Speech API 实时收音
     - 语速监测：>160 字/分弹红警"听觉加工不足"；<80 弹黄警"容易走神"
     - 读音校验：onend 后调 VoiceTextParser.checkPronunciation，漏读造价术语/数字红警
     - 朗读遍数硬限：readCount>=2 后"开始复述"按钮才解锁
   - RECALL 阶段：只显示问题、答案已遮蔽（DOM 层不渲染 back）；持续监听复述
     - peeked 检测：复述文本清洗标点后，连续 12 字命中 back 原文 → 判偷看，本次判分作废
     - 不支持语音识别的浏览器降级为 textarea 输入
     - "想不起来了"按钮 = 主动看答案，自动标记 peeked
   - GRADE 阶段：4 档按钮（①完整 ②数字错 ③概念混 ④完全忘），自评后写 localStorage.rp_grade_log（任务 C 接后端）
   - 安全：RECALL 阶段 back 不渲染到 DOM（真正 API 层隔离在任务 C）
2. **flashcard.js 改动**：
   - tabs 数组加 `{ id: 'read2', label: '🗣️ 朗读训练' }`，位置在"闪卡练习"后
   - render() 入口加 read2 分支：渲染 `<div id="rpMount">`，requestAnimationFrame 里调 ReadPractice.start(container, allCards)
3. **index.html ×2**：在 voice-text-parser.js 后插入 read-practice.js

### 验证
- node --check read-practice.js / flashcard.js 均通过
- tools/startup_verify.py = 27 PASS / 0 FAIL
- 浏览器实测：待用户在闪卡模块点"🗣️ 朗读训练"tab 验证三阶段切换、语速提示、peeked 检测

### 备份
- flashcard.js.bak_rp1_20260922

### 未做/边界
- 后端 SRS 写入：localStorage 暂存，任务 C 接 /api/v1/mt/recall/grade
- 采分点覆盖检测、错误细分类、单位陷阱：P1-4 补
- 真正的"答案不下发到前端"API 隔离：任务 C（RECALL 阶段调 /veiled 接口只返回问题）
- 录音存档：P2-9

### 状态
✅ 任务 B 前端完成，等待任务 C（后端 SRS 4 档调度）。


## 变更记录（2026-09-21 20:55）知识库 RAG 接通学习资料库（多源去重 + 增量补索引）
- 结论澄清（实测推翻专家误报）：知识库 RAG 一直可用。/rag/status documents_count=25957、Ollama 在线(127.0.0.1:11434)、嵌入 quentinz/bge-small-zh-v1.5(512维，真向量，非 TF-IDF 兜底)；向量存文件矩阵 backend/data/rag_knowledge/(index.json 56MB + vectors.matrix.npy 50MB)，不在 SQLite。专家“0 embedding / Ollama 未启动”是探针找错存储口径 + 过时状态。
- 问题：RAG 索引源 LIBRARY_DIR=backend/data/files（旧工作目录，治理后 458 个权威 PDF + 题目切图），而权威培训资料已迁到 F:\水利智学系统\学习资料库\一造培训资料（data/external_library.json 的 roots）。
- 重合实测：学习资料库 483 个 PDF 中 481 个已在主源（按文件名+大小精确重合），主源还额外含一建水利/水利案例独有资料；学习资料库仅净缺 1 个主源没有的《一造水利案例编规—水利工程设计概(估)算编制规定 2024 323号文》(69.6MB)。新版真题透析与主源版同名同页数，跨源去重保留主源版（内容等价）。
- 代码改造（backend/api/v1/rag_knowledge.py，备份 rag_knowledge.py.bak_multisrc_20260921_204904，py_compile 通过）：新增 _extra_library_roots() 读 external_library.json 的 roots；_select_library_files() 升级为跨【主源 LIBRARY_DIR + 增补源(学习资料库)】统一治理去重，主源 bias=1000 保证存量索引零扰动，增补源本轮仅纳入 PDF（视频不支持；html/docx 多为视频页/工作稿，噪声待评估后再放开）；同内容按(核心名+页数，或大小)跨源只保留一份；去重审计仍落 dedup_audit.json。
- 索引：独立进程 backend/tools/build_rag_index.py 增量构建（不阻塞后端、不 --rebuild）；458 个主源文件命中 manifest 直接跳过，新增 323号文解析 401 块、入索引 397 块、0 错误、用时 0.9 分钟（文本 PDF，无需 OCR）；文档块 25957 → 26354。
- 验证（信源=实际运行）：提权重启后端后 /rag/status docs=26354、ollama_available=true；HTTP 检索“独立费用/工程勘测设计费”命中 323号文、相关度 0.80–0.83，“预备费计算”回归 0.74–0.76；bu 知识库页 DOM 触发 /rag/search?use_rerank=true 返回 ok，结果卡片渲染 323号文条文（科研勘测设计费、政府指导价第五/六条，相关度 83%）；干净重载无 connection refused（重启瞬间残留消失），仅 favicon.ico 404 无害。
- 边界与后续长期项：①增补源本轮只纳 PDF，学习资料库内 docx(20)/html(69) 是否纳入待评估噪声；②存储重复——backend/data/files 内 481 个 PDF 与学习资料库重复，且该目录还含一建水利/水利案例独有 PDF 与 595 张题目切图(疑被题库 OCR 引用)，是否整合为单一真源须先排查引用关系、再由用户拍板，本轮不擅删；③专家 latest_report 的 RAG 探针应改为读 /rag/status 与 rag_knowledge 目录而非查 SQL 向量表，属探针治理长期项。


## 2026-09-21 水利案例“真实数据”小样打通（教材案例一，questions.id=6251）
- 定性核实：官方不公布一造《案例分析（水利）》真题（233网校等多来源），市面均为考生回忆版；水利案例“真题”口径保持 0，禁止 AI 编造、禁止把教材/模拟题标成真题。
- 删除 AI 假题 #5819：全资料库 PDF 搜不到其特征数字 80850、source/create_time 均空；已全字段 JSON 备份（题库质检_20260921/备份/备份_水利假题5819.json）后软删。
- 真实素材盘点（fl_file_library 命中680）：官方教材 id=521 五章约30+道【案例X】为主力（背景表→问题→分析要点→分步答案，结构规整、可溯源）；3套全真模拟预测卷 id=649/650/651（题答分离待对齐）；章节问答题 id=1112 等自带完整计算过程可甄别恢复。
- 小样入库：教材案例一《引水工程总投资构成》p9–16 按原文入库 id=6251（subject=一造水利案例、type=case、q_type=案例、source=学习资料库:教材-2024一造水利案例.pdf p9-16、source_kind=教材例题、year留空、case_total_score=20、4小问分步参考答案+分析要点）；仅修正明显 OCR 错字，未改任何数字/算式。
- 三层验证：PRAGMA integrity_check=ok；/api/qb/all?subject=一造水利案例 返回1题且 case_background/case_sub_questions/case_total_score 完整下发（归一 q_type=case）；Playwright 走模块自身 _normalizeQ→_renderCaseMode 渲染，案例背景+4小问分步答案（6579.9/971.9/9447.27/10803.47）正常，布局未动。全库活跃=1193（1192+本道），水利案例活跃=1。
- 待授权前端2处（均未改，守布局/功能锁死）：①章节刷题/模考 DataService.getQuestions('一造管理') 科目写死（question-practice.js L480/1129/2927、mock-exam.js L63、data-service.js L128），水利案例进不了练习池，需跟随顶部科目切换；②案例“显示答案/AI讲解”内联 onclick 引用全局 questionPracticeModule，但 Framework 仅注册为 _modules['question']、未挂 window（实测 typeof=undefined），真实点击会 ReferenceError（案例题此前为0故未暴露），最小修复为模块注册后 window.questionPracticeModule=该实例，不改布局。
- 环境：直接 SQL 写库后服务自检重启一次（8000端口恢复、integrity ok、数据无损）；后续批量改走 API 或暂停文件监控写入，避免触发重启。


---

## 2026-09-21 一造水利案例：前端科目联动打通（A）＋教材真实案例批量入库（B，第一/三章共16题）

### 〇、铁律口径（保留）
- 官方**不公布**一造《案例分析（水利）》真题（全主观、6道大题、每题20分、120分/4小时）；市面均为考生回忆版。水利科目"真题"分类永远=0，**绝不AI编造真题/假案例/假数字**。库中AI假题#5819已全字段备份后软删；教材例题 year 留空，前端真题池按 year 非空 过滤，水利真题自然为空并toast"该筛选条件下暂无真题"，无硬编码特判。
- 本批案例全部取自《教材-2024一造水利案例》（学习资料库id=521，262页文本层），PyMuPDF按物理页 get_text(sort=True) 提取，数字一律不改，仅修明显OCR单位错字（万m³→元/m³、5毛→元 等）。

### 一、A 前端科目联动（已完成、Playwright端到端实测零报错、管理科目零回归、布局未动）
- 堵点：①章节刷题/每日一练/模考题源硬编码 getQuestions('一造管理')；②案例"显示答案"内联onclick引用全局 window.questionPracticeModule 但从未挂载（潜伏ReferenceError）。
- 改动（补丁 patch_frontend_subject.py，逐处assert、全匹配写回、.bak备份 后缀 .bak_subj_20260921_211114）：
  - frontend/modules/layout/topbar.js：init从localStorage/Store恢复科目；#realGlobalSubject onchange写localStorage('currentSubject')与Store.currentSubject。
  - frontend/modules/question/question-practice.js：constructor存管理树快照并_applySubjectChapters；新增_currentSubject/_waterChapters(水利五章id1-5)/_isWaterCaseSubject；_isCase加科目守卫；init用_subjectBound防重复订阅subject:changed；三处getQuestions('一造管理')统一改当前科目；文件末尾先挂 window.questionPracticeModule 再 register。
  - frontend/modules/exam/mock-exam.js：订阅subject:changed重置；_loadPool取当前科目且filter掉case/案例（主观题不进客观自动判分模考）。
  - frontend/index.html：三脚本版本号 bump ?v=20260921subj1（SW按指纹URL取新，未动CACHE_NAME）。
- 实测（ui_subject_switch.py / ui_ch1_10.py / ui_ch3.py）：切水利后章节树变五章、计数正确；案例模式真实点"显示答案"展开分步算式；水利真题toast为空；切回管理恢复6章选择题；全程console/pageerror=0；侧栏135px/顶栏56px/主色#1a73e8/版式均未动。

### 二、B 教材真实案例入库（subject='一造水利案例', year='', is_deleted=0, source_kind='教材例题'）
入库脚本：import_ch1_cases.py / import_ch1_more.py / import_ch3.py（均幂等按title判重、显式is_deleted=0、integrity_check＋API回读）。
- 第一章 水利工程造价构成（10题，完整覆盖总投资四大块＋信息化）：
  - 6251 案例一 引水工程总投资构成 p9-16（4问，总投资10803.47）
  - 6252 案例二 引水工程工程部分造价构成 p16-21（4问，工程部分静态475104.60）
  - 6253 案例三 流域综合治理（河道堤防）总投资 p21-24（4问，总投资27657.49）
  - 6254 案例四 水利工程类型、堤防工程造价构成 p24-28（4问，独立费用1695.23）
  - 6255 案例五 建设征地移民补偿（一）p28-33（**8问**，总投资291634.29）
  - 6256 案例六 建设征地移民补偿（二）p33-36（**7问**，征收/征用/复垦/青苗/综合单价）
  - 6257 案例七 环境保护工程造价构成 p36-39（3问，环保专项投资130.32，依SL359-2006）
  - 6258 案例八 水土保持（生态建设一）p39-42（6问，工程总投资6050.66）
  - 6259 案例九 水土保持（开发建设二·种草单价）p42-47（5问，撒播单价5180.56元/hm²、总投资99928元、水保设施补偿费250000元）
  - 6260 案例十 水文/水利信息化项目总投资及造价构成 p47-52（3问，静态总投资1256.41；含闸门监控/水雨情/视频/IT基础构架/网络安全/管理信息化六系统，对应数字孪生水利信息化）
  - 注：PDF书签第一章仅标案例一~四，正文p24-52实含案例五~十（已全部补入）。
- 第三章 水利工程计量与计价应用（6题，含用户点名的施工用水/电/风单价）：
  - 6261 案例一 引水工程设计工程量计算 p84-86（3问，开挖/衬砌/超挖出渣/配合比换算）
  - 6262 案例二 水利建筑工程单价分析和投资计算（斜井石方开挖）p86-94（2问，开挖单价385.75元/m³、投资578625元）
  - 6263 案例三 堤防整治工程单价计算（土方填筑）p94-100（3问，堤防29.12、水闸28.13元/m³）
  - 6264 案例四 引水隧洞通风机械调整及出渣运距 p100-102（2问，通风综合系数2.01、综合运距1258.33m）
  - 6265 案例五 **施工用电和施工用水预算价格** p102-104（3问，电网0.99/自发电2.35/综合电价1.13元·kW⁻¹·h⁻¹、施工用水0.76元/m³）
  - 6266 案例六 **施工用风预算价格** p104-106（2问，移动61.73/固定118.30元每台时、用风0.17元/m³）
- 现状：水利案例活跃=16（第一章10、第三章6），全库活跃=1208，PRAGMA integrity_check=ok，/api/qb/all?subject=一造水利案例 回读16题、q_type均归一为case。

### 三、小问分值口径（重要）
- case_total_score 统一=20（考试真实规则：6题×20分）；教材例题本身不赋小问分。
- 前端小问徽标缺省5分/问；对小问数≠4的题（案例五8问、六7问、八6问、九5问及第三章各题）已在 case_sub_questions 每问显式给 score 且合计=20，**该小问分值仅为前端展示权重、非教材赋分**。

### 四、待办（下一批，须PyMuPDF重读原文、不得凭摘要编数字）
- 第三章剩余：案例七 混凝土材料预算价和工程单价 p106-132；案例十 水轮发电机设备及安装 p132-141；案例十一 压力钢管制作及安装单价 p141-169（书签缺三/六/八/九，正文需逐页核）。
- 第二章 工程经济 p53-83；第四章 招标投标 p170-216；第五章 合同价款管理 p217-262。
- 教材依据水总〔2014〕429号编制规定，用户核心为2024新323号文，结构化时比对新旧差异并标注。
- 真题页硬编码"320/128/68%"未接真实统计；离线同步 is_deleted 合并策略（防#5819被本地副本带回）仍待处理。


---

## 变更记录（2026-09-22 任务B-补：主辅链路隔离警示条 + 双向引导）

### 需求
用户确认：朗读训练（read2 主链路）与朗读记忆专练（read 磨耳朵）保持两个 tab 物理隔离，中间加引导箭头和警示条，不合并。

### 实现
1. **朗读记忆专练 tab 顶部红色警示条**（flashcard.js L557 后插入）：
   - 红底警示："本模式无生产效应，TTS 自动播放只有听觉+视觉双通道，缺少你自己开口的口腔运动编码。不能替代朗读训练的现场朗读+闭卷复述，不更新 SRS 评分。"
   - "🗣️ 去朗读训练（主链路）"按钮（点击切到 read2 tab）
2. **朗读训练 GRADE 阶段底部蓝色引导**（read-practice.js _renderGrade）：
   - 蓝底提示："判分后自动进下一张。通勤、走路等碎片时间可切到朗读记忆专练磨耳朵唤醒线索；但别用它替代现场朗读+闭卷复述。"

### 验证
- 浏览器实测：磨耳朵 tab 顶部红色警示条渲染正确，"去朗读训练"按钮点击后正确切到 read2 tab
- 朗读训练 GRADE 阶段底部蓝色引导条渲染正确
- tools/startup_verify.py = 27 PASS / 0 FAIL

### 状态
✅ 主辅链路视觉隔离完成。继续任务 C 后端 SRS 联调。


---

## 2026-09-22 07:56 ｜ B真实案例建设：第三章案例七~十六全部入库（6267~6276）＋修复两个前端切换竞态

### 一、入库（教材 id=521《教材-2024一造水利案例.pdf》原文，不改一个数字，source_kind=教材例题、year空、is_deleted=0、case_total_score=20）
脚本 `题库质检_20260921/import_ch3b.py`（七~九）、`import_ch3c.py`（十~十一）、`import_ch3d.py`（十二~十六），均幂等按 title 判重。
- 6267 案例七 混凝土材料预算价和工程单价（泵站C25）p106-114，3问[7,5,8]：墙体浇筑单价670.54元/m³（材料358.56、搅拌22.03、运输20.38）。
- 6268 案例八 土方填筑（均质土坝含覆盖层摊销）p114-121，3问[3,7,10]：覆盖层摊销0.83、挖运10.90、填筑含摊销34.72元/m³（每100实方耗126自然方，枢纽土方间接费8.5%）。
- 6269 案例九 材料预算价与帷幕灌浆估算 p121-132，4问[3,7,7,3]：水泥预算价548.56元/t、钻孔355.08元/m（廊道×1.05、82°再×1.02）、灌浆348.80元/m、帷幕灌浆投资149.59万元。
- 6270 案例十 水轮发电机设备及安装 p132-141，3问[4,10,6]：设备费52.58万/台（运杂综合5.16%）、安装8.39万/台（海拔3020m人工×1.20机械×1.45）、5台设备及安装304.85万元。
- 6271 案例十一 压力钢管制作及安装 p141-149，2问[10,10]：制作10131.43元/t（钢板作未计价装置材料、5%损耗）、安装6035.64元/t。
- 6272 案例十二 引水工程勘测设计费 p149-152，3问[10,5,5]：计费额730541万、内插基价14177.99、勘察收费15937.84万（含作业准备费15%）、设计收费15000.31万、初设勘察11156.48（加权70%）、初设设计4800.10（加权32%）。
- 6273 案例十三 枢纽资金流量、建设期融资利息及总投资 p152-159，3问[6,8,6]【用户重点：基本预备费/价差预备费两个独立知识点】：建安资金流量7360/5400/5205/4010/3025；**基本预备费1675**（分年225/520/490/285/155，基数为分年度投资非资金流量）；静态投资35175；**价差预备费本题取0**；**建设期融资利息4315.86**（S1~S5=176.40/564.01/928.67/1205.84/1440.94，贷款80%、利率4.9%、当年半年计息+上年全额复利）；**总投资39490.86万元**。
- 6274 案例十四 水利建筑工程工程量清单计价（双曲拱坝）p159-164，2问[10,10]：6项普通混凝土综合单价另摊温控42.64元/m³（编码500109001001~006），分类分项117722.92、措施8560.61（环保2%/文明1%/安全1%/小临3%+进退场200+安拆120）、预留金1000，**招标控制价127283.53万元**（GB50501-2007）。
- 6275 案例十五 水利设备安装工程工程量清单计价（水轮机组）p164-167，2问[10,10]：水轮机6×712.56=4275.36、发电机6×632.50=3795.00，分类分项8070.36、措施549.57（环保1.5%）、预留金200，**招标控制价8819.93万元**。
- 6276 案例十六 补充机械台时费定额编制 p167-169，3问[4,8,8]：运杂综合费率6.19%/运杂费37140元；一类费用103.98（折旧35.98、修理替换63.32、安拆4.68，出厂价除13%进项税）；二类114.98（机上人工7.94按中级工6.62、燃料107.04柴油除税）；**台时费218.96元/台时**。

### 二、第三章实有16题（书签仅标7个，逐页核对补齐），至此第三章全章入库完成
当前库：一造水利案例活跃=26（第一章10 + 第三章16）、全库活跃=1218、PRAGMA integrity_check=ok、/api/qb/all?subject=一造水利案例 回读26题。水利"真题"分类仍为0（官方不公布案例真题，#5819假题维持软删）。

### 三、测试中发现并修复两个真实前端竞态（不碰布局/侧栏/主色/版式，仅数据与挂载逻辑）
1. **章节计数跨科目串数**：init 默认科目与切换科目的两次异步 `_loadChapterStats` 竞态，管理全量统计晚到会写到水利章节树（出现第二/四/五章170/245/189题）。
   修复 `frontend/modules/question/question-practice.js`：①入口记录 `wantSubject` 快照，await 返回后科目已变则丢弃过期结果；②计数前先把当前科目树 count 全归零再填充，杜绝残留。备份 `.bak_race_*`，index.html 指纹 bump 为 `?v=20260922race1`。
2. **切科目/快速切页后页面被旧模块异步重绘覆盖（章节树0.6s后消失、跳回首页）**：根因是旧 dashboard 实例启动时的异步 `_loadRealData()` 在切到题库后才返回，闭包仍持有共享 contentContainer，render() 把题库覆盖成 dashboard-area（与科目无关，属慢异步旧实例回写整类问题）。
   修复 `frontend/index.html` 的 `renderPage`：切换到**不同**模块前，把上一个活动模块实例的 `container` 指向离屏 div，使其在途 render 写到离屏节点（单例切回时 init 会重新指回 contentContainer）；同模块重复 init 不隔离。未改任何模块内部、未调 destroy，零副作用。

### 四、三层验证（脚本 `ui_ch3full.py`，headless Edge，零 pageerror）
- 切"一造水利案例"后五章计数=10/0/16/0/0；**专门等待2.5s（旧模块异步回写窗口）后章节树仍在、第3章仍16题**（隔离补丁生效）。
- 勾选第三章进入案例模式，16题（案例一~十六）全部可刷、顺序随机；一次性 JS 点全部"显示答案"无 DOM 失效。
- 抽验命中：案例十三 基本预备费1675/价差预备费/融资利息4315.86/总投资39490.86；案例十六 台时费218.96/一类103.98/二类114.98/折旧35.98/运杂37140。截图 `ui_第三章_资金流量预备费.png` 已肉眼核验，三问分步算式与黄条要点齐全、布局未动。

### 五、下一步（B 继续，均须重读 PDF 原文、不得凭摘要编数字）
第二章 工程经济 p53-83（资金时间价值/方案比选/价值工程）；第四章 招标投标 p170-216；第五章 合同价款管理 p217-262（变更/索赔/调价/结算）。


---

## 2026-09-22 08:06 ｜ B真实案例建设：第二章 工程经济 全章15个案例入库（6277~6291）＋三层验证通过

### 一、物理页边界校准（重要，纠正页码口径）
用文本关键词逐页核对：第三章章标题在**物理页84（书内印刷页76，偏移−8）**，第二章正文跨**物理页53~83（书内印刷45~75）**，共案例一~十五15题。首次 dump 套固定偏移曾漏案例一~三、尾部混入第三章，已改按关键词校准重dump（`教材原文\第二章_p55-83.txt`，案例一背景另补物理53-54）。**库内 source 页码统一采用 PDF 物理页号（阅读器跳转页），书内印刷页=物理页−8，与已入库第三章口径一致。**

### 二、入库（教材 id=521 原文，不改一个数字，source_kind=教材例题、year空、is_deleted=0、case_total_score=20）
脚本 `题库质检_20260921/import_ch2.py`（幂等按 title 判重），id 6277~6291：
- 6277 案例一 资金时间价值(一) p53-56，3问[6,6,8]：资金流量1690/2350/4030/2930、静态12100、年有效利率6.17%、建设期利息582.52万（22.21/75.41/183.72/301.18）。
- 6278 案例二 资金时间价值(二) p57-59，5问[各4]：建设期利息109.62、年折旧369.27、等额本息551.12(A/P,6%,4)=0.2886、总成本1027.85/1137.65、还款资金444.38>436.54、ROI=10.58%。
- 6279 案例三 动态投资回收期 p59-60，1问：正常年净现金流600、第3年540，P't=8.19年。
- 6280 案例四 防洪水库国民经济评价 p61-63，2问：投资现值15290.0/年值1838.4、运行费现值1931.9、防洪效益现值12150.7（等比j=3%）、ENPV=−5071.2、EBCR=0.7055，经济不合理。
- 6281 案例五 盈亏平衡 p63-64，2问：Q*=12000万kWh、利用率BEP=68.5%。
- 6282 案例六 敏感性分析 p64-65，2问：SAF投资−1.1117、有效电量1.4278（最敏感），不利变动FIRR跌破8%、FNPV转负。
- 6283 案例七 风险概率分析 p65-66，2问：NPV五档−2372.22~2855.56、E(NPV)=600.2万、P(NPV≥0)=65%、方差1736050.51、σ=1317.59。
- 6284 案例八 寿命期相同互斥方案 p67-68，2问：静态回收期水库8.33/调水12.40/污水回收6.42年，污水回收FNPV=327.70万可行。
- 6285 案例九 不同寿命机械比选 p68-69，1问：最小公倍数法NPV_A=3023.2>NPV_B=1588.8、年值法NAV_A=489.6>NAV_B=259.5，选A。
- 6286 案例十 0-1/0-4评分价值指数 p69-72，3问[6,8,6]：0-1权重F1~F4=0.3/0.2/0.4/0.1，价值指数A1.0890/B0.9970/C0.9166/D1.0173（A最优）；0-4权重0.2500/0.0833/0.2500/0.4167。
- 6287 案例十一 价值工程目标成本 p73-74，1问：现实4978、目标4658、降低额A85/B600/C−133/D−144/E−88，改进顺序B、A、E、C、D。
- 6288 案例十二 河道防渗三方案 p75-77，2问[4,16]：功能指数A0.352/B0.324/C0.324、成本指数0.325/0.424/0.251、价值指数1.083/0.764/1.291，C黏土铺盖最优。
- 6289 案例十三 挖装运输机械配套 p77-80，2问：生产率5.4装载352.17/2.0装载130.43/反铲45.88 m³/h，挖装费0.85、运输费10.13元/m³最低；2台5.4装载机+50台15t+12台8t+13台5t（缺口组合二费22560元最低）。
- 6290 案例十四 成本曲线方案优化 p80-82，3问[4,8,8]：CA=100000+60Q、CB=200000+55Q，工程量分界20000m³、工期分界148.15d。
- 6291 案例十五 设备购置vs租赁 p83，3问[4,10,6]：年折旧11.88、ACA=19.72>ACB=11.92租赁优；贴现率降到0时A(11.88)<B(16)反超。

### 三、三层验证（脚本 `ui_ch2.py`，headless Edge，零 pageerror）
- DB：PRAGMA integrity_check=ok；水利案例活跃=**41**（第一章10+第二章15+第三章16）、全库活跃=1233；/api/qb/all?subject=一造水利案例 回读41题。
- 浏览器：切科目后五章计数=**10/15/16/0/0**；等待2.5s（旧模块异步回写窗口）章节树仍在（上一轮 renderPage 隔离补丁对第二章同样有效）；勾选第二章15题（案例一~十五）全部可刷、显示答案一次性展开无 DOM 失效。
- 抽验命中：案例一 582.52/1690/12100/6.17%/22.21；案例十三 352.17/22560/0.85/10.13/1.77。截图 `ui_第二章_机械配套.png` 已肉眼核验，分步算式+黄条要点齐全、布局未动。

### 四、进度与下一步
一造水利案例教材已入库 第一/二/三章共41题。剩余：**第四章 水利工程招标投标**、**第五章 水利工程合同价款管理（变更/索赔/调价/结算）**，均须 PyMuPDF 重读原文、按关键词校准物理页边界后照 import_ch2 模板入库，不得凭摘要编数字。


---

## 变更记录（2026-09-22）存储单一真源整合：去重 1.6GB + 核心两科聚焦 + RAG 全量重建对齐学习资料库

- 范围（用户拍板）：执行“1整合”，把 `backend/data/files` 与权威培训资料库 `F:\水利智学系统\学习资料库\一造培训资料`（external_library.json 的 root）收敛为单一真源，消除重复 PDF、不留存储浪费；**核心科目仅一造管理、一造水利案例，其他科目（一建/二造/计价/计量等）数据不迁入、不进前端、不进 RAG，仅靠 roots 配置预留接入接口**。
- 盘点（只读实证，脚本 _inventory_files.py/_audit_db_files.py，清单 _files_inventory.json）：data/files 不只是 RAG 旧源，更是资料库服务的存储/上传根（file_library_service FILE_LIBRARY_DIR、下载/上传/fl_bridge 均依赖），故不能整目录删。原 1354 文件中 PDF 753：与学习资料库“同名+同大小”字节级重复 **711 个(1594.7MB)**、水利定额 4 个(355.7MB，RAG 全局排除)、过程副本 23 个(15.1MB，18 个 _nowm 叠代+3 个时间戳+2 test)、独有权威 15 个(888.5MB＝4 本一建教材+11 个一造水利案例章节讲义)。DB fl_file_library 未删 1096＝external 1079 + 内部 17。
- 去重（已 apply，零断链）：_dedupe_files.py 逐个校验学习资料库存在“同名且 size 完全相等正本”才删，删 711、失败 0、清空目录 68，清单 _dedup_log.json（含每项正本路径，可追溯/恢复）；_clean_junk.py 双重校验（DB 无活跃内部记录 + 学习资料库有正本）后删 21 个过程副本(15.1MB)，2 个 test 文件因 DB id1/id509 活跃保留。累计释放约 **1.61GB**。
- 独有资料归位（同盘 shutil.move 原子、留 _migrate_log.json）：11 个水利案例章节讲义→`一造培训资料\2026-一造水利案例\00.教材章节讲义\`；4 个水利定额→`…\2026-一造水利案例\00.定额工具\`（定额是水利案例工具书，RAG 仍按“定额”全局排除不分析）。非核心隔离到 external root **之外**的 `F:\水利智学系统\学习资料库\_其他科目预留\`：4 本一建教材+1 本一级建造师大纲→`一建教材（2026）\`，1 个跨科 `一建、一造复习重点.xls`→`跨科与其他\`；该目录在 root 外，os.walk 扫不到，故不进资料库前端、不进 RAG，以后把目录加入 external_library.json 的 roots 即接入（＝预留接口）。
- DB 对齐：软删 11 个章节旧内部记录 id152-162、跨科 xls id184（导出 _relocate_db.json 留档，可逆）；两次 POST `/api/v1/fl/external/scan` 重扫，归位 added=15、隔离大纲 removed=1、errors=0。归位后 data/files 回归为系统工作目录，仅剩 2 个 test PDF + 595 配图 png + 3 个纯一造复习 xls + db + 1 jpeg。
- RAG 全量重建对齐正本（独立构建器 backend/tools/build_rag_index.py，日志 _rag_rebuild.log/_rag_inc*.log）：先备份 `backend/data/rag_knowledge.bak_singlesrc_20260922`（310.5MB/26379 文件）；`--rebuild` 全量 28.6 分钟、治理后 455 文件、0 错误；随后两次普通增量按“治理集合中已不存在文件即删块”(index_builder L528-546) 分别剔除一建大纲 112 块、跨科 xls 205 块。**终态 19375 块 / 453 文件 / 0 错误**，嵌入 quentinz/bge-small-zh-v1.5（512 维真向量，非 TF-IDF），documents=library_chunks=vector_matrix 三者一致、index_healthy=true；所有块 source_path 已由旧 data/files 路径对齐为 `学习资料库/一造培训资料/...` 正本。重建期后端沿用旧索引不中断，完成后提权重启加载。
- 验证（信源=实际运行）：①`/api/v1/rag/status` docs=matrix=19375、healthy、ollama=true、restored_from_backup=false；②核心正例 top 命中正确科目与正本——预备费/独立费用·工程勘测设计费/水利概算→一造水利案例（教材-2024一造水利案例 + 张莉精讲），双代号网络计划/资金时间价值→一造管理（教材-2025一造管理 + 蒋莉莉/环球精讲），得分 0.89–1.08；③一建反例（项目管理/法规/经济/执业大纲）**一建来源泄漏=0**（仅返回低分一造内容 0.70–0.96）；④资料库 `/api/v1/fl/list` total=**1098**、逐条 file_path 在盘、缺失=0、含一建文件=[]，类型 视频501/讲义498/教材8/题库36/大纲2/其他54；⑤bu 知识库 UI（生产模块 knowledge.js，#/knowledge_base）检索“独立费用 工程勘测设计费 概算”返回“找到 10 条相关结果（已AI重排序）”，首条“第一章 水利工程造价构成/科研勘测设计费”相关度 78%，console 0 error；资料库页去重后仍显示共 1096→归位后口径一致、文件夹树/标签正常、网络无失败。
- 关键口径/接口：资料库 router 自带前缀 `/api/v1/fl`（全量列表 GET `/api/v1/fl/list?page_size=5000` 返回体字段 files；重扫 POST `/api/v1/fl/external/scan`；测后端用 127.0.0.1 避 IPv6 回退）；多科目接入只需改 `backend/data/external_library.json` 的 roots 数组并重扫+重建，无需改代码。
- 遗留/边界：①学习资料库 root 直属的 12 个核心文件（一造两科教材/大纲/323号文/知识点清单等）保持用户原始摆放未重组（不擅自改用户资料库目录）；`~$` Word 临时锁文件未动（可能正打开）。②`backend/modules/mm/service.py` L46-47 教材路径仍硬编码 data/files 下 2025 一建文件名、本就落空，一建移出后依旧；后续思维导图教材解析需改指学习资料库内一造管理/水利案例教材正本（属功能修复，未在本轮范围）。③3 个纯一造复习 xls、595 配图、1 真题 jpeg 留 data/files 工作目录（非重复、内部记录有效）。④本轮 _*.py/_*.log 按既有惯例留项目根，迁移审计 _files_inventory.json/_dedup_log.json/_migrate_log.json/_relocate_db.json 保留可追溯。


---

## 2026-09-22 一造水利案例·第四章《水利工程招标投标》16个教材案例全章入库（B阶段）

### 一、范围与来源（真实教材原文，零编造）
- 来源：学习资料库 id=521《教材-2024一造水利案例.pdf》第四章，物理页 p170–216（书内印刷页 p162–208，偏移−8，已用“第四章/案例一~十六”关键词逐页校准）。
- 全章共 **16 个案例（案例一~十六）**，全文 67126 字符 dump 至 `题库质检_20260921/教材原文/第四章_p170-214.txt`，案例十六问题2/3答案尾在物理 p216（`dump_ch4_tail.py` 补提）。书签大量漏标，案例边界以逐页 Grep“^案例[一二…]”核对。
- 入库 id **6292~6307**，chapter=“第四章 水利工程招标投标”，title 前缀【教材案例四-N】，year 空、source_kind=教材例题、case_total_score=20、is_deleted=0；小问分值合计均=20（脚本 assert 校验）。脚本 `import_ch4.py`（幂等按 title 判重）。

### 二、16题清单与教材原文关键答案（数字一律以 dump 原文为准）
- 四-1 招标方式与评标(一) p170-174，3问：技术复杂可邀请招标、邀请4家≥3合规、自行招标6条件；不妥（截止不足20日/保证金有效期须与投标有效期一致·水利一般56天/踏勘应在预备会前且统一组织）；综合评估法均值22962.75，报价得分29.43/29.06/28.36/29.28，单价8/10/8/8，技术27/25/22/25，**总分92.43/93.06/85.36/90.28，第一中标候选人B**。
- 四-2 招标方式与评标(二) p174-178，4问：自行决定邀请招标不妥（地方重点项目须报本级政府批准）；同样时限/保证金不妥；B钢筋制安5683.20×352=2000486.40、原合价2900486.40差−90万，以单价为准修正B报价88650→**88560**；5家均值85546，98~101%满分、超高每1%扣1.5超低扣1，**总分87.99/85.62/87.75/91.20/86.20，第一中标候选人D**。
- 四-3 工程招标程序 p178-180，2问：初设未批准即招标、监理与施工招标同步均违规（监理须先确定）；合同条款不妥（奖罚不对等/延误确认未含非承包人原因/每天5万近1%·总限额10%过高，GB50500-2013误期赔偿最高合同价5%；进度款60%过低；初设阶段不宜固定价应可调价按监理确认实际量结算；政策法规地质变化风险分配不合理·情势变更）。
- 四-4 工程招标(隧洞) p180-183，3问：合同类型单价/总价/成本加酬金；事件1单价取费适当下浮**正确**（进退场费、安全措施费已在措施清单计列避免重复）；石方洞挖=5000×3.14×(6+0.2×2+0.3×2)²/4=**192325 m³**（超挖16838+附加3000摊入单价，事件2的212163错）；C30衬砌=5000×[3.14×(6+0.3×2)²/4−3.14×6²/4]=**29673 m³**（事件3的51025错，超挖超填摊入单价）。
- 四-5 招标与评标(公平性) p183-186，3问：本地/外地注册资金差别+本流域业绩属地方保护违规；合作过A等/初次C等差别对待违规；保证金20万超控制价500万的2%（应≤10万）、截止前可撤回无权没收；不组织踏勘合法但陪同单个投标人违规；延长有效期A不得改报价但应补偿保证金费用、E拒绝则投标失效退保证金；资信 A90×0.03=2.7、B70×0.03=2.1差0.6分，1分=496×1%=4.96万，分差折造价=**2.976万元**。
- 四-6 工程投标(一) p186-188，3问（不平衡报价）：两技巧；前期土方/石方/锚杆各提10%→16.86/108.26/200.48，上调总额186143.14元，后期封堵521.63→469.47（降44338.55）、衬砌602.32→**560.24**（剩余额度141804.59/3370）；锚杆量增50%：锚杆200.48、封堵→489.47，**多收益13681.5元**。
- 四-7 工程投标(二) p188-190，2问：固定价/可调价/成本加酬金，固定价特点与4适用条件，本河道工程（图纸简单量明确工期1年）固定价合适；砌块涨价期望=2.5%×1/6+4.0%×4/6+4.6%×1/6=**3.85%**，保本单价=305×1.0385=**316.74元/m³**。
- 四-8 工程投标(三) p190-193，4问：量减则单位固定成本升利润降，不平衡报价±10%、实质性变化一般15%属变更；盈亏平衡土方40/(12.5−6)=**6.15万m³**、石方60/(36.2−20)=**3.70万m³**；土方减20%→单价11.25、石方38.03，多收益**3.01万元**；混凝土CA=500000+360Q、CB=800000+340Q，无差别点**15000m³**（<选A >选B），B方案10万m³获利60万→单价**354元/m³**。
- 四-9 工程投标(四) p193-195，2问：不平衡报价（基础+9.30%/结构+8.33%/安装−10%，总价均8260不变）；月款215/300/475与235/325/427.5，按(P/A)与(F/P,1%)折算到24月末，终值9120.90→9169.76，**增加48.86万元**（解法二48.85）。
- 四-10 招标投标评标(一) p195-198，5问：先交保证金后买文件+发售仅2天不妥（发售≥5日、保证金递交投标文件同时）；截止不足20日、有效期自发售起算不妥；陪同单独踏勘不妥；A自改清单工程量不妥（未响应将否决）；评委8人非单数且专家4人<2/3不妥；B的C25混凝土1085×553.19=600211.15与合价60021.12不符以单价为准修正；C低价不能直接否决，应先书面说明+举证。
- 四-11 招标投标评标(二) p198-202，4问：修改撤回无24h限制/有效期自截止起算/保证金须一致/不统一组织踏勘妥当；施工招标文件八组成；开标密封应由投标人或代表（公证机构）检查、招标人代表暗示E降价违规；联合体A资格预审后增A4成员→无效，C暂列金额530≠招标520→否决，有效B/D/E/F；均值8479.25，**总分95.98/97.05/97.85/95.95，第一中标候选人E**。
- 四-12 投标与评标(一) p202-204，4问：B项目经理注册单位不符、评标办法无通融规定→废标；C借澄清改工期（实质性内容）不允许、原工期超标属重大偏差→废标；G梁板柱4690×537.80=2522282.00与合价252228.20差227.01万，修正后24539.29>控制价24525.36→废标；剔除B/C/G后均值23782.06，加权基准价=24525.36×0.4+23782.06×0.6=**24079.38万元**。
- 四-13 投标与评标(二) p204-207，4问：4家通过初评≥3不重新招标；C合价算术错以单价为准（改245504有效）但主动补沥青木板报价无效、D单价小数点错以合价为准（21.50有效）、F单价偏低非算术错误不能澄清（改518.50无效），向F发澄清函本身不妥；修正报价C**4016973**/D4051613/F4041226/G4007101；基准价**4029228.25元**，报价得分（满分55高扣1低扣0.5）C54.85/D54.44/F54.70/G54.73。
- 四-14 招标评标与中标 p207-209，2问：发售仅3天<5日、保证金时点错、正本应1份非3份、截止前送达即可（非3小时前）、有效期起算与保证金一致；程序（疑问应17天前·澄清15天前且发所有人不指来源不足15天顺延、候选人应标明顺序、报告3日内公示且公示≥3日故7月5日发通知书不妥应7月6日后、发通知书同时通知未中标人、签约后5工作日退保证金、确定中标人15日内交书面报告）。
- 四-15 投标评标与中标 p209-212，4问：不平衡报价原理±10%；前期土方18.35/石方23.78/土方填筑27.96，上调219703.86元，后期防护栏杆347.63降194291.48、路面89.26→**88.57**（剩余25412.38/36642.62）；事件1要求G降到与E相同属就实质性内容谈判不合法；事件2未依法满公示即发通知书不妥、事件3通知未中标人及退保证金滞后、11月28日交报告超15日。
- 四-16 招标法律责任及处理 p212-216，3问：可异议项=指定分包/备选方案规则（仅中标人备选才考虑）/澄清不足15天应顺延/拒绝延长有效期应退保证金；答复要求（异议截止10日前提出、3日内答复、答复前暂停）；事件1委托代理人未参加开标会按无效标妥当、事件2临时改最低投标价法不妥、事件3工期超期重大偏差不能澄清补救、事件4应单价为准修正合价而非保总价改单价、事件5不得要求按最低价签约、事件6招标人原因拒签应退保证金并双倍补偿；澄清注明来源=泄露潜在投标人名称，招标投标法第52条警告+1万~10万罚款等。

### 三、三层验证（全绿）
1. DB：PRAGMA integrity_check=ok；水利案例活跃 **57**（一10+二15+三16+四16）、全库活跃 **1249**；第四章=16。
2. API：/api/qb/all?subject=一造水利案例 code=200 回读 **57** 题。
3. 浏览器（Playwright `ui_ch4.py` + `verify_ch4_1.py`）：顶栏切“一造水利案例”后五章计数 **10/15/16/16/0**；切科目后等2.5s章节树仍在（旧竞态修复持续有效）；勾选第四章遍历16题、显示答案一次性 eval_on_selector_all 全部展开；12组关键数字（含四-1的22962.75/93.06/B、四-2的88560/91.20/D、四-4的192325/29673、四-6的13681.5、四-7的316.74、四-9的48.86、四-11的97.85/E、四-12的24079.38、四-13的4029228.25/54.85、四-16双倍赔偿等）全部命中；**0 pageerror**。截图 `ui_第四章_隧洞工程量.png` 已 Read 肉眼核验（布局未动、中文正常、绿框答案+黄条要点）。
   - 注：ui_ch4 首跑“四-1”误报 False 系脚本 key“四-1”被“四-10”标题子串抢占所致（验证脚本 bug，非数据问题），verify_ch4_1.py 改用“案例四-1】”精确匹配后 7/7 全命中。

### 四、产物
- 入库 `import_ch4.py`（已执行，id6292-6307）；提取 `dump_ch4.py`/`dump_ch4_tail.py`；原文 `教材原文/第四章_p170-214.txt`；回归 `ui_ch4.py`/`verify_ch4_1.py`；截图 `ui_第四章_隧洞工程量.png`。
- 前端、布局零改动（本轮仅题库数据入库与只读验证）。
- 下一步：第五章《水利工程合同价款管理》（物理 p215 章标题起，已定位案例一~五至 p230，p230–262 剩余案例待关键词扫描定边界后 dump、精读、入库）。


---

## 变更记录（2026-09-22）诊断报告问题4治本：RAG 检索精度/重建崩溃安全/启动自愈（含科目边界自我纠正，终态回两科 19375）

### 需求
对照《系统交付级诊断报告》问题4「RAG 知识库空库 / AI 问答成功率≥80%」逐项实测核对、从检索管线内核治本、把验收标准固化为自动回归；报告不实要标记、真问题深化推进。

### 报告论断核对（不实/无据）
- "RAG 空库（rag_embeddings 0 行）"不实：该表早已弃用（core/night_jobs/_init_rag.py 只建表不灌数），真索引在文件矩阵 backend/data/rag_knowledge/（index.json+vectors.matrix.npy/json+lib_*.npy+library_manifest.json），Ollama quentinz/bge-small-zh-v1.5(512维真向量)在线。
- "成功率约50%"无评测依据。真缺口=成功率≥80%从未自动验证 + 全量重建先破后立有残库风险 + 核心专名"赢得值法"漏召回 + .xls 缓存缺失块永不补。

### 实现（四处内核治本，与科目无关，全部 py_compile 通过并经提权重启生效）
1. 检索专名硬召回（api/v1/rag_knowledge.py）：新增 _extract_hard_terms（按通用修饰/量词切回核心专名，"赢得值法"补"赢得值"）；_rank_hits 在向量 top120 粗排候选外并集专名硬召回（标题+0.10/正文+0.05，每术语标题≤8/正文≤4、总≤48，守科目/category），关键词加权改用切分后术语。新增 _matrix_row_by_doc 反查。
2. 全量重建崩溃安全（core/rag/index_builder.py）：build_library_index(rebuild=True) 改影子构建（*.rebuild_tmp），内存摘块、先建向量矩阵，再 os.replace 原子提交 index/manifest/矩阵，提交后才清孤儿 npy；中途失败不触碰正式库；_build_vector_matrix 的 npy/json 也改 .tmp+os.replace。
3. 启动自检自愈（rag_knowledge.py）：_self_heal_index/_scan_backup_indexes/_count_library，正式库不足最佳完整备份一半判残、存 .corrupt 后回滚告警；/rag/status 新增 library_chunks/vector_matrix_chunks/index_healthy/restored_from_backup。
4. .xls 缓存自愈：缓存无效(_cache_ok=False)必须重新解析、按同科指纹幂等补全（cache_recheck），两个一造复习重点 xls 已重核、零重复。

### 科目边界自我纠正（重要，遵守既有拍板）
- 排查中一度误把一建归档目录 `学习资料库\_其他科目预留\一建教材（2026）` 加进 external_library.json roots 并增量补录 6552 块（库达 25927，含一建）。后核对本文件 2026-09-22「存储单一真源整合」用户已拍板"核心仅一造管理/一造水利案例，一建等不进前端不进 RAG、仅 roots 预留接口"，遂主动纠正：external_library.json 移除该 root（恢复仅 一造培训资料 一个 root），用新崩溃安全代码全量重建回到核心两科。一建教材物理文件未动，预留接口不变（将来加回 root 重建即接入）。
- 回归 reg_rag_retrieval 阈值同步改两科口径：总数≥15000、核心两科各≥1000，一建预留不做门槛。

### 验证（信源=实际运行，全绿）
- 崩溃安全双验证：①启动全量 rebuild 后 28 秒强杀，正式 index.json 块数/字节/mtime 纹丝不动；②回退一建后新代码完整跑通一次全量 rebuild——453/453 文件、19375 块、0 错误、24.7 分钟、原子提交，期间线上服务不中断。
- 磁盘终态：index=vectors.matrix(npy/json)=lib_*.npy 均 19375 三者对齐；科目 {一造管理 10574、一造水利案例 8801}；一建/预留来源泄漏 0；manifest 453；0 字节向量 0；影子/.tmp 清零、一建孤儿向量已回收；待 OCR 5（正常）。
- 提权重启后 /rag/status：documents=library=matrix=19375、index_healthy=true、restored_from_backup=false、ollama=true。
- 真机 HTTP 限定水利案例检索"赢得值法三参数四指标"：top1="第五章/赢得值法（挣值法）"(sim≈0.61、keyword_hits=16，含 CV/SV 公式)。
- 新增回归 reg_rag_retrieval：索引完整性 + 18 题黄金集(top5/top1 均 18/18=100%，阈值85%/70%) + 科目硬隔离跨科0 + 赢得值(水利案例)/经济寿命(管理)两专名兜底，ALL_ASSERTIONS_PASS。
- /rag/chat(qwen2.5:3b) 9 道核心真题端到端：作答 9/9=100%、要点正确 9/9=100%（赢得值三参数 C2/C3/拟完计划投资、四指标 CV/SV/CPI/SPI 准确）。
- 全量一键回归：14 PASS / 0 FAIL / 0 ERROR / 1 SKIP（共15项，新增 RAG 项），章节/案例/配图/真题零回退。

### 产物/备份
- 改：backend/api/v1/rag_knowledge.py、backend/core/rag/index_builder.py、backend/tests/regression/run_all.py（RAG 超时300s）；新增 backend/tests/regression/reg_rag_retrieval.py；backend/data/external_library.json（回退为单一一造 root）。
- 数据：backend/data/rag_knowledge/ 终态 19375；重建前旧库留有 index.json.bak_struct_* / .manualbak_* 等结构备份可追溯。
- 诊断报告附录 A8 已据实重写（含空库勘误、四处治本、科目边界纠正、19375 两科终态与全绿验证）。

### 未做/边界
- 一建等其他科目维持 root 外预留、不进 RAG（遵用户拍板）；接入=改 roots+重扫+崩溃安全重建，无需改代码。
- 新崩溃安全代码的"残库→启动自愈回滚"路径已有代码与演练保护，未人为造残库触发真实回滚（中断演练已证明正式库不会残）。
- 诊断/探针 RAG 检查改读 /rag/status 与 rag_knowledge 目录（而非弃用的 SQLite rag_embeddings）属探针治理长期项。

### 状态
✅ 问题4 治本销项：空库勘误、成功率 9/9=100% 并由回归门禁持续兜底、重建崩溃安全/启动自愈/专名硬召回/.xls 缺陷四治本，索引回到用户拍板的核心两科 19375 终态。

---

## 变更记录（2026-09-22）诊断报告问题6深化：离线同步覆盖矩阵实测、补齐笔记离线写、对齐能力声明并固化回归

### 需求
对照《系统交付级诊断报告》问题6「离线同步没跑通」逐层实测核对（不凭文档），报告不实要标记、真缺口从管线内核治本、对比销项进代码并加本地回归门禁。

### 报告论断核对（不实/过时先标记）
- "sync_records 0 行=没跑通、手机答题存 localStorage 不同步、换设备丢"对当前模块化代码不成立（过时勘误）：核心"手机离线答题→服务器"此前已修复销项（报告第五章勘误#5）。同步落库以 (user_id, operation_id) 唯一索引做并发幂等占位，不能只看某张表历史行数。
- 实测覆盖矩阵：后端 /offline_sync/batch 回放能力齐备；前端答题、收藏、闪卡复习(SM-2)、视频进度(固定 operation_id 幂等)、思维导图(save/delete)五类写操作均已入 IndexedDB 离线队列（offline-manager.js：shuili_offline_db/operation_queue，online 事件+启动4s 自动回放，杀后台不丢）。
- 两处真实缺口：①笔记(note)离线写未入队（后端 add/update/delete_note 回放本就有，前端4写入口+题目内嵌"存入学习笔记"离线只报错不入队）；②/sync/status 与 /offline_sync/status 的 supported_operations 只硬编码 6 类，与 process_operation 实际 12 类不符。

### 实现（全部 node --check / py_compile 通过；后端已提权重启生效；frontend/static 影子副本 md5 已同步）
1. frontend/modules/note/note.js：统一 _api 增加离线写切面——仅当 window.__ZHIXUE_OFFLINE__===true（手机/平板 Tailscale https）且 /note/ 的 POST/PUT/DELETE 网络失败或 503 时，映射 add_note/update_note/delete_note 调 OfflineManager.addOperation 入 IndexedDB，返回 {offline:true} 走成功路径；新建同时写 localStorage(zhixue_pending_notes) 乐观态（列表"⏳ 待同步"）；afterRender 一次性监听 offline-sync-complete，回放成功后清乐观态并重拉对齐真实 id；saveNewNote/saveEditNote/deleteNote/saveInlineNote 四入口据 offline 标志提示"离线已…，联网后自动同步"。在线(http本机/https在线)行为完全不变。
2. frontend/modules/question/question-practice.js：题目内嵌"存入学习笔记"网络失败 catch 由"仅 toast+localStorage 草稿"改为同时入 add_note 队列（草稿保留）。
3. frontend/offline-manager.js：批量同步成功后 window.dispatchEvent(new CustomEvent('offline-sync-complete'))，供笔记等模块最终一致刷新。
4. backend/api/v1/sync_unified.py：两处 /status 的 supported_operations 由 6 类补全为与 process_operation 一致的 12 类（补 review_flashcard、collect_add/remove、video_progress、mindmap_save/delete）。
5. 新增 backend/tests/regression/reg_offline_sync.py 并纳入 run_all（glob 自动纳入，默认超时足够）：status 列全12类；笔记 add→update→软delete(is_deleted) 回放落库；同 operation_id 重放 skipped；未知操作只标该条 failed 不拖垮同批；测试笔记硬删零残留；后端不在线 [SKIP] exit 0。

### 验证（信源=HTTP 探针+浏览器真机+回归，全绿）
- 后端探针：add_note 返回 note_id；同 operation_id 重放 skipped"操作已同步，跳过重复(并发幂等)"；update 落库内容正确；未知操作 failed 而同批 delete_note 成功；delete 置 is_deleted=1（软删，crud.delete_note 语义）；硬删后零残留。
- 浏览器真机（在线不回归）：笔记模块新建弹窗→保存→后端列表可见(id 落库)→删除(软删后列表过滤)，全程正常、控制台无错。
- 离线切面纯逻辑（置 __ZHIXUE_OFFLINE__=true 捕获 addOperation）：POST /note/create→add_note、PUT /note/99→update_note(note_id=99)、DELETE /note/99→delete_note 字段映射正确；新建写1条待同步乐观态；开关 false 时一律不入队（门控正确），测后还原。
- 提权重启后 /offline_sync/status supported_operations=12 类。
- 全量一键回归：15 PASS / 0 FAIL / 0 ERROR / 1 SKIP（共16项，新增 reg_offline_sync PASS），既有项零回退。

### 产物/备份
- 改：frontend/modules/note/note.js、frontend/modules/question/question-practice.js、frontend/offline-manager.js（含 static 影子副本同步）、backend/api/v1/sync_unified.py；新增 backend/tests/regression/reg_offline_sync.py。
- 前端改前备份：*.bak_offline_20260922_095241。
- 诊断报告：问题6原文处加 2026-09-22 复核勘误标记，文末新增附录 A9（覆盖矩阵/两处治本/回归/实测/边界）。
- 本轮一次性探针/补丁脚本 tools/_*.py、_runall_offline.log 已清零（正式回归在 tests/regression/）。

### 未做/边界
- /offline_sync/pull 用户数据"下行"在新架构未启用（frontend/sync-manager.js 未被 index.html 加载）；多端在线直连同一后端已保证最终一致（A 机同步后 B 机在线 fetch 即见），纯离线浏览他端新数据属增强项、报告真验收未要求。
- 笔记 update/delete 离线即时乐观态较弱（数据已入队不丢，联网回放后刷新生效）；新建已有"⏳待同步"乐观显示。
- 手机/平板 Tailscale https 真实断网→恢复演练在移动端专项（问题9）其他对话框进行；本机 http 下 __ZHIXUE_OFFLINE__ 恒 false（设计门控），前端断网路径以纯逻辑+后端回放回归覆盖。
- 学习进度无独立前端写点（后端由答题聚合），update_learning_progress 仅为预留操作。

### 状态
✅ 问题6 治本销项：报告"没跑通"勘误为过时；离线写队列在原有答题/收藏/闪卡/视频/导图闭环基础上补齐笔记，覆盖全部核心用户写操作；能力声明对齐 12 类；幂等/容错/软删/零残留由 reg_offline_sync 自动门禁持续兜底。

---

## 变更记录（2026-09-22）诊断报告问题7深化：题库版本号 / 增量更新 —— 后端增量分发治本 + 回归门禁，前端增量合并随问题9真机

### 需求 / 真验收
报告问题7（P0）：版本号接口 + 最后更新时间 + 启动查版本 + 变了才拉 + 增量 `?since`。真验收：①后端改一道题答案，移动端下次启动自动更新；②题库没改不重复下载；③增量只下载变更题。

### 论断核对（逐层实测，不实先标记）
- `/api/v1/system/version` 早返回 `last_question_update/question_total` 等——报告评分表"版本号完全没做"**不实**。
- `frontend/sw.js`（L299-336）对同源 `/api/` GET 为"网络优先竞速 3s + 缓存回退 + 后台刷新"，手机联网启动 3s 内取最新题库并覆盖缓存——**验收①在线已满足**，"改了不更新"在线场景**标记为部分失实**；弱网/离线回缓存与 questions.json 快照。
- 实测真缺口（报告未点出）：①`last_question_update` 只统计 is_deleted=0，删最新题版本戳不推进/倒退；②**模块化 `/api/qb/questions` 在 modules/qb/service.py 用 raw SQL 改/删题，不写 update_time/deleted_at（不触发 ORM onupdate），版本戳与时间戳增量对模块化路径全部失真（根因）**；③后端无 questions 级增量端点（incremental_pull 仅 notes/answer_logs）；④update-kernel.js 只比对 build_ts/sw_version，不消费题库版本；⑤models.Question ORM 漏映射表已有的 deleted_at 列。

### 实现（后端治本，已提权重启生效）
| 文件 | 改动 |
|---|---|
| backend/models/models.py | Question 补 deleted_at 列映射 |
| backend/crud/crud.py | soft_delete_question 补 deleted_at/update_time |
| backend/modules/qb/service.py | update_question raw SQL 补 update_time；delete_question、batch_delete_questions 补 is_deleted=1,update_time,deleted_at（修复根因） |
| backend/api/v1/question.py | 新增 GET /question/sync?since=&subject=&limit= |
| backend/api/v1/system.py | /system/version 增 question_version（全表 MAX(update_time) 含删除，单调），last_question_update 保留 |

- /question/sync 契约：无 since=首装全量活跃题 upserts（复用 _orm_question_dict，1249 与 question_total 对拍）、deletes 空；有 since=update_time>since，软删进 deletes(id)、活跃变更进 upserts；始终返回 server_version=全表 MAX(update_time) 含删除；支持 subject 过滤、limit 分页(has_more)。

### 验证
- HTTP 实测：全量 upsert=1249=question_total、deletes=0、has_more=false；since=当前版本→upsert=0/delete=0（验收②后端依据）；不存在科目→0。
- 新增 reg_question_sync.py（21 断言）ALL_ASSERTIONS_PASS：全量对拍/空增量/新增修改进 upserts/模块化 raw SQL 删除推进 update_time+deleted_at 并进 deletes+版本戳推进/科目过滤/零残留。
- 内联探针：QbService.update_question 改答案 A→C，update_time 同步推进（治本前不会），探针题物理硬删。
- 全量一键回归：**16 PASS / 0 FAIL / 0 ERROR / 1 SKIP（共 17 项，新增 reg_question_sync；reg_file_recognize 固定 SKIP）**，既有项零回退。
- bu 真机冒烟：后端重启后 /api/v1/question/list 与 /api/qb/questions 均 200、total=1249，题目页控制台无错误。

### 产物 / 备份
- 改：models/models.py、crud/crud.py、modules/qb/service.py、api/v1/question.py、api/v1/system.py；新增 backend/tests/regression/reg_question_sync.py。
- 后端改前备份：*.bak_qsync_20260922_101743。
- 诊断报告：问题7原文处加 2026-09-22 复核勘误块，文末新增附录 A10（论断核对/真缺口/治本表/契约/回归/边界）；报告长度 94423→100856。
- 本轮临时补丁/探针脚本 tools/_*.py、_runall_qsync.log 已清零（正式回归在 tests/regression/）。

### 未做 / 边界（如实）
- 移动端"启动查 question_version→变了才拉 /question/sync?since=→增量合并进本地题库库"需可增量合并的本地题库表（当前离线侧仅按 URL 单条 SW/DATA_CACHE 缓存 + questions.json 全量静态快照）与 HTTPS/Tailscale 真机闭环；按用户分工**随问题9（移动端真机）对话框接入**，接入点 GET /api/v1/question/sync?since=，后端契约与回归本轮先行就绪，不在无真机条件下半成品强塞。
- 电脑本机 http 直连零 SW 缓存、始终实时取数，不受影响。

### 状态
✅ 问题7 后端侧治本销项：含删除的单调题库版本戳 + 题库增量分发端点 + "ORM/模块化 raw SQL、单删/批删全路径改删都推进时间戳"齐备，由 reg_question_sync 自动门禁持续兜底；验收①在线已满足、②③后端契约就绪。前端瘦客户端版本门控与单题增量合并明确归问题9真机对话框。


---

## 变更记录（2026-09-22）诊断报告问题8「自动备份」深化治本——分层 gzip 备份 + 在线恢复 + 前端一键恢复 + 回归门禁（销项）

### 背景 / 实测（文档≠事实，小心求证）
- 报告“没有自动备份”**失实**：根 `auto_backup.py` 早已被 `start.bat` 以 pythonw 常驻拉起，`backups/auto_backup.log` 实测每小时 `backup ok`（09-21 08:28 → 09-22 06:29）；后端 `/api/v1/backup/*` 手动备份 API 也早已存在。
- 但真问题比报告设想更严重：旧守护**每小时** sqlite `.backup` 整库（213MB）+ `shutil` 整拷 `frontend/modules`（含大量 .bak），扁平 `backups/auto/YYYYMMDD_HHMM/` 仅留 KEEP=10 ≈ **10 小时回滚窗口**，10 份实测 **2.17GB**；不写清单、前端备份弹窗 0 备份、无自动备份恢复入口；`backup_manager` 清单 `backups/backup_manifest.json` 与“布局规范”清单**文件冲突**（首次手动备份会覆盖布局规范记录）；恢复用 `copy2` 覆盖 Windows WAL 活库有占用/不一致隐患；守护 06:29 后已停止。

### 治本（进代码）
- 重写根 `auto_backup.py`：只备库；`online_backup` 用 SQLite backup API 在线一致；hourly/daily 均 gzip（213MB→71.3MB）；分层 hourly 留 12 / daily 当天首份留 30 / safety 恢复前安全网留 10；原子写 `backups/auto/manifest.json`；`restore_online()` = gzip 解压 → 当前活库先 online backup 成 `safety/pre_restore_微秒.db` → `src.backup(live)` 页级覆盖 → integrity_check + 题数校验；127.0.0.1:**63187** 单实例端口锁；`once`/常驻 3600s；run_cycle/restore_online 参数化可测。
- 重写 `backend/api/v1/backup.py`：保留原 create/list/restore/delete/verify/stats；新增 `GET /backup/auto_list`、`POST /backup/restore_db {kind,name}`（后缀白名单 hourly/daily=`.db.gz`、safety=`.db` + basename 防穿越 + 不存在 404/非法 400 + 恢复前后 engine.dispose()）。
- `backend/utils/backup_manager.py` 清单改 `backups/manual_backup_manifest.json`，与布局规范解冲突。
- 前端 `frontend/modules/settings/settings.js`（已同步 static 影子副本、md5 一致）：备份弹窗新增“🗄️ 自动数据库备份”区（每日近 30 + 小时折叠近 12，名称/大小/时间 + 恢复按钮），新增 `window.restoreAutoDb`（强确认 → /restore_db → 成功刷新）；原手动区改名“手动备份（全项目）”；node --check 通过。
- 新增 `backend/tests/regression/reg_backup_restore.py`（15 断言，临时库不碰正式库）。

### 验证
- once 与常驻首轮真实产出：`daily/20260922.db.gz`、`hourly/20260922_1049.db.gz`、`hourly/20260922_1110.db.gz` 各 71.3MB，manifest counts 正确；守护 pythonw 存活、端口 63187 LISTENING、11:10 `backup ok`，此后每小时自动。
- 回归：`reg_backup_restore` **15 断言 ALL PASS**（分层保留 / gz 有效 / 篡改后从 hourly 与 daily.gz 在线恢复 / integrity ok / 安全网微秒防覆盖 / HTTP auto_list 200 / 非法 kind 400 / 路径穿越 400 / 不存在 404）。
- 全量 run_all：**17 PASS / 0 FAIL / 0 ERROR / 1 SKIP（共 18 项**，含 reg_question_sync、reg_backup_restore），既有项零回退。
- bu 真机：备份弹窗显示真实“每日备份 20260922.db.gz 71.3MB”与小时折叠、`restoreAutoDb=function`、控制台 0 错误（未实战点恢复以免动正式库，恢复正确性由临时库回归证明）。
- 专家 `latest_report` 重跑：全为历史已知结构性 warning（缺失模块、新旧 API 并存、Ollama 未启、硬编码、RAG 探针查弃用表等），**无一条指向本轮改动、无新增**。

### 产物 / 备份
- 改：`auto_backup.py`（根，备份 `auto_backup.py.bak_q8_*`）、`backend/api/v1/backup.py`、`backend/utils/backup_manager.py`、`frontend/modules/settings/settings.js`（+ static 影子副本）；新增 `backend/tests/regression/reg_backup_restore.py`。
- 真实备份产物 `backups/auto/{hourly,daily}/*.db.gz`、`manifest.json`（勿删）。
- 诊断报告：问题8原文处加 2026-09-22 复核勘误块，文末新增附录 A11；报告长度 100856→105317。

### 未做 / 边界（如实）
- 旧版 10 个扁平目录 `backups/auto/YYYYMMDD_HHMM/`（约 2.1GB）新版不识别也不清理；**删除不可逆，待用户确认后清理**（确认新版稳定前保留）。
- safety 安全网“微秒防覆盖”为磁盘最终代码，运行中后端在其后一次自然重启前加载的是秒级命名版（功能等价，仅同秒连续两次恢复的极端情形可能覆盖，人工弹窗恢复不触发）；hourly/daily gz 与 `/restore_db` 运行中已是最终版；守护进程已用最终版。
- 手动“全项目备份”（含 frontend 整目录）能力保留，清单独立为 `manual_backup_manifest.json`，与自动库备份分工。

### 状态
✅ **问题8 治本销项**：真验收三条（每天 1 份留 30 天 / 能在线恢复且恢复前自动安全网 / 旧备份自动清理）全部达成，`reg_backup_restore` 门禁持续兜底；常驻守护已拉起、每小时自动。唯一遗留=旧 2.1GB 扁平目录待用户确认后清理（不可逆，不擅删）。

---

## 变更记录（2026-09-22）诊断报告问题10「重复题去重细度不够」深化治本——题干 SimHash＋海明鸽笼粗筛（60秒→1秒）＋可恢复标记＋答案门槛＋回归门禁（销项）

### 背景 / 实测（文档≠事实，小心求证）
- 报告“只按 content_hash 去重、近似题/跨源同真题去不掉”**部分失实**：系统早有 `utils/deduplication.py`（Jaccard 0.3＋SequenceMatcher 编辑距离 0.4＋字符余弦 0.3 组合）、考点分组、`/deduplication/scan?method=combined`、`/auto_merge` 与设置页“智能去重”弹窗（阈值 60/70/80/90）。
- 但实测挖出报告未点出的真缺陷：①完全无 SimHash/海明距离；②**ORM `Question` 漏映射表已有的 content_hash/duplicate_of/duplicate_reason 三列**，getattr 恒空→MD5 预过滤失效→全量 O(n²)，1249 道活跃题扫描 60-67 秒；③/scan、/auto_merge 在预过滤阶段把 content_hash 完全相同的精确重复组直接丢弃（最该合并的漏处理）；④/auto_merge 软删 is_deleted=1、只比 title+option_a、不写追溯、不可恢复；⑤merge_point_duplicates 写表中**不存在的 duplicate_type 列**、异常被 try/except 吞，考点合并实际失败；⑥L3 仅密度提示，与“同知识点＋同答案”语义不符；⑦385 道活跃题 content_hash 为空。
- 连带发现：`GET /question/sync` 的 server_version=MAX(update_time) 被 strftime **截断到秒**，同秒批量提交的题在 since=该版本 时仍被误判更新（空增量误报，批量去重标记稳定触发，reg_question_sync 一度 FAIL=52）。

### 治本（进代码）
- `utils/deduplication.py` 末尾新增 SimHash 段：指纹/主判据**只取规范化题干** normalize(title)（避免“甲乙丙丁/对错”通用选项主导指纹；选项仅作一致性辅助≥0.5，无选项的判断/案例题不卡）；SimHash 64 位 unigram+bigram（bigram 权重2、MD5 派生比特）；`_band_candidate_pairs` 64 位分 4 段 16 位、鸽笼原理保证海明≤3 至少一段相同，O(n²)→少量候选对；候选对 combined（含编辑距离）精判过阈值；DSU 并查集聚组。L3 point_answer 按（规范化知识点, 规范化答案：去非字母数字＋大写＋多选字母排序）分组，再要求海明≤10、精判≥0.80、选项一致；密度提示 point_density 单独返回不并入待删。修 merge_point_duplicates 改写 is_duplicate/duplicate_of/duplicate_reason。
- `models/models.py` Question 补三列映射 content_hash(String64,index)/duplicate_of(Int)/duplicate_reason(String256)。
- 整体重写 `api/v1/deduplication.py`：/scan 走 scan_questions_core，统一返回 L1-exact/L2-simhash 组＋point_answer＋point_density（字段对齐前端弹窗）；/auto_merge 改**可恢复标记**（不软删），L2 规范化答案不一致跳过、计 answer_mismatch 留人工，返回 by_layer/message；新增 /mark、/restore（body 字段名 **question_id**，规避 main.py 全局中间件删除裸 id）、/merge_group（标记语义）；/report 保留。
- `api/v1/question.py` /question/sync server_version 保留微秒（%f），消除同秒边界误报。
- 保留运维脚本 `tools/backfill_content_hash.py`（幂等补指纹，本轮补 385 道）、`tools/mark_exact_duplicates.py`（L1 标记、沿 duplicate_of 链解析最终保留题）。
- 前端（settings.js 两份＋app_v3 两份，node --check 通过，SW CACHE_NAME 与 index 指纹 bump）：默认阈值 0.7→0.9；扫描文案“约1-2分钟”→“通常1-2秒”；三层说明改 content_hash / SimHash海明＋编辑距离 / 同知识点同答案人工审核；消除自动合并双重确认（单次、文案如实：标记不删题、答案不一致跳过）；自动合并沿用弹窗阈值与 method=combined（所见即所合并），toast 显示后端标记/跳过数。

### 验证
- 构造题集自测（9题）：标点差海明0、加空格/约字海明0-2、无关题海明28-32；题干不同即便选项相同也不误并。
- 真实库 1249 活跃题：前端同源 method=combined 扫描实测 **1092ms（旧60-67秒，约60倍）**；threshold=0.9 检出重复71/组55/唯一1178/同知识点同答案14组，L2 抽样均为跨 3xxx/4xxx/5xxx/6xxx 来源的同一真题。
- 数据落地：content_hash 回填385（活跃全有）；精确6组逐题人工核对后标记；自动标记新标52（精确1/近似42/同知识点同答案9），全库活跃标记重复 **91、去重后可出题 1158**；**8 道答案不一致题（6104/5515/5105/6086/5956/5974/6030/6249）全部 is_duplicate=0 保留可出题、留人工**。
- 回归：新增 `reg_dedup_simhash.py` **33 断言 ALL PASS**（纯算法15＋HTTP双方法秒级只读7＋探针 mark/restore 端到端含练习过滤/恢复/零残留11）。全量 run_all：**18 PASS / 0 FAIL / 0 ERROR / 1 SKIP（共19项）**，含连带修复后的 reg_question_sync，既有项零回退。
- bu 真机：智能去重弹窗默认90%、扫描秒级、L1/L2/考点组与统计正确、自动合并仅1次确认文案准确、控制台0错误。
- 专家 144 位重跑：0 error/critical、28 warning 均历史已知（缺失模块/新旧API并存/DB213.8MB/硬编码/巨型文件6/>500KB JS7/原生弹窗），数量级稳定、无新增。

### 产物 / 备份
- 改：`backend/utils/deduplication.py`、`backend/api/v1/deduplication.py`（整体重写）、`backend/models/models.py`、`backend/api/v1/question.py`（仅 server_version 微秒）、`frontend/modules/settings/settings.js`＋static 影子、`frontend/js/app_v3_897262.js`＋static 影子、`frontend/index.html`（指纹）、`frontend/sw.js`（CACHE_NAME）。
- 新增：`backend/tests/regression/reg_dedup_simhash.py`、`backend/tools/backfill_content_hash.py`、`backend/tools/mark_exact_duplicates.py`（后两者保留为运维脚本）。备份：`*.bak_q10_20260922_113024`。
- 诊断报告：问题10原文处加 2026-09-22 复核勘误块、闭环总表问题10打钩、文末新增附录 A12；报告字符 105317→110009。

### 未做 / 边界（如实）
- 去重弹窗 UI 暂未加单题“恢复”按钮（后端 /restore 能力与回归已就绪；加按钮属界面变更，按布局锁死约定未自行扩 UI）。
- 8 道答案不一致题保留人工裁决，不自动隐藏。
- 全局中间件会从 POST body 删除裸 id 等系统字段，今后新 POST 端点字段名须避开（已在代码注释标明）。
- 进程侧教训：排查期间多次提权 restart 与系统双层守护（system_monitor＋watchdog）并发、又手动前台起 main，造成多实例进程树互杀（与去重代码无关，前台 main 曾稳定服务7分钟、回归全PASS）；最终由原生 watchdog 兜底拉起、稳定托管，后续不再手动前台起 main、不在看门狗自发重启窗口并发 restart。

### 状态
✅ **问题10 治本销项**：真验收三条（改几个字能识别 / 不同PDF同真题能合并 / 刷题刷不到重复）全部达成，`reg_dedup_simhash` 门禁持续兜底；标记可恢复、答案不一致留人工、数据不丢。连带修复问题7增量同步 server_version 秒级截断边界。


---

## 变更记录（2026-09-22 任务C完成：SRS 4档调度后端联调）

### 需求
前端 read-practice.js 判分从 localStorage 暂存切换到真实后端 API，对接 FSRS 4档调度。

### 实现
1. **scheduler.py 路由双重前缀修复**：prefix 从 `/api/mt/recall` 改为 `/recall`（被 include 到 /api/mt 下，最终路径 /api/mt/recall/*）
2. **SM-2 ↔ FSRS 桥接公式修复**：
   - 旧：`new_ease = 2.5 + (5 - difficulty)/2`，新卡 difficulty=10 时算成 0.0（bug）
   - 新：线性映射 ease=2.5↔diff=1, ease=1.3↔diff=10，读/写双向
3. **read-practice.js _submitGrade 接真实 API**：
   - 旧：localStorage.rp_grade_log 暂存
   - 新：async POST /api/mt/recall/grade，失败 fallback localStorage
   - payload 含 card_id/grade/recall_mode/peeked/spoken_text/read_count/read_duration_ms/read_cpm/read_misses

### 验证
- GET /api/mt/recall/queue?limit=5 → 200，5 张卡无 back 字段（遮蔽成功）
- POST /api/mt/recall/grade（浏览器实测）→ 200，mt_recall_logs 写入 id=3
- 数据库核对：flash_cards 表 ease_factor/interval_days 更新正常
- tools/startup_verify.py = 27 PASS / 0 FAIL

### 状态
✅ 任务C完成。主链路三阶段（朗读→遮蔽复述→4档自评）+ SRS 后端闭环打通。


---

## 变更记录（2026-09-22 P1-4/P1-5/P1-6 批量）

### P1-4 任务B补全：采分点+错误细分类+单位陷阱
- GRADE 阶段加错误类型下拉（数字粗心/概念混淆/单纯口误/审题失误/知识点不懂）
- GRADE 阶段加采分点勾选区（如卡有 answer_points_json）
- 确认判分按钮替代直接提交，payload 含 wrong_type/points_covered/points_total
- 浏览器实测 wrong_type=number_error 写入 mt_recall_logs

### P1-5 任务E记忆大师8项（核心项）
- READ 阶段顶部加"预回忆"开关（localStorage.rp_pre_recall 持久化）
- READ 阶段右下角显示记忆锚点（口诀前4字，浅灰极小）
- RECALL 阶段加"💡 给个提示"按钮，逐级释放线索（关键词→双词→完整口诀）
- 浏览器实测：提示3次点击后显示完整口诀"固投（主固）、交工"

### P1-6 任务F应试专项（核心项）
- 后端：wrong_type=slip（单纯口误）不更新 SRS，只写日志
- 前端：连续3次 grade>=3 弹出疲劳预警 toast
- 其余17项中的限时模考/反向提问/变序提问等留待后续按需开启

### 验证
- tools/startup_verify.py = 27 PASS / 0 FAIL
- 注：slip 跳过 SRS 为后端改动，需重启后端生效


---

## 变更记录（2026-09-22 P2-7/P2-9）

### P2-7 任务G：环境噪音监测
- _startReadMic 里加 Web Audio API AnalyserNode 噪音检测
- 每 800ms 采样 RMS，>0.08 时在 pronHint 显示红色警告"环境噪音较大，建议换安静环境"

### P2-9 草稿板
- RECALL 阶段加可折叠草稿板（details/summary）
- textarea 写核心数字/公式，不影响判分

### 待重启生效
- 后端 scheduler.py slip 跳过 SRS 改动需重启

### 状态
P0-P1-P2 核心模块全部完成。AI 克隆音色（P2-8）为独立大工程，留作后续专项。


---

## 2026-09-22 一造水利案例·第五章《水利工程合同价款管理》16个教材案例入库 —— 全教材五章73题收官（B阶段）

### 一、范围与来源（真实教材原文，零编造）
- 来源：学习资料库 id=521《教材-2024一造水利案例.pdf》第五章，物理页 p217–262（书内印刷页 p209–254，偏移−8，已用“第五章/案例一~十六”逐页关键词校准）。
- 全章共 **16 个案例（案例一~十六）**，全文 66008 字符/2060 行 dump 至 `题库质检_20260921/教材原文/第五章_p217-262.txt`，案例边界以逐页 Grep“案例X”核对（教材书签第五章0个、实有16个）。
- 入库 id **6308~6323**，chapter=“第五章 水利工程合同价款管理”，title 前缀【教材案例五-N】，year 空、source_kind=教材例题、case_total_score=20、is_deleted=0；小问分值合计均=20（脚本 assert）。脚本 `import_ch5.py`（幂等按 title 判重，len(cases)==16 断言）。
- **特别说明（保真）**：案例十六教材正文止于“分析要点”（赢得值法 BCWS/BCWP/ACWP、CV/SV、CPI/SPI 公式与步骤），**未印标准答案数字**；入库时背景/问题/公式照录原文，答案严格按教材公式与表5-12、5-13数据复算（SPI=0.875、CPI=1.155、预计最终4761.43万元），并在 top、两小问 analysis 中**显式标注“教材未附标准答案，数字为按教材公式复算”**，不冒充教材原答案。

### 二、16题清单与教材原文关键答案（数字以 dump 原文为准，关键数已经计算器复算一致）
- 五-1 合同类型与结算 p217-220，4问：三类型；预付款8000×15%=**1200**，至上月底累计扣回R=1200/5600×(3500−1600)=**407.14**；本月未审核变更50不计、完成600、累计4100，累计扣回**535.71**、本月扣**128.57**，质保金总额240/已扣210/本月只扣剩余**30**，本月结算=600−128.57−30=**441.43万**（≥400支付）；已交履约担保不得同时预留质保金（建质〔2017〕138号）。
- 五-2 计量与价款结算 p220-223，4问：填筑需自然方=360000×1.045×1.7/1.55=**412606m³**>386000需借土；完工结算按图纸有效压实方356600×20=**7132000元**（非签证362000/清单360000）；文物计日工160万列暂列金额；暂估价=2500+(3000−2500)×1.09=**3045**，其他项目=160+3045=**3205万**。
- 五-3 预付款进度款完工结算(一) p223-225，4问：F1/F2越大扣越慢对承包人越有利；工程预付款**1500**、材料预付款**450**（第1~9月每月扣50）；起扣1500/扣清13500；第2月累计1200不扣付**650**、第3月累计2000工程预付款累计扣回62.5（教材印**63**）付**687**、第14月累计14200扣清本月扣25付**875**、第15月无扣付**800**；完工总额=15000+500=**15500万**。
- 五-4 预付款进度款完工结算(二) p225-230，4问：提交经认可预付款保函后监理方出付款证书；起扣250/扣清2250、材料预付270第2~7月每月扣45、安全费62.5首月付50%；各月：第1月100+270+31.25=**401.25**、第2月**105**、第3月**270**、第4月**567.50**、第5月**611.25**、第6月**251.25**、第7月55<100结转、第8月75<100转完工结算；农民工工资不得拖欠、人工费按月足额拨专用账户；完工付款申请单完工证书后28天、最终结清申请单保修责任终止证书后28天，完工申请单四项内容。
- 五-5 变更与索赔(一) p230-235，1综合问6事件：洪水不可抗力（工期可赔利润不赔、费用各自承担——甲水泥5t赔/灌浆泵不赔、乙空压机2.5万与临时道路不赔）；文物（甲工期+费用、30万计日工走暂列金额）；最强降雨（看是否构成异常恶劣气候、达标准一般只赔工期）；发包人交通桥未定致关键线路电梯推迟30天（工期+费用+利润）；监理指示缆机改自卸汽车入仓（变更，强度680→480工期增，按关键线路或与总时差比较）；钢材涨价（锚杆单价子目按约定调、总价承包基坑排水不调）。
- 五-6 变更与索赔(二) p235-238，4问：变更估价三原则；事件1关键项目石方明挖增超15%属变更、事件2喷层20→15cm改变质量特性属变更、事件3新增锚索属追加额外工作属变更、事件4锚杆排水孔非关键项目不属变更；月强度578443/5=115688.60、工期索赔197100/115688.60=**1.70月**、调整后综合单价**56.92元/m³**；完工结算七项合计**54844089.61元**（石方明挖44142786.90、喷砼1782555.20、排水孔585062.73、锚杆1497913.56、锚索1176510.15等）。
- 五-7 变更与索赔(三) p238-240，2问：暴雨先看专用条件是否界定异常恶劣气候、达不到视为可预料不赔；渗水量19200→35000变更合理，承包人报原价2倍（1574640）两错（不能按全工期180天应分段60+120天、未考虑台时随渗水量变化）；台时单价=787320/4320=**182.25元/h**，前60天24×60×182.25=262440、后120天43.75×120×182.25=956812.50，变更合同价=**1219252.50元**。
- 五-8 索赔(一) p240-242，2问：晚交场地5天+避让缆机停工5天=**10天**（道路整修2天与本项目无关）；人员45人窝工45×30×10=**13500**、机械闲置只算一类费=**8671.70**、利润(13500+8671.70)×7%=**1552.02**，合计**23723.72元**。
- 五-9 索赔(二) p242-246，4问：发包人迟供渣场赔工期10天+窝工闲置+利润，承包人自误30天自担；6项赶工费逐项：降效142500不成立（效率翻倍3.756→7.512、剩余893.66m需119d、责任工期119−30+10=**99d<可用111d**不降效）、施工支洞**523800合理**（变更新增工作）、人员进退场37600/保险28130/机械进退场26630均重复计价不成立、加班工资218720不成立（效率不变无需加班）；审核按图纸量+变更三原则+投标标准；要求4月23日完工则可用89d<责任工期99d认定赶工降效。
- 五-10 变更及合同价调整(一) p246-248，4问：合同规定合理（关键项目超约定%且实质性变动才调价、风险共担）；量增超15%固定成本已分摊超出部分单价应降、量减用AP补偿未摊销措施费/安拆费/进出场费/管理费；实际55万：51.75×39.05+3.25×36.08=**2138.10万**；实际42.5万（减5.56%≤15%）：42.5×39.05+2.5×39.05×6.4%=**1665.87万**。
- 五-11 变更及合同价调整(二) p248-250，3问：量变影响工期/方案与成本（量减单位固定成本增不利）；变化率土方5.19%<15%不变更、混凝土18.78%>15%变更；混凝土报价69721800、固定成本20916540，反算单位变动成本**167.22元/m³**，减少后总价61208770.40、新单价**324.27元/m³**；土方1584563.73×20=31691274.60，最终价款合计**92900045.00元**。
- 五-12 变更及合同价调整(三) p250-252，2问：系船柱基础图纸已明示、图纸（优先顺序第7位）优先于已标价工程量清单（第8位），不属新增变更；新渣场平均运距未超招标文件（最远远3km）不引起实质性变动单价不调；锚杆减20%按“是否关键项目/幅度/是否实质性变动”三要件判断，一般仅数量增减价格不调。
- 五-13 物价调价(一) p252-254，1问：定值权重0.15、材料0.45(100→120)/人工0.25(150→168)/机械0.15(130→156)，ΔP=1000×[0.15+(0.54+0.28+0.18)−1]=**150万**，清单项目调价后1150、变更150（已按现价不调）、材料预付款100照付，该月支付**1400万**。
- 五-14 物价调价(二) p254-256，3问：定值权重=承包人风险、变值=发包人承担，涨时定值越小越有利/跌时越大越有利；6月土方308.394+石方1868.634+边坡626.088=**2803.116万**；甲供水泥占20%扣400万、混凝土材料权重0.40→0.20、定值0.14→0.34，12月边坡325.41+灌浆608.35+混凝土(2000×系数−400)1747.94=**2681.70万**。
- 五-15 违约责任 p256-260，3问：Ⅰ区正常完工、Ⅱ区延误40天，违约金2000×3‰×40=240万、封顶3000×5%=**150万**，按150万赔偿；质保金Ⅰ区30/Ⅱ区60，完工证书后14天各退一半（15、30），Ⅰ区漏水修补20从质保金扣，保修满最终结清退60+30−30−15−20=**25万**；签约前已交履约担保的不得同时预留质保金、进度款中不预留。
- 五-16 赢得值偏差 p260-262，2问（**教材未附标准答案、按公式复算**）：BCWS=C1累计4000、BCWP=C2累计3500、ACWP=C3累计3030；SV=−500、**SPI=0.875<1进度延误**；CV=+470、**CPI=1.155>1造价节约**；偏差持续预计最终造价=5500/CPI=5500×3030/3500=**4761.43万元**。

### 三、三层验证（全绿）
1. DB：PRAGMA integrity_check=ok；水利案例活跃 **73**（一10+二15+三16+四16+五16）、全库活跃 **1265**；第五章=16。
2. API：/api/qb/all?subject=一造水利案例 code=200 回读 **73** 题。
3. 浏览器（Playwright `ui_ch5.py`）：顶栏切“一造水利案例”后五章计数 **10/15/16/16/16**；切科目后等2.5s章节树仍在（旧两处竞态修复持续有效）；勾选第五章遍历16题、显示答案一次性 eval_on_selector_all 全部展开；14组关键数字（五-1的1200/407.14/441.43、五-2的412606/7132000/3205、五-3的687/875/15500、五-4的401.25/567.50/611.25/251.25、五-6的1.70/56.92/54844089.61、五-7的182.25/1219252.50、五-8的23723.72、五-9的893.66/99/523800、五-10的2138.10/1665.87、五-11的167.22/324.27/92900045、五-13的150/1400、五-14的2803.116/2681.70/1747.94、五-15的240/150/25、五-16的0.875/1.155/4761.43）全部命中；**0 pageerror**。标题匹配 key 用“五-N】”精确片段，规避“五-1”被“五-10”子串抢占。截图 `ui_第五章_赢得值偏差.png` 已 Read 肉眼核验（布局未动、中文正常、复算标注清晰）。

### 四、全教材五章收官总览（B阶段真实数据建设主体完成）
| 章 | 章名 | 题数 | id区间 | 物理页 |
|---|---|---|---|---|
| 一 | 水利工程造价构成 | 10 | 6251~6260 | 约p?（已入库） |
| 二 | 工程经济 | 15 | 6277~6291 | p53~83 |
| 三 | 水利工程计量与计价应用 | 16 | 6261~6276 | p84~169 |
| 四 | 水利工程招标投标 | 16 | 6292~6307 | p170~216 |
| 五 | 水利工程合同价款管理 | 16 | 6308~6323 | p217~262 |
| 合计 |  | **73** |  | 教材全部案例主观大题 |
- 全部为2024官方教材原文案例，year 空、source_kind=教材例题、case_total_score=20；**官方不公布《案例分析（水利）》真题，水利“真题”分类永远为0，无一条AI编造真题/假数字**；AI假题#5819维持软删。
- 产物：入库 `import_ch5.py`、提取 `dump_ch5.py`/`locate_ch5.py`、原文 `教材原文/第五章_p217-262.txt`、回归 `ui_ch5.py`、截图 `ui_第五章_赢得值偏差.png`。前端、布局零改动（本轮仅题库数据入库与只读验证）。
- 后续题源（未启动）：模拟卷资料库 id=649/650/651（题答分离需对齐）、章节题 id=1112（带解析，可甄别恢复）；id=152-163 为“一建水利水电”勿混入一造水利。


---

## 变更记录（2026-09-22 P2-8 语速滑块 + 后端重启）

### P2-8 TTS 语速滑块
- READ 阶段底部加 TTS 语速滑块（0.7x-1.3x，步进0.05）
- 滑块值存 localStorage 'speak_rate'，TtsService 自动读取
- 与磨耳朵 tab 共用同一语速设置

### 后端重启
- 旧进程（WMI 启动，高权限）无法 taskkill
- 直接 Start-Process python main.py 启动新实例
- slip 跳过 SRS 改动已生效

### 验证
- tools/startup_verify.py = 27 PASS / 0 FAIL


---

## 变更记录（2026-09-22 全部优化收尾）

### 新增功能
1. **错题池标签**：topbar 显示红色"错题池"标签（card._pit_priority>0）
2. **录音存档开关**：READ 阶段 checkbox，存 localStorage rp_save_rec
3. **题干提示词清除开关**：READ 阶段 checkbox，清除"是什么/有哪些"等提示词
4. **模考倒计时开关**：READ 阶段 checkbox，开启后 RECALL 阶段 60 秒倒计时，超时自动 GRADE
5. **BGM 开关**：磨耳朵 tab，默认关闭，提示"不可用于背诵/自测"
6. **TTS 语速滑块**：READ 阶段底部，0.7x-1.3x，与磨耳朵共用

### 验证
- tools/startup_verify.py = 27 PASS / 0 FAIL

### 全部功能清单（P0→P2）
- P0：文本预处理底座 + 三阶段状态机 + SRS后端闭环 + 主辅隔离警示条
- P1：错误类型5分类 + 采分点勾选 + 预回忆开关 + 记忆锚点 + 阶梯线索3级释放
- P1：slip口误不更新SRS + 疲劳预警（连续3错）+ 环境噪音监测
- P2：草稿板 + 语速滑块 + 录音存档开关 + 题干提示词清除 + 模考倒计时 + BGM开关


---

## 变更记录（2026-09-22 重启脚本）

### restart_backend.bat
- 项目根目录新增 restart_backend.bat，仅重启后端（不启动VS Code/浏览器/Ollama）
- 流程：netstat找8000端口PID → taskkill /F /PID → WMI启动新main.py → curl验证
- 以后后端改动后直接跑 `restart_backend.bat` 即可，无需用户手动重启


---

## 变更记录（2026-09-22 收尾）

### 新增
1. **记忆漂移监测**（后端）：连续两次相同 wrong_type → drift_count++
2. **反向提问按钮**（前端 GRADE）：互换 front/back，训练反推能力
3. **本轮统计**（topbar）：显示本轮已判分数

### 验证
- restart_backend.bat HTTP 200
- tools/startup_verify.py = 27 PASS / 0 FAIL


---

## 变更记录（2026-09-22 多感官联动）

### 新增
- **多感官极简联动**：朗读阶段识别到关键词时，答案卡片短暂蓝色高亮边框（400ms），不闪烁动画、不加音效
- **反向提问按钮**：GRADE 阶段"🔄 反向问我"，互换 front/back 训练反推
- **本轮统计**：topbar 显示已判分数
- **记忆漂移监测**：后端连续两次相同 wrong_type → drift_count++

### 验证
- 27 PASS / 0 FAIL


---

## 变更记录（2026-09-22 序列位置+自适应+诊断看板）

### 新增
1. **序列位置防护**：本轮结束追加中间30%-70%位置 grade>=3 的卡复测
2. **自适应提取难度**：mastery>50 的熟练卡 TTS 自动提速10%（⚡标记）
3. **诊断看板**：topbar 实时显示 ✅完整/⚠️数字错/🔀概念混/❌完全忘/💬口误 计数
4. **耳机提示**：首次进入朗读训练 toast 推荐半开放耳机
5. **生理提示**：磨耳朵 tab 加骨传导差异说明


---

## 变更记录（2026-09-22 易混对抗+听觉自测+变序提问）

### 新增
1. **易混对抗回忆**：GRADE 阶段有 pair_group 的卡显示"⚔️ 对抗回忆"按钮，弹同组易混概念问题
2. **听觉专项自测**：READ 阶段"🎧 听觉自测"按钮，隐藏文字5秒只播放 TTS
3. **变序提问**：GRADE 阶段"🔀 换个问法"，3种随机问法（请口述/考场遇到/闭卷回忆）

### 验证
- 27 PASS / 0 FAIL


---

## 变更记录（2026-09-22 录音存档）

### 新增
- **录音存档**：READ 阶段开启"录音存档"后，MediaRecorder 录制朗读音频
- GRADE 阶段显示 `<audio controls>` 回放
- 判分后 URL.revokeObjectURL 判完即焚，不占存储
- 默认关闭，仅本地不服务端存储


---

## 变更记录（2026-09-22 冲刺模式）

### 新增
- **冲刺模式开关**：READ 阶段 checkbox，开启后只保留 mastery<30 的薄弱卡，切换时重新开始本轮


---

## 变更记录（2026-09-22 专项复盘+最终收尾）

### 新增
- **专项类型筛选**：READ 阶段下拉，按 concept/formula/comparison/error/process 筛选卡片
- 与冲刺模式可叠加（类型+薄弱双重过滤）

### 最终功能全景
**主链路**：朗读≤2遍→遮蔽复述（peeked检测）→4档自评→FSRS调度
**认知增强**：预回忆/记忆锚点/阶梯线索3级/多感官高亮/疲劳预警/噪音监测/序列位置复测/自适应语速
**应试专项**：5类错误细分/采分点勾选/单位粗心/模考倒计时/题干提示词清除/反向提问/变序提问/易混对抗/冲刺模式/专项筛选/听觉自测/记忆漂移
**辅助支线**：磨耳朵tab（警示条+BGM开关+语速滑块+生理提示）/草稿板/录音存档（判完即焚）
**后端**：queue遮蔽下发/grade写日志/SRS更新/slip跳过/错题池优先/漂移监测


---

## 变更记录（2026-09-22 交付收口：过时题门禁补标 + 稳定性韧性治本 + 全套交付文档）

### 背景与实测（不凭文档，全部真机/HTTP/SQL/回归）
- 对照《系统交付级诊断报告》交付前必查清单与甲方 12 项交付物清单逐项实测。
- 真机逐一切换 19 个模块：18 个 SPA 模块全部渲染、无空壳、JS 错误 0；系统管理中心独立页正常（需求 78/78、全绿）。核心刷题真机走通。
- 性能真机实测：翻题中位 13ms/最大 23ms（要求<100ms）；冷首屏约 2.7s（要求<3s）；核心只读接口中位均<500ms。
- 实测期间后端两次不可达，定位根因为**部署机整机内存枯竭**（Ollama 7B≈2GB + DevEco≈1GB + 多个 Doubao≈2GB 同开，可用内存一度 0.37–1.4GB），AI 推理换页、进程被系统回收；app.log 无代码 traceback，属环境非代码缺陷。

### 治本（改管线/内核，非表面）
1. **过时题（问题2）深化 + 门禁**：强关键词扫描 + 逐道人工确认，补标 3 道漏网（id 6202 TOT、6203 PFI/BOT、3775 ABS，2025 版教材删项目融资模式整章），共屏蔽 **28 道**；取题 4 处源码均含 is_outdated 过滤，可练池∩过时题=0（零泄漏）。新增运维脚本 `backend/tools/mark_outdated.py`（dry-run/仅人工确认 id 落标）。
2. **稳定性韧性治本（真实盲区）**：`backend/utils/ai_busy.py` 的 busy_info() 增加**置标志进程 pid 存活校验（psutil）**——后端在忙时崩溃/被回收导致残留忙标志时立即失效并清理，看门狗可秒级兜底，不再被"假忙"拖到二级监控约 10 分钟；进程存活则维持豁免、绝不误杀合法案例批改；psutil 不可用退回 25 分钟 MAX_AGE。
3. 核查确认既有防护：AI 调用本地模型 120s/降级 60s 超时、AI 问答为同步 def 走线程池不阻塞事件循环、看门狗轻量探针 unknown 先复核不误杀。

### 验证（自动化回归，进代码门禁）
- 新增 `reg_outdated_gate`（13 断言）、`reg_ai_busy_watchdog`（13 断言）。
- 全量 `tests/regression/run_all` 实测：**20 PASS / 0 FAIL / 0 ERROR / 1 SKIP，共 21 套件**（SKIP=reg_file_recognize 手动工具）。
- ai_busy.py 改动已通过 restart_backend.ps1 提权重启后端 + 看门狗加载，health 正常。
- 当前 /system/version：活跃题 1271、净题 1157、过时 28、重复 91、知识点 235、错题 581。

### 产物（docs/ 交付文档，8 份）
- P0：部署指南、用户使用手册、验收报告、备份恢复指南。
- 增强：管理员运维手册、测试报告、版本说明、已知问题清单。
- 旧 docs/部署手册.md、docs/恢复手册.md 顶部加"已废弃、以新文档为准"声明（旧文含"路径不能中文"等不实表述，已纠正）。
- 诊断报告：必补文档清单打钩、问题2 章节补深化、文末新增附录 A13（含对报告不实/过时论断的标记）。

### 未做 / 边界（如实）
- 问题9（手机/平板真机、Tailscale 外网、移动端题库增量合并）按用户分工归其他对话框，本任务不碰；后端增量/离线写队列/网络优先缓存已就绪。
- "连续运行 24h 不崩"未做满 24h 压测，验收报告如实标为待补测（双层自愈已具备）。
- API 文档（P2）、独立培训课件未单独成册，已在验收报告/已知问题清单登记。
- 待用户拍板（不可逆，未擅动）：backups/auto 旧 10 个整盘备份目录约 2.1GB 清理；去重弹窗单题恢复按钮（布局锁死）；8 道答案不一致题（6104/5515/5105/6086/5956/5974/6030/6249）人工裁决。
- 部署机建议 16GB 内存、运行时关闭 DevEco Studio 等内存大户（已写入部署指南/已知问题）。

### 状态
- 问题 1–8、10 在 PC 本地范围闭环并具备回归门禁；交付前必查清单 PC 项全部达标；4 份 P0 + 4 份增强文档交付。PC 本地版具备交付条件，移动端与 24h 长稳另行验收/补测。


---

## 第二阶段·三套2023环球模拟卷18题入库收官（2026-09-22）

### 一、目标与铁律
- 在第一阶段官方教材73个案例大题(已100%入库并三层验证)基础上，建设第二批可溯源题源：资料库 id=649/650/651＝2023环球《水利案例全真模拟预测卷(一/二/三)-题目答案分离.pdf》，每套固定6道大题(一、阅读理解编号1~6)，三套共18题。
- 铁律重申：官方不公布一造《案例分析(水利)》真题，水利"真题"分类永远=0；模拟题 source_kind='模拟题'、year 一律留空(前端真题池按 year 非空过滤，year空自然不进真题池，无硬编码特判)；绝不AI编造，题答全部照原卷录入，不改一个数字。
- 每套章节分布规整：题1=第一章造价构成、题2=第二章工程经济、题3/4=第三章计量计价、题5=第四章招投标、题6=第五章合同价款(网络+索赔/进度款)。

### 二、配图端到端方案(本段关键突破，零前端改动)
- 18题中9题的定额表/网络图/进度曲线/配合比表/工程量单价整表为图片、PDF文本层缺失(各卷题3/4/6)。已用 render_mock_figs.py(PyMuPDF DPI200，words按视觉y聚类成行+去空格子串匹配+锚点限定"答案部分"页之前定位，裁页眉44pt/页脚50pt、跨页PIL拼接)渲染9张PNG到 backend/uploads/question_images/，逐张Read肉眼核验合格，后端 /uploads 已mount、HTTP 200 image/png。
- 挂接方式：在 case_background 末尾追加带内联样式的 <div><img src="/uploads/question_images/mock_jX_tN.png" style="max-width:100%;height:auto;border:1px solid #d1d5db;border-radius:6px;display:block;"></div>。前端 question-practice.js L961 案例背景用 innerHTML 渲染、不转义HTML，question_serializer.py 不清洗 case_background，故img原样显示；不改任何前端/布局/CSS(符合布局锁死)。
- 9图：mock_j1_t3(堆石坝定额)/j1_t4(隧洞通风系数)/j1_t6(网络索赔)、j2_t3(堤防土方定额)/j2_t4(混凝土配合比)/j2_t6(水闸进度曲线)、j3_t3(绞吸挖泥船定额)/j3_t4(资金流量)/j3_t6(丁坝网络及工程量单价整表)。原PDF浅灰斜向防盗水印无法裁剪去除、不影响阅读，保留原图真实不P改；盗版页脚slogan已在渲染时裁掉、入库文字剔除。

### 三、入库结果(脚本 import_mock_j1/j2/j3.py，照 import_ch5 模板)
- 卷一 id=6324~6329、卷二 id=6330~6335、卷三 id=6336~6341，连续18题，全部 subject='一造水利案例'、year空、source_kind='模拟题'、q_type='案例'/type='case'、case_total_score=20，小问score仅前端展示权重、每合计严格assert==20，is_deleted=0。
- 各题关键答案数字均照原卷：卷一t1其他费31275.99/基本预备费50112.64/总投资479832.63、t2利息273.6/折旧1009.53、t3运输14.68压实17.04、t4通风系数2.66洞内907洞外967、t5候选人A92.87>D91.59>E89.43、t6顺延1月补偿465万违约240万；卷二t1工程部分静态2725.81静态总投资3017.32、t2利息170.52折旧614 A=857.29 ROI12.89%、t3土方单价22.71、t4掺粉煤灰水泥185粉煤灰43砂615石1620水0.125外加剂0.37、t5甲95.55>乙93.54>丙92.62、t6关键线路185d实际190d罚20000；卷三t1一至五13479.19静态14153.15总投资16019.35、t2 FNPV=1190.82静态回收3.04年、t3挖泥5.85元/m3、t4建安资金流量2330/5750/7020/4900静态3476.8/7420/9561.2/6042、t5评审价E2055<B2320<C2345、t6合同价539万预付107.8第6月付25.59第7月付25.338。
- 卷三t3挖泥船单价表原PDF文本层OCR严重错位，已对照 mock_j3_t3.png 逐级重算并全部自洽：定额单位10000m3、Ⅲ类土排距1.2km在[80356](1.1km)/[80357](1.3km)间内插、其他机械费费率4%、调整系数=排高1.015^2(=1.03)+挖深0.03×2(=0.06)=1.09；人工236.29、机械台时费小计44804.77+其他机械费1792.19=46596.96、基本直接费46833.25、其他直接费2%=936.67、间接费5%=2388.50、利润7%=3511.09、税金9%=4830.26、合计58499.77，/10000=5.85元/m3。

### 四、三层验证(全部通过)
- DB层：PRAGMA integrity_check=ok；source_kind='模拟题'18题、教材例题73题；五章分布 一13/二18/三22/四19/五19=91；id 6324~6341连续。
- API层：/api/qb/all?subject=一造水利案例 回读91题，9张配图<img>标签与URL原样保留，case_total_score与小问合计均20，year全空(真题池口径0题)；source_kind 字段API序列化器不下发但DB值正确(='模拟题')。
- 浏览器层(Playwright headless Edge，清SW/cache后)：卷一t3/t6、卷二t3、卷三t3/t6 共5张抽验，图片 naturalWidth=1654真实加载、自适应832px、容器scrollWidth=clientWidth=1359无横向溢出、0 pageerror；肉眼核验答案列式与数字正确、中文布局正常；干净加载后前端五章计数13/18/22/19/19=91，与DB一致。(注：后端曾因watchdog停止而8000拒连，已用 `python backend/main.py` 独立进程重启恢复HTTP200；一次测试因切科目后等待不足显示中间计数，充分等待后正确，非系统缺陷。)

### 五、当前题库状态
- 一造水利案例活跃题=91(官方教材例题73 + 三套环球模拟卷18)，全库活跃=1283；AI假题#5819维持软删；水利真题=0(官方不公布)。
- 产物目录 题库质检_20260921/：import_mock_j1/j2/j3.py(三套入库脚本)、render_mock_figs.py(9图渲染/锚点)、verify_mock_api.py/verify_mock_db.py/check_chapter.py/probe_ui_count.py(校验)、ui_mock_j1.py/ui_mock_j23.py(浏览器回归)、教材原文/模拟卷一_二_三_全文.txt(权威题答文字)；9张PNG在 backend/uploads/question_images/。

### 六、遗留(后续)
- 章节题 id=1112/1114《2025水利案例章节题》疑为选择/判断小题(非20分案例大题)，题型不同，是否入、入哪个q_type待读原文判定。
- 模考班 模拟题(一).docx/(二).docx 可能含更清晰图表/解析(docx内嵌图)，PDF图表存疑时可交叉核对。
- 教材73题自身图形题尚未配图，同一配图链路(渲染→uploads→case_background内联img)可直接复用。
- 模拟卷答案不标每小问分值，脚本score按工作量/答案权重分配、合计严格=20(仅前端展示)，若用户有口径要求再调。
- 更早遗留：真题页硬编码"320/128/68%"未接真实统计、CommonUtils首次加载偶发Unexpected identifier、离线同步is_deleted合并策略(防#5819被本地副本带回)、《经典300》剩余约200道主题一致性专项、一造计价6题来源未细查。


---

## 变更记录（2026-09-22 专家发现28项逐项核定 + 过时基线纠偏）

### 核查（只认生效代码 + 真机，排除 tools/历史备份/browser-profile/night_jobs 噪音）
- 对诊断报告"补充章·八 专家主动发现 28 项"逐项核定，结论写入报告**附录 A14**：
  **✅已实现 19、◐部分实现 5、❌未实现 4（均 P2 增强）、⏩随问题9 移动端 1**。
- P0 五项（版本号/增量/自动备份/学习计划/RAG）全部闭环；L3 学习计划真机看板呈现"学习计划/今日目标/连续学习/掌握度"，旧基线"前端空壳"失实。
- 报告早期"没有 X"多已落地并取证：视频倍速/断点续播、考试倒计时/高频TOP、收藏、题目笔记关联（刷题真实写 notes 关联题目）、数据导出、深色多主题、磁盘预警（18:13 真机告警磁盘92.6%/内存96.6%）、双层崩溃自愈、四类日志、做题进度保存。
- ◐ 部分（如实标差距，不夸大为"没有"）：学习时长为答题数估算非真实计时、难度自适应为掌握度级非 IRT、错题专属打印/题目标签/押题趋势。
- 【二次求证订正】❌ 未实现降为 3 项 P2：首次引导(E1)、字体调节(E4)、视频关联题(V3)；数据加密(B3)改 ◐（口令 bcrypt 哈希 + 局域网自签 TLS 已有，仅静态业务库/备份明文）；难度自适应(L4)、错题导出(E5)升 ✅。详见诊断报告 A14 / A14.5。

### 治本 / 纠偏
- `backend/core/standards/feature_status.py`（融合度35-40%/119未落地/49缺失/4死按钮/"前端空壳"）确认为**开发早期历史快照、无运行时消费、不暴露甲方**，已加历史基线警告与 L3 已接线订正（只改注释，py_compile 通过，无逻辑变更）。
- 订正报告统计笔误：专家发现 P2 实为 9 项（原文写 8）。

### 验证
- 真机模块化看板确认学习计划/连续学习渲染；生效前端 grep 取证 X2/E3/B2/V1/V2/O3 等；feature_status 语法校验通过。
- 未新增 / 修改任何运行时业务逻辑，无需回归重跑（21 套件终态仍为 20 PASS / 1 SKIP）。

### 状态
- 10 核心问题（问题9移动端另线）+ 专家发现 P0 全部闭环；剩余仅 P2 体验/加固增强，已如实登记，不阻断 PC 本地版交付。


---

## 变更记录（2026-09-22 低内存 AI 护栏治本，防 OOM 中断）

### 背景（真机事故，非代码崩溃）
- 实测两次后端不可达均根因部署机整机内存枯竭：AI 走 deepseek-r1:7b（约2GB）推理时同开 DevEco（约1GB）+ 多个 Doubao（约2GB），可用内存一度 0.37–1.4GB，18:13 service_monitor 真实告警内存 96.6%、磁盘 92.6%，进程被系统回收；app.log 无 traceback。
- 代码侧盲区：原失败降级目标 DEFAULT_MODEL 仍是 7B，低内存下降级不能降低内存峰值，照样 OOM。

### 治本（core/ai_controller.py，最小侵入、内存充足零影响）
- MODEL_CONFIG 增补 qwen2.5:3b（低内存降配模型）。
- 新增可回归纯函数 apply_memory_guard(model, avail_gb) 与 available_mem_gb()（psutil，缺失自动让位）：
  - 可用内存 < AI_MEM_DOWNGRADE_GB(默认1.5GB)：7B(qwen2.5:7b/deepseek-r1:7b) 自动降配 qwen2.5:3b，route_reason 留痕；
  - 可用内存 < AI_MEM_REFUSE_GB(默认0.5GB)：不发起任何生成请求，返回友好中文提示（请关闭其他程序后重试），need_review=False；
  - 多模态 4B 无小替代，仅在硬地板以下拒绝；阈值均可经环境变量调整。
- 模型调用失败的降级链改为优先 3B、再回默认 7B（原先直接回 7B）。
- 缓存命中在护栏之前判定，低内存下缓存答案仍可用。

### 验证（进代码门禁）
- 新增 `backend/tests/regression/reg_ai_memory_guard.py`（28 断言：纯函数各档/边界、psutil 缺失让位、端到端 ask 极低内存不调模型直接拒绝、低内存改调 3B、充足内存保持 deepseek7B），全 PASS。
- 全量 run_all 实测：**22 PASS / 0 FAIL / 0 ERROR / 1 SKIP，共 23 项**（原 20 + 本轮内存护栏；RAG 在 1.64GB 可用内存下亦通过）。
- 已用 restart_backend.ps1 提权重启后端 + 看门狗加载（18:26 health=200）。

### 文档同步
- 测试报告（套件表 +1、稳定性段）、管理员运维手册（机制 + 阈值 + 期望 21PASS/22项）、版本说明、验收报告（22 套件）、已知问题清单（O-1 治本 + 兜底清单）、诊断报告附录 A14（O1 证据）全部同步。

### 状态
- 交付机内存中断风险由"纯环境、只能事后自愈"升级为"调用前主动降配/暂停 + 事后双层自愈"双重防护；16GB 内存建议仍保留（环境硬约束无法在代码内完全消除）。


---

## 变更记录（2026-09-22 三大安全/质量缺口补齐）

### 1. 前端安全铁律闭环（核心）
- start() 改为 async，队列从 GET /api/mt/recall/queue 获取（后端不下发 back）
- 新增 _ensureFullCard()：仅 READ/GRADE 阶段按需 GET /api/mt/recall/full/{id}
- 进 RECALL 前剥离 cards[index].back（fullCache 保留供 GRADE）
- GRADE 从 fullCache 恢复答案
- 浏览器实测三阶段：READ hasBack=true → RECALL hasBack=false 且 UI 无答案泄露 → GRADE hasBack=true

### 2. 读音校验
- _startReadMic 累积 spokenFull，调 VoiceTextParser.checkPronunciation
- 数字/术语/缩写漏读时 rpPronHint 红色强告警，记录 readMisses
- readMisses 随 grade payload 上报后端 mt_recall_logs.read_misses_json

### 3. 视觉辨识总开关
- READ 选项行加"纯黑白"checkbox（localStorage voice_visual_off）
- 开启后 VoiceTextParser 输出纯黑白只保留加粗，切换即时重渲染

### 验证
- tools/startup_verify.py = 27 PASS / 0 FAIL
- 浏览器三阶段安全实测通过


## 变更记录 · 2026-09-22 晚（专家28项二次求证 + E5 治本 + 静态目录真相）

- **E5 错题导出死函数治本并真机验收**：生效源 `frontend/modules/wrong/wrong-book.js` 工具栏新增复用 wrong-review-btn 样式的"📥 导出CSV"并在 bindEvents 接线；render 缓存 `_displayQuestions`，导出尊重状态/知识点/时间筛选；答案索引健壮转字母；标准 CSV 双引号转义 + BOM；新增年份/知识点/掌握状态列。真机下载 `错题本_2026-09-22.csv`：80 道、表头 10 列、答案 B/D 正确、无乱码、空答案 0 行。static 影子该文件已与源对齐。
- **新增回归 `reg_frontend_wiring`（13 断言，glob 自动纳入 run_all）**：防"写了函数没挂按钮"死功能回潮；守护导出接线、筛选一致、公共库自洽、源/影子该文件一致。全量 **22 PASS / 0 FAIL / 0 ERROR / 1 SKIP，共 23 项**（SKIP=reg_file_recognize），日志 backend/data/logs/reg_run_20260922_wiring.txt。
- **静态目录真相（重大勘误）**：dev/解压即用时 backend/main.py 把 `/static` 挂到项目根 `frontend/`（config.get_resource_dir dev 返回项目根），真机模块 HTTP 实测含源独有 safeStemHtml，证明服务的是 **frontend/modules 源（新版自洽）**；`frontend/static/` 是历史影子、不被服务，与源 11 模块分叉、缺 mindmap.ct*.js、公共库落后。早期"改 modules 须同步 static 影子"对 dev 不成立，特此勘误；打包收目录须专项整体核对（诊断报告 A14.5、已知问题 U-11），禁止零散覆盖。
- **专家28项二次求证分级订正**：B3 ❌→◐（bcrypt 口令 + lan_gateway 自签 TLS 已有，仅静态库/备份明文）；L4 ◐→✅（AI 薄弱点/掌握度自适应实质达标，非 IRT）；E5 ◐→✅（本轮治本）。终态 ✅20 / ◐4 / ❌3(E1/E4/V3) / ⏩1。
- SW CACHE_NAME bump 至 shuili-exam-v6-20260922-wrongexport1；后端已重启（BUILD_TS 更新），health=ok。
- 文档同步：诊断报告 A14/A14.5、测试报告（23 套件）、验收报告、管理员运维手册、版本说明、已知问题清单 U-4/U-9/U-10/U-11。


---

## 第三阶段：2025《水利案例章节题（带解析）》24道主观案例大题精编入库（2026-09-22 收官）

### 一、成果
- 将《2025水利案例章节题（带解析）》全部 **24 道【问答题】主观案例大题**精编入库，`source_kind='章节题'`，id **6342–6365**（连续），`q_type='案例'`、`type='case'`、`case_total_score=20`、`year=''`、`destination='question_bank'`。
- 五章分布：第一章 造价构成 4 题（6342–6345）、第二章 工程经济 6 题（6346–6351）、第三章 计量与计价应用 5 题（6352–6356）、第四章 招标投标 5 题（6357–6361）、第五章 合同价款管理 4 题（6362–6365）。
- 入库后水利案例活跃 **115 题**＝教材例题73（6251–6323）＋模拟题18（6324–6341）＋章节题24（6342–6365）；全库活跃 **1307 题**（一造管理1186、一造水利案例115、一造计价6）；max(id)=6365。
- 标题统一前缀【章节题X-N】，幂等按 title 判重；题干入 `case_background`，逐问 {no,score,question,answer,analysis} 入 `case_sub_questions`，题级解析入 analysis，来源精确到 PDF 页码入 source。

### 二、配图（16 题有图，共 16 张，backend/uploads/question_images/）
- 章节题 PDF 为**扫描件**：表格/网络图是内嵌位图、文字层为 OCR 叠加；`get_drawings()` 矢量线框检测两次验证无效（死路）。
- 少表题用 `get_images()→get_image_rects()→extract_image()` 取原始 JPEG，PIL 等宽居中纵向拼接（剔除 Σ/系数等公式符号碎片与题干空白表）；多表跨页题用整页 `get_pixmap(matrix=2.6, clip=去页脚40pt)` 按题页区间拼长图（零裁切错误）。
- 第二章 6 张（chap2_t1~t6）、第三章 5 张整页长图（chap3_t1~t5，含全部定额/台时费/单价分析表）、第四五章 5 张（chap4_t1 EPC参数表、chap4_t2 评分三表、chap4_t4 开标报价单、chap5_t1 网络图+表5-1+填好投资数据表【位图精拼】、chap5_t2 索赔网络原图/调整图）；四-3、四-5、五-3、五-4 为纯文字合规题，不配图。

### 三、OCR/印刷错误校正（仅在数学自洽时改，并在题内加注；表格只信位图不信 OCR 文本层）
1. 二-2（6347）：原印“总成本97.38、所得税121,26”系漏印/错位，按所得税基数与现金流出反推校正为 **总成本957.38、所得税121.26**（净现金流1791.83 吻合）。
2. 四-1（6357）：C方案年费用原印“18.8”，按公式重算 [490×0.9091+490×0.8264+25×8.2014×0.8264−55×0.1486]×0.11746=**118.8 万元**（漏百位1）；排序 B123.41>A120.4>C118.8，C 最优。
3. 三-4（6355）：招标清单 OCR“17001.05=16190”校正为 **17000/1.05=16190**（开挖2万自然方×0.85=17000压实方再除阶段系数1.05）。
4. 五-4（6365）：索赔首句原印“批准60万”与分项（图纸26天×2=52＋文物5天×2=10）矛盾，以分项合计 **62万** 为准并加注。

### 四、三层验证（全部通过）
- DB：PRAGMA integrity_check=ok；章节题24、五章4/6/5/5/4；16题含 `<img>`；24题 case_total_score 与小问 score 合计均=20；year 全空、destination 全 question_bank；真题(year非空)池仍为 **0**。
- API：/api/qb/all?subject=一造水利案例 回读 115 题、章节题24、16图、总分全20；配图 URL HTTP 200（question_serializer 不下发 source_kind 属正常，以 DB 为准）。
- 浏览器（Playwright/msedge headless，0 pageerror）：切一造水利案例后五章计数 **17/24/27/24/23＝115**；抽验二-2（还本付息表 nw508）、三-2（挖泥船超长图原始1548×8392 自适应至834宽）、五-1（网络图732×572）配图 naturalWidth>0、**无横向溢出**、可纵向滚动；显示答案绿框与灯泡解析分层正常。

### 五、口径说明（需知会）
- **小问分值**：章节题原卷不标每小问分值。DB 的 case_sub_questions[].score 按答案工作量/采分点权重分配且合计严格=20；前端 question-practice.js 与后端 AI 批改沿用**既定铁律“无官方分值时大题20分按小问数平分（余数从第1问各+1）”**，故页面小问分值为平分结果（如3问=7/7/6、2问=10/10、4问=5×4、5问=4×5），与教材/模拟题口径一致，未改前端。
- **编规口径差异（待拍板是否统一标注）**：本套章节题解析依据**旧编规 水总〔2014〕429号 及营改增办法 办水总〔2016〕132号**（如柴油2990、炸药5150限价等），与主线 **2024年323号文新编规** 在费率/费用构成上存在差异；24题已照原文作为练习题录入，仅个别题解析保留132号原文表述，尚未加统一“旧编规口径”标记。

### 六、备份与脚本（题库质检_20260921/）
- DB 备份：backend/data/shuili_exam.db.bak_chapc1/c2/c3/c45_20260922（每章入库前自动备份，软删可恢复）。
- 入库脚本：import_chap_c1.py / c2.py / c3.py / c4c5.py；配图：probe_/render_/extract_chap*；验证：verify_chap_all.py、ui_chap_all.py、db_overall.py。
- 权威题答：教材原文/章节题_带解析_全文.txt（57页 dump）＋原 PDF 整页渲染/内嵌位图。

### 七、铁律遵守
官方不公布《案例分析（水利）》真题，本阶段**零真题、零 AI 编造案例/数字**，全部内容可溯源至章节题原 PDF；OCR 改动均经原图核对或数学重算并加注。


## 变更记录 · 2026-09-22 晚二（前端“渲染即绑定”同源治本 + file-library）

- 接续 E5，真机发现错题本**筛选重渲染后导出按钮 onclick 丢失**（hasOnclick=false），定位为“render innerHTML 重建后未重绑事件”通病：wrong-book 仅 afterRender 成对、4 条交互重渲染路径漏绑。治本：render() 末尾统一 bindEvents()（幂等 onclick，无叠加），覆盖全部 6 条渲染路径；真机筛选“已掌握”导出恰 1 道、重置全量 81 道、重渲染后按钮均存活。
- 全量扫描 19 个业务模块 render/bindEvents：另确证 **file-library 4 处漏绑**（清空筛选、上传完成、删除标签、重命名标签），按其既有成对模式补 bindEvents；ai-brain（内联 onclick）、mock-exam/video（render 内自带绑定）经核查无此问题，排除静态误报。真机建/删临时标签验证主界面按钮存活、控制台零报错。
- reg_frontend_wiring 扩到 **20 断言**（wrong-book 渲染即绑定 + file-library 4 处重绑 + 源公共库自洽 + 源/影子一致），单跑 ALL_PASS；wrong-book.js、file-library.js 源与 static 影子均已对齐。
- 后端已重启（uptime 归零、BUILD_TS 刷新），SW CACHE_NAME=shuili-exam-v6-20260922-wrongexport1；测试报告/版本说明/诊断报告 A14.5.1 已同步。


## 变更记录 · 2026-09-22 晚三（静态源/影子专项收口：双向比对 + catalog 修正 + 影子隔离 + 门禁升级）

- 对 frontend（源）与 frontend/static（影子）的 core/js/modules/pages/css/lib 做双向哈希比对：源 188 文件、影子 70；影子缺源 123、同名落后 16；影子独有 5 项逐一核实全为已迁移旧版/零引用/备份（core/tts-service.js 与源 js 旧备份 MD5 相同；两个 mapper 现行在 js/core；system-admin.css 零引用；一个 .bak），源无资产丢失。
- 据实更正 A14.5：历史 build_exe.bat 用 --add-data "frontend;frontend" 整体收源，frozen 仍服务源，影子仅死重、不会导致回退；真实危害是死重 + catalog 体检假阳性 + 改错目录。
- 治本：catalog.py TTS 体检路径由 frontend/static/core/tts-service.js 修正为真机源 frontend/js/tts-service.js（py_compile 通过）；影子根写 _DEPRECATED_DO_NOT_USE.txt 废弃标记（保留不删）；reg_frontend_wiring 升级为 24 断言（移除源/影子一致，新增 index.html 59 个本地资源在源全部存在=真机零404、catalog 不得指影子、废弃标记须存在）。
- 后端已重启（uptime 归零）；全量回归 22 PASS / 0 FAIL / 1 SKIP（reg_file_recognize），共 23 项，门禁 ALL_ASSERTIONS_PASS。U-11 降为低/已隔离；打包姿势=整体收 frontend 源、勿单列 frontend/static。


---

## 变更记录（2026-09-22 晚：除人工录音外全部功能收尾）

### 一、应试专项（前端 read-practice.js）
- 单位陷阱模式（rp_unit_trap）：数字后单位橙色下划线高亮，GRADE 自检
- 限定词遮蔽模式（rp_qualifier_mask）：除外/不含/必须/应当/不得/无约定/严禁等显示为黑底____
- 打印/导出：rpPrintBtn 调 window.print()；components.css 加 @media print（去色彩留加粗、隐藏按钮/导航）
- 新增 _applyTrapModes(html)，READ/GRADE 答案统一套用

### 二、记忆诊断与调度（后端 scheduler.py）
- grade 接口新增 hearing_dependency 听觉依赖度埋点（漏读≥2 升10；grade=1 降5；grade≥3 升3）
- queue 题型权重：formula/comparison 权重2、error 权重1，高难度卡优先（强制朗读+自由回忆）
- queue 新增 pit_only=1 参数：只练朗读错题池
- 新增 GET /recall/pit/stats（错题池/漂移/听觉薄弱计数）
- 新增 GET /recall/diagnostics（4档分布、自由回忆通过率、错误类型、口误占比）
- 易混打散重写为"暂存缓冲+无关卡落地补入+兜底缝隙插入"贪心算法，保持优先级且不丢卡
- 运行时易混对识别 _infer_pair_group：基本预备费/价差预备费、静态/动态投资、代理/非代理CM、成本/价格（pair_group 列为空也能调度打散，不改数据）
- 前端 topbar 加错题池徽章（点击切换只练错题池）、🌀漂移数、🎧听觉薄弱数

### 三、AI 克隆本人音色 —— 配音接口框架（录音由用户后续人工完成）
- 新建 backend/modules/mt/voice_clone.py（prefix=/voice）：
  - POST /voice/upload/{card_id}（multipart 录音，自动按 front+back+mnemonic 算内容 hash）
  - GET /voice/audio/{card_id}（取本人音频；卡片改版 hash 不符返回 409 需重录）
  - GET /voice/status（ready/stale 列表与计数）
  - DELETE /voice/audio/{card_id}
  - POST/GET /voice/rhythm（现场朗读语速/停顿特征，节奏迁移占位）
  - 音频落盘 backend/data/voice_audio/，新建表 mt_voice_audio、mt_voice_rhythm
- 新建 frontend/core/voice-audio-service.js：playCard 本人音频优先、404/409 回退云扬TTS；recordAndUpload(MediaRecorder)；loadStatus；uploadRhythm
- 磨耳朵 tab 加配音面板：优先播放本人配音开关（rp_prefer_own_voice）、🎙️为当前卡录音配音、已配/失效计数；连续磨耳朵队列本人音频优先
- 单卡正面/背面/全部播放改走 VoiceAudioService.playCard
- 现场朗读判分后自动上报 read_cpm 到 /voice/rhythm（节奏迁移数据沉淀）
- index.html 引入 voice-audio-service.js（主+static 副本，版本号 rp/va）

### 四、前端自动启动健壮性修复
- 问题：afterRender 拉卡后 render 重建 #rpMount，rAF 启动时序竞态导致偶发卡 0 张
- read-practice.js 内置 setInterval(200ms) 自动引导：发现 #rpMount 未绑定即 start，render 重建后自动重绑（cards 已有时只重绑不重复 fetch）
- flashcard.js read2 分支简化为只放挂载点；start 加 null 守卫与幂等重绑

### 五、测试与验证
- 新建 tools/test_mt_queue.py（临时库，7 断言：不下发back/不丢卡/同组间隔≥3/错题池优先/formula加权/pit_only/预备费易混识别）→ 0 FAIL
- tools/startup_verify.py = 27 PASS / 0 FAIL
- 浏览器实测：自动启动 cards=20、切 tab 自动重绑、陷阱渲染（单位4处/限定词3处）、错题池徽章、磨耳朵配音面板、voice API 全生命周期（上传→status ready→取音频200→删除）
- restart_backend.bat 杀进程改为普通 taskkill 失败自动 RunAs 提权（WMI 后端为高完整性级别时需要点一次 UAC）

### 待用户人工完成
- 仅"录入本人声音/AI克隆配音"：在磨耳朵 tab 点"🎙️为当前卡录音配音"逐卡录音（或后续接入克隆模型批量生成后走同一 upload 接口）；框架已就绪，录音放入即生效，卡片改版自动标记失效重录


## 变更记录 · 2026-09-22 晚四（L2 学习时长治本：墙钟→活跃心跳，随机假图→真实趋势）

- 二次求证更正报告失实：study_sessions 表存在且持续写入（782 行），前端也在 beforeunload 上报，并非“无计时”；真问题是①仅关闭时一次性上报整段墙钟（不判可见/挂机、module 写死 dashboard，含 16722s 脏条）②study_trend 只统计题数、近7天时长图用 Math.random 造假，真实秒数从未使用。
- 治本：新增 core/study_time.py（UTC+8 归组、单条封顶 1800s、坏值忽略、并入答题趋势）；analytics.study_trend 增返 study_seconds/study_minutes；index.html 重写为活跃心跳（可见+90s 空闲判定、60s 按模块上报、单条≤60s、切后台/卸载 sendBeacon 结算、断网 localStorage 队列补报）；app_v3 drawStudyTimeTrend 去 Math.random 改真实分钟、修周几错位。
- 验收：reg_study_time 14 断言、reg_frontend_wiring 第8组 6 断言；HTTP 端到端 +120s 精确；真机连续两条 module=question/duration=60s 心跳；全量 23 PASS/1 SKIP/共24项。L2 ◐→✅。每日目标番茄钟分钟条(today_minutes)为另一口径，未改。


---

## 20260922 题库刷题 7 项问题修复 ＋ 思维导图教材树“科目跟随”根治（问题7）

### 一、用户点名的 7 项与处理结论
1. **考点定位重复显示**：question-practice.js 结果区外层重复拼了一次 point_name（_formatChapter 已拼）。已删外层拼接（补丁P1）。
2. **AI解析慢**：本地 qwen2.5:7b 推理＋8GB内存紧张（后端 ai_controller 内存<1.5GB 自动降3B、<0.5GB 拒绝）。前端能做的已做：①同题解析 localStorage 缓存（key=qp_ai_explain_{subject}_{id}），二次点击秒开；②点击后按钮变“解释中…”、每秒计时，≥20s 提示“已等待N秒/内存紧张较慢/可先做其他题”；③失败按网络/500/404 分类＋重试/报错按钮（P12a/P12b）。已浏览器实测反馈链路。**模型降配/加内存属硬件决策，未擅改，待用户拍板。**
3. **草稿本不透明＋触控笔横画误切题**：①草稿面板背景 0.72→0.40、去模糊，header 0.8→0.62、工具条 0.6、两处画布 0.5→0.12（P2-P5）；②根因是 canvas 的 touchend 未拦截、横画冒泡到容器横滑手势切题——_bindSwipeNav 对 #qpDraftPanel 内起手直接 return，画布 mouse/touch 事件 preventDefault+stopPropagation（P6/P7，passive:false）。CDP 模拟触控笔横向手写 176px：题目不切换、画布正常接收笔迹；截图肉眼确认可透见题干表格。
4. **取消选择还有背影**：触屏粘滞 :hover/:focus 与系统 tap 高亮。.qp-option 加 -webkit-tap-highlight-color:transparent、:focus 去 outline、@media(hover:none) 关闭 hover 底色（保留 selected/对错态颜色）；章节卡 .qp-chapter-item 同理；多选取消后 opt.blur()（P8-P10）。实测多选 A 选中→取消 class 正确移除。
5. **“内存不足”提示乱码（鍐呭瓨涓嶈冻…）**：源头是离线工具 tools/gen_case_refpoints.py 在 GBK(cp936) 黑窗口直接运行时，UTF-8 输出被当 GBK 渲染。已改为：重定向(非tty)用 utf-8、裸控制台(isatty)用 gbk、errors=replace（G1）。**该内存守卫（CASE_MIN_FREE_GB=4.5GB）是防本地7B OOM 的保护，不是bug**；全项目无任何 .bat/.py 自动调用该脚本（夜间任务链路编码一致不乱码），仅手动/计划任务在控制台直跑才会遇到。在线后端守卫在 core/ai_controller.py（阈值可用环境变量覆盖）。
6. **题库刷题没有收藏**：代码链路本就完整（state.favorites＋localStorage question_favorites＋_syncCollect＋#qpFavorite，普通题/案例题各一处），缺可见反馈。已在收藏/取消后加 toast（“⭐已加入收藏（左侧我的收藏可查看）”/“已取消收藏”，P11）。实测☆⇄⭐、localStorage、我的收藏计数 0↔1 正常。
7. **章节归类错误（S曲线被归第一章）**——经多层核查，**题库刷题归类本身完全正确**：DB questions.chapter、前端 _parseChapter/_qChapterNo、后端 question_norm、练习池三层一致；S曲线/赢得值/投资进度偏差题（id 6323 教材五-16、6335 模拟二-6、6362/6363 章节五）全部在**第五章 水利工程合同价款管理**；水利案例五章计数 17/24/27/24/23，第一章练习池17题零混入。真正错显在**思维导图模块“节导图(按教材结构树)”**，双层根因：
   - **前端bug（已修）**：mindmap.ct2.js 的 this.SUBJECT 写死‘一造管理’，教材树/导图列表不跟随顶部科目，切到水利仍渲染一造管理第1章目录；且模块未订阅 subject:changed。已新增 init() 订阅 subject:changed、_syncSubject() 动态同步科目并在换科时清空旧科缓存重载；节/章/科目导图在无树时给**真实空态**（不套用他科目录、不编造节名）；科目导图标题去写死；切到水利案例**默认自动落到“🌳造价结构树”Tab**（落实既定需求），切回其他科目回节导图。
   - **数据缺口（不可编造，需补料）**：/api/v1/material/tree 对一造水利案例返回空——course_materials 里水利案例仅 id=49《323号文编制规定》（非教材，desc仅72字符），**系统中没有《一造水利案例》官方教材PDF**（“水利电子教材”被错标成一建水利实务 id=45 或一造管理 id20/22，均 is_deleted 或非本科目）。因此水利“章—节”教材树无真实来源，已让前端显示明确空态并引导造价结构树；**待用户上传《一造水利案例》教材PDF后，smart_extract_outline 会自动解析生成节导图**。

### 二、改动文件（活跃前端，static 死副本不动）
- frontend/modules/question/question-practice.js（P1–P12b 共13处）
- frontend/modules/mindmap/mindmap.ct2.js（M1–M5：init订阅/科目同步/三处空态/标题动态）
- tools/gen_case_refpoints.py（G1 编码自适应）
- frontend/index.html：question-practice 指纹→?v=20260922qfix7b；mindmap.ct2 指纹→?v=20260922q7
- frontend/sw.js：CACHE_NAME → shuili-exam-v6-20260922-q7fix（两模块均在 PRECACHE，按发版规律必须 bump，真实浏览器强刷两次生效；KEEP 仍含 DATA_CACHE/视频/AI问答缓存）

### 三、备份
- question-practice.js.bak_20260922_7fix
- mindmap.ct2.js.bak_20260922_q7
- tools/gen_case_refpoints.py.bak_20260922_7fix
- DB 最新备份 backend/data/shuili_exam.db.bak_oldstd_20260922（本轮前端修复未改库）

### 四、验证（Playwright＋msedge headless，脚本在 题库质检_20260921/）
- ui_verify_core.py：五章计数17/24/27/24/23；第一章17题零混入；旧编规琥珀标记正常；0 pageerror。
- ui_verify_interact.py（hasTouch＋CDP dispatchTouchEvent）：收藏0↔1、草稿横画不误切题且笔迹被接收、多选取消无残影，0错误。
- ui_verify_q7.py：水利进入默认造价结构树、节导图真实空态无管理目录、切管理正常显示34节点教材树、再切水利回造价树，科目切换不刷新即时生效，0错误。
- ui_verify_ai.py：作答提交后AI按钮出现，点击变“解释中…”＋计时提示，0错误。
- 所有改动 node --check 通过；后端未改动、HTTP 200。

### 五、待用户决策/补料
- 问题2/5：是否接受更激进的模型降配或为夜间任务预留内存（8GB机器建议跑采分点/大批量AI前关 WPS/微信/钉钉/浏览器，保证可用内存≥4.5GB）；在线阈值可用环境变量调整。
- 问题7数据侧：需上传《一造水利案例》官方教材PDF，才能生成真实教材“章—节”结构树；在此之前水利节导图维持真实空态，费用结构走“造价结构树”。


## 变更记录 · 2026-09-22 晚五（L2 真机可见层再求证：改错文件纠偏 + 柱高塌缩修复）

- 小心求证关键：先前改的 app_v3 drawStudyTimeTrend（去 Math.random）属旧单体、现行模块化 SPA 路由不可达；真机用户看到的“近7天学习趋势”是 modules/analytics/analytics.js 的 trendBar0..6 柱图。
- 模块化原图两个真缺陷：①虽调 study_trend 却按“星期几桶”累加答题数 d.total、标签写死周一~周日（缺数据日错位），未呈现学习时长；②柱高用百分比、父项在 align-items:flex-end 行内无确定高度，柱高塌缩、真机几乎不可见（用户看到空白图的根因）。
- 治本：柱改消费真实 study_minutes、按真实日历左6天前→右今天对齐并动态写周几、今天柱高亮、hover“周X·学习N分钟”、柱高改固定像素(行高70px/上限46px)；容器/配色/DOM 零改动。真机实测柱高与分钟严格成比例(721分=46px、554分=35px、今天600分=38px深蓝)、console 零错。
- 门禁第8组增模块化 3 断言（消费 study_minutes、真实日历对齐、像素柱高防塌缩）；旧单体 canvas 保留防御性去 random。

---

## 晚六 B3 备份加密治本（2026-09-23 凌晨，对照诊断报告 B3 / A11）

- 新增 `backend/core/backup_crypto.py`：AES-256-GCM 分块认证加密（魔数 SLBKENC1、8MB 流式恒定内存、块序号+结束标志入 AAD，篡改/调换/截断/错钥全拒绝），机器绑定主密钥 `backend/data/keys/backup_master.key`（32B、不进 backups、不进备份包），旧明文 gzip/SQLite 魔数探测透明透传。
- `auto_backup.py`：run_cycle gzip 后原地加密（.db.gz 内容为加密容器、encrypted 标记、加密故障降级明文不阻断备份）；restore_online 先识别解密再解压；新增 normalize_backup_bytes / restore_from_bytes 供上传恢复统一走"解密→解压→SQLite 校验→在线页级恢复+安全网"。
- `utils/backup_manager.py`：手动全量快照库改 shuili_exam.db.enc、不留明文；_verify 解密临时校验；restore 优先解密 .enc；_should_exclude 排除 backup_master.key（密钥绝不入包）。
- 修复两处真实缺陷：①前端上传恢复 POST 下划线 /api/common/system/restore_upload 而 common 仅注册连字符 → 模块化页面 404（common 补下划线+连字符双别名，export_db 同补，api/v1/system 上传恢复同步治本）；②旧上传恢复原样 wb 覆盖活库无校验、传错即毁库 → 改智能归一化+在线恢复，非法在动库前拒绝。前端 settings.js 上传 accept 放宽 .db/.db.gz/.db.enc（纯过滤器非布局）。
- requirements.txt 声明 cryptography>=42。
- 门禁：新增 reg_backup_crypto（9 组，含临时库端到端加密备份恢复、手动快照 .enc 与密钥不入包、上传四形态通吃+垃圾/异钥拒绝）；reg_backup_restore 适配加密。全量回归 25 套件 / 24 PASS / 0 FAIL / 1 SKIP。
- 真机确证：224MB 活库 run_cycle 产 hourly/daily .db.gz 头 b'SL'、各 71.5MB、looks_encrypted=True；主密钥 32B；auto_list 正常；三上传恢复端点喂垃圾均 status=error 拒绝、活库 3093 题前后不变；export_db 下划线别名 200。
- 边界：运行态活库 SQLite 仍明文（透明加密不纳入交付）；export_db/旧 /system/backup 保持明文（登录态+TLS 主动导出）；换机还原加密备份须携带 backup_master.key；口令派生密钥/密钥导出 UI 待评估。B3 维持 ◐（缺口仅余运行态活库）。
- 文档：诊断报告新增 A11.6 + 更新 B3 行；备份恢复指南/测试报告/验收报告/已知问题 U-4/版本说明/管理员运维手册（密钥与换机须知）均已回写。


---

## 2026-09-23 闪卡朗读模块：熟练卡降级调度 + BGM 正确率埋点（认知科学引擎）

### 1. 熟练卡自动降级（需求第六条：连续3次完整复述→关闭朗读直入复述）
- flash_cards 新增列 `read_streak INTEGER DEFAULT 0`（_ensure_schema 幂等 ALTER）。
- grade：grade==1（完整复述）read_streak+1；grade>=2 归零。UPDATE SQL 加字段。
- queue：SELECT 加 read_streak；连续>=3 的卡返回 `skip_read=1`。
- 前端 read-practice.js 新增 `_entryPhase(card)`：skip_read=1→直入 PHASE.RECALL（自动 _startRecallMic），预回忆→PRE，否则 READ；start() 第一张与 _nextCard() 下一张统一使用。复述失败后端 read_streak 归零，下次自动恢复朗读。
- 实测：卡453 连续3次 grade=1→read_streak=3（queue 标 skip_read），再 grade=2→归零；前端 _entryPhase(skip卡)='recall'、普通卡='read'，进入 skip 卡直显复述 UI 跳过朗读。

### 2. BGM 正确率埋点（需求模式B：开BGM卡片单独标记，长期正确率下降自动建议关闭）
- 前端 flashcard.js playCurrent：rp_bgm==='1' 时把播放卡累加进 localStorage `rp_bgm_exposed`（{cardId:次数}）。
- read-practice grade payload 加 `bgm_exposed` 布尔（查当前卡是否在 rp_bgm_exposed）。
- 后端 GradeBody 加 bgm_exposed；mt_recall_logs 幂等 ALTER 加 bgm_exposed 列（PRAGMA table_info 去重）；日志 INSERT 加字段。
- diagnostics 新增 bgm_pass_rate / non_bgm_pass_rate / bgm_sample / bgm_advice：BGM暴露卡（样本>=5）完整复述通过率比未暴露卡低>=15个百分点→返回"建议关闭背景音乐"。
- 磨耳朵 tab BGM 开关下新增 #bgmAdvice 橙色提示，进入时拉取 diagnostics 填充。
- 实测：插6条BGM日志（通过率33% vs 非BGM 66.7%）→正确触发建议；清理测试行后恢复。

### 3. 验证与版本
- startup_verify 27 PASS/0 FAIL；test_mt_queue 7断言 0 FAIL。
- 后端经 restart_backend.bat（RunAs提权）重启；前端版本 bump：read-practice v=20260923rp5、flashcard v=20260923rp6，主副本与 static 镜像同步，浏览器注销SW清caches回归通过（朗读训练自动启动 cards=20、磨耳朵配音面板/警示条/bgmAdvice 齐全）。
- 边界：测试对真实卡453 grade了4次造成 SRS 改动，最终停在 grade=2 缩短间隔的保守方向（更频繁复习，不会漏学）。
- 仍依赖用户人工：磨耳朵逐卡录音配音（框架已就绪，录音放入即生效；卡片改版 hash 不符自动标记重录）。


---

## 20260923 《一造水利案例（2024）》教材导入，水利“教材结构树”补齐（问题7数据侧闭环）

### 一、目标与教材定位
- 用户明确“一造水利案例2024就是教材”，要求补齐水利案例教材“章—节”结构树，使思维导图“节导图”由空态变为真实教材树。
- 全系统排查：backend/uploads 内原无水利案例教材（唯一水利大部头 246a5be8 经 TOC/正文确认为 **2026一建《水利水电工程管理与实务》**，第1篇水利水电工程技术，非本教材，维持 id=45 一建水利实务归属不动）。
- 最终在 **F:\水利智学系统\学习资料库\一造培训资料\教材-2024一造水利案例.pdf**（14.2MB，262页）定位到权威教材：2024版《建设工程造价案例分析（水利工程）》，中国水利水电勘测设计协会编，黄河水利出版社。

### 二、教材真实结构（无传统“节”，章下即“案例”）
- 该教材为案例分析教材，正文按“案例”组织，章下一级即案例（作为结构树的“节”，level=2）。
- 五章 73 案例，与题库“教材73题”完全吻合：
  - 第一章 水利工程造价构成：案例一~十（10）
  - 第二章 工程经济：案例一~十五（15）
  - 第三章 水利工程计量与计价应用：案例一~十六（16）
  - 第四章 水利工程招标投标：案例一~十六（16）
  - 第五章 水利工程合同价款管理：案例一~十六（16）
- 目录页在 PDF p6-8（“目录”），案例标题以目录为准；PDF物理页与教材内部页码偏移=8（正文第一章 PDF p9 = 内部 p1）。

### 三、导入执行（脚本 题库质检_20260921/import_textbook.py，幂等）
1. DB 在线一致性备份：backend/data/shuili_exam.db.bak_textbook_20260923（sqlite backup API）。
2. 教材按 md5 命名复制到 backend/uploads：**edbdcdad8d5f3e7a9de3b34b3106708a.pdf**（14.2MB）。
3. course_materials 插入新记录 **id=50**：subject=一造水利案例、user_id=1（admin，与其他活跃教材一致）、file_type=pdf、file_path=uploads/edbdcdad….pdf、file_hash=edbdcdad…、is_deleted=0；description 为 78 节点扁平 JSON（5 章 level=1 + 73 案例 level=2，字段 num/title/start_page/level/confidence/end_page，与一造管理教材同构）。
4. id=49《323号文》仍保留（description 非“[”开头，/tree 自动跳过，不混入教材树）；水利案例现有 2 条材料（323号文 + 教材），互不冲突。

### 四、三层验证（全部通过，0 pageerror）
- DB：id=50 字段正确，description 78 节点（章5/案例73）。
- API（verify_tree_api.py）：GET /api/v1/material/tree?subject=一造水利案例 返回 1 科目 1 教材 78 节点；323号文未混入；抽查 1.1 引水工程总投资构成 p1、3.5 施工用电和施工用水预算价格计算 p94、5.16 投资偏差、进度偏差分析 p252 均正确。
- 浏览器（ui_verify_textbook_tree.py / ui_regression_switch.py，真实下拉 #realGlobalSubject）：水利节导图渲染 5 章 73 案例、不再空态；切一造管理正常显示管理教材树且不误显水利；切回水利自动落“🌳造价结构树”且不误显管理；0 页面错误。截图 ui_水利_教材节导图.png。
- 前端代码未改动（mindmap.ct2.js 已支持科目跟随与树渲染），故不 bump 指纹/SW；树为动态 fetch。SW 对 /api 网络优先，在线会自动刷新此前可能缓存的空树（个别浏览器若仍见空态，强刷一次即可）。

### 五、现状与可选后续
- 每个案例（节）在节导图中显示“暂无导图”，点击左侧节可逐节生成“问题版(填空)/答案版”导图——属可选增强，未自动批量生成（避免一次性大量本地7B推理触发内存守卫）。
- 至此问题7“数据侧”闭环：水利案例教材结构树真实、完整，未编造任何节名。


---

## 晚七 T3 整门「量化通过概率」治本（2026-09-23，对照诊断报告 T3 / A14.7）

- 盘点：系统本有考点出现概率(exam_analysis/prediction)、单知识点答对概率(BKT)、kg/prediction 三层预测；缺"整门及格概率"。
- 真机数据陷阱多轮求证：①exam_records 大量弃考秒交、系统把未答记 wrong（right0/wrong80、start==end、用时2-37s、明细固定模板），"right+wrong作答率"判据失效→误判21场有效、概率19.8%；②改 user_answer 非空判有效，早期真模考(id2/3/4)不回填user_answer→又误剔、概率94.4%；③最终规则：真实作答率≥0.6 或 score>0 或(无明细)用时≥180s 为有效，0分无作答痕迹判弃考；模考时效衰减(半衰期30天)；不依赖全0的 user_mastery。
- 新增 core/exam_pass_predict.py：EWMA近期正确率＋正态近似(Phi,math.erf)＋时效模考校准，sd×1.6/地板0.045，样本<20不输出精确概率；输出概率/预计分/置信度/可解释factors/免责声明。
- 端点 GET /api/v1/exam_analysis/pass_probability?subject= ：真机一造管理有效模考4场(早期40-50分3场、9/7认真作答0分1场)、近期练习70% → 通过概率41.4%临界/置信高/预计52.9；水利案例无客观答题→数据不足(安全)。
- 门禁新增 reg_pass_predict(31断言)；全量回归 26项/25PASS/0FAIL/1SKIP。
- T3 维持 ◐：后端能力(端点+门禁)已真机验证，前端无可见展示(布局锁死、展示形态待拍板)，接入界面后可✅。
- 文档：诊断报告新增 A14.7 + 更新 T3 行；测试报告 26 套件。


---

## 2026-09-23 闪卡：配色切换修复 + 磨耳朵布局和谐优化（用户点名授权布局调整）

### 1. 配色方案不能切换（根因修复）
- 根因：getCurrentSchemeName() 读 getComputedStyle('--primary') 得到 rgb() 格式，而方案存 hex，比较永不命中→返回'自定义'→toggle 永远切回第1套，表现"不能切换"。
- 修复 theme.js：新增 rgbToHex() 把计算值归一化为 hex；getCurrentSchemeName 优先读 localStorage currentColorScheme、hex 比较兜底。实测连续切换 森林绿→活力橙→优雅紫→水利蓝，主色实际变化。

### 2. 配色切换入口移到底部时间左侧
- statusbar.js：real-footer-right 最前（时间左侧）加可点击"🎨 配色名"#realFooterScheme，点击 toggleColorScheme；监听 app:color-scheme-changed 同步名称；加 .real-footer-scheme 样式。

### 3. 磨耳朵（朗读记忆专练）布局压缩，闪卡区域增大
- 标题"🎵口诀磨耳朵"与红色警示"⚠️本模式无生产效应·不更新SRS·去朗读训练"改为标题行左右布局（警示压成胶囊）。
- 删除原 BGM checkbox 框：BGM 开关移到系统设置（settings.js 语音区加 #rpBgmSetting，app_v3 loadSpeakSettings 回填 rp_bgm）；骨传导提示并入录音按钮 title。
- 本人配音面板压成一行（优先播放/录音/状态/已配·失效计数）。
- "✏️去卡片管理编辑"移到播报控制行，与 开始/停止/下一个 同一行（状态文字弹性居中）。
- 实测闪卡完整可见（第1/562），控件不再挤占卡片区，布局和谐；数字考点 tab 恢复正常（63张）、朗读训练主链路正常（20卡）。

### 4. 过程事故与修复（已闭环）
- 首次 patch 用 c.find('fc-special-header') 误匹配到 number 分支首个同名 header，把磨耳朵内容塞进 number、丢失 read 分支（render 结果只剩 style、内容空白）。
- 从 backups/auto/20260921_2128 提取正确 number 分支，重建 number+read 分支结构，node --check 通过，浏览器三 tab 实测正常。
- 教训：锚点必须带分支上下文确保唯一，不用裸 find 通用 class。

### 5. 验证与版本
- startup_verify 27 PASS/0 FAIL；前端 flashcard v=20260923rp7，theme/statusbar/settings 同步主副本与 static 镜像，浏览器注销SW清caches回归通过。


---

## 晚八 X3 题目级自定义标签内核治本（2026-09-23，对照诊断报告 X3 / A14.8）

- 据实定位：FlashCard/Note/资料库都有标签，唯独 Question 无标签字段/表，确证缺口。
- 新增 question_tags 表（按用户隔离、三列唯一）；core/question_tags.py 纯函数（normalize/parse/apply，宽容分隔、大小写去重、限长32/限量50、每题上限20）；api/v1/question_tags（list/of_question/add/remove/questions，非法400）；main.py 注册。
- 真机求证：首次误选历史模考明细悬空 id(465/2708，题库重建后活库已无)，改用真实 id(3246/3248)后端到端 9 组全过、测后清理无残留；记录"历史模考明细 question_id 悬空"现象。
- 门禁新增 reg_question_tags(20断言)；全量回归 27项/26PASS/1SKIP。
- X3 维持 ◐：后端能力真机验证，前端无打标/筛选 UI(布局锁死待拍板)，接入后可✅。
- 文档：诊断报告新增 A14.8 + 更新 X3 行；测试报告 27 套件。


---

## 2026-09-23 磨耳朵卡片内容被压扁看不清——修复（用户截图反馈）

### 问题根因（实测复现）
- 未播放/默认状态下 .fc-read-card 高度坍缩到 163px（answer-box 仅 24px、绿色答案块文字被裁切看不清），播放中才正常（约516px）。
- 根因：.fc-special 是 flex column、高约479px，内含 header/desc/配音行/卡片/控制行/设置区，控件占去约280px；.fc-read-card 经 .fc-manage-card 得到 flex:1 1 0%，垂直空间不足时被 flex-shrink 压缩，原 height:min(440px,60vh) 无法保底。

### 修复
- flashcard.js _getCSS：.fc-special .fc-read-card 改为 `height:min(460px,62vh); min-height:380px; flex:0 0 auto`（不参与压缩，靠 .fc-special overflow-y:auto 滚动），覆盖 .fc-manage-card 的 flex:1。
- 实测未播放：卡片 h=399、answer-box h=217（绿色大块白字清晰）、trick h=35；滚动后口诀蓝块/面包屑/控制行/设置区完整可见。

### 其他
- 期间后端进程停止（端口0），WMI 重新启动恢复。
- 版本 flashcard v=20260923rp8，主副本与 static 同步，注销SW清缓存验证；startup_verify 27 PASS/0 FAIL。


---

## 晚九（2026-09-23 08:45）analytics「应试预测」Tab + watchdog 误重启治本

**用户指令**：在智能训练分析新增 Tab 放 T3/X3；自主推进、不能断点。

**完成**：
1. analytics.js 新增「🎯 应试预测」Tab：整门通过概率环（跟随科目，conic-gradient，数据不足安全降级）＋我的标签 chips 浏览；init 订阅 subject:changed。真机：一造管理 **41%/临界/52.9/100**，水利案例**数据不足/及格84**，切回恢复，console 零错。
2. 排查并治本一个新缺陷：高负载（整机内存 85.7%）时 TCP＋urlopen 同时超时，旧 watchdog 用同样超时的 urlopen 复核 unknown → 两次误重启健康后端（运气型：08:36:07 同情况复核成功就没重启）。watchdog 改为健康三态（超时不判死）＋unknown 延长窗口只认 ConnectionRefused。
3. 门禁：reg_frontend_wiring 增第 9 节（10 项）；新增 reg_watchdog_hardening（13 项，含 mock 三态）。全量回归 **28 套件 / 27 PASS / 0 FAIL / 1 SKIP**。
4. sw.js CACHE_NAME 升 v7-20260923-predict（analytics.js 在预缓存）。

**销项/终态**：T3 ◐→✅。专家 28 项 **✅22 / ◐2 / ❌3 / ⏩1**；◐2=B3、X3（刷题页打标/筛题 UI 触布局，待授权）；❌3=E1/E4/V3。诊断报告 A14.9/A14.10、测试报告均已回写。tools 无 _*.py 残留。

**当前运行**：后端 pid 26156（08:38 起，稳定）、watchdog pid 22544（加固版，08:42 起）。


---

## 20260923 《一造水利案例》73个案例“问题版(填空)/答案版”双版导图全部生成（节导图闭环）

### 一、目标
- 教材结构树（id=50，5章73案例）导入后，每个案例在节导图中仍显示“暂无导图”。本次为全部73案例逐节生成双版导图：问题版（填空自测）+ 答案版（完整解答），共 **146 条 mind_maps 记录**。

### 二、导图存储与匹配机制（mind_maps 表）
- 每个案例两条记录：map_type=with_answers（答案版）、only_questions（问题版）；subject=一造水利案例、user_id=1。
- chapter 字段写“第X章第Y节 案例标题”，前端 mindmap.ct2.js 的 _buildKeyMap 用正则解析为 key“X.Y”，与教材结构树节点 num（案例序号，每章从1）精确匹配，点击节即经 /api/v1/mindmap/{id} 拉取 content_md，用 markmap 渲染。

### 三、生成方式：离线确定性提炼（不调用本地7B、零编造）
- 脚本 题库质检_20260921/build_case_mindmaps.py：按案例页码区间从教材PDF提取正文，识别“一、背景/二、问题/三、分析要点/四、答案”四段，组织层级 Markdown（📌分析要点 + ❓问题与解答，逐问题列等式）。
- 问题版在答案版基础上，仅把每个等式“=最终结果（单位）”与“为…万元”中的结果数字挖空为 ____，完整保留公式系数（×4.2%、0.35%）与代入中间值，适合填空自测。

### 四、过程中发现并修复的关键问题
1. **相邻案例共用物理页、头/尾残留**：案例起始页顶部常残留上一案例“问题3/4/5”答案，导致 split 误切、结构错位。case_raw 增加“头截断”（用“案例X+标题”锚点定位起点）与“尾截断”（下一案例锚点），并把页范围设为含下一案例起始页。
2. **无编号问题/答案兜底**：部分案例（2.9施工方案比选、2.11价值工程）问题不用“1.2.”编号、答案用“(1)(2)”而非“问题N:”。question_heads/answer_parts 增加兜底：无编号时整段清洗为单个问题；答案无“问题N:”时整段清洗挂问题1。
3. **表格穿插在答案中间**：答案清洗改为“逐行保留等式、跳过表格碎片”（按数字占比/表头词识别表格行并跳过），表格后的计算不再被误删；表格数字只作跳过、不据OCR。
4. **末案例5.16无答案**：教材 p262 为末页，案例十六“投资偏差、进度偏差分析”只有背景/问题/分析要点、无“四、答案”。split_segs 修正为“无答案时分析要点延伸到文末”，导图完整呈现赢得值法（BCWP/BCWS/ACWP、CV/SV/CPI/SPI 公式、六步骤），答案区标注“教材未附参考答案，请依据分析要点自行测算”，**不编造结果**。
5. **OCR清洗**：修正“第一幸/技资/叫共电”、数字千位空格（4 070. 6→4070.6）、字母误识（498. l→498.1、597. O→597.0、O.35%→0.35%），并去页眉页脚。
6. **旧编规口径标记（用户既定要求）**：每个案例导图标题下统一加“⚠️【旧编规口径】…依据水总〔2014〕429号；现行水总〔2024〕323差异见造价结构树”。

### 五、三层验证（全部通过，0 pageerror）
- DB：水利案例 with_answers=73、only_questions=73；按章 10/15/16/16/16 ×2；无 <450 字符的残缺导图、无空分析要点。
- 质量审计（audit_quality.py）：73案例“真实问题数/题干/解答块/问题节点”全部对齐，异常列表为空。
- 浏览器（ui_verify_final.py，msedge headless）：节导图“暂无导图”计数=0；抽查 2.11价值工程（价值指数/改进顺序）、3.5施工用电用水、5.16赢得值（SPI/CV）内容正确；0 页面错误。截图 ui_516_最终.png。
- 前端代码未改动（markmap渲染与匹配逻辑已支持），故不 bump 指纹/SW；导图为动态 fetch，SW 网络优先会自动刷新（个别浏览器若见旧态，强刷一次）。

### 六、备份
- DB 备份：shuili_exam.db.bak_casemaps_20260923_084834（最新，另有 083938/084200 及 bak_textbook_20260923）。


---

## 2026-09-23 磨耳朵一页显示：配音控件归位 + 卡片弹性（用户授权自由调整位置）

### 调整
- 删除独立配音紫块与冗余 desc 说明；"优先播放本人配音/录音配音/已配·失效计数"移到卡片下方第二行，与 重复/间隔/模式 设置并排。
- 卡片 .fc-read-card 由固定 height/min-height380 改为 `flex:1 1 auto; min-height:240px`（弹性填充标题与控制行之间空间），max-width 720。
- 卡片下方两行：①播放控制（开始/停止/下一个 + 状态 + 去卡片管理编辑）；②配音+播报设置（优先播放/录音/已配失效 + 重复/间隔/模式）。
- 实测 fits=true（.fc-special scrollH=clientH=477，无滚动）：标题/卡片/控制/设置全部一页；小窗 answer-box 82px 内可滚动，大屏卡片与答案区随高度自动增大。

### 验证与版本
- flashcard v=20260923rp10，主副本与 static 同步，注销SW清缓存验证；startup_verify 27 PASS/0 FAIL。


---

## 20260923 导图导航调整：一造水利案例“无节”，案例直接聚合到章导图/科目导图

### 一、用户依据
- 2024《一造水利案例》教材结构为“章 → 案例”，章下一级即案例、**没有“节”**。用户明确：案例不应套用“节导图（按节）”，应直接进入“章导图”和“科目导图”。

### 二、改动（仅 frontend/modules/mindmap/mindmap.ct2.js，2处）
1. 切到一造水利案例时，默认 Tab 由原“造价结构树”（教材未导入时的旧逻辑）改为 **章导图（chapter）**；其余科目仍默认节导图。
2. 一造水利案例时 **隐藏“📋节导图”Tab**（无节、避免把案例误当节）；保留“🖼️章导图 / 📦科目导图 / 🌳造价结构树”。其他科目 Tab 不变。
- 聚合机制本已具备：章导图 _mountAgg 按 chNum 聚合该章全部案例（每个案例拉取双版导图连续渲染）；科目导图 filter 全 true 聚合全科。案例即 _allSections（level=2）。

### 三、版本号
- index.html：mindmap.ct2.js 指纹 ?v=20260923ch1。
- sw.js：CACHE_NAME = shuili-exam-v8-20260923-ch1。

### 四、验证（Playwright msedge headless，0 pageerror）
- 水利案例：默认即章导图（章下拉存在）；Tab 栏无“节导图”、有“章导图/科目导图”；第1章聚合含首案例(1.1引水工程总投资构成)与末案例(1.10水文/水利信息化)；科目导图含第3章(施工用电)、第5章(投资偏差)案例。
- 回归 一造管理：Tab 栏仍有“节导图”、默认节导图（无章下拉）。
- 截图：ui_水利_章导图.png。
- 备份：mindmap.ct2.js.bak_chapter_20260923_152214；index.html/sw.js .bak_20260923_152*。

### 五、并行进展
- 案例1（1.1）已完成“教材知识点 ＋ 📖323现行口径”融合（六部分vs五部分、五大费用、投资层级三公式、现行参数9%/7%/0.7%/2.5%、数字孪生/输水管线差异），作为全稿融合模板；其余72案例按此模板批量融合（推进中）。


---

## 2026-09-23 X3 题目级标签前端闭环：刷题页打标 + 标签练习（X3 ◐→✅）

### 改动（frontend/modules/question/question-practice.js）
- 两处答题操作区加「🏷️ 标签」#qpTagBtn → _editQuestionTags() 统一弹窗：chips 展示、× 即时 remove；输入逗号批量 + 回车/按钮 add（≤32字、每题≤20）。
- select tabs 增「🏷️ 标签练习」；_renderTagTab/_loadTagTab 拉 list 渲染单选（标签+题数）；#qpTagStart → _startPractice('tag', tag)。
- _startPractice 增 source==='tag'：拉 question_tags/questions 取 ids，质量题池内严格过滤，空则回 select、绝不凑数。

### 真机 e2e（测后清理）
- 第一章第一题 id=4904 打标“交付测试”成功；标签练习列表“交付测试 1题”，开始后 source=tag、题目仅 [4904]；随后 remove 清理，of_question/4904 与全局 list 均空，无残留；console 无错。

### 门禁 / 版本
- reg_frontend_wiring 增第10节（9 断言 ALL_PASS，套件合计 42 断言）；SW 升 shuili-exam-v8-20260923-x3ui；全量回归 28 套件 / 27 PASS / 0 FAIL / 1 SKIP（reg_file_recognize）。
- 诊断报告 append A14.11、二次求证表 X3 升 ✅；测试报告同步。专家 28 项终态：**✅23 / ◐1(B3) / ❌3(E1·E4·V3) / ⏩1**。


---

## 20260923 全73案例“教材知识点 ＋ 323现行口径”融合完成（双版导图）

### 一、目标（用户最新指令）
- 导图用一造水利案例**教材知识点**生成，并**结合《水总〔2024〕323号》编规**；不能只贴“旧编规”标签把现行规范推走。教材案例（429口径、应试直接依据）为主体，同步结合现行323口径。

### 二、实现：可复用知识块库 ＋ 案例映射（离线确定性、零编造）
- fused_323_lib.py：把323全链条思维导图拆成约30个**可复用知识块**（工程分类c、项目六部分A、五大费用B、建安4要素C、设备费D、独立费用E、预备费F、融资利息G、人工H、材料I、施工电J/水K/风L、台时M、砂石N、混凝土O、建筑单价8步P、安装单价Q、其他直接费R、间接费S、利润税金T、建筑概算U、设备费编制V、施工临时W、独立费用编制X、投资层级Y、资金流量Z、数字孪生b，及 econ/bid 衔接块），每块条目均摘自323思维导图原文。
- run_fused_all.py：建立 73 案例 → 知识块映射，在教材导图“📌分析要点”与“❓问题解答”之间插入“📖323现行口径”分支，并把双口径标记替换原“旧编规”标记。
  - 第三章计价类结合最密（如3.2→人工/材料/台时/单价8步/费率/利润税金；3.5→电/水价格公式；3.13→资金流量/融资利息/投资层级）。
  - 第一章按总投资/项目组成/移民/环保/水保/信息化对应（信息化→数字孪生块）。
  - 第五章按预付款/保留金（资金流量）、变更索赔（单价8步）、物价调价（材料补差/价差预备费）、偏差（投资层级）对应。
  - **第二章（工程经济）、第四章（招投标）323不直接规定其方法**：用 econ/bid 衔接块诚实说明（招投标：概算作最高投标限价参考、投标报价企业自定），不硬凑、不编造。
- 问题版：除教材等式结果挖空外，323现行参数（增值税率9%、利润率7%、设备采保0.7%、商品混凝土基价200等）一并挖空；纯文字案例（招投标/经济评价）与无答案的5.16本无确定数字结果，不硬挖。

### 三、三层验证（全部通过，0 pageerror）
- 生成检查：73案例全部含“📖323现行口径”；最短答案版646字符（3.6施工用风，内容本就少），无残缺。
- API抽查代表案例：2.1(econ+融资利息,3347)、3.2(单价8步,3544)、3.5(电/水价格,1227)、4.6(投标衔接,2781)、5.16(赢得值+教材未附,1918) 关键词全部命中。
- UI：章导图选第3章，聚合含施工用电价格、单价取费程序、融资利息；截图 ui_融合_第3章.png；0页面错误。

### 四、版本与备份
- 前端在导航调整时已 bump（index.html mindmap.ct2.js ?v=20260923ch1；sw.js CACHE_NAME shuili-exam-v8-20260923-ch1）；本次为数据更新（动态fetch），不再 bump。真实浏览器若见旧态强刷一次。
- DB备份：shuili_exam.db.bak_fusedall_20260923_153041（最新；另有 bak_fused_20260923_151750）。


---

## 2026-09-23 识别拆分精度深化：选择题答案/解析回填 + 题型校准

### 治本（utils/question_pipeline.py、utils/pdf_parser.py）
- 文末回填正则扩展：兼容环球卷 `N.【正确答案】X` + `【答案解析】`（原只认【答案】/【解析】）；旧口径兼容。
- 题型校准客观信号优先：回填后统一重判 q_type，答案≥2字母=多选、1字母=单选，无答案才看E选项/原标签；修单通道题 q_type 缺失、错误原 multi 标签。

### 真机复测
- 1110/1111 管理模拟A/B：答案 0→100%、解析 0→95-96%、单选60/多选20 零误判；823 真题全100%。
- 排除两处误判（不实）：多选5选项本就正确（A-E）；案例小问 stem 完整（验证误读字段名）。

### 特殊案例（待拍板）
- 1082 第34题 A/B/C/D 是4张现金流量图（无文字，答案C），真机截图确证——"选项不可能有图"的实锤反例；管线正确不硬凑但题缺，呈现策略触布局、待用户拍板。

### 门禁 / 回归
- 新增 reg_answer_backfill（16 断言 ALL_PASS）；全量回归 29 套件 / 28 PASS / 0 FAIL / 1 SKIP。
- 诊断报告 append A14.12、测试报告同步。专家28项终态不变：✅23 / ◐1(B3) / ❌3(E1·E4·V3) / ⏩1。


---

## 2026-09-23 章/科目导图“单棵大树”改造（案例无节，直接到章/科目）

### 背景
用户反复强调“案例就没有节，直接到章和科目导图去”。此前虽已默认进章导图、隐去节导图，但 `_mountAgg` 仍把每个案例渲染成带“X.Y”编号、带边框、320px 高的独立 markmap 卡片纵向堆叠，视觉上仍是“章→一节节案例”。目标：**一章一棵完整树、全科一棵完整树**，案例是章的自然分支，不再有“节”这一层。

### 离线生成合并树（gen_agg_maps.py）
- 从 DB 读 73 案例双版（answer id=197+2gi、question id=198+2gi）。
- `case_body(md,shift)`：去掉每案例 MD 的 `# 一造水利案例 / ## 第X章 / ### 案例N` 外壳与 `>` 引用标记，从 `####` 起保留正文；标题层级按 shift 调整。
- 章树：根 `# 第X章 章名` → `## 案例N 标题` → 正文（shift=-1：原 ####→###、#####→####）。
- 科目树：根 `# 一造水利案例（全科汇总）` → `## 第X章` → `### 案例N` → 正文（shift=0，层级不变）。
- 长度：章树 23564/25846/41273/40597/46295（第1-5章答案），科目树 178292；问题版略短。

### 入库（mind_maps，id343–354，共12条）
- chapter_answer：343(第1章)、347、349、351、353（第2-5章）；chapter_question：344、348、350、352、354。
- subject_answer=345、subject_question=346（chapter 字段“全科”）。
- **波折与修复**：首版 upsert 的 WHERE 只有 subject+map_type、漏了 chapter，致 5 章 chapter_answer 互相覆盖、只剩 id343（chapter 标“第1章”、内容却是第5章 46295）。修正 WHERE 为 subject+map_type+chapter 后重跑，12 条全部正确（备份 `shuili_exam.db.bak_aggmaps_20260923_182049`）。

### 前端补丁（mindmap.ct2.js）
- patch_agg_tree.py（10 段）：
  - state 加 subjectMode；_loadAll 加 `_buildAggMap()`。
  - 新增 `_buildAggMap`（rawMaps 按 map_type 建 chapterAgg[章号]={answer,question} 与 subjectAgg）、`_mountAggTree(elId,id,expandLevel)`（清空容器→建 100% 高内层 div→复用 `_mount` 单棵树）、`_exportAggTree(label,id)`。
  - 章/科目工具栏加“答案版/问题版”切换按钮（mmChMode/mmSubMode，接上 chapterMode/subjectMode）；body 由 mmChapterBody/mmSubjectBody（卡片堆叠）改为 mmChapterTree/mmSubjectTree（flex:1 overflow:auto 单树容器）。
  - bindEvents：章选章/切模式→chapterAgg 找 id→单树；科目同理。旧 `_mountAgg/_exportAgg` 保留未删（节导图已隐藏）。
- **大树 fit 缩成竖线问题**：章树节点成百上千，markmap 默认 initialExpandLevel=-1 全展开后 fit，缩放比例极小，整树挤成一条竖线、文字不可读。patch_expand_level.py（5 段）给 `_mount` 加 expandLevel 参数、Markmap.create 的 initialExpandLevel 用它；**章树 expandLevel=2（章→案例→📌/📖/❓三分支）、科目树=1（根→5章）**，fit 后清晰，点击节点逐层展开（markmap 标准交互：点击 toggle、滚轮缩放、拖拽平移）。

### 版本与验证
- index.html：mindmap.ct2.js `?v=20260923ch3`；sw.js CACHE_NAME `shuili-exam-v8-20260923-ch3`。
- Playwright（msedge headless）实测、0 pageerror：默认章导图单 svg；第1章含案例1-10；选第3章含案例16与“323现行口径”；点 mmChMode 切问题版含 ____、按钮文案正确；科目树单 svg、含第1章造价构成与第5章合同价款；科目问题版含挖空。截图 ui2_章导图_第3章.png（根在中、16案例排开、各含📌/📖/❓）、ui2_科目导图.png（根→5章）确认视觉正常。
- 前端备份 mindmap.ct2.js.bak_aggtree_20260923_182240、.bak_expand_20260923_182536。
- 真实浏览器需 Ctrl+F5 强刷。


---

## 2026-09-23 图形选项题方案2 + 表格小数误判题号治本

### 图形选项题（方案2，用户拍板）
- supplement 检测"题目无文字选项+答案区有答案+题干含图/空括号"→ 选项A-D占位"见配图"、回填答案、标记_figure_option。
- 新增 attach_figure_option_images：按"题干底→下一题顶"整组坐标渲染选项图（位图/矢量一并截入），作题干配图（水平居中、不两列）；常规 attach 跳过该类。
- 真机 e2e：1082 第34题（4张现金流量图、答案C）79→80题、缺号消除，配图生成；已入库 id=6366，DataService 1071→1072；作答选C"✓选对"、解析/口诀完整。

### 表格小数误判治本
- 1083 第44题表格小数 2.0/1.5/1.0 被题号正则误当"2."致题块截断漏拆；题号正则加 (?!\d)（点号后紧跟数字=小数）。复测 79→80题；44题库内本已存在、数据不缺。
- 1082/1083/1084 现均 80 题无缺号。

### 门禁 / 回归
- reg_answer_backfill 扩至 22 断言（4b图形题方案2、第5节表格小数），ALL_PASS；全量回归 29 套件 / 28 PASS / 0 FAIL / 1 SKIP。
- 诊断报告 append A14.13、测试报告同步。专家28项终态不变：✅23 / ◐1(B3) / ❌3(E1·E4·V3) / ⏩1。

## 2026-09-23 真题透析→题库覆盖核查：补录 67 题 + 覆盖门禁（A14.14）

### 求证路径（轻量）
- 放弃单进程顺序扫 84 份 PDF（卡死教训），改以真题透析 id 801-805(2020-2024)、1437(2025) 逐题比对题库；两级匹配：L1 严格归一化整串相等，L2 题干前 14 汉字 containment（兼容【年份】前缀/空格/题号）。

### 补录 67 题（均过质量门，gatefail=0；性质=历史导入遗漏、当前管线已能正确产出）
- 2020 +16(id6381-6396，假缺4)；2021 +0(同题已在库)；2022 +15(6397-6411)；2023 +17(6412-6428)；2024 +14(6367-6380)；2025 +5(6429-6433)。

### 资料缺口标记（源文件，非管线缺陷）
- 2024 透析 PDF 仅题号 1-61，多选 62-80（19 题）源 PDF 缺（透析二仅 mp4/flv、无 PDF）；全库检索无 2024 完整真题卷 PDF。已在诊断报告标记，待获取透析二 PDF/真题卷再导入；不视频抽题、不编造。

### 真机 e2e
- 补录含图题 id=6371（2024 双代号网络图关键工作数，答案 D=6）：配图水平居中不两列、选项 A3/B4/C5/D6、点 D → class user-correct ✓；配图文件实际存在。2023 同类网络图 id=6415 配图完整。

### 门禁 / 回归
- 新增 reg_real_paper_coverage：6 年透析 parse+两级匹配，断言每年透析题 100% 在库，运行 84s ALL_PASS；套件 29→30（29 PASS / 0 FAIL / 1 SKIP）。
- 年度覆盖（active）：2020=68/2021=82/2022=71/2023=74/2024=55/2025=80/模拟=820，一造管理共 1250 题；透析内容 100% 覆盖。
- 诊断报告 append A14.14、测试报告同步。专家 28 项终态不变：✅23 / ◐1(B3) / ❌3(E1·E4·V3) / ⏩1。


---

## 2026-09-23 七项诉求收官：全局搜索 / 配色提示 / 错题按钮 / 章节张冠李戴 / AI解析 / 口诀乱关联 / AI克隆配音框架

### 1. 顶部全局搜索（闭环）
- 新增 `backend/modules/search/global_search.py`（router prefix `/api/search`，GET `/global?q=&limit=8`），跨 5 类表参数化 LIKE：questions / flash_cards / notes / course_materials / knowledge_points+knowledge_framework（去重）。main.py 注册。
- topbar.js 重写：250ms 防抖→分组下拉（题库/闪卡/知识点/笔记/资料）、关键词高亮、章节元信息；Enter 开第一条、Esc 关、点击跳转，定位写 sessionStorage `global_open_target`；flashcard.js 新增 `_consumeOpenTarget()` 自动切 tab 并选中。实测搜“缺陷责任期”正常、点闪卡结果自动定位 id293。

### 2. 配色切换提示位置
- theme.js 删除切换时的 showToast；statusbar.js 新增 `_flashScheme()`，在底部状态栏配色入口（时间左侧）短暂显示“已切换：<方案名>”2.5s。实测无弹窗、状态栏提示正常。

### 3. 移除“标记错题”按钮
- question-practice.js 删除 `#qpMarkWrong`；答错由后端判题时自动落错题本（UI 提示“已自动加入错题本”），绑定代码有空值保护。

### 4. 章节张冠李戴治理（共修 76 题，章号≥7 清零）
- 备份 `backups/shuili_exam_before_chapter_fix_20260923_1831.db`。
- 定章优先级：标题明确法律名 > source 文件名（去连字符，“第N讲第X章”取X）> knowledge_point > chapter 泛指；第3章“工程项目合同/信息管理”具体词排在泛指“合同”之前。
- 17 题归第3章（id3582-3591、5419、5433、6136-6143）；59 题按标题法律名修正（价格法 id5260/5331/5493 等归第2章第4节；招标投标、政府采购、建筑法/质量/安全条例各归其节；裸章号 5830/5831/5922/6232/6123 修正）。实测《价格法》题全部在第2章。

### 5. AI 生成缺失解析（全部完成）
- 一造管理 single/multiple 原缺 151 题，用 qwen2.5:7b 批量生成（2~4句、≤120字、清洗前缀、失败重试、断点续跑），现 1187 题解析无缺失。
- 坏数据治理：软删除 4 道跨题/跨页拼接、题干选项答案互不对应的损坏题（id3406/3566/3595/3610，可恢复）；id6175 解析过短已重生成。
- 质量校验：无 <think>/AI口吻/乱码；关键题（6101/6103/6108）准确。

### 6. 口诀乱关联治理（系统性问题，已解决）
- 诊断：23 个核心口诀被 4~16 个不同考点错误共用（如投标保证金/中标公示/履约保证金被套“大公外国”，租赁/撤销权/提存被套合同框架口诀）。
- 高置信手写 25 卡（缺陷责任期“**实际竣工起算·一般一年最长二·质保金3%**”、投标保证金2%、中标公示3日、履约10%、中标通知30日订合同、租赁20年、撤销权1年/误解90日/最长5年、提存5年、三类抗辩、代位权、风险交付转移、合同书面、不可抗力、城建税7/5/1），并补齐 12 张缺口诀卡。
- 其余 144 卡用 qwen2.5:7b 基于卡片自身 front+back 重生成专属口诀（数字严格来自 back、分批6张批末提交、复用≥3 清零），抽查数字准确、无乱关联。

### 7. AI 模仿本人音色批量配音框架（除录入声音外全部就绪）
- 新增 `backend/modules/mt/voice_engine.py`：可插拔引擎（CosyVoice2 / GPT-SoVITS 零样本，edge-tts 回退）、引擎探测（以配置为准、端口仅参考，避免 GCPHost 占用误判）、voice profile（参考音频+文本）、配置持久化 `voice_engine.json`。
- 新增 `voice_dubbing.py`：文本预处理（清洗 Markdown/HTML、公式符号转写）、停顿切分（逗号300/句号400/数字时限公式500ms）、逐段克隆合成→ffmpeg 注入静音并拼接→落盘→写 mt_voice_audio(source=ai_clone)，hash 版本联动、断点续跑。
- 路由经 mt/routes.py 挂载 `/api/mt/voice/*`（profile/script、profile/upload、engine、batch、batch 进度）。
- 前端磨耳朵控制行新增“🗣️录入我的声音 / 🤖一键AI配音”及引擎状态与进度轮询。
- 安装脚本 `tools/install_cosyvoice.ps1`（ModelScope 下载 CosyVoice2-0.5B、跳过 deepspeed 等重依赖、生成 start_cosyvoice.bat，可重复）。
- **引擎已装并端到端跑通（2026-09-24）**：
  - 内存受限（16GB物理/commit≈29GB）下确定稳妥管线：参考音色只编码一次；文本按 ≤30字短分段逐段合成（句末400 / 数字公式500 / 逗号300ms），段间 gc，ffmpeg anullsrc 注入停顿、concat 拼接为 64kbps mp3，写 mt_voice_audio(source=ai_clone)。
  - 全自动生命周期：点“一键AI配音”后端隐藏拉起 CosyVoice（实测 35s 就绪）→ 编码 speaker → 逐卡合成；批量结束（成功/失败三退出点）自动关闭引擎释放约 4GB（实测 availPhys 0.24→6.21GB）。
  - 验证：card_id=10 成品 36.44s、24kHz、/audio/10 HTTP 200、库记录 source=ai_clone。
  - 前端：实际入口 index.html 引用 static 版，modules 与 static 两版 flashcard.js 的 poll/onclick 均已更新（未录声音先提示、去掉通用音色确认、按钮禁用/恢复、显示引擎启动与错误）。
- **用户仅剩两步**：①在“朗读记忆专练”点“🗣️录入我的声音”录约30秒（当前 voice_profile 内为测试音频 zero_shot_prompt，须替换为本人声音）②点“🤖一键AI配音”。全套 606 张 CPU 上约 10 小时量级，属一次性挂机，hash 联动支持断点续跑。
### 7.1 配音收尾：方案①导入 + 方案②自动选麦克风（2026-09-24，已端到端验证）
- 根因：系统默认录音设备为 ToDesk 虚拟声卡（无远程输入时输出静音），本机真实麦克风信号被压至正常约 1/100（说话 peak 0.008），电脑直录拿不到有效声音。
- 方案①（离线上传·推荐）：磨耳朵页新增“📁导入声音文件”按钮 + 隐藏 file input，点按钮选手机/外部录音（webm/mp3/ogg/m4a/wav 均可），走 /profile/upload，ffmpeg 统一转 16k 单声道；无需拖拽。
- 方案②（电脑录音）：getUserMedia 授权后 enumerateDevices，自动排除 ToDesk/Virtual/虚拟，按 deviceId exact 切到真实麦克风再录。
- 端到端实测（edge-tts 中文样本代跑）：上传 200 → ref.wav 20.78s RMS0.0595 peak0.657；引擎拉起→speaker 编码 14s→synth 49s 出 4.7s 音频 RMS0.113 peak0.794→引擎自动关闭。
- 测试样本已移出 voice_profile，当前 profile_recorded=false（干净待录入），防止误用测试音色批量。
- 用户最终操作：手机安静环境录约 30 秒（可读录入页脚本）→ 传电脑 → 点“📁导入声音文件” → 点“🤖一键AI配音”挂机（606 张约 10 小时，断点续跑）。


### 附带修复：index.html 活跃心跳恢复（全量回归发现）
- 全量回归暴露 reg_frontend_wiring FAIL：index.html 旧版缺活跃心跳、仍含墙钟上报 module:dashboard（前端合并回退，与问题7同源，本轮未主动改 index.html）。
- 已恢复：IDLE_MS 90s 空闲/visibilitychange 隐藏不计、activeSecs 累计、study_pending_queue 断网补报、module 取当前路由；reg_frontend_wiring 重跑 ALL_PASS。不可见 JS 逻辑、不触布局。


---

## 2026-09-23 晚｜思维导图“知识点版”重构 + 科目下拉阻断修复（已验证）

### 一、导图从“按案例堆叠”改为“按知识点融合”（用户：“案例是用里面的知识点和例题名称以及新编规融合成导图”）
- `kp_data.py` 固化 5 章约 72 个跨案例归纳知识点，结构 `KP[章]=[(知识点名,[对应例题],[要点公式],[323新口径])`；共性知识点（工程量计算、单价编制、施工电/水/风）只出现一次、不随案例重复。
- `gen_kp_maps.py` 生成知识点版章/科目导图并更新 id343–354（备份 `shuili_exam.db.bak_kpmaps_20260923_222009`，在线 backup API 一致备份）。
  - 章树：`# 第X章 → ## N.知识点 → ### 📚对应例题/📝要点与公式/📖323新编规 → - 内容`；科目树多一层（## 章 → ### 知识点 → #### 三类）。
  - 问题版 `blank()` 仅挖“数字+%/元/天/日/倍/月/年”等参数（区间整体挖），符号/几何公式与例题名称保留。
- 前端 `mindmap.ct2.js` 复用单棵树渲染；科目树 initialExpandLevel 1→2（知识点版多一层）。

### 二、点击节点名称即展开（用户：“点击就显示，不点击就不显示”）
- markmap 默认仅节点前圆点(circle) click→toggleNode；`patch_click_toggle` 在挂载容器加事件委托：点击 foreignObject（排除 a 链接）→ `d3.select(g.markmap-node).datum()` → `inst.toggleNode(d.data)`。
- 已验证 fold 1→0、state 树同步、depth3 子节点正确出现（答案版公式/例题名称、问题版 ____ 均可见）。

### 三、科目下拉只剩“一造管理”阻断缺陷修复
- 根因：`core/subject-scope.js` 的 `SubjectScope.list()` 请求 `/api/common/system/all_subjects`（404，catch 退化为只显示当前科目）；后端实际接口为 `/api/v1/system/all_subjects`（`api/v1/system.py`，聚合 题库/教材/视频/闪卡/导图 科目，返回 `{subjects:[...]}`）。
- 修复 fetch 路径为 `/api/v1/system/all_subjects`；下拉恢复 10 项（含一造水利案例）。

### 四、版本机制关键认知（避免重复/无效 bump）
- 用户真实入口是根路由 `/`：`main.py root()` 读磁盘 index.html，把所有 src/href 的 .js/.css 的 `?v=` 统一替换为 `core.build_meta.BUILD_TS`（后端进程启动时间戳，重启即更新），**不写盘**；`/static/index.html` 是磁盘原版（指纹可能旧），验证必须走 `/`。
- 改前端内容后**重启后端**即自动发新版；SW 不走根路由，CACHE_NAME 需手动 bump（当前 v9-20260923-upfix）。

### 五、验证（Playwright + requests，0 pageerror）
- 科目下拉 10 项含水利；水利默认章导图；章知识点结构/点击展开公式与例题名称；问题版参数挖空；Tab（水利显章/科目/造价树、隐节）；科目导图含 5 章与“赢得值”等知识点。

### 六、注意
- 排查期间发现 watchdog/main 被约每 7–9 分钟整体重启一次（疑另一个 Doubao 会话反复跑 start.bat），两会话并发会互相覆盖、打断验证；后续若再遇环境反复，先确认是否有其他会话在操作。
- 例题逐问详解仍在 id197–342（节导图 Tab 已隐藏）；知识点版“📚对应例题”仅列名称，是否加点击跳转待用户口径。

## 2026-09-24 教材“开始目录拆分解析失败”治本（A14.15）

### 四类链式根因（真机求证）
- ①material.py 缺 logger，方法0失败→except 内 logger NameError，跳出外层 try，方法1/2兜底没机会跑（直接现象“name 'logger' is not defined”）。
- ②方法0 extract_ocr_toc 返回 TOCNode 未转 dict，ch.get 报 AttributeError。
- ③end_page 扁平算法，章 P1-0。
- ④方法0对文字型也走 OCR 容错、产脏数据（水印碎片/丢节/假章/页码0）且优先级最高会抢占——只修报错反而更糟。

### 治本
- 补 logger；新增 normalize_chapters（TOCNode 边界转 dict）、compute_end_pages（层级 end_page，章 end=最后节 end）；重排优先级：方法1全PDF六步首选、方法0仅扫描件 OCR 兜底、方法2内置outline最后。

### 验证 / 门禁
- 重启后端单实例；真机：一造管理 id48=34章（章end正确、节齐全、无脏数据），水利案例 id49=17章。
- 新增 reg_material_split（22断言，自包含确定性）ALL_PASS；套件 30→31，全量 30 PASS / 1 SKIP。

### 全量回归两点求证（A14.15 续）
- watchdog_hardening 静态断言 FAIL：实查 watchdog.py 已用更优 listen_state 内核监听表/really_dead 判据，逻辑正确、仅门禁字符串过时 → 按“实际代码>门禁”对齐门禁，重跑 PASS，不回退正确代码。
- frontend_wiring 4 项 FAIL：question-practice.js「标签练习 tab」整块回退（打标功能在），系问题7前端增量合并遗漏、归其他对话框，本对话框不改该文件。
- 最终：31 套件 = 29 PASS / 1 FAIL（frontend_wiring 跨对话框）/ 1 SKIP；本对话框 30 套件全确证。


## 2026-09-24 教材“分析要点”原生知识点校准（72→120点）＋扁平化交互重构

### 诉求与取证
- 用户：教材每个案例“分析要点”里本就含知识点，分两种——①明确写“知识点1/知识点三”等编号（原样采用编号与表述）；②无关键词（按“本案例考查/重点考查…”及“问题N”逐条还原）；多次强调“一定要全”。
- 全文检索“知识点”25处、集中第2章7个案例（阿拉伯/中文编号混用），其余65案例无字样；逐案例定位“分析要点”，原文存档《教材原生_分析要点全量.txt》（约2226行）；自动切分脚本不可靠，改人工逐章通读全部73案例。

### 成果：120 个有教材依据的知识点（kp_data.py 重写为 5 元组）
- 分布：第1章24、第2章24、第3章19、第4章27、第5章26。
- 结构：(名称,[教材出处],[对应例题],[要点公式],[口径说明])；第4章27点补齐教材原文引用的法规依据（招标投标法/实施条例、GB 50501-2007、标准施工招标文件等）。
- verify_coverage：120点、73案例全覆盖、无未覆盖。

### 扁平化交互重构（关键）
- 去掉“📍教材出处/📚例题/📝公式/📖口径”分组标题层，具体条目直接挂知识点下、用 emoji 前缀区分；章/科目树 initialExpandLevel 由 2 改为 1；click 仍用普通（非递归）逐级 toggleNode。
- 层级：章＝章(0)→知识点(1)→条目(2)，初始只见知识点名、点一次显示全部条目；科目＝全科(0)→章(1)→知识点(2)→条目(3)，点章见知识点名、点知识点见条目。
- 删除 build_chapter/build_subject 开头产生空节点的 blockquote（消除多余空节点）。

### 三层验证（全通过）
- DB层 id343–354：知识点标题计数 24/24/19/27/26、科目120，扁平 emoji 齐全、无 blockquote，全部通过。
- API层：GET /mindmap/{id} 200、内容完整（📍📖齐全）。
- 浏览器 Playwright：章19、展开含 📍📚 及“设计开挖量”公式、问题版挖空 ____、科目120及逐级展开，0 pageerror。

### 备份 / 版本
- DB 最新备份 bak_kpmaps_20260924_075624；kp_data.py.bak_72_20260924、.bak_kp4_20260924_075616；mindmap.ct2.js .bak_expand1_20260924_074931；sw.js .bak_sw_20260924_075817。
- SW CACHE_NAME → shuili-exam-v10-20260924-kpflat；后端已重启发版（真实浏览器若仍旧可 Ctrl+F5）。

### A14.16 目录页码乱序治本
- 根因：①PDF cmap 页码字形缺陷(0→O/o、6→g、7→z)；②前导符依赖，无/单前导符的第二/三/四/六章被步骤1丢弃、右置页码 top 错位拆独立行。
- 治本：_emit 坐标分离右置页码(不含前导符)、_repair_page_token 形似纠错(须合法页码)、_normalize_toc_entries 重建规范行/去叠字、compute_end_pages 钳制 end≥start。
- 真机接口 e2e：id49 七章 P1-9…P155-252、id48 六章 P1-20…P285-370 均单调正确。
- 门禁 reg_material_split 22→36 断言 ALL_PASS。
### A14.17 案例教材两级目录治本（id50）
- 现象：id50《案例分析水利工程》仅出 8 个“章”（案例六~十六）、页码全 P1，大批案例丢失。
- 根因（四类）：①目录标题 OCR 成“目录. .”“4目录”，干净“目录”反在末页，锁定从末页起、丢前两页；②“案例N”两级编号无识别分支、被当 level1；③页码/前导符 top 错位拆独立行、_reattach 未被调用；④部分页码 OCR 残缺（（。/仰的/口的/侈的/怜的）。
- 治本：_is_toc_title（去噪后恰为“目录”）锁定 page6-8、排除噪声标题；step4 案例→level2、step5 案例序号、_normalize_hierarchy 去案例前缀并编号“章.案例”；_normalize_toc_entries 增孤立页码同页 top 配对(≤12pt)、双省略号满足 RE_LEADER；残缺页码相邻推断、end 由下一案例界定。
- 真机：5 章/73 案例=78 节点 mono/bad0；章1（1/8/13/16/20/25/28/31/34/39）、章4、章5 全对，2.11=65、2.12=67；id48/id49/id50 零回归。
- 门禁 reg_material_split 36→47 断言 ALL_PASS；HTTP e2e 8 项 PASS。报告不实标记：无（初次结果经证为真实缺陷）。


## 2026-09-24 知识点“📚例题”可点击 → 案例逐问详解弹层

### 诉求
- 用户确认：让知识点“📚对应例题”可点击，直接查看该案例逐问详解（id197–342，节导图 Tab 已隐藏）。

### 实现（最小侵入、布局零改动）
- gen_kp_maps：新增 (ch,n)→gi 映射与 case_links；解析例题条目编号 X.Y（多案例如“4.1、4.2”展开为多链接），链接标题用 FLAT 权威标题，生成 markdown 链接 [X.Y 标题](#case-id)，跟随答案/问题模式选 id（answer=197+2gi / question=198+2gi）。
- mindmap.ct2.js：新增案例详情 modal（固定遮罩＋关闭＋markmap 容器）；模块根持久事件委托拦截 a[href^="#case-"]（preventDefault，不触发节点 toggle、不改 hash）；新增 _openCaseModal（expandLevel=-1 全展开，通读逐问）。
- 链接统计：章 33/27/26/43/35，全科 164。

### 验证（全通过）
- 浏览器：第3章展开知识点→点 📚链接（#case-247＝3.1）→ modal display=flex、标题“答案—第3章第1节 引水工程设计工程量计算”、body 渲染含分析要点与逐问计算式、关闭后 none，0 pageerror；视觉自检布局正常。
- verify_case_ids：73 案例 id 规律 0 不符。

### 备份 / 版本
- DB bak_kpmaps_20260924_155029；mindmap.ct2.js .bak_casemodal_20260924_154856；SW bump v11-20260924-casejump；后端已重启发版（旧浏览器 Ctrl+F5）。


## 2026-09-24 导图支持鼠标拖拽平移

### 问题根因
- markmap 的 d3.zoom 本支持左键拖拽平移（绑在 svg），但节点 foreignObject 上 `mousedown stopPropagation`，事件不冒泡到 svg，导致按在节点上拖不动、仅空白背景处可拖。

### 修复
- markmap-view.js：foreignObject 去掉 mousedown 阻断（保留 dblclick 阻断），加 user-select:none 防拖动选中文字；circle 圆点保留 mousedown 阻断（圆点是明确折叠按钮，不用于拖拽）。
- d3.zoom 拖拽后自动抑制 click（document 捕获阶段 stopImmediatePropagation），拖拽不误触节点 toggle；未移动的干净单击仍正常 toggle；📚案例链接点击不受影响。滚轮缩放、触控板行为保持原样。

### 验证（全通过）
- 浏览器合成事件：节点上 mousedown→move(130,70)→mouseup，pan dx=130 dy=70 精确；拖拽后 click 不到达节点冒泡（不误展开）；干净单击 toggle 正常（展开、案例链接出现）；0 pageerror。

### 备份 / 版本
- markmap-view.js .bak_drag_20260924_155757；SW bump v12-20260924-drag；后端已重启发版（旧浏览器 Ctrl+F5）。

## 2026-09-24 横向覆盖全部 7 本教材目录拆分：四项通用识别治本（A14.18）

### 真机基线（治本前）
- id47 法规 10 章完美；id44 管理碎片“8”、mono False；id45 水利第 9/11/13 章页码异常 + “务第9章”噪声；id43 经济严重错误 42 碎片章；一造 id48/49/50 正确。

### 四项通用治本（识别内核，与科目无关）
1. 编号独立成行并回标题 `_merge_standalone_number_lines`（收紧：纯编号须含点 X.X、排除裸页码、标题须含中文）；一次误伤 id48（6→8 碎片）已修复回归。
2. 丢百位页码唯一补全 `_repair_truncated_page_numbers`（回退谷底 + 百位唯一：25→225 / 35→335 / 44→444；教材开头正常小页码不触发）。
3. 篇标题跨行重组（`_reconstruct`：无 leader 第X篇标题向后吞并单字，“实/务”拼回，消除“务第9章”）。
4. OCR 行首编号字形纠错 `_repair_entry_glyphs`（id43 实为 HiddenHorzOCR 扫描件；`^才X.X→1X.X`、`^第X童→第X章`，正常“人才/儿童”不误伤）。

### 验证 / 门禁
- 全 7 本 mono=True、bad0：id43 20 章 + 74 节、id44 10 章、id45 15 章（补全页码全对、标题噪声消除）、id47 10 章；一造 id48 6 章 / id49 7 章 / id50 5 章 73 案例零误伤。
- reg_material_split 47→**56 断言** ALL_PASS；HTTP e2e id48/43/45 共 8 项 PASS。
- 非核心 OCR 已知限制：id43“恬5合同价款约定”编号/页码损坏错位、无法可靠唯一还原，保留可读节点、标 OCR 不可信，不臆测。
- 报告不实标记：无（报告未对非核心一建下结论，缺陷为主动核查新发现真实问题；id43 性质经 HiddenHorzOCR 修正为扫描件 + OCR 层）。
- 专家 28 项终态不变：✅23 / ◐1(B3) / ❌3(E1·E4·V3) / ⏩1。

## 2026-09-24 讲义题目识别器内核重写（A14.19）：945 题、坏题 0

### 真机基线（治本前）
- PDFQuestionExtractor（utils/pdf_question_extractor.py）服务讲义 detect_questions / import_questions 端点；98 份一造管理精讲短讲义。id306 实有 17 道完整例题，旧识别器仅 2 道，且把【考点清单】填空当题干、错配后面例题选项答案（张冠李戴），多选全标单选；普遍每份答案标记 1–18、识别仅 0–5。

### 治本（识别内核重写）
1. 新增 RE_QMARK 锚点【例题•单选/多选】（• U+2022 / · U+00B7 均覆盖，不匹配【例题讲解】）；有强锚点即切块，零锚点才走数字题号（点后 (?!\d) 排表格小数）；治本 id409/410（旧 marks≥3 阈值错误）。
2. RE_OPT_MARK 兼容全角点．/全角字母Ａ-Ｅ/选项同行/A 后无点，全角归一。
3. 选项排列错乱（id444#3 印成 A C B D）：按位置收集、同 key 首次、集齐 A-D、相邻切值归位，不要求文本流严格连续。
4. 图形选项题（4 道，选项为现金流量图）：RE_FIGURE + 合法字母答案占位“见配图”、figure_option；配图本身为讲义场景已知限制（真题图形题已由 question_pipeline 方案2 覆盖）。
5. 计算演示/简答（id332 公式、id348 土地增值税“解：”）正确排除。
6. 题型答案事实优先：id311/425/446 源标多选但答案单字母 → single。
7. 导入：缺答案 30 道 no_answer 跳过不进可练池；deduplicate 批内签名去重 + 库比对，返回 duplicate/no_answer。

### 验证 / 门禁
- 全 98 份：945 题 = single692 / multi253、figure4、no_answer30、坏题 0（答案字母不在选项）、多选误判 0、召回 99.8%。
- 新建 reg_pdf_question_extract.py 40 断言 ALL_PASS（合成文本/确定性）。
- 后端重启（PID15272、单实例）；HTTP e2e：306=17 / 323=7 / 433=18(fig3) / 444=39(noans2)。
- 报告盲区标记：A14.12“识别拆分精度深化”仅覆盖真题 question_pipeline，未含讲义独立链路 PDFQuestionExtractor，已补、独立门禁守底；后续提“识别”须注明链路。
- 专家 28 项终态不变：✅23 / ◐1(B3) / ❌3(E1·E4·V3) / ⏩1。

## 2026-09-24 E1 首次使用引导落地（A14.20）：专家项 ❌→✅

### 治本（不改布局，仅新增可关闭覆盖层）
- 新建 frontend/modules/onboarding/onboarding.js，index.html 引入；首次（无 onboarding_done_v1）自动三步：欢迎 → 六步学习路径（material→question→exam→wrong→flashcard→analytics，可点击直达）→ 学习闭环。
- 路径点击写标记、关闭、hash 跳转；完成/跳过/×/Esc 经 StorageService 标记后不再自动弹；settings 系统工具加“🧭 新手引导”可重新打开；sw bump v13、precache onboarding.js（离线首次引导）。

### 验证 / 门禁
- 真机 e2e 六项全过（自动弹出 / 三步 / 路径跳转 / 标记持久 reload 不弹 / 设置重开 / 布局零改动、主色 #1a73e8）。
- 新建 reg_onboarding.py 18 断言 ALL_PASS。
- 报告原 E1“生效前端无 onboarding”论断经真机核对属实，本次真实补齐，无不实。
- 专家 28 项：E1 ❌→✅，终态 **✅24 / ◐1(B3) / ❌2(E4·V3) / ⏩1**。

## 2026-09-24 E4 字号大小调节落地（A14.21）：专家项 E4 ❌→✅、V3 用户决定不做

### 治本（不改布局结构/位置，仅整体缩放）
- 求证：旧 setFontSize 仅在死副本 app_v3_*.js（改 rem 基准），活前端大量 px、不引用它，字号确不可调，报告 E4 论断属实。
- 用 documentElement.style.zoom 全局缩放：index.html head 最早内联读 zhixue_font_scale_v1 即应用（不闪烁）。
- 设置→基本设置 主题配色下加“🔠 字号大小”四档：0.9/1.0(默认现状)/1.08/1.18，clamp 0.9~1.25，写本地、即时高亮；sw bump v14。

### 验证 / 门禁
- 真机：无标记 zoom=1＝现状；点“较大”zoom=1.08 视觉放大且写入；刷新保持；恢复标准；布局尺寸/位置不变。
- 新建 reg_font_scale.py 12 断言 ALL_PASS。
- V3 用户明确“视频不用关联题”，专家表 ❌→⏩ 不纳入交付。
- 专家 28 项终态：**✅25 / ◐1(B3 静态库加密) / ❌0 / ⏩2**。

## 2026-09-24 B3 数据加密二次实测与边界收敛（A14.22）

### 求证 / 结论
- 复跑 reg_backup_crypto（9组）与 reg_backup_restore，均 ALL_ASSERTIONS_PASS：备份 AES-256-GCM 加密链路健在、密钥分离、备份树无 .key。报告“备份已加密”属实。
- B3 三层已就位：口令 bcrypt 哈希 + 局域网自签 TLS + 备份/恢复整条加密。
- 活库 SQLCipher 透明加密经威胁模型评估**明确不做**：本机单人不公网、密钥落盘与库同机≈无增益、破坏“双击解压即用”、224MB 停服迁移高风险、密钥丢失即报废；业内单机 SQLite 通常不做。
- B3 由“待拍板”收敛为“已评估、无进一步动作建议”。专家终态维持 ✅25 / ◐1(B3 活库明文，已评估不做) / ❌0 / ⏩2。


## 2026-09-24 应用图标替换为“大坝·学士帽”（方案2）

### 决策
- 用户从 4 个图标方向中选定方案2（水利大坝泄水＋学士帽，蓝/青）。
- 先按平台规格导出：1024×1024 PNG（595.9KB，<3MB）、WEBP（38.3KB，<100KB），及 216 PNG/WEBP，存于 `图标_水利智学/`。

### 替换范围（活跃文件，布局零改动）
- `favicon.ico`（16/32/48 多尺寸 ICO）、`icon-192.png`、`icon-512.png` 内容更新为方案2。
- `manifest.json`：icons/shortcuts 图标统一加 `?v=20260924logo`，移除原 💧 svg data-uri 条目。
- `modules/layout/sidebar.js`：顶栏 💧 emoji → `<img class="sidebar-logo">`（26×26），CSS 由字号改为图片尺寸，标题文字不变。
- `index.html`：启动加载页 📚 → icon-512 `<img>`（72px）；head 的 favicon/apple-touch/manifest 引用加版本查询。
- `sw.js`：CACHE_NAME v15-admin → `v16-20260924-logo`，PRECACHE 图标 URL 同步加版本（SW 仅移动端 HTTPS 注册）。

### 关键认知
- 系统按访问来源差异化：电脑本机（localhost/127.0.0.1）注销 SW、清空 Cache、零缓存直读；SW 仅移动端（Tailscale HTTPS）启用。故本机 caches 为空是设计行为，非故障。

### 验证（全通过）
- HTTP：favicon image/x-icon、icon-192 naturalWidth=192、icon-512=512、manifest icons/shortcuts 带版本；侧边栏 IMG complete、naturalWidth=192；特写截图确认显示大坝帽图标、布局不变；0 pageerror；sw.js node --check 语法 OK。

### 备份
- 7 文件 `.bak_logo_20260924_184912`（favicon/icon192/icon512/manifest/sw/sidebar/index）。


---

### 7.2 题库图表直显 + 日历星期修正 + 报错根因批量修复（2026-09-24，已实测）

**任务①图表直显**：配图本就直接显示（.q-figure display:block，点击仅放大 lightbox）；表格类内容被 PDF 抽成纯文本，已重建为受控 HTML 表格（5931 单代号关系表、5930 双代号紧前表、5749 敏感性分析表、5523 价值工程成本表），刷题页直接渲染、宽表横向滚动；5523 移除与 HTML 表格重复的表格配图。版本戳 components/common-utils/question-practice→v20260924fig1。

**任务②日历星期**：dashboard 学习日历表头写死“五六日一二三四”与数据错位，改为 weekDays 动态生成（周一开头）并修正 .join('')；实测 2026-09-24 落在“四”列高亮。dashboard.js→v20260924cal1。

**任务③报错根因修复**：71 条 recognition_errors，根因四类——表格识别失败 / 选项张冠李戴切分错位 / 解析混入选项 / 页码与【经典例题】杂质残留。共处理 15 题：4 表格重建；选项题干清洗（3252 选项B改“建筑安装工程投资”[2017真题核实]、3283 选项A改“业主与建筑师”、5968 去【经典例题答案】、4909 选项E补“个月”、3267 去页码）；5 严重错位软删除标缺陷（5820/5822/5823/5850/5853）；5614 标过时（造价咨询企业资质已取消）。报错记录收尾：fixed 50、ignored 14、confirmed 7（缺图缺选项、待回PDF重导）、pending 0。

**顺带修复**：题库按钮“加载后数秒内点击无反应”的绑定窗口期——afterRender 在 await _loadChapterStats 前先 bindEvents() 一次；实测加载后 5 秒按钮即可点、全选立即生效。question-practice.js→v20260924fix1。

备份：backend\data\shuili_exam_before_errorfix_20260924.db。


---

### 7.3 手机竖屏遮挡批量修复 + 分析/AI末端功能实测（2026-09-27，已实测）

**背景**：用户反馈手机竖屏刷题内容被遮挡，尤其多选题“✓提交答案”按钮被挡、无法刷题，多处显示被遮挡、布局不协调；要求 144 名专家真正起作用、功能齐全到每个末端（含无按钮的分析功能），能两行显示的尽量两行。

**统一根因**：手机端真正滚动容器是 `.content-scroll`（整页 overflow:auto），而桌面式“固定高度模块 + 内层列表 overflow:auto”在窄屏被压扁，内容困在极小内滚窗、看似被遮挡。

**修复（仅 `frontend/css/mobile-shell.css`，全部包在 @media≤720，桌面零改动）**：
- 增补七：刷题题卡 `.qp-question-card`（含 `.has-analysis`、**含未答题态**）与左右栏改块级自然高、取消固定高/内层滚动；解析区取消 60vh/300px 内滚；多选提交条 `#qpMultiTip/#qpMultiSubmit` 自适应、按钮 min-height44 不被裁切；题干16px、选项15px、长文自然换两行。
- 增补八：落地页 `.qp-chapter-tree` 自然高、2 列、章（父级）column-span 横跨整行；条目 flex 布局、复选框17px、标题13px 长名换两行、计数不挤压。
- 增补九：错题本 `.wrong-book-module/.wrong-list` 改 flex:none、自然高、overflow:visible；错题卡全宽，操作按钮换行、min-height40。

**缓存指纹（确保 HTTPS 手机端拿到新样式）**：`index.html` 引用 → `mobile-shell.css?v=20260927mob9`；`sw.js` CACHE_NAME → `shuili-exam-v17-20260927-mobfix`（install 解析首页指纹重新预缓存）。

**验证（CDP 模拟 390×844 iPhone，硬重载禁缓存，逐项通过）**：
- 多选题（id=5480，answer=AE，5选项）真实点 A、C 后提交：A 绿“✓选对”、C 红“✗错选”、E 橙“●正确答案(漏选)”，出答案解析与考点定位；提交按钮无需滚动即完整可见。
- 落地页章节树自然展开（约1097px）、2 列、章标题横跨、整页滚动；错题本 `.wrong-list` 展开（约71526px）、卡片含选项与“查看解析/加入复习/移除错题”。
- 分析功能确认真实有数据（非演示）：学习分析 5 标签（数据/考点图谱/真题/大纲/应试预测），386答题/61.7%正确率/189错题/21考试、近7天趋势、章节雷达；应试预测 23%通过、预计35.9/100、风险较大、置信度中、含4场有效模考加权依据；AI薄弱点（科目覆盖率25%、逐章覆盖率/正确率/未掌握错题/待刷、一键强化）。
- AI 详细解析端点 `POST /api/v1/ai/explain_question` 实测 code=200、返回 1722 字结构化解析（考点定位/解题思路/逐项分析）；Ollama 11434 运行，qwen2.5:7b 等模型齐全。

**专家对比说明**：144 专家经 `python backend/core/experts/latest_report.py` 确认全部真实运行（非空壳）。后端启动完整环境基线为 28 个治理类 warning（新旧API并存、巨型文件、硬编码主色、RAG 0 embedding、期望路径文件缺失但功能落在 ai_brain/ai_unified/analytics 等其他模块——属路径约定不一致，非用户功能损坏）。手动 `GET /api/common/experts/run-trigger/startup` 在未装 fastapi 的降级子进程执行，冒烟类专家报 import 失败、扫描根目录不同，数字与基线不可直接比较；本次改动仅移动端 CSS 与缓存指纹，不涉及后端逻辑/布局常量，不构成功能回归。


---

### 7.4 手机竖屏精细化压缩：选择章同行 / 底部切题栏 / 薄弱区折叠 / 错题筛选同行（2026-09-27，已实测）

**用户 4 项需求（全部手机竖屏）**：
1. 刷题模式“选择章”压缩宽度；
2. 切换题操作不方便；
3. “薄弱点强化训练”可动态隐藏、增加显示区域；
4. 错题本“全部状态/全部知识点/全部时间”可在一行显示。

**改动**：
- 新增 `frontend/js/mobile-tweaks.js`（仅 matchMedia≤720 生效；桌面/平板/横屏 no-op 并复位）：
  - A. 做题时在底部注入固定切题栏 `#mQNav`：[← 上一题] [x/total] [下一题 →]，按钮 min-height46、拇指可达；通过代理点击原 `#qpPrev/#qpNext`（原按钮被塞在顶部工具条的横向滚动区、位于屏幕外，是“切题不方便”根因），行为与原按钮一致；进入练习自动从第 1 题计数，末题同步原按钮“完成/交卷”文字。
  - B. 章节落地页“薄弱点强化训练”默认折叠为单行标题（含“展开▼/收起▲”开关），点标题或开关展开，未隐藏功能。
  - MutationObserver + 400ms 定时 reconcile，幂等，适配异步/重渲染。
- `frontend/css/mobile-shell.css` 增补十（@media≤720）：章节配置“按章:[选择章 flex1 1 0 约160px] 题量:[输入框72px]”同一行；错题筛选条改 row，三个 `.wrong-filter-select`（含 .wide）flex1 1 0 同一行、字号12，按钮保持整宽；薄弱区折叠/底部切题栏样式；`body.m-nav-on` 内容预留 76px 底部空间。
- `index.html` 引入 mobile-tweaks.js（?v=20260927mt1）；`sw.js` CACHE_NAME→`v18-20260927-mtweak`，PRECACHE 增补 `/static/js/mobile-tweaks.js`。

**验证（CDP 390×844，硬重载禁缓存，全通过）**：
- 落地页薄弱区默认折叠（单行，省约150px），点“展开”恢复 3 个薄弱章按钮、可再“收起”。
- 章节配置“按章/选择章/题量/输入框”全部同一行（选择章160px、输入框72px）。
- 开始练习底部出现切题栏：第1题上一题禁用、显示 1/20；作答后点底部“下一题”→2/20（多选提交按钮仍完整可见）；点“上一题”→1/20 且保留作答与解析；双向均正常。
- 错题本三个下拉同一行（各约108px、标签完整），筛选/批量删除/艾宾浩斯/导出CSV 仍整宽。
- console 无 error/warning。


---

### 7.5 平板适配：竖屏底部切题栏延伸 + 配置标签理顺；横屏桌面布局核查（2026-09-27，已实测）

**背景**：手机竖屏交付后连接平板，对平板竖屏（≤1024）与横屏（>1024）做专项检查优化。

**改动**：
- `frontend/js/mobile-tweaks.js`：拆成两个断点——
  - 底部固定切题栏（#mQNav）由 ≤720 扩到 **≤1024（手机 + 平板竖屏）**：平板竖屏较高，顶部上一题/下一题离拇指远，底部大按钮双手握持可达；
  - 薄弱点强化训练折叠仍只限 **≤720（手机竖屏）**：平板空间足够，保持展开。
- `frontend/css/mobile-shell.css`：
  - 增补十一：#mQNav 样式随 JS 移到 @media≤1024（按钮 min-height48、字号16），内容预留 80px；
  - 增补十二：新增 @media 721~1024，章节配置 `.qp-config-label/.qp-count-label` 强制 white-space:nowrap（修复“按章:/题量:”被 34px 窄宽挤成竖排），选择章 flex1 1 0、题量输入框 64px，整行 nowrap。
- `sw.js` CACHE_NAME→`v19-20260927-tablet`。

**验证（CDP 模拟，硬重载禁缓存）**：
- 平板竖屏 820×1180：抽屉导航；章节树多列铺开；章节配置整行、标签横排（按章/选择章160~234/题量/输入框64）；薄弱区展开、3 个薄弱标签完整不溢出；进入练习底部出现切题栏（1/20），作答后点底部下一题→2/20、上一题→1/20，双向正常；错题本三个下拉同行，筛选/批量删除/艾宾浩斯/导出CSV 按钮右缘≤796<宽804，全部在界内。
- 平板横屏 1180×820（>1024）：常驻侧栏135、汉堡隐藏、底部栏不出现；落地章节树两列；做题左右分栏（题卡1033宽）；学习分析总答题397/正确率60.5%、7天趋势、掌握度雷达、覆盖率图均渲染；模拟考左题区779+右答题卡260、倒计时、50题号、题干表格完整。
- 说明：本机物理窗口小于模拟视口时，截图工具只捕获物理窗口区域（固定元素在模拟视口底部落在捕获区外），属截图合成偏差；已用 innerWidth/Height、getBoundingClientRect、getComputedStyle 及实际点击切换确认真实布局正确，真实平板（物理大屏）正常渲染。

---

## 2026-09-27 启动文件全面核查（144专家视角·列举法对比）

### 核查范围
start.bat(9319B) / .env / requirements.txt / backend/main.py(46792B,947行) / frontend/index.html(28636B) / watchdog.py / 项目根目录治理

### 核查结论
- **P0 严重问题 7 项**（立即修复）：JWT默认密钥、/uploads重复挂载+日志泄露路径、前端50+script同步阻塞、根目录451个临时脚本(占65%)、main.py自重启+watchdog双重重启、每次pip install、版本号三处不一致(V4.0/V4.5.15/V4.5.17)
- **P1 重要问题 14 项**（本周修复）：index.html body背景硬编码、15个JS无指纹、启动7+Python子命令串行、13+启动入口混乱、main.py 947行职责过载、数据库迁移硬编码、每请求2条日志、无stop.bat优雅关闭、meta标签无效、PyPDF2/pypdf重复、watchdog阈值不一致、CORS过松、app_v3旧代码并存、全局异常掩盖bug
- **P2 一般优化 18 项**（迭代改进）：端口检测误杀、LAN IP取虚拟网卡、相对路径、无.env.example、内联style 130行、大量!important、无noscript、无preload、SQLite无连接池、日志散落、备份散落、workers=1、RateLimit过严、无README、编码乱码、带指纹资源no-store、健康探针硬编码路径、无启动耗时统计

### 关键数据
- 根目录 697 个文件，其中 451 个临时/补丁/诊断脚本（占65%）
- 前端 50+ 个 script 全部同步加载，无 defer
- 启动入口 13+ 个（start.bat/start.sh/start_backend/start_simple/start_cosyvoice/restart×2/一键启动×2/备份/rollback/build/clean_restart）
- 版本号 3 处不一致

### 交付物
- 启动文件全面核查与优化清单_20260927.html（56KB，含总览仪表盘/P0-P2逐条列举/按文件速查表/4阶段执行路线图/预期收益表）

---

## 2026-09-30 架构归一治理：代码归一性 + 文件唯一性 + 数据源关系 + 过程分析资源接入（已实测）

**目标（用户原话）**：全面解决代码归一性（恰恰好、不重复、功能不丢失）；文件唯一性；每个数据源都与系统建立关系；充分利用数据资源，含过程分析资源。技术栈 FastAPI+原生JS+SQLite 锁死；前端布局锁死（只改文件组织/重复逻辑，不改页面呈现）。

**安全前提**：改前用 sqlite backup API 全量备份主库 → `backend/data/migration_backup/shuili_exam_before_unification_20260930.db`（68.8MB，integrity ok）。

### 一、代码归一（前端 + 后端）
- **前端**：逐函数 diff 两份 common-utils，唯一「dup 有 / live 缺 / 被 live 代码（file_library.js，带 if 守卫）调用」的 `notifyComplete`（提示音+绿框+✅弹窗）合并进 `core/common-utils.js` 并挂 window——顺带修复一个潜在缺失函数；归档未被服务的 `frontend/static/` 镜像整树与 `js/modules/common-utils.js`（50KB 重复副本）到 `frontend/_archive/`。
- **后端**：AST 扫出 21 组结构相同函数，逐组核实均不满足「精确相同 + 机械可替换」（同名类方法、闭包模块级常量行为不同、零调用私有 helper），故 **0 合并**（不为归一而改行为）；仅归档 2 个全仓零引用文件（modules/common/logger.py、modules/resource/pdf_parse_cache.py）到 `backend/_archive/deadcode_20260930/`。

### 二、文件唯一性
- 根目录 103 个一次性临时文件（图23/日志25/脚本20/json30/杂5）归入单一归档 `_archive/root_temp_20260930/`，写 MANIFEST.md 含一键回滚；正确保留 4 个有运行时引用文件（restart.log、专家全量体检结果.json、system_graph.json、system_health_state.json）。

### 三、数据源 → 系统关系（迁移幂等，已执行）
| 数据源 | 建立的关系（确定可追溯） | 消费方（功能/API） |
|---|---|---|
| question_images(596) | 规范化异常路径，补 source_doc/exam_year/fl_id/file_exists/confidence/legacy_path，按年份(2023/24/25)关联源文档 fl_file_library(1437/1438/1439) | `/api/v1/media-rel/question-images`、`/raw/{fn}`；前端「本题关联」面板 |
| extracted_images(23928 / 469父文档) | 解码 file{id}_p{p}_{c} 与 {id}_{p}_{c} 两命名，id=fl_file_library.id；新建索引表 extracted_image_index；未挂载目录由路由代理出图 | `/extracted-images`、`/by-doc`、`/raw/{fn}`；file_library「讲义浏览」面板 |
| embedded_videos(64有效) | 按章节 node_code（按科目限定）匹配知识点与题目，video_question_links 1→5249（64视频/1220题，零重复） | `/videos/grouped`、`/videos/{id}/questions`、`/questions/{id}/videos`；video「章节关联」面板 |
| 过程分析表 | 复用5张已有读端点表；为4张纯「只写不读」表新建只读路由 thinking_chain(9)/ai_learning(34)/data_quality_report(11)/chapter_score_stats(127) | `/api/v1/insights/*`；AI中心复盘库/习得规则 tab、专家中心质量趋势 tab、系统管理问题/待办清单、分析章节×年份表 |

### 四、验证（实测，非「应该/大概」）
- 前端 119 个非归档 JS 全过 `node --check`；index.html 79 个 /static 路径全部可解析。
- 后端 320 个业务 py 全过 py_compile；`import main` 路由数 913 与基线 **delta 0**。
- 真实 ASGI 实例（127.0.0.1:8011，main:app）端到端：题库 total1335、闪卡958、关键词检索命中、binder2 图 HEAD200、根 index200；media-rel 与 insights 各端点全 200（totals 596/23928/9/34/11/127），by-doc469、raw 图 200（39072B）。
- 视觉：dashboard/question/video/experts/analytics/ai_intelligence 六页桌面截图核对，外壳布局零变化，新浮动按钮小而可折叠不遮挡，新 tab 与既有同一样式。

### 五、遗留 / 待用户拍板
1. 8000 端口仍跑提权旧进程（PID14156，非提权会话无法结束），**需用户用 start.bat 或 restart.ps1 重启**才加载新路由/面板。
2. 64 个视频本体与 596 张真题裁剪图磁盘缺失：关系/索引已建好，视频经 WLAN 预缓存、裁剪图从源 PDF（backend/uploads/question_files）重生成后即被消费；当前 UI 如实显示「文件缺失/需预缓存」，不假装可播放。
3. 高风险数据只盘点、零执行：`deliverables/高风险数据处置清单_20260930.md`，合计可释放约 54.9GB（backups约44.8高 / data约8.98中 / uploads约1.16低）；ollama_models(16.47GB)+ollama(1.81GB)绝对保留，.git(20.89GiB，gc无法瘦身、严禁重写历史)；命令均标注【需用户确认后执行】。
4. 真题透析「页→题」仅到年份粒度（PDF 无 page_contents），后续导入写 pdf_page 可细化。

**销项**：CHANGE_LEDGER #30–#34。



---

### 7.3 磁盘归一清理（低+中风险，2026-09-30，已实测）

**已执行（释放约 8.3GB，F盘 173.0→181.2GB）**
- 第一批低风险：uploads\split_output(925MB临时拆分)、*_nowm.pdf(34MB去水印副本,原件保留)、data\tts_cache(3.4MB)。
- 第二批中风险：data 顶层重构中间 db 快照27个 + before_errorfix/fullfix/28_restore、data\backups 旧8个、migration_backup 旧3个、rag_knowledge.bak 2目录，共 7451MB。
- 保留锚点：data 顶层 refpoints_20260930_000042、s4、s5_20260930_083135；data\backups\pre_qb_pdf_fix_9/28；migration_backup\unification_9/30；F盘 backups\pre_techdebt_9/27(29.6GB)+GOLDEN_9/21(16.8GB)。

**暂停（待移动硬盘重连）**：高风险 backups 旧全量目录(9/1、9/6、9/9、9/10、9/15)+auto旧hourly ≈ 44.8GB。外置盘 G:\水利智学系统_外置备份_20260929（含 FULL_20260916 33GB、代码备份_9/4 57.6GB）在核实中途物理掉线，需重新插拔、核实外置副本完整后再执行。

**验证**：服务 PID42900 全程未中断，根及 media-rel/insights 端点全 200，PRAGMA integrity_check=ok，questions 3161/flash_cards 1090/knowledge_points 213/mind_maps 285/rag_embeddings 9482/embedded_videos 437/wrong_questions 691，零丢失。CHANGE_LEDGER #68。

---

### 7.4 鸿蒙APP双端 P1 修复（2026-09-30，已实测）

**背景**：双端体检（手机/平板，报告 `F:\HAP\shuili-hap\reports\鸿蒙APP双端体检报告_20260930.html`）无 P0，P1=7、P2=18。本轮按"低风险高收益"修复 4 项；P1-03 同步桥中文乱码需真机抓包，本轮跳过。

**已修复（只改点名处，布局零变化）**
- P1-05 在线 `/api/v1/exam/stats` 500：`get_exam_stats` 遇历史记录 score=None 即 sum/max 崩溃；改为先过滤 None，avg/best 仅基于有效分数（无则回退 0），空记录补 recent_scores:[]。
- P1-01 在线"进入完整版"失败无回退（白屏只能杀进程）：根因 gotoServer 覆盖 pendingUrl 致 onErrorReceive 本地回退条件永不成立；新增 switchingToServer 标志，远程主帧错误即复位并 gotoLocal()，提示"服务器连接失败，已回到本地离线模式"。
- P1-06 缺刘海/挖孔适配：index.html viewport 加 viewport-fit=cover；mobile-shell.css 顶栏/底栏改 min-height + env(safe-area-inset-top/bottom) 内边距。
- P1-07 顶栏输入 13px 聚焦自动放大、专家中心按钮命中盒过小：#realSearchInput/#realGlobalSubject 移动端强制 16px；.ec-link-btn 改 min-height:38px / min-width:44px / inline-flex 居中。

**验证（实测，非"应该/大概"）**
- 后端：单元级构造 score=None 假记录，旧逻辑确抛 TypeError、新逻辑 avg/best/recent 正确、空记录返回零值（本机库当前无 None，无法在线复现 500）。
- 前端：Playwright 手机 390×844@3 / 平板 820×1180@2 双视口，viewport-fit 生效、零横向溢出、顶栏控件 computed 16px、0 pageerror；经 /static 真实路径断言 CSS 含 env(top/bottom)、ec-link-btn 含 38/44px。
- 产物：rawfile/www 重建 118 文件/11.81MB，数据条数与基线逐项一致（questions3161 / flashcards1089 / mindmaps285 / notes46 / lectures454 / materials48 / videos435 / wrong526 / exam_history22 / syllabus137），零丢失；default HAP（signed 12.97MB）解包 135 条目数据齐全、hvigor BUILD SUCCESSFUL；release 发布 .app（12.75MB）签名校验通过。

**遗留 / 待真机**
1. hdc 无设备：P1-03 同步桥中文乱码抓包、安全区 env() 真值、在线切换真机回退、启动时延等见 final_findings.json 的 real_device_checklist，均标"待真机"，未写"真机通过"。
2. 其余 P1（P1-02 SSL 全放行、P1-04 视频死种子）与 18 项 P2 本轮锁死未动。
3. AGC 发布需用户上传新 .app 并加测试账号；发布前 ENABLE_SELFTEST 置 false。

**销项**：CHANGE_LEDGER #71。


---

## 20261004 题目去重全面启动：跨档打通（真题keeper）+ 全入口副本过滤（用户要求"全部落地"）

### 一、目标与根因（实测，非推测）
- 用户要求：同一道题在真题与模拟/练习文档同时出现时**只保留真题(keeper)**；题散落在所有文档，须全面分析、全部落地。
- 落地前现状：questions 共5993、活跃(is_deleted=0)4626=真题1745/模拟699/练习2182；已有重复标记1944**全是同档**（真题→真题918、练习→练习845、模拟→模拟181），**跨档=0**；翻转=0、已删真题=0。
- 根因：`utils/deduplication.py` 的 `classify_pair_strong_weak` 的 canon_stem 用**原始题干**（含题号"8."/年份"【2024】"前缀），跨档同题仅前缀不同即判 weak_fp；而会去前缀(`_strip_stem_prefix`)的 `adjudicate_pair` 只处理已在 qb_review_queue 的项——跨档对既不被强判、也不进队列。L3 跨源又依赖 point_id 一致，跨档题在不同PDF知识点挂载/OCR排版不同而漏配。

### 二、引擎增强（复用现有方法论，未新起标准、未引依赖）
- `backend/utils/deduplication.py` 新增纯函数 `plan_cross_tier_merge(items, stem_gate=0.90, queue_stem=0.82)` + helper：
  - **不依赖 point_id**：三路阻塞召回跨档候选——去题号/年份前缀(`_strip_stem_prefix`)后题干 canon 精确键 + 选项集合 multiset 精确键(需 `_options_substantive`) + 题干 simhash 海明≤3。
  - 强判复用 `classify_pair_strong_weak`（把入参 title 替换为去前缀文本后调用）；**选项集合型强证据额外要求去前缀题干 combined sim≥0.90**，防止"共用同一组选项的不同题"（组织形式类、现金流量表类）被误并；canon_stem/exact_hash 直接成立。
  - `_DSU` 同时收缩既有同档重复关系与跨档强边；每组：有真题则 keeper=`choose_keeper`(真题活跃根)，无真题(模拟↔练习)则 keeper=`choose_keeper`(全部活跃根)；成员对最终keeper**实时强裁决**为准，弱则不自动（宁可漏判不可误杀）。
- `backend/api/v1/deduplication.py` 同 router 新增 `POST /deduplication/cross_tier_merge?apply=false`（默认 dry-run）/true，幂等软标记 + queue_ensure/queue_add，{code,data} 返回。

### 三、apply 落地（只软标记、可 /restore，无物理删除、未删真题）
- **31 跨档组 = 真题keeper组17 + 无真题(模拟↔练习)组14；43 动作 = NEW 30 + REPOINT 13**。
  - NEW：模拟→真题 2、练习→真题 18、无真题场景 10；REPOINT：扁平化直接指向 keeper 13。
  - 28 个"链内成员对最终keeper非直接强证据"保留原同档标记、不改挂（链尾均健康keeper，不泄漏）。
  - 二次重跑 apply：new=0/repoint=0（**幂等**）。
- 落地后方向(双方活跃)：真题→真题918、练习→练习843、模拟→模拟172、**练习→真题19、模拟→真题2**、模拟→练习16、练习→模拟4；is_duplicate=1 总数 1944→1974。

### 四、全入口副本过滤（独立验证发现"检索/模考仍与真题同时出现"，共补12处，8文件）
- 指定两处：`q_query.py` search_fts 的 where 补 `(is_duplicate=0 OR IS NULL)`（FTS+LIKE共用）；`exam.py` generate_exam 源头补副本过滤（real/weak/predict/题型比例/普通全模式生效）。
- 其余10处：sprint(high_freq/predict_exam/confusing_pairs)、qb service(列表快路径/收藏列表/知识点统计)、qb routes(constant_points)、global_search 题库组、functional_index 收藏、crud.generate_custom_exam。
- 刻意不动：错题本历史快照（#119口径）、移动端 /question/sync 复制协议（客户端读 is_duplicate 自隐，过滤反致残留）、detail 按id直查。

### 五、验证（实际执行，主控独立复核一致）
- 回归：reg_dedup_simhash / reg_dedup_strong / reg_stem_duplicate **均 exit 0**（simhash 含"/scan<15s"项转绿）。
- 语法：backend `compileall` 0 错误；前端 **132 个 .js 全部 node --check 通过、0 失败**。
- 功能(HTTP+浏览器)：刷题 /list、random_real 0 副本；**search_fts 三组 keeper(7263/7270/7286)在、副本(8571/7786/8441)均消失**；**exam/generate 三模式79题抽样副本泄漏=0**；错题、闪卡(question_flashcard_rel 448)关联完整0丢失；刷题页浏览器实测正常（V4.5.18）。
- 红线保持：**翻转=0、已删真题=0、活跃悬空=0、活跃指向已删keeper=0**；跨档→真题=21。
- /scan 性能：空闲实测 4.5–5.4s（此前40.2s系回归并发探测争抢CPU，非固有热点，未改逻辑/阈值）。

### 六、questions 表之外散落题目（已全表排查，结论）
- **已入库**：水利案例教材73案例（案例一~十六按章编号，与node 1.1~5.16一一对应，73/73覆盖）；真题/模拟/章节题/练习；uploads 17 PDF 全映射。
- **已关联**：lectures 98 挂节点；video_question_links、question_flashcard_rel 448；rag_embeddings 为 page_contents 索引。
- **待人工（确有成题未入库）**：①**一造管理教材9个计算例题**（例3-4/3-5/4-1~4-4/5-1/5-3/6-4，p126~362，questions 0命中）建议经 question_pipeline 以 case 类补抽；②4个未被source引用的真题解析PDF（fl id=806/807/816/841，2020/2022另一讲师版）需抽查是否含新题；③讲义PDF内嵌题、48条视频孤儿链接、一建4本教材（跨考试）。
- 非缺题遗留：question_images 596 张图斑 question_id=0（题在库、图未回挂）；322题 source=file_N 溯源缺失。

### 七、备份
- 跨档落地前：`backend/data/backups/cross_tier_20261004_081305_shuili_exam.db`（114MB，questions=5993）。
- 入口过滤前：`backend/data/backups/visibility_filter_20261004_084837_shuili_exam.db`（114MB，questions=5993）。
- 均为 sqlite backup API 在线一致快照；回滚直接以备份覆盖 .db（先停后端）。

### 八、仍需人工（仅出清单，未自动处置）
- qb_review_queue kind=dedup **pending 113 簇**：其中**答案真冲突6组**（anchor 3558/6715/6765/7948/8415/8896，优先）、weak_fp 107。
- 待补抽/抽查：一造管理9计算例题、4个真题解析PDF；28链内成员维持原标记。

**销项**：CHANGE_LEDGER #121、#122。
