﻿# 🚨 工作铁律（最高优先级，所有对话框必须遵守）

> 本文件是唯一权威基准。任何对话框打开项目时，**必须先读本铁律**，再开始工作。

## 铁律1：修改必记录（闭环要求）

**每次修改功能后，必须同步完成以下三步，缺一不可：**
1. ✅ 改代码（实现功能）
2. ✅ 写需求记录到本文件末尾（时间、需求、实现、状态）
3. ✅ 验证功能正常

**违反此铁律 = 严重错误。** 不允许只改代码不记录，否则新对话框看不到需求，重复犯错。

## 铁律2：记录格式

每次记录必须包含：
- **日期**：YYYY-MM-DD HH:mm
- **模块**：哪个模块
- **需求**：用户要什么
- **实现**：怎么改的
- **状态**：✅已完成 / ⚠️待验证 / ❌有问题

## 铁律3：先读总控，再动手

**任何对话框开始工作前，必须先读总控文件末尾的"变更记录"部分**，了解最新需求和已完成的工作，不要重新分析、不要重复劳动。

## 铁律4：布局锁死，只改功能

- 布局已锁死，不调整布局
- 只负责把功能填充到现有布局里
- 要改布局必须先征求用户同意

## 铁律5：旧代码是答案

- bug先看旧代码（app_v3_897262.js）怎么写的
- 不要自己重新写、不要重新分析
- 对比新旧代码功能差异，缺什么补什么

## 铁律6：迁移阶段全面检索旧代码

**迁移阶段，不能用新代码名称来找旧代码功能，要全面分析：**
1. 不能只搜索新代码里面的函数名、变量名
2. 要全面分析旧代码，分散在各处的功能也能分析出来
3. 代码检索要全面起作用，不能只搜索关键词
4. 要从功能角度分析，不要从代码角度分析

---





---

## 🔧 调试经验库（遇到问题先查这里！）

### 1. 路由问题

**症状：** URL是#/xxx但页面显示dashboard（学习看板）

**原因：**
- index.html启动时硬编码renderPage('dashboard')
- 没有监听hashchange事件

**解决：**
- 启动时从URL hash读取初始页面
- 监听hashchange事件，自动切换页面
- 侧边栏导航时，同步更新window.location.hash

---

### 2. API路径404问题

**症状：** 前端调用API返回404 Not Found

**原因：**
- 前端调用的路径和后端实际路由不一致
- 常见错误：复数vs单数（/questions vs /question）
- 常见错误：多了/少了前缀

**解决：**
1. 检查后端router的prefix定义
2. 检查main.py的include_router prefix
3. 拼出完整URL，对照后端路由定义
4. 用PowerShell测试：Invoke-RestMethod -Uri "完整URL"

**常见错误：**
- ❌ /api/v1/questions/random（复数）
- ✅ /api/v1/question/random_real（单数）

---

### 3. API返回401未登录

**症状：** 前端调用API返回401 Unauthorized

**原因：**
- 前端fetch没有带Authorization token
- 或者localStorage里没有token

**解决：**
- 从localStorage取token
- fetch时带上Authorization: Bearer xxx header

---

### 4. bu模式坐标点击不准

**症状：** bu.click_xy点击侧边栏菜单没反应，页面不切换

**原因：**
- bu视口尺寸太小（702x654）
- 侧边栏菜单坐标和实际位置不对应
- 侧边栏可以滚动，坐标必须精确

**解决：**
- 用bu.find("菜单名")找到元素的ref
- 用bu.snapshot()看DOM结构
- 坐标要精确，差一点就点不到

---

### 5. Service Worker缓存问题

**症状：** 修改代码后浏览器还是显示旧版本

**原因：**
- Service Worker缓存了旧的JS文件

**解决：**
- URL后面加时间戳：?_t=随机数
- 或者禁用Service Worker（重命名sw.js）
- 或者完全关闭浏览器再打开

---

### 6. Edit工具经常失败

**症状：** Edit工具报错OLD_STRING_NOT_FOUND

**原因：**
- 空格/换行符不一致
- 中文编码问题

**解决：**
- 用Write写Node脚本到文件里再运行
- 用行号插入代码比字符串匹配更可靠

---

### 7. PowerShell转义问题

**症状：** node -e里的正则表达式引号被PowerShell转义破坏

**解决：**
- 复杂脚本写到文件里再运行
- 用here-string（@'...'@）写Node脚本文件

---

### 8. 假数据/硬编码问题

**症状：** 页面显示的题目选项是"甲、乙、丙、丁"

**原因：**
- state初始化时有硬编码的假数据
- 异步API加载失败，用了兜底的假数据

**解决：**
1. 删除state初始化时的假数据
2. 改成从后端API获取真实数据
3. 检查API调用是否成功

---

*遇到问题先查这里，不要重新分析！*

## 📁 关键文件索引（快速查找）

| 文件 | 位置 | 说明 |
|---|---|---|
| **前后端分析合并报告** | 本地AI分析结果/前后端分析合并报告.md | 前端68个模块+后端100个文件的完整分析，功能、API、按钮清单 |
| 前端详细分析 | 本地AI分析结果/前端分析/旧代码模块分析.json | 前端模块的结构化分析数据 |
| 后端核心结论 | 本地AI分析结果/AI代码分析总报告_核心结论汇总.md | 后端分析的核心结论 |
| 旧版单体代码 | frontend/js/app_v3_897262.js | 旧版34848行单体代码，所有功能的答案在这里 |
| 新模块化架构 | frontend/modules/ | 新版模块化前端代码，25个模块 |
| 后端API | backend/modules/ai/routes.py | AI相关API接口定义 |

> **重要**：任何对话框需要查功能、查API、查按钮时，先查"前后端分析合并报告"！

---
# 📋 变更记录（按时间倒序，最新在最上面）
## 2026-09-15 15:30 工具 - 功能落地自动盘点脚本

- **模块**：tools/feature_audit.py（新增工具）
- **需求**：统计总方案里还有多少想法没形成代码，且要用代码把各模块文件串联起来，不写死静态表格
- **实现**：
  1. 新建 `tools/feature_audit.py`：内置 BASELINE 单一数据源（19个模块 + 各自缺口清单 + 基线行数）
  2. 动态扫描 `frontend/modules/` 每个 JS 文件的真实行数、正则检测"开发中/暂未/TODO"死按钮
  3. 对照缺口基线，自动生成 `功能落地统计_20260915.md`
  4. 改完模块后删对应 gap 行，重跑脚本即可刷新报告
- **本次盘点结果**：未落地功能点 119 个；完全没建的辅助 render 组件 49 个；代码里死按钮 4 处
- **状态**：✅ 已完成（脚本已跑通验证）


## 2026-09-14 23:20 思维导图 - 删除过时功能

- **模块**：思维导图（mindmap.js）
- **需求**：合并导图和从PDF生成都是过时功能，已经在文件资料库里了
- **实现**：
  1. 从PDF生成按钮：改成提示"此功能已迁移到「学习资料库」"，并自动跳转
  2. 合并导图按钮：改成提示"此功能已迁移到「学习资料库」"，并自动跳转
- **状态**：✅ 已完成


## 2026-09-14 23:15 思维导图 - 合并导图功能实现

- **模块**：思维导图（mindmap.js）
- **需求**：确认合并导图之前只是显示"待完善"提示，没真实现
- **实现**：
  1. 获取当前编辑的导图内容
  2. 获取选中的要合并的导图内容
  3. 合并内容（用分隔线隔开）
  4. 更新编辑器、保存到localStorage
  5. 关闭弹窗、更新预览
- **状态**：✅ 已完成


## 2026-09-14 23:10 题库刷题 - 每日一练功能实现

- **模块**：题库刷题（question-practice.js）
- **需求**：关闭每日一练弹窗和开始每日一练之前只是显示"待完善"提示，没真实现
- **实现**：
  1. 关闭弹窗：隐藏每日一练modal
  2. 开始每日一练：调用 /api/v1/questions/random?count=10 获取随机题目，进入练习模式
- **状态**：✅ 已完成


## 2026-09-14 23:05 笔记模块 - 导出和朗读功能实现

- **模块**：笔记（note.js）
- **需求**：导出笔记和朗读笔记之前只是显示"待完善"提示，没真实现
- **实现**：
  1. 导出笔记：把笔记内容导出成.txt文件（带日期命名）
  2. 朗读笔记：调用浏览器TTS API（SpeechSynthesisUtterance）朗读笔记内容
- **状态**：✅ 已完成


## 2026-09-14 23:00 题库管理 - 导入题目功能对接真实API

- **模块**：题库管理（question-manager.js）
- **需求**：导入题目按钮之前只是显示"待完善"提示，没真实现
- **实现**：
  1. 点击导入按钮弹出文件选择器（支持.pdf/.xlsx/.txt/.docx）
  2. 调用 POST /api/v1/questions/import 后端API
  3. 导入成功后重新加载题目列表
- **状态**：✅ 已完成


## 2026-09-14 22:55 AI拍照解题 - 对接真实API

- **模块**：AI拍照解题（photo-solve.js）
- **需求**：不再用纯模拟数据，要调用真实后端API
- **实现**：
  1. _simulateAnalysis方法改成async
  2. 先尝试调用 window.aiService.scanSolve() 真实API
  3. API失败时兜底用模拟数据
- **状态**：✅ 已完成


## 2026-09-14 22:50 模拟考试 - 删除硬编码假数据

- **模块**：模拟考试（mock-exam.js）
- **需求**：删除硬编码的历史考试记录假数据
- **实现**：把this.historyRecords从8条硬编码假数据改成空数组，从StorageService/后端API获取
- **状态**：✅ 已完成


## 2026-09-14 22:45 思维导图 - 语法错误修复

- **模块**：思维导图（mindmap.js）
- **需求**：大括号不匹配，页面崩溃
- **原因**：init方法重复了两次（之前修复时不小心加了两行）
- **实现**：删除重复的init方法行
- **状态**：✅ 已完成


## 📋 待办清单（基于本地AI对比分析）

> 对比旧代码68个render模块，新代码只完整实现了2个（3%），还有大量功能待补充。

### 🔴 不完整的核心模块（17个）

| # | 模块 | 文件路径 | 缺失功能 | 优先级 |
|---|---|---|---|---|
| 1 | 学习看板 | dashboard/dashboard.js | 知识点掌握度 | P1 |
| 2 | 题库刷题 | question/question-practice.js | AI薄弱点刷题、历年真题刷题 | P0 |
| 3 | 题库管理 | manager/question-manager.js | 题库管理页面 | P1 |
| 4 | 模拟考试 | exam/mock-exam.js | 考试模式配置、考试进行、考试结果 | P0 |
| 5 | 错题本 | wrong/wrong-book.js | 错题筛选与渲染 | P1 |
| 6 | 我的收藏 | collect/collect.js | 收藏页面 | P2 |
| 7 | 闪卡 | flashcard/flashcard.js | 闪卡库 | P1 |
| 8 | 笔记 | note/note.js | 笔记渲染模块 | P2 |
| 9 | 视频讲义 | video/video.js | 视频播放、视频管理、讲义管理、网站资源 | P1 |
| 10 | AI拍照解题 | photo/photo-solve.js | AI扫描页面 | P0 |
| 11 | 教材 | material/material.js | 教材上传、拆分、管理、阅读视图 | P2 |
| 12 | 思维导图 | mindmap/mindmap.js | 思维导图渲染 | P1 |
| 13 | 冲刺中心 | sprint/sprint.js | 考试倒计时、记忆训练方法、专项训练题库 | P1 |
| 14 | 记忆训练 | memory/memory.js | 考试专项记忆训练页面 | P1 |
| 15 | 文件资料库 | library/file-library.js | 文件管理功能 | P1 |
| 16 | 智能分析 | analytics/analytics.js | ✅ 已完整 | - |
| 17 | 系统设置 | settings/settings.js | ✅ 已完整 | - |

### 🟡 完全缺失的辅助模块（49个）

**布局/基础组件：**
- renderLogin - 登录页
- renderModuleNav - 模块导航
- renderPage - 页面框架
- renderGlobalSubjectOptions - 全局科目选项
- renderMajorMultiSelect - 专业多选
- renderMajorSingleSelect - 专业单选

**章节/知识点组件：**
- renderIndependentChapterTree - 独立章节树
- renderIndepTreeNode - 独立章节树节点
- renderChapterTreeNode - 章节树节点
- renderSingleNode - 单节点
- renderWeakPointsList - 薄弱点列表

**视频子组件：**
- renderPlaylistItems - 播放列表项
- renderVideoPlayerVideoList - 视频播放列表
- renderVideoPlayerLectureList - 讲义列表
- renderNetworkResourceList - 网络资源列表
- renderLectureList - 讲义列表
- renderLocalVideoTable - 本地视频表格

**教材子组件：**
- renderChapter - 章节
- renderMaterialList - 教材列表
- renderReaderTree - 阅读器树
- renderReaderMaterialList - 阅读器教材列表
- renderSyllabusAnalysisTab - 大纲分析Tab

**记忆训练子组件：**
- renderTrainingQuestionHTML - 训练题目HTML
- renderTrainingQuestion - 训练题目
- renderMemoryTrainingStep - 记忆训练步骤
- renderDeepTrainingStep - 深度训练步骤

**高级功能：**
- renderKnowledgeGraph - 知识图谱
- renderKnowledgeGraphViz - 知识图谱可视化
- renderKnowledgeGraphECharts - 知识图谱ECharts
- renderExamAnalysis - 考试分析
- renderExamCharts - 考试图表
- renderExamTopBar - 考试顶栏
- renderStudyPlanUI - 学习计划UI
- renderFormulaTrainer - 公式训练器
- renderFormulaTraining - 公式训练
- renderWatermarkRemover - 去水印
- renderBackupManager - 备份管理
- renderServiceMonitor - 服务监控
- renderDedupUI - 去重UI
- renderDedupOffline - 离线去重
- renderImportPreview - 导入预览
- renderExamFormatPreview - 考试格式预览
- renderSingleQuestion - 单题
- renderPdfMarks - PDF标记
- renderFcPagination - 闪卡分页
- renderLibraryCard - 资料库卡片
- renderMindmapSummary - 思维导图总结
- renderMarkmapToContainer - Markmap渲染

---

### 🎯 修复顺序建议

**P0（必须优先）：**
1. 题库刷题 - AI薄弱点刷题、历年真题刷题
2. 模拟考试 - 完整考试流程
3. AI拍照解题 - 完整扫描流程

**P1（重要）：**
4. 学习看板 - 知识点掌握度
5. 题库管理 - 完整管理功能
6. 错题本 - 筛选功能
7. 闪卡 - 闪卡库
8. 视频讲义 - 完整视频功能
9. 思维导图 - 完整渲染
10. 冲刺中心 - 完整冲刺功能
11. 记忆训练 - 完整训练功能
12. 文件资料库 - 完整管理功能

**P2（次要）：**
13. 我的收藏
14. 笔记
15. 教材

**P3（后续）：**
16. 完全缺失的辅助组件（49个）

---


## 2026-09-14 22:20 模拟考试 - 章节数据从后端API获取

- **模块**：模拟考试（mock-exam.js）
- **需求**：章节数据不应该硬编码，应该从后端API获取
- **实现**：
  1. 从 `/api/v1/question/chapter_tree?subject=一造管理` 获取章节树
  2. 提取章级别的章节填充到下拉框
  3. 如果API失败，兜底使用默认章节（仅作为备用）
- **状态**：✅ 已完成


## 2026-09-14 22:15 模拟考试 - 章节下拉框修复

- **模块**：模拟考试（mock-exam.js）
- **需求**：章节下拉框是空的
- **原因**：从DataService.getQuestions提取章节，但question.chapter字段为空
- **实现**：改用硬编码章节列表（和题库刷题模块保持一致），共6个章节
- **状态**：✅ 已完成


## 2026-09-14 22:10 题库刷题 - 开始练习按钮修复

- **模块**：题库刷题（question-practice.js）
- **需求**：点击"开始练习"按钮没反应
- **原因**：practiceQuestions为空时，_renderPracticeMode()里q=undefined，导致报错
- **实现**：在_renderPracticeMode开头加空数组判断，为空时显示"正在加载题目..."
- **状态**：✅ 已完成



# 水利智学系统 - 总管文件（架构总控）
# 所有专家都按这个总管来工作
# 版本：V10.0（2026-09-13，深度融合版，旧代码接口全清单）
# 说明：所有内容都来自已读的设计文档，不是空框架，支持回溯
# 续写机制：每次写一部分，下次接着写，进度看第十三章
# 核心：一条线串到底，只有一个标准 + 安全网兜底
# 新增：每个工作组都有旧代码接口详细清单和核心算法要求

---

## 🧭 快速目录（按行号跳转）
> 在编辑器里按 Ctrl+G 输入行号即可秒达。
| 章节 | 行号 |
|---|---|
| 📌 使用说明 | 11 |
| 🏛️ 第一章 总体目标与最高铁律 | 20 |
| 👥 第二章 专家团队与决策机制 | 80 |
| 🏗️ 第三章 六层架构与模块域 | 194 |
| 🔄 第四章 标准工作流程 | 389 |
| 🏗️ 第五章 技术架构标准 | 550 |
| 🎨 第六章 UI布局标准（锁死） | 658 |
| 📊 第七章 业务逻辑标准 | 877 |
| 🔧 第八章 代码规范标准 | 1228 |
| 🔄 第九章 新旧融合标准 | 1265 |
| 🛡️ 第十章 回溯安全网 | 1357 |
| 📁 第十一章 文件索引 | 1436 |
| 🚀 第十二章 执行规则 | 1507 |
| 📝 第十三章 续写机制 | 1585 |
| 第十四~二十章 各工作组详细要求 | 1651–2438 |
| 第二十一章 新旧模块迁移对应表 | 2549 |
| 📎 附录1–14 全部md文档合并 | 6284起 |
| 🖥️ 附录15–26 服务器配置与启动脚本 | 文末B区 |
| 📋 附录C区 动态文件索引 | 文末C区 |
| 🔍 附录D区 跨平台检索说明 | 文末D区 |

> 代码文件检索：另开终端跑 `python tools/search.py 关键词`

---

## 📌 总管使用说明
> 🚨【跨对话共同基准·开机第一行】本项目**唯一 md 文件**就是本文件——所有规则、铁律、工作框架、实施细则、布局规范、代码规范、开工必读、会话流水全部在本文件内（正文+附录1–14）。任何对话框进来：先读本文件开头→查附录找对应内容→干活→把新进展追加到附录1（开工必读·会话流水）。不靠对话记忆，不另立文件。
> 这是整个系统的总管文件，所有专家都按这个文件工作
> 用户提任何需求，先读这个总管，确认方向后再干活
> 每个专家负责自己的模块，按总管里的要求来做
> 有任何问题，回到这个总管找答案

---

## 🏛️ 第一章：总体目标与最高铁律（宪法级）

### 1.1 系统定位
- **系统名称**：水利智学系统 V4.5.15
- **核心目标**：帮用户43天考过一造
- **主用设备**：平板（横屏刷题+视频）
- **技术栈**：FastAPI + SQLite + PWA + 本地Ollama
- **部署**：本地可运行，双击start.bat启动

### 1.2 宪法的地位【来源：系统设计宪法.md V2.6】
本纲领是系统最高设计准则，优先级高于任何临时需求、个人判断和历史代码。
所有开发、修改、重构、迁移必须严格遵守。
与本纲领冲突的旧代码，在迁移时必须修正为本纲领规定的方向。

### 1.3 最高优先级铁律（死规则）【来源：系统设计宪法.md】
**对于影响系统功能和稳定的改动，必须先制定好规则和机制，写入本纲领和实施细则，经专家审议通过后，方可执行。**
- 禁止"先改了再说"
- 禁止"边改边想"
- 禁止无规则的临时改动
- 任何未入纲的重大改动，一律视为违规操作，必须立即回滚

### 1.4 执行流程（强制）【来源：系统设计宪法.md】
```
需求提出 → 专家分析 → 制定规则和机制 → 写入纲领和细则 → 用户确认 → 备份 → 执行 → 验证 → 锁定
```

### 1.5 三重检查机制（铁律）【来源：系统设计宪法.md】
任何改动执行后，必须经过三重检查，缺一不可：
1. **自检**：执行人对照规则逐项检查，生成自检报告
2. **交叉检查**：另一组专家独立验证，确认执行到位
3. **用户检查**：关键改动必须由用户确认效果

检查频率：核心功能改动100%检查，一般改动抽查30%

### 1.6 执行彻底性保障（铁律）【来源：系统设计宪法.md】
禁止"差不多就行"、禁止"部分完成"、禁止"以后再补"。
1. **清单制**：每项改动必须有明确的完成清单，逐项打勾
2. **边界检查**：检查是否有遗漏的页面、函数、数据、边界情况
3. **反证检查**：主动寻找反例，证明改动不彻底
4. **覆盖率指标**：必须达到量化标准
5. **遗留问题登记**：确实无法一次完成的，必须登记，禁止silently跳过

### 1.7 违规处罚机制【来源：系统设计宪法.md】
1. 未入纲先改动 → 立即回滚，记录违规
2. 执行不彻底 → 重新执行，加倍检查
3. 检查不通过 → 回滚，分析原因，完善规则
4. 屡犯不改 → 暂停执行权限，专家审议

所有专家做任何功能、任何代码，都必须回答：**这个功能能不能帮用户更快考过一造？**
- 能 → 就做
- 不能 → 先不做

### 1.8 系统定位
- 名称：水利智学系统 V4.5.15
- 主用设备：平板（横屏刷题+视频）
- 技术栈：FastAPI + SQLite + PWA + 本地Ollama
- 部署：本地可运行，双击start.bat启动

---

## 👥 第二章：专家团队与决策机制【来源：系统设计宪法.md】

### 2.1 常务委员会（4位，日常决策）
日常架构决策、功能迭代、缺陷修复、代码审查，由以下4位常务委员一致通过：

| 专家角色 | 职责领域 | 核心关注点 |
|---------|---------|-----------|
| **系统架构师** | 整体架构、模块划分、代码质量、可维护性 | 增量迁移、模块解耦、跨模块通信、代码规范、监控机制 |
| **造价培训专家** | 业务逻辑、考点体系、学习路径、备考效率 | 科目名称规范、考点图谱、真题分析、学习计划、薄弱点算法 |
| **网页设计师** | UI/UX、布局规范、响应式、交互体验、视觉统一 | 四大板块布局、弹窗规范、状态栏、触控优化、多端适配 |
| **AI专家** | 本地大模型、多模态识别、智能推荐、离线能力 | Ollama集成、PDF-VL识别链路、置信度、AI自动工作、RAG知识库 |

### 2.2 全体委员会（重大决策）
重大决策（纲领修订、架构变更、核心功能新增、数据结构变更、安全策略调整），必须由全体委员会≥2/3同意。

### 2.3 决策判定标准【来源：系统设计宪法.md】

| 决策类型 | 判定标准 | 决策机构 | 通过条件 |
|---------|---------|---------|---------|
| **日常决策** | ①不改变系统架构；②不改变数据结构；③不影响其他模块；④修改范围≤1个文件或≤50行代码；⑤不涉及核心功能；⑥不涉及安全策略；⑦不涉及纲领修订 | 常务委员会（4位） | 4位一致通过 |
| **重大决策** | ①改变系统架构或模块划分；②改变数据库表结构；③影响≥2个模块；④修改范围≥2个文件或≥200行代码；⑤涉及三大核心功能（AI/考试练题/多端同步）；⑥涉及安全策略；⑦涉及纲领修订 | 全体委员会 | ≥2/3同意 |

### 2.4 专家团队分工（按模块）

| 工作组 | 负责域 | 核心任务 |
|--------|--------|----------|
| 🔴 题库组 | qb | 题目CRUD、刷题、错题、收藏、考试组卷、IRT算法 |
| 🟠 记忆组 | mt | 闪卡CRUD、今日复习、FSRS算法、公式训练、TTS语音 |
| 🟡 导图组 | mm | 导图CRUD、PDF解析、导入导出、科目层级 |
| 🟢 AI组 | ai | PDF视觉识别、Ollama管理、口诀生成、案例评分、流式对话、拍照解题 |
| 🔵 资源组 | resource | 教材管理、视频管理、讲义管理、大纲管理、文件库 |
| 🟣 公共组 | common | 数据分析、冲刺中心、数据治理、系统管理、备份、笔记、TTS、RAG知识库 |
| ⚪ 质量组 | 全局 | 代码质量、布局规范、数据质量、测试用例、回归验证 |

### 2.5 七大工作组（按模块划分）

#### 🔴 第一组：题库工作组
**负责模块**：题库域（qb）
**专家人数**：10位
**核心任务**：
1. 刷题核心逻辑融合（单选/多选答题流程）
2. 错题本功能实现
3. 掌握度分析算法
4. AI薄弱点推荐
5. 考试组卷
**交付物**：题库域新旧功能对比表 + 融合后的代码

#### 🟠 第二组：记忆工作组
**负责模块**：记忆域（mt）
**专家人数**：10位
**核心任务**：
1. SM-2间隔重复算法完整实现
2. 闪卡CRUD + 导入导出
3. 艾宾浩斯复习计划
4. TTS语音朗读
5. 公式训练
**交付物**：记忆域新旧功能对比表 + 完整的SM-2算法

#### 🟡 第三组：导图工作组
**负责模块**：导图域（mm）
**专家人数**：8位
**核心任务**：
1. 思维导图CRUD + 节点操作
2. PDF识别→知识点提取
3. 三级导图结构（节→章→科目）
4. 双版本导图（问题版/答案版）
**交付物**：导图域新旧功能对比表 + 识别流程

#### 🟢 第四组：AI工作组
**负责模块**：AI域（ai）
**专家人数**：10位
**核心任务**：
1. 本地Ollama对接
2. AI拍照解题
3. AI口诀生成
4. AI知识点提取
5. AI智能答疑
**交付物**：AI域新旧功能对比表 + 本地AI对接方案

#### 🔵 第五组：资源工作组
**负责模块**：资源域（resource）
**专家人数**：8位
**核心任务**：
1. 教材管理（上传/拆分/去重）
2. 视频管理（播放/分类/进度）
3. 讲义管理（上传/查看/删除）
4. 大纲管理（上传/解析/查看）
**交付物**：资源域新旧功能对比表

#### 🟣 第六组：公共工作组
**负责模块**：公共域（common + sync + auth）
**专家人数**：10位
**核心任务**：
1. 认证系统（登录/注册/JWT）
2. 全局筛选（科目/章节）
3. 多端同步
4. 备份恢复
5. 系统设置
6. 笔记管理
**交付物**：公共域新旧功能对比表

#### ⚪ 第七组：质量工作组
**负责模块**：全局质量
**专家人数**：14位
**核心任务**：
1. 代码质量检查（11项清单）
2. 布局规范检查
3. 数据质量检查
4. 测试用例编写
5. 回归验证
**交付物**：代码质量报告 + 测试用例清单

---

## 🏗️ 第三章：六层架构与模块域【来源：系统模块化融合方案.md】

### 3.1 六层架构分层（从上到下）
```
L6 前端展示层  frontend/
  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐
  │ core/    │  │ modules/ │  │ js/大文件│  │ static/ │
  │ 框架层   │  │ 业务组件 │  │ 打包应用 │  │ 静态资源 │
  └──────────┘  └──────────┘  └──────────┘  └─────────┘
        ↓ fetch /api/v1/*
L5 API路由层  backend/api/v1/  +  backend/modules/
  ┌─────────────────────┐  ┌──────────────────────────┐
  │ 旧API（33个文件）   │  │ 新模块（7个域）           │
  │ /question /exam     │  │ qb 题库域                │
  │ /flashcard /video   │  │ mt 记忆域                │
  │ /material /mindmap  │  │ mm 导图域                │
  │ /assistant /ai      │  │ ai  AI域                 │
  │ /analytics /system │  │ resource 资源域          │
  │ ...                 │  │ sync 同步域              │
  │                     │  │ common 公共域            │
  └─────────────────────┘  └──────────────────────────┘
        ↓
L4 业务逻辑层  backend/utils/
  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐
  │ PDF处理  │ │ AI能力   │ │ 学习算法 │ │ 数据治理  │
  └──────────┘ └──────────┘ └──────────┘ └───────────┘
        ↓
L3 数据模型层  backend/models/models.py
  38张表：users/questions/wrong_questions/flash_cards/...
        ↓
L2 基础设施层  backend/core/
  config.py 配置 │ db.py 数据库 │ deps.py 依赖注入
  security.py 安全 │ logger.py 日志
        ↓
L1 存储层  SQLite + 文件系统
  shuili_exam.db │ uploads/ │ 测试资料附件/
```

### 3.2 七大模块域划分【来源：系统模块化融合方案.md】

| 域 | 缩写 | 核心功能 | 旧代码文件 |
|---|------|---------|-----------|
| 题库域 | qb | 题目CRUD、刷题抽题、答题记录、错题管理、收藏管理、考试组卷、质量分级、IRT算法 | question.py, exam.py, wrong_analysis.py, relation.py |
| 记忆域 | mt | 闪卡CRUD、今日复习、FSRS算法、BKT算法、学习路径、能力雷达、六分类、公式训练 | flashcard.py, formula_trainer.py, tts.py, music.py |
| 导图域 | mm | 导图CRUD、PDF解析、导入导出、科目层级、章节导图 | mindmap.py |
| AI域 | ai | PDF视觉识别、Ollama管理、口诀生成、案例评分、流式对话、效果评估、提示词管理、拍照解题 | assistant.py, knowledge_graph.py, ai_brain.py, ai_scan.py |
| 资源域 | resource | 教材管理、视频管理、讲义管理、大纲管理、文件库 | material.py, video.py, lecture.py, outline.py |
| 同步域 | sync | 多端同步、离线缓存、PWA | sync.py |
| 公共域 | common | 数据分析、冲刺中心、数据治理、系统管理、备份管理、笔记管理、TTS语音、RAG知识库、监控 | analytics.py, system.py, note.py |

### 3.3 新旧融合的架构原则【来源：系统模块化融合方案.md】

```
当前状态：
  L5旧API ──→ L4utils ──→ L3models  （跑通中）
  L5新模块 ──→ L4service ─→ L3models  （骨架已搭）

目标状态：
  L5新模块 ──→ L4service ─→ L3models  （全部业务在此）
  L5旧API ──→ 兼容层 ────→ L5新模块   （薄壳转发）

融合方式：
  1. 新模块service补全业务逻辑
  2. 旧API路由改为薄壳，转发到新service
  3. 前端API_BASE不变，无感知
  4. 验证通过后删除旧API文件
```

### 3.4 依赖规则（模块化铁律）【来源：系统模块化融合方案.md 第117-127行】
| 规则 | 说明 |
|------|------|
| L6前端 → L5路由 | 只通过fetch调API，不直接读后端文件 |
| L5路由 → L4逻辑 | 路由层只做参数校验和响应封装，业务逻辑下沉到utils或service |
| L4逻辑 → L3模型 | 工具类操作models，不直接写SQL |
| L3模型 → L2基础设施 | 通过db.py的engine连接数据库 |
| **模块间禁止跨域import** | qb不能import mt的service，mm不能import ai的service |
| **跨模块通信** | 通过API路由调用，或通过事件总线 |

### 3.5 数据流（用户刷题主链路）【来源：系统模块化融合方案.md 第93-115行】

```
用户点击刷题
  │
  ▼
前端 question-practice.js
  │ fetch('/api/v1/question/random_real')
  ▼
API路由层 question.py (旧) 或 qb/routes.py (新)
  │
  ▼
业务逻辑层 utils/pdf_parser.py / crud/crud.py
  │
  ▼
数据模型层 Question表
  │
  ▼
存储层 shuili_exam.db
  │
  ▼
返回题目列表 → 前端渲染
```

### 3.6 系统总规模【来源：实际代码统计 2026-09-13】

| 层 | 文件数 | 代码量 | 说明 |
|---|--------|--------|------|
| 后端入口 | 1个 | ~740行 | main.py 路由注册中心 |
| 后端core | 11个 | ~150KB | 配置、数据库、AI控制器、监督中心 |
| 后端utils | 53个 | ~1100KB | PDF解析、OCR、AI解题、算法、工具类 |
| 后端旧API | 35个 | ~567KB | api/v1/ 全部业务路由（旧单体） |
| 后端新模块 | 54个 | ~783KB | modules/ 7个模块（新架构） |
| 后端models | 1个 | 38张表 | 数据模型定义 |
| 前端core | 8个 | ~36KB | 框架、API封装、事件总线 |
| 前端modules | 26个 | ~580KB | 22个业务组件+4个布局组件 |
| 前端js大文件 | 11个 | ~2500KB | app_v3.js(1630KB)+resource.js(698KB) |
| **总计** | **~200个** | **~6500KB** | |

### 3.7 旧API完整清单（35个文件，~567KB）【来源：实际代码统计 2026-09-13】

#### 题库域（5个文件，150KB）
| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| question.py | 65.4 | 28 | 题目CRUD、刷题、答题、错题、收藏、PDF导入解析、章节树、掌握度分析 | pdf_parser, data_quality_pipeline, section_matcher |
| exam.py | 21.3 | 10 | 模拟考试组卷、交卷、成绩、历史、AI阅卷、考试配置 | deps |
| question_file.py | 2.8 | 4 | 文件上传/列表/删除/下载 | 无 |
| wrong_analysis.py | 4.6 | 2 | 错题摘要、薄弱点统计 | deps |
| relation.py | 5.0 | 3 | 题目↔闪卡双向关联 | deps |

#### 记忆域（4个文件，35KB）
| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| flashcard.py | 15.0 | 9 | 闪卡CRUD、批量导入、今日复习、复习记录、统计 | sm2_engine, quality_gate_framework |
| formula_trainer.py | 7.7 | 11 | 公式列表、识别/填空/推导/应用训练、答题检查 | formula_trainer |
| tts.py | 7.0 | 3 | TTS语音合成、音色列表、缓存清理 | 无 |
| music.py | 2.9 | 3 | 背景音乐上传/列表/删除 | 无 |

#### AI域（5个文件，92KB）
| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| assistant.py | 33.7 | 10 | AI对话、搜索、历史、配置、Ollama管理 | ai_solve, local_search, study_planner |
| knowledge_graph.py | 30.7 | 7 | 知识图谱：总览、章节映射、考情趋势、考点、薄弱点、预测 | 无 |
| ai_brain.py | 9.9 | 14 | AI大脑：总结、知识提取、口诀生成、概念解释/对比、错因分析 | ai_brain |
| ai_scan.py | 5.8 | 2 | AI拍照解题、历史记录 | ai_solve, local_search |
| ai_unified.py | 1.5 | 0 | AI统一入口（空文件） | 无 |

#### 资源域（5个文件，110KB）
| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| material.py | 46.4 | 19 | 教材上传/批量上传、去重、章节拆分、偏移校准、预处理 | pdf_splitter, scan_preprocessor, smart_toc_extractor |
| video.py | 25.6 | 19 | 视频上传/分类/列表/批量导入、进度、题目关联、笔记、B站搜索 | video_mnemonic_extractor |
| syllabus.py | 22.2 | 5 | 大纲上传、解析、分析报告 | ai_solve |
| lecture.py | 12.5 | 7 | 讲义上传/列表/删除/文件夹删除、题目识别/导入 | pdf_question_extractor |
| note.py | 2.9 | 5 | 笔记CRUD | deps |

#### 分析域（4个文件，51KB）
| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| analytics.py | 19.0 | 12 | 总览、章节正确率、学习趋势、薄弱点、错因分布、每日计划 | error_classifier |
| combined_analysis.py | 13.7 | 3 | 静态/动态/综合分析 | 无 |
| exam_analysis.py | 10.0 | 5 | 考试总览、章节分数、常考点、考点详情、预测 | deps |
| sprint.py | 7.7 | 7 | 热力图、年份分布、自定义考试、高频考点、预测卷、易混对比 | deps |

#### 系统域（10个文件，90KB）
| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| system.py | 18.5 | 22 | 健康检查、科目管理、统计、资源扫描、操作日志、备份/恢复、导出DB | deps |
| sync_unified.py | 27.0 | 11 | 同步push/pull、检查点、冲突解决、批量同步、设备管理 | audit_logger |
| data_check.py | 18.5 | 5 | 表结构、一致性、文件检查、全量检查 | 无 |
| deduplication.py | 13.4 | 4 | 扫描、自动合并、合并组、报告 | deduplication |
| preprocess_config.py | 13.7 | 4 | 全部配置、按类型获取/更新/重置 | 无 |
| rag_knowledge.py | 11.6 | 5 | RAG状态、索引、搜索、文档列表 | 无 |
| subject_switch.py | 9.1 | 2 | 切换信息、全部进度 | deps |
| backup.py | 3.1 | 6 | 创建/列表/恢复/删除/验证/统计备份 | backup_manager |
| monitor.py | 3.0 | 8 | 健康、状态、错误、降级控制、功能开关 | service_monitor |
| auth.py | 6.5 | 8 | 注册/登录/改密/个人信息/头像 | security |

#### 思维导图（1个文件，51KB）
| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| mindmap.py | 51.1 | 16 | 导图CRUD、PDF生成/拆分/上传、模板、合并、AI展开/生成/总结/聊天 | ai_solve, pdf_splitter, smart_toc_extractor |

### 3.8 新模块完整清单（54个文件，~783KB）【来源：实际代码统计 2026-09-13】

| 模块 | 文件数 | KB | 路由数 | 业务函数 | 核心能力 |
|------|--------|-----|--------|---------|---------|
| ai | 11 | 155 | 28 | 106 | PDF视觉识别(VLM)、Ollama管理、口诀生成、关键词提取、案例评分、流式对话、效果评估、提示词管理 |
| common | 17 | 165 | 33 | 131 | 文件库CRUD、文件库桥梁、预处理服务、题目导入、数据安全、监控、优雅退出、统一响应 |
| mm | 3 | 63 | 15 | 23 | 导图CRUD、PDF解析、导入导出(MD/OPML)、批量导入、科目层级、章节导图 |
| mt | 9 | 118 | 16 | 108 | 闪卡CRUD、今日复习、复习记录、六分类、FSRS算法、BKT算法、学习路径规划、能力雷达 |
| qb | 6 | 60 | 15 | 60 | 题目CRUD、批量删除、导出、统计、PDF识别确认、质量分级分析、IRT算法 |
| resource | 4 | 48 | 8 | 35 | 资源CRUD、上传/下载、批量删除、统计、PDF解析缓存 |
| sync | 3 | 40 | 10 | 11 | 同步状态、检查点、冲突列表/解决、统计、触发同步、上传/下载数据 |

---

## 🔄 第四章：标准工作流程（新旧融合五步法）【来源：系统设计宪法.md + 融合总方案】

### 4.1 新旧融合五步法（强制执行，不能跳步）

```
第1步：旧代码深度研读
  → 完整读取旧代码文件（从第1行到最后1行）
  → 逐函数拆解，记录每个函数的功能、参数、返回值、业务逻辑
  → 形成《旧代码函数清单》
      ↓
第2步：神经末梢拆解
  → 拆解到每个按钮、输入框、API调用、state字段
  → 理解每个功能的用户交互流程
  → 形成《神经末梢清单》
      ↓
第3步：对照迁移
  → 按神经末梢清单逐一迁移到新模块
  → 每迁完一项打勾，确认无遗漏
  → 不静默替换，所有功能点都要覆盖
      ↓
第4步：完整性自检
  → 逐项自检，确认无遗漏、无阉割、无静默替换
  → 边界检查：是否有遗漏的页面、函数、数据、边界情况
  → 反证检查：主动寻找反例，证明不彻底
      ↓
第5步：独立验收
  → 非迁移责任人独立验收
  → 质量工作组按测试用例验收
  → 不通过的打回重做
  → 通过的标记为✅
```

### 4.2 新旧融合原则【来源：系统模块化融合方案.md】
1. **新布局不动**：用户已经习惯了的界面，不要乱改
2. **旧代码不删**：旧代码继续跑，新模块慢慢建
3. **API路径不变**：前端不用改，后端换实现
4. **零数据迁移**：新旧用同一批数据库表，不用导数据
5. **旧API兜底**：新模块没写完的功能，旧API继续跑

### 4.3 全面读取铁律【来源：用户对话 + 系统设计宪法.md】
1. 必须完整读取文件，从第1行读到最后1行
2. 分批读取也要读完，读到[End of file]才能开始分析
3. 没读完不准开始任何修改/融合工作
4. 每次读取都要报进度："已读前X行，还剩Y行"
5. 禁止只看开头结尾就说"读完了"
6. 禁止只读100行就结束

### 4.4 修改前检查清单【来源：CODE_SAFETY_RULES.md】
- [ ] 是否违反布局锁死？
- [ ] 是否违反刷题逻辑铁律？
- [ ] 是否违反读取铁律？
- [ ] 是否备份了当前版本？
- [ ] 是否分析了修改影响范围？
- [ ] 是否有明确的完成清单？

### 4.5 保障机制（五重保障）【来源：系统模块化融合方案.md 第298-304行】

1. **双轨并行**：旧API不删，新模块逐步接
2. **兼容层路由**：旧URL转发到新service，前端零改动
3. **数据一致性**：同一批表，不需要迁移
4. **独立回退**：每个模块可单独切回旧API
5. **逐步验证**：一个功能一个功能切，对比新旧返回

### 4.6 执行计划【来源：系统模块化融合方案.md 第306-317行】

| 时间 | 做什么 | 工作量 |
|------|--------|--------|
| 第1天 | 新模块加兼容层路由 + 接线孤立算法 | 1.5天 |
| 第2-3天 | 补qb/service：刷题/答题/错题/收藏/组卷 | 2天 |
| 第4天 | 补ai/service：对话/拍照/知识图谱 | 1.5天 |
| 第5天 | 补common/service：分析/冲刺/数据治理 | 1.5天 |
| 第6天起 | 系统冻结，全力备考 | — |
| 考后 | 补resource/service：教材/视频/讲义/大纲 | 3天 |
| 考后 | 补common/service：系统管理/备份/笔记/TTS | 1天 |

### 4.7 已完成任务清单【来源：系统模块化融合方案.md 第385-407行】

| 模块 | 完成内容 | 新增端点 | 验证 |
|------|---------|---------|------|
| mt | FSRS算法接线 | POST /api/mt/fsrs/review, GET /api/mt/fsrs/status, GET /api/mt/fsrs/plan | ✅ |
| mt | 学习路径规划接线 | POST /api/mt/learning-path/generate, GET /api/mt/learning-path/weak-points | ✅ |
| qb | IRT算法接线 | POST /api/qb/irt/ability, GET /api/qb/irt/quality, GET /api/qb/irt/level | ✅ |
| qb | 刷题核心service | random_questions/record_answer/get_wrong_list/delete_wrong/mark_wrong_mastered/get_collect_list/add_collect/delete_collect/get_chapter_tree/get_knowledge_points | ✅ |
| qb | 刷题核心routes | GET /api/qb/random, POST /api/qb/answer/{qid}, GET /api/qb/wrong/list, DELETE /api/qb/wrong/{wid}, POST /api/qb/wrong/{wid}/mastered, GET /api/qb/collect/list, POST /api/qb/collect/{qid}, DELETE /api/qb/collect/{qid}, GET /api/qb/chapter-tree, GET /api/qb/knowledge-points | ✅ |
| ai | AI对话功能 | POST /api/ai/ask, GET /api/ai/history, POST /api/ai/study-plan | ✅ |
| qb | 考试域service | generate_exam/submit_exam/get_exam_history/get_exam_detail/get_exam_stats | ✅ |
| qb | 考试域routes | GET /api/qb/exam/generate, POST /api/qb/exam/submit/{id}, GET /api/qb/exam/history, GET /api/qb/exam/{id}, GET /api/qb/exam/stats | ✅ |
| qb | 题库补充端点 | GET /api/qb/wrong/today, PUT /api/qb/wrong/{id}, GET /api/qb/filters, GET /api/qb/mastery-analysis, POST /api/qb/analyze-wrong-reason | ✅ |
| common | 分析域routes | GET /api/common/analytics/overview, /chapter-accuracy, /weak-points, /wrong-reason-distribution, /sprint/heatmap, /sprint/high-freq | ✅ |
| ai | AI补充端点 | POST /api/ai/search, GET/POST /api/ai/config, GET /api/ai/providers, GET /api/ai/ollama/models, POST /api/ai/ollama/test, POST /api/ai/scan/solve, GET /api/ai/scan/history, POST /api/ai/brain/summarize, POST /api/ai/brain/explain | ✅ |
| mm | 导图补充端点 | GET /api/mm/template/default, POST /api/mm/merge, /merge-all, /ai/expand, /ai/generate, /ai/summarize | ✅ |
| common | 系统补充端点 | GET /api/common/all-subjects, /operation-logs, /search, /storage-info, /lan-info, /tts/voices, /tts/speak, CRUD /api/common/notes | ✅ |
| resource | 教材管理框架 | GET/POST/DELETE /api/resource/materials/* | ✅ 框架 |
| resource | 视频管理框架 | GET/DELETE /api/resource/videos/* | ✅ 框架 |
| resource | 讲义管理框架 | GET/POST/DELETE /api/resource/lectures/* | ✅ 框架 |
| resource | 大纲管理框架 | GET/POST/DELETE /api/resource/syllabi/* | ✅ 框架 |
| common | 分析域补充 | GET /api/common/analytics/study-trend, /subject-balance, /daily-plan, /sprint/year-distribution, /sprint/confusing-pairs, /sprint/predict-exam, /sprint/custom-exam | ✅ |
| qb | 考试域配置 | GET /api/qb/exam/config, /config/official, POST /config/verify, /{id}/switch-report | ✅ |

### 4.8 待完成任务清单【来源：系统模块化融合方案.md 第368-379行】

- [x] 第1步：新模块加兼容层路由
- [x] 第1步：接线孤立算法文件（FSRS、学习路径规划、IRT）
- [x] 第2步：补qb/service刷题核心（随机抽题/答题记录/错题/收藏/章节树/知识点）
- [ ] 第2步：补qb/service考试组卷
- [x] 第3步：补ai/service对话功能（ask/history/study-plan）
- [ ] 第3步：补ai/service拍照解题
- [ ] 第4步：补common/service数据分析
- [ ] 第4步：补common/service冲刺中心
- [ ] 考后：补resource/service教材/视频
- [ ] 考后：补common/service系统管理

### 4.9 数据验证结果【来源：系统模块化融合方案.md 第409-414行】
- 题库总量：正常读取
- 章节树：95个章节
- 知识点：248个
- 错题：91条
- 收藏：3条

### 4.10 分阶段计划（按优先级，不贪多）

#### 🔥 第一阶段：P0核心功能（第1-3天）
**目标**：把最核心的刷题功能跑通

| 工作组 | 任务 | 交付物 | 优先级 |
|--------|------|--------|--------|
| 题库组 | 刷题核心逻辑融合 | 单选题/多选题答题流程 | P0 |
| 公共组 | 认证系统融合 | 登录/注册/全局筛选 | P0 |
| 质量组 | P0功能测试用例 | 核心功能测试清单 | P0 |

#### ⚡ 第二阶段：P1重要功能（第4-7天）
**目标**：把记忆和AI功能跑通

| 工作组 | 任务 | 交付物 | 优先级 |
|--------|------|--------|--------|
| 记忆组 | SM-2算法完整实现 | 闪卡间隔重复 | P1 |
| AI组 | 本地AI对接 | AI解题/口诀生成 | P1 |
| 题库组 | 错题本/掌握度分析 | 错题自动归集 | P1 |
| 导图组 | 思维导图基础功能 | 节点增删改 | P1 |

#### 📊 第三阶段：P2数据治理（第8-14天）
**目标**：把数据质量和资源管理跑通

| 工作组 | 任务 | 交付物 | 优先级 |
|--------|------|--------|--------|
| 资源组 | 教材/视频/讲义管理 | 文件上传/存储/查看 | P2 |
| 导图组 | PDF识别→导图生成 | 智能思维导图 | P2 |
| 质量组 | 数据去重/质量监控 | 三层去重机制 | P2 |
| 公共组 | 多端同步/备份 | 离线同步 | P2 |

#### 🎨 第四阶段：P3体验优化（第15天以后）
**目标**：打磨细节，提升体验

| 工作组 | 任务 | 交付物 | 优先级 |
|--------|------|--------|--------|
| 前端组 | 布局优化/多端适配 | 平板/手机适配 | P3 |
| AI组 | AI能力增强 | 智能答疑/学习计划 | P3 |
| 质量组 | 性能优化/bug修复 | 全量回归测试 | P3 |

---

## 🏗️ 第五章：技术架构标准（所有专家都要遵守）

> **注**：六层架构模型和模块域划分详见第三章，本章不重复，只记录技术规范和融合细节。

### 5.1 模块间规则
1. **模块间禁止跨域import**：qb不能import mt的service
2. **跨模块通信**：通过API路由调用，或通过事件总线
3. **路由层薄壳**：routes.py只做参数校验和响应封装
4. **业务逻辑下沉**：所有业务逻辑都在service.py里

### 5.2 全量端点融合对比表【来源：系统模块化融合方案.md 第418-500行】

> 旧API约200个端点，新模块约150个端点
> 状态：✅已融合  🟡部分融合  ❌未融合

#### 题库域（旧28端点 → 新25端点）
| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /question/random_real | GET /api/qb/random | ✅ |
| GET /question/ai_weak_review | — | ❌ 待补 |
| GET /question/list | GET /api/qb/questions | ✅ |
| GET /question/detail/{qid} | GET /api/qb/questions/{id} | ✅ |
| DELETE /question/{qid} | DELETE /api/qb/questions/{id} | ✅ |
| POST /question/answer/{qid} | POST /api/qb/answer/{id} | ✅ |
| POST /question/collect/{qid} | POST /api/qb/collect/{id} | ✅ |
| DELETE /question/collect/{qid} | DELETE /api/qb/collect/{id} | ✅ |
| GET /question/collect/list | GET /api/qb/collect/list | ✅ |
| GET /question/wrong/list | GET /api/qb/wrong/list | ✅ |
| GET /question/wrong/today | — | ❌ 待补 |
| PUT /question/wrong/{wid} | — | ❌ 待补 |
| DELETE /question/wrong/{wid} | DELETE /api/qb/wrong/{id} | ✅ |
| POST /question/wrong/{wid}/mastered | POST /api/qb/wrong/{id}/mastered | ✅ |
| GET /question/filters | — | ❌ 待补 |
| GET /question/knowledge_points | GET /api/qb/knowledge-points | ✅ |
| GET /question/chapter_tree | GET /api/qb/chapter-tree | ✅ |
| GET /question/export | GET /api/qb/questions/export | ✅ |
| POST /question/import | — | ❌ 待补 |
| GET /question/export_excel | — | ❌ 待补 |
| GET /question/template | — | ❌ 待补 |
| POST /question/parse_pdf_preview | POST /api/ai/pdf/upload/recognize | ✅ |
| POST /question/import_parsed | POST /api/qb/recognize/confirm | ✅ |
| GET /question/mastery_analysis | — | ❌ 待补 |
| GET /question/diagram/{filename} | — | ❌ 待补 |
| POST /question/ai_match_chapter | — | ❌ 待补 |
| POST /question/batch_match_sections | — | ❌ 待补 |
| POST /question/analyze_wrong_reason | — | ❌ 待补 |

#### 考试域（旧10端点 → 新5端点）
| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /exam/generate | GET /api/qb/exam/generate | ✅ |
| POST /exam/submit | POST /api/qb/exam/submit/{id} | ✅ |
| GET /exam/history | GET /api/qb/exam/history | ✅ |
| GET /exam/detail/{id} | GET /api/qb/exam/{id} | ✅ |
| GET /exam/stats | GET /api/qb/exam/stats | ✅ |
| POST /exam/switch_report/{id} | — | ❌ 待补 |
| POST /exam/ai_grading/{id} | POST /api/ai/case/grade | 🟡 部分 |
| GET /exam/config | GET /api/qb/exam/config | ✅ |
| GET /exam/config/official | GET /api/qb/exam/config/official | ✅ |
| POST /exam/config/verify | POST /api/qb/exam/config/verify | ✅ |

#### 记忆域（旧9端点 → 新16端点）
| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| POST /flashcard/create | POST /api/mt/flashcards | ✅ |
| POST /flashcard/from_question | — | ❌ 待补 |
| POST /flashcard/batch_import | — | ❌ 待补 |
| GET /flashcard/list | GET /api/mt/flashcards | ✅ |
| PUT /flashcard/{cid} | PUT /api/mt/flashcards/{id} | ✅ |
| GET /flashcard/review_today | GET /api/mt/review/today | ✅ |
| POST /flashcard/review/{cid} | POST /api/mt/review/{id} | ✅ |
| DELETE /flashcard/{cid} | DELETE /api/mt/flashcards/{id} | ✅ |
| GET /flashcard/stats | GET /api/mt/statistics | ✅ |
| — | POST /api/mt/fsrs/review | ✅ 新增 |
| — | GET /api/mt/fsrs/plan | ✅ 新增 |
| — | POST /api/mt/learning-path/generate | ✅ 新增 |
| — | GET /api/mt/categories/* | ✅ 新增 |

#### AI域（旧36端点 → 新32端点）
| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| POST /assistant/ask | POST /api/ai/ask | ✅ |
| POST /assistant/search | POST /api/ai/search | ✅ |
| GET /assistant/history | GET /api/ai/history | ✅ |
| GET /assistant/config | GET /api/ai/config | ✅ |
| POST /assistant/config | POST /api/ai/config | ✅ |
| GET /assistant/providers | GET /api/ai/providers | ✅ |
| GET /assistant/ollama/status | GET /api/ai/ollama/status | ✅ |
| POST /assistant/ollama/setup | — | ❌ 待补 |
| GET /assistant/ollama/models | GET /api/ai/ollama/models | ✅ |
| POST /assistant/ollama/test | POST /api/ai/ollama/test | ✅ |
| POST /ai_scan/scan | POST /api/ai/scan/solve | ✅ |
| GET /ai_scan/history | GET /api/ai/scan/history | ✅ |
| POST /ai_brain/summarize | POST /api/ai/brain/summarize | ✅ |
| POST /ai_brain/explain | POST /api/ai/brain/explain | ✅ |

### 5.3 孤立算法文件（写了但没接线）【来源：系统模块化融合方案.md 第276-285行】

| 文件 | 大小 | 状态 |
|------|------|------|
| mt/learning_path_planner.py | 20.8KB | 孤立 → 已接线 ✅ |
| mt/ability_radar.py | 26.4KB | 孤立 → 已接线 ✅ |
| mt/bkt_algorithm.py | 10.1KB | 只被孤立文件引用 → 已接线 ✅ |
| qb/irt_algorithm.py | 13KB | 只被孤立文件引用 → 已接线 ✅ |
| resource/pdf_parse_cache.py | 14KB | 孤立 |

---

## 🎨 第六章：UI布局标准（锁死，绝对不动）【来源：新模块化布局 + 用户实测 + style.css】

> **注**：本章为新模块化布局的实际参数，已替代旧版V2布局规范。所有布局参数以实际运行系统为准，本章记录最新实测值。

### 6.0 实际运行基准（模块化布局，锁死源头）【来源：frontend/index.html + tokens.css 实际加载，2026-09-13】

> 🚨 **版本唯一铁律（根治垃圾文件）**：
> 1. **一个文件一个版本**：活跃目录里不许出现 .bak/.backup/V1/V2/最新版/最终版/改后 等多版本并存
> 2. **旧版必归档**：改文件前先备份到 _archived/，不是在同目录留 .bak
> 3. **基准只看实际运行**：设计稿/效果图不算数，只从 index.html 实际加载的文件提取
> 4. **禁止嵌套备份**：备份目录里不许再包含备份目录（防7.7GB套娃重演）
> 5. **改完跑 gen_file_index.ps1**：代码改完刷新索引，保持同步
> 以下为**实际运行系统**加载的真实文件，不是设计稿。V2.0效果图已过时，废弃。

**实际加载的基准文件**（index.html 第23-26行CSS + 第30行起JS）：
| 文件 | 作用 | 版本 |
|---|---|---|
| frontend/index.html | 实际入口（V4.5.15模块化版） | 9/12最新 |
| frontend/css/tokens.css | CSS Token体系，设计系统唯一来源 | v20260906 |
| frontend/css/components.css | 组件样式 | v20260908 |
| frontend/css/style.min.css | 主样式压缩版 | v20260906 |
| frontend/css/common.css | 通用样式 | governance_v1 |
| frontend/modules/layout/topbar.js | 顶部导航模块 | — |
| frontend/modules/layout/sidebar.js | 侧边导航模块 | — |
| frontend/modules/layout/module-nav.js | 模块导航 | — |
| frontend/modules/layout/statusbar.js | 底部状态栏 | — |

**真实布局参数（tokens.css提取）**：
| 项 | 值 |
|---|---|
| 主色 | #1a73e8（蓝） |
| 主色深 | #1557b0 |
| 主色浅 | #e8f0fe |
| 背景 | #f5f7fa |
| 卡片 | #ffffff |
| 文字 | #1f2937 |
| 边框 | #e5e7eb |
| 侧边栏宽 | 135px（!important强制） |
| 头部高 | 56px（--header-h） |
| 输入框高 | 38px（--input-h） |
| 内容最大宽 | 1400px |
| 圆角 | 4/6/8/12/16px 五档 |
| 间距 | 4/8/16/24/32/48px 六档（8px基数） |
| 字号 | clamp自适应：xs→3xl 八档 |

**模块化布局铁律**：
- 侧边栏固定135px（index.html第18-19行 !important）
- 所有颜色/尺寸/间距必须用tokens.css变量，禁止硬编码
- 布局模块独立：topbar/sidebar/module-nav/statusbar 四个JS模块
- V2.0效果图.html 已废弃，仅作历史参考

### 6.1 三层布局结构（锁死）【来源：index-modular.html 第18行 + style.css】
```
┌─────────────────────────────────────────┐
│  顶部导航栏（56px高，style.css:229）：科目切换、全局菜单  │
├──────────┬──────────────────────────────┤
│          │  侧边导航栏（135px固定宽，index-modular.html:18）：模块切换 │
│          ├──────────────────────────────┤
│          │  content-header（标题+筛选栏，固定不滚动，min-height:36px，style.css:853）│
│          ├──────────────────────────────┤
│          │  content-body（内容区，可滚动，padding:12px 14px，style.css:856）  │
│          ├──────────────────────────────┤
│          │  分页栏（固定底部，不滚动）      │
├──────────┴──────────────────────────────┤
│  底部状态栏（40px高，style.css:231）：进度、状态信息     │
└─────────────────────────────────────────┘
```

### 6.2 布局铁律（绝对不动）【来源：index-modular.html 第18行 + style.css】
- ✅ 竖向导航栏：**固定135px宽**（min/max都是135px，!important强制）【来源：index-modular.html 第18行】→ 绝对不动
- ✅ 顶部导航栏：**56px高**【来源：style.css 第229行】→ 绝对不动
- ✅ 底部状态栏：**40px高**【来源：style.css 第231行】→ 绝对不动
- ✅ 主内容区底部padding：**32px**【来源：style.css 第227行】→ 绝对不动
- ✅ 登录界面布局：已锁死 → 绝对不动

### 6.3 Flex布局铁律【来源：通用布局规范V1.0.md】
- 外层容器：display:flex;flex-direction:column;height:100%
- header/footer：flex-shrink:0（不压缩）
- content-body：flex:1;overflow-y:auto;min-height:0（可滚动）

### 6.4 表格规范【来源：通用布局规范V1.0.md】
- 单个table，包含thead和tbody
- 表头放在content-header区域，固定不滚动
- 行高：32px（padding:7px 6px）
- 斑马纹：偶数行#f8fafc，奇数行#ffffff
- 超长省略：white-space:nowrap;overflow:hidden;text-overflow:ellipsis

### 6.5 按钮规范【来源：style.css 实际参数】
| 尺寸 | padding | 字体 | 场景 |
|------|---------|------|------|
| 大 | 12px 24px | 18px | 主操作、登录按钮 |
| 默认 | clamp(6px, 0.8vw, 10px) clamp(12px, 1.5vw, 18px) | 14px | 普通按钮 |
| 小 | 4px 10px | 14px | 表格内、PDF工具栏 |
| 超小 | 2px 8px | 11px | 最小操作 |

### 6.6 颜色规范【来源：通用布局规范V1.0.md】
- 主色：#2563eb
- 成功：#16a34a
- 警告：#d97706
- 危险：#dc2626
- 标题：#1e293b
- 正文：#334155
- 边框：#e2e8f0
- 背景：#f8fafc

### 6.7 字体规范【来源：style.css 实际参数】
- 基础正文：响应式 `clamp(14px, 1.5vw, 16px)`（默认14px）
- 导航项：14px，图标18px（宽22px）
- 表格：13px
- 辅助文字：12px
- content-header标题：14px，加粗
- 页面标题：16px / 18px / 20px
- 卡片标题：16px

### 6.8 多设备适配【来源：多设备适配指南.md】
- 平板（推荐）：横屏刷题+视频，竖屏阅读笔记
- 手机：侧边栏仅图标，内容单列
- 电脑：多列布局，效率优先
- 响应式断点：≤480px手机 / 769-1024px平板 / >1200px电脑

### 6.9 弹窗规范【来源：通用布局规范V1.0.md】
- 所有弹窗统一宽度：720px
- 所有弹窗统一高度：88vh
- 居中显示
- 遮罩层：rgba(0,0,0,0.5)
- 关闭按钮：右上角

### 6.10 表格列宽规范【来源：通用布局规范V1.0.md 第66-77行】
| 列类型 | 推荐宽度 | 说明 |
|--------|----------|------|
| 序号 | 40px | 居中 |
| 单选/多选框 | 40px | 居中 |
| 题型 | 50px | 居中，标签形式 |
| 答案 | 45px | 居中，加粗 |
| 年份 | 45px | 居中 |
| 类型 | 55px | 居中，标签形式 |
| 操作 | 80px | 居中，按钮组 |
| 章节 | 120px | 居中，超长省略 |
| 题干/标题 | 自适应 | 左对齐，超长省略 |

### 6.11 单元格规范【来源：通用布局规范V1.0.md 第79-91行】
- 所有单元格：`white-space:nowrap;overflow:hidden;text-overflow:ellipsis`
- 数字列：居中对齐
- 文本列：左对齐
- 操作列：居中对齐，按钮间距2px
- 行高：32px（padding:7px 6px）
- 斑马纹：偶数行`#f8fafc`，奇数行`#ffffff`
- 悬停：`#eff6ff`

### 6.12 导航项规范【来源：style.css 实际参数】
- padding：5px 10px
- 字体大小：14px
- 图标与文字间距：8px
- 左侧选中条：3px宽，primary颜色
- hover/active背景：primary-light
- 导航图标：22px宽，18px字体
- 导航组标题：13px，加粗，大写，0.5px字间距
- 导航栏滚动条：4px宽，透明背景

### 6.13 卡片规范【来源：style.css 实际参数】
- 内边距：16px 18px
- 圆角：var(--radius)（8px）
- 阴影：var(--shadow)
- 底部外边距：12px
- 行高：1.7
- 背景：var(--card)

### 6.14 滚动条规范【来源：style.css 实际参数】
- 宽度/高度：6px
- 圆角：2px
- 轨道：透明
- 滑块：var(--border)颜色
- hover：var(--text2)颜色
- 导航栏滚动条：4px宽
- 表头底部：`2px solid #e2e8f0`
- 行分隔：`1px solid #f1f5f9`
- 表格外边框：`1px solid #c5cae9`

### 6.15 按钮类型与间距【来源：style.css 实际参数】
- 主按钮：`btn-primary`（蓝色背景）
- 次按钮：`btn-outline`（边框+透明背景）
- 危险按钮：`btn-danger`（红色背景）
- 成功按钮：`btn-success`（绿色背景）
- 同组按钮间距：6px
- 按钮内边距：clamp(6px, 0.8vw, 10px) clamp(12px, 1.5vw, 18px)

### 6.16 间距规范【来源：style.css 实际参数】
- 页面容器：`padding:12px 14px`
- 卡片内边距：`16px 18px`
- 模块间距：`12px`
- 元素间距：`8px`
- 紧凑间距：`4px`
- 卡片圆角：8px

### 6.14 题型标签色【来源：通用布局规范V1.0.md 第196-205行】
- 单选题：`#dbeafe`背景，`#1e40af`文字
- 多选题：`#fef3c7`背景，`#92400e`文字
- 判断题：`#dcfce7`背景，`#166534`文字
- 案例题：`#fce7f3`背景，`#9d174d`文字
- 真题：`#dcfce7`背景，`#166534`文字
- 模拟题：`#fef3c7`背景，`#92400e`文字
- 练习题：`#f1f5f9`背景，`#475569`文字

### 6.15 字体规范详细【来源：通用布局规范V1.0.md 第209-230行】
| 级别 | 大小 | 字重 | 适用场景 |
|------|------|------|----------|
| 大标题 | 18px | 600 | 页面标题 |
| 小标题 | 16px | 600 | 卡片标题 |
| 正文 | 14px | 400 | 普通文本 |
| 小字 | 13px | 400 | 表格内容 |
| 辅助 | 12px | 400 | 辅助信息 |
| 超小 | 10px | 400 | 标签、按钮 |
- 行高：标题1.3，正文1.5，表格1.2

### 6.16 筛选栏规范【来源：通用布局规范V1.0.md 第234-251行】
- 标题+筛选栏同一行，flex布局
- 标题左对齐，筛选栏右对齐
- 筛选元素间距：4px
- 超出时横向滚动：`overflow-x:auto`
- 下拉框：高度26px，宽度70-120px
- 输入框：高度26px，宽度120-150px
- 按钮：高度26px，padding:2px 10px
- 所有元素：`flex-shrink:0`（不压缩）
- 筛选栏和表头都在content-header中，固定不滚动

### 6.17 分页栏规范【来源：通用布局规范V1.0.md 第255-267行】
- 固定在content-body下方，不随滚动
- 高度：36px
- 居中对齐
- 左侧显示总数，右侧显示页码
- 普通页码：`btn-outline`，小尺寸
- 当前页：`btn-primary`，小尺寸
- 页码间距：4px

### 6.18 页面独立样式类规范【来源：通用布局规范V1.0.md 第95-123行】
- 命名规则：`页面名-page`（如`.qb-manager-page`）
- 优先级：全局样式 < 页面样式类 < 内联样式
- 禁止用`!important`覆盖全局样式
- 修改页面样式时，只修改该页面样式类下的样式

### 6.19 实施检查清单【来源：通用布局规范V1.0.md 第285-302行】
每个页面上线前必须检查：
- [ ] 页面是否有独立样式类
- [ ] 表格是否是单个table
- [ ] 表头是否固定不滚动
- [ ] 列宽是否符合规范
- [ ] 单元格是否超长省略
- [ ] 斑马纹是否正确
- [ ] 按钮尺寸是否符合规范
- [ ] 颜色是否符合规范
- [ ] 字体大小是否符合规范
- [ ] 间距是否符合规范
- [ ] 筛选栏与标题是否同一行
- [ ] 分页栏是否固定底部
- [ ] 是否有未使用的`!important`

### 6.20 禁止事项【来源：通用布局规范V1.0.md 第30-34行、第308-314行】
- ❌ 禁止把表头和内容分成两个table
- ❌ 禁止用`position:sticky`在th上
- ❌ 禁止用内联样式写死固定尺寸
- ❌ 禁止滥用`!important`
- ❌ 禁止修改全局CSS影响其他页面
- ❌ 禁止表头与内容之间有空白条

### 6.21 工具栏/筛选栏单行显示铁律【来源：用户实测 2026-09-14，笔记模块教训】

> **全局要求，所有模块通用，不是笔记模块专属。**

- ✅ **同一模块顶部工具栏内的所有控件（标题、新建按钮、搜索框、筛选下拉、导出/操作按钮）必须排在同一行**，不得拆成两行。
- ✅ 实现方式：外层容器 `display:flex; flex-wrap:nowrap; align-items:center; gap:6px; width:100%;`
- ✅ 弹性控件（搜索框）用 `flex:1; min-width:0;` 自动伸缩；固定控件（按钮、下拉）用 `flex-shrink:0;` 不收缩。
- ✅ 下拉框限宽（如 `max-width:100px`），避免把其他控件挤换行。
- ✅ 内边距/字号紧凑化（padding 6-8px、font-size 12px）以在窄栏内容纳。
- ❌ 禁止把"标题+新建"放一行、"搜索+筛选+导出"放第二行这种拆行写法；除非用户明确要求两行。
- ❌ 禁止用 `flex-wrap:wrap` 导致控件在窄宽度下自动换行。
- 📌 **已应用模块**：note.js 左栏 header（2026-09-14）。其他模块改造时按此标准对齐。

### 6.22 卡片视觉规范（用户确认"这种是可取的"，已锁死）【来源：memory.js 2026-09-14】

> **全局卡片设计标准**，所有模块的统计卡/功能入口卡/方法卡都按此风格。记忆训练页已按此实现并经用户确认。

- **两种卡片类型**：
  1. **数据统计卡（顶部大数字）**：
     - 背景：`linear-gradient(135deg,#浅色,#中色)`（浅→中，不深）
     - 白色大数字 22px + 白色 92% 透明 label 12px
     - 圆角 12px，padding 8px 10px，阴影 `0 2px 8px rgba(0,0,0,0.06)`
     - hover 上浮 2px
  2. **功能入口卡（图标+名称+描述）**：
     - 背景：`linear-gradient(135deg,${淡色} 0%,#ffffff 100%)`（淡色→白）
     - 顶部 3px 饱和色条
     - 白底圆角 icon 方块 36×36px（圆角 8px），带同色 20% 透明阴影
     - 饱和色粗体名称 13px + 灰色描述 11px
     - 圆角 12px，padding 10-14px 8px，hover 上浮 2px
- **锁死色板**（浅→中渐变 / 淡色背景）：
  - 蓝：#60a5fa→#3b82f6 / 淡 #eff6ff
  - 橙：#fbbf24→#f59e0b / 淡 #fff7ed
  - 绿：#34d399→#10b981 / 淡 #ecfdf5
  - 紫：#a78bfa→#8b5cf6 / 淡 #f5f3ff
  - 红：#f87171→#ef4444 / 淡 #fef2f2
  - 青：#22d3ee→#06b6d4 / 淡 #ecfeff
  - 粉：#f472b6→#ec4899 / 淡 #fdf2f8
  - 靛：#818cf8→#6366f1 / 淡 #eef2ff
  - teal：#2dd4bf→#14b8a6 / 淡 #f0fdfa
- **一屏显示参数**（记忆训练已锁死）：
  - 模块 `height:calc(100vh-105px); overflow:hidden; gap:4px; padding:3px`
  - 统计卡 padding 8px，大数字 22px
  - 方法卡 padding 10px 8px
  - 进度卡 padding 8px，大数字 18px
- ❌ 禁止整块饱和色平涂（太刺眼）；❌ 禁止灰白无配色（辨识度低）；✅ 淡渐变+顶部色条+白 icon 方块是黄金组合。
- 📌 已应用：memory.js 顶部4统计卡 + 易混淆概念卡 + 4工具卡 + 9方法卡 + 底部3进度卡。
- 📌 **其他模块同步要求**：dashboard、analytics、question-manager、collect、note 等模块的统计卡/入口卡，一律按此色板和卡片规范。

### 6.23 统计卡布局规范（用户确认"这样好看些"）【来源：dashboard.js 2026-09-14】

> **所有模块顶部统计卡统一左icon右文字布局**，禁止居中上下堆叠。

- **普通统计卡**（累计答题/正确率/待复习/连续学习）：
  - 布局：flex row，左 icon 右文字
  - icon：48×48px 白底彩色方块，圆角 10px，带阴影
  - 右侧：大数字 22px 粗体 + 标签 12px，左对齐，垂直居中
  - 背景：浅→中渐变（#93c5fd→#60a5fa 等），白字
  - 圆角 10px，padding 12px 16px，gap 12px
- **考试倒计时卡**（特殊）：
  - 背景：纵向渐变（180deg），深→浅
  - icon：56×56px 大图标（不用方块背景）
  - 右侧：大数字 28px 粗体 + 天 13px + 考试名 12px 粗体 + 阶段 11px
  - 数字和"天"基线对齐
- **渐变色调淡规范**：
  - 蓝 #93c5fd→#60a5fa
  - 绿 #6ee7b7→#34d399
  - 红 #fca5a5→#f87171
  - 橙 #fcd34d→#fbbf24
  - 紫 #c4b5fd→#a78bfa
  - 阴影透明度统一 0.2

### 6.24 章节名称格式规范（用户锁死）【来源：question-manager.js 2026-09-14】

- **章格式**：`数字 章名`，如 `1 工程造价管理及其基本制度`
- **节格式**：`数字.数字.数字 全称`，如 `3.4.1 流水施工的特点和参数（一）`
- **禁止**：`第1章`、`第3章第4节` 这种简称
- **下拉选项**：按章分组（optgroup），组名=章格式，选项=节格式
- **薄弱/高频考点**：薄弱考点用节格式，高频考点用章格式

### 6.25 面板配色规范（全局）【来源：dashboard.js 2026-09-14】

- **内容面板**（待复习/AI建议/掌握度/配置栏等）：
  - 背景：`linear-gradient(135deg,${淡色} 0%,#ffffff 100%)`
  - 顶部 3px 饱和色条
  - 圆角 8px
- **面板颜色分配**：
  - 快捷入口：蓝顶条
  - 今日目标：淡绿→白，绿顶条
  - AI时间安排：淡蓝→白
  - 学习日历：淡紫→白，紫顶条
  - 今日待复习：淡红→白，红顶条
  - AI学习建议：淡黄→白，橙顶条
  - 章节掌握度：淡青→白，青顶条
  - 收藏工具栏：淡粉→白，粉顶条
  - 刷题配置栏：淡蓝→白，蓝顶条
- **列表项 hover**：淡蓝 #dbeafe，圆角 4px
- **斑马纹**：偶数行 #f9fafb

### 6.26 题库管理布局（用户锁死）【来源：question-manager.js 2026-09-14】

- 顶部筛选栏：单行显示（类型/章节/难度/年份/搜索/新增/导入/重置/清空）
- 中间列表区：flex:1 自适应高度，独立滚动
- 底部分页栏：固定屏幕底部，左"共N条记录"，右"上一页/页码/下一页"
- 表格斑马纹：偶数行 #f9fafb，hover #dbeafe
- 章节格式：章=`1 工程经济`，节=`1.1.1 全称`

---

## 📊 第七章：业务逻辑标准（所有专家都要遵守）【来源：用户对话 + 规划细则V3.0 + 数据去杂 + 思维导图原则】

### 7.1 刷题逻辑铁律【来源：question.py 实际代码 + 用户对话确认】

#### 7.1.1 题型判断铁律
- **四个选项=单选，五个选项=多选**（铁律，不能改）
- 题型也存在数据库字段`q_type`里：单选/多选/计算

#### 7.1.2 答题交互逻辑
- **单选题**：点了选项就出解析（不需要点提交）
- **多选题**：选完选项后，点提交按钮才出解析
- **不需要答题卡**：单题刷题模式
- 题目位置固定，选项和解析区可滚动

#### 7.1.3 核心判题逻辑【来源：question.py 第313行】
```python
is_correct = user_answer.upper() == q.answer.upper()
```
- 答案不区分大小写，统一转大写后字符串比较
- 多选题答案格式：字母连写，如"ABD"
- 必须完全匹配才判对，多选少选都算错

#### 7.1.4 数字题智能判分【来源：用户对话确认】
- 题目本身已经带单位的，用户输入数字或带单位都算对
- 答案是范围的（如"15%-20%"），输入范围内任意数字都算对
- 不要求用户全文复述，数字+单位智能匹配

#### 7.1.5 错因分析逻辑【来源：question.py 第1394-1436行】
答错后自动分析错因：
1. **记忆遗忘**：答案为空或答题时间<3秒
2. **审题错误**：题目问"不正确/错误/不属于"，或多选题只选了一个
3. **计算错误**：题目包含计算关键词（计算、费用、造价、投资、成本、税率等）
4. **粗心大意**：答案和正确答案只差1个字符（相似度极高）
5. **概念不清**：默认错因

### 7.2 科目名称铁律【来源：用户对话确认】
全局统一用简称：
- 一造管理、一造水利案例、一造计价
- 一建管理、一建法规、一建经济、一建水利
- 二建水利

### 7.3 去重铁律【来源：数据去杂与质量治理分册】
- **全局所有文件都要去重**：题目、教材、闪卡、视频、讲义
- 三层去重：精确去重 → 相似度去重 → 语义去重
- 去重机制：数据库唯一索引 + 哈希表双重作用
- 导入时自动去重，不重复入库

### 7.4 学习算法标准【来源：question.py + knowledge_graph.py 实际代码】
- **掌握度 = 正确率*0.6 + 用时效率*0.4**【来源：question.py 第1074行】
- 用时效率 = max(0, min(1, 1 - (平均用时 - 30) / 120))【来源：question.py 第1072行】
- 掌握等级：≥80优秀 / ≥60良好 / ≥40一般 / <40薄弱【来源：question.py 第1077-1084行】
- **AI薄弱点优先级 = 错误次数*3 + 逾期天数*2 + 最近错误权重(max(0,7-天数)*2) - 复习次数*0.5**【来源：question.py 第220行】
- 异常数据排除：用时<2s疑似乱选，>300s疑似离开，不纳入掌握度计算

### 7.5 闪卡核心业务逻辑【来源：flashcard.py + sm2_engine.py】

#### 7.5.1 闪卡字段
- 正面：知识点/问题
- 背面：答案/解析
- 标签：科目 + 章节 + 知识点
- 分类：专项类型、教材页码、记忆诀窍（mnemonic）
- 去重：MD5哈希去重，相同内容不重复创建【来源：flashcard.py 第20-36行】

#### 7.5.2 闪卡生成方式
1. 手动新建
2. 从题目一键生成（题干=正面，答案+选项+解析=背面）【来源：flashcard.py 第42-84行】
3. 批量导入（文本/文件/错题/AI生成）
4. 从错题本导入

#### 7.5.3 今日复习筛选
- 查询条件：next_review <= 今天
- 脏数据过滤：空内容、纯数字、URL、乱码、纯标点【来源：flashcard.py 第233-250行】

#### 7.5.4 六分类评分（质量分级0-5分）【来源：sm2_engine.py 第16-23行】
| 分数 | 名称 | 说明 | 颜色 |
|------|------|------|------|
| 0 | 完全忘记 | 看到答案完全没印象 | 红 |
| 1 | 错误模糊 | 答错，看到答案有点印象 | 浅红 |
| 2 | 错误似曾相识 | 答错，看到答案觉得应该会 | 橙 |
| 3 | 正确困难 | 答对，但想了很久 | 黄 |
| 4 | 正确犹豫 | 答对，稍微想了一下 | 浅绿 |
| 5 | 完全掌握 | 完全正确，毫不犹豫 | 绿 |

#### 7.5.5 SM-2间隔重复算法【来源：sm2_engine.py 第34-70行】
**答错（<3分）：**
- 间隔重置为1天
- 复习次数归零
- 易难度系数降低

**答对（>=3分）：**
- 第1次答对：间隔1天
- 第2次答对：间隔6天
- 第3次及以后：间隔 = 当前间隔 × 易难度系数

**易难度系数调整：**
- 范围：1.3 - 3.0，默认2.5
- 调整公式：EF' = EF + (0.1 - (5-q) * (0.08 + (5-q) * 0.02))

#### 7.5.6 闪卡掌握度计算【来源：sm2_engine.py 第72-100行】
- 复习次数权重：30%（最多10次满分）
- 间隔天数权重：25%（最多30天满分）
- 易难度系数权重：25%（1.3-3.0归一化）
- 最近质量权重：20%（0-5分归一化）
- 掌握度阈值：>= 0.8 视为掌握

#### 7.5.7 闪卡操作流程逻辑【来源：app_v3.js 前端代码】

**页面布局：两个Tab**
- Tab1：📋 闪卡列表（表格显示所有闪卡）
- Tab2：🎵 朗读记忆专练（语音播报模式）

**闪卡列表页操作：**
- 顶部按钮：新建闪卡、批量导入、全部删除
- 表格列：序号、章、专项类型、核心内容、关键词、页码、记忆诀窍
- 单张操作：🔊朗读、⬅️上一张、下一张➡️
- 点击卡片：翻转（正面↔背面）

**新建闪卡表单：**
- 字段：正面、背面、专项类型、教材页码、记忆诀窍、标签
- 提交：保存/取消

**批量导入闪卡（4种方式）：**
1. 文本导入：粘贴文本，自动解析
2. 文件导入：上传文件，自动解析
3. 错题导入：从错题本选择题目，一键生成闪卡
4. AI生成导入：AI自动生成闪卡

**朗读记忆专练页操作：**
- 范围：当前单科目的全部闪卡
- 播放控制：播放/暂停、上一张、下一张、停止
- 播报模式：连续播放、单张循环、随机播放
- 说明：遍历所有闪卡重复播报，没口诀的播放知识点
- 切到其他模块：继续播放，不中断
- 朗读规则：不读"知识点"三个字

**语音播报设置：**
- 语速调节
- 翻卡后自动读背面（开关）
- 启用/关闭语音播报（开关）
- 测试播报按钮
- 优先使用本地语音（离线可用）

---

### 7.6 其他模块操作逻辑【来源：app_v3.js 前端代码】

#### 7.6.1 记忆训练模块操作逻辑

**页面布局（从上到下）：**
1. 顶部：记忆训练统计（今日完成、总进度）
2. 考试科目专项记忆训练（按当前科目过滤显示）
3. 记忆工具 & 科学记忆法（快捷入口）
4. 九大科学记忆法（9个一行，点击查看详情+实战训练）

**九大科学记忆法：**
- 间隔重复法（艾宾浩斯）
- 联想记忆法
- 谐音记忆法
- 宫殿记忆法
- 首字母记忆法
- 口诀记忆法
- 图表记忆法
- 分段记忆法
- 过度学习法

**操作：**
- 点击记忆法卡片：查看详情+开始实战训练
- 艾宾浩斯复习计划：根据错题和闪卡自动生成今日复习任务
- 考试专项训练：按当前科目过滤，只显示该科目的考点

#### 7.6.2 思维导图模块操作逻辑

**页面功能：**
1. 从PDF生成思维导图：直接上传PDF，自动解析目录生成
2. 从教材生成：选择已上传的教材，自动拆分生成
3. 从讲义同步：先在讲义管理里同步文件夹，再到导图里用AI拆分
4. 思维导图编辑器：节点编辑、AI展开、AI总结、AI聊天
5. 导出：MD/OPML/图片
6. 模板选择、合并多个导图

**操作流程：**
- 上传PDF → 解析目录 → 生成思维导图 → 编辑 → 保存
- 同步讲义文件夹 → AI拆分 → 生成导图

#### 7.6.3 AI拍照解题模块操作逻辑

**页面布局：左右两块**
- 左边：上传区域（拍照/上传图片）
- 右边：解析结果（答案、解析）

**操作流程：**
1. 拍照或上传题目图片
2. AI识别题目内容
3. 本地知识库优先匹配
4. 显示答案和解析
5. 自动记录到历史记录

**历史记录：**
- 下面一个大的历史记录区域
- 包含：题目、选项、答案、解析
- 点击查看详情

#### 7.6.4 教材管理模块操作逻辑

**页面功能：**
- 上传PDF教材
- 教材列表（显示文件名、大小、上传时间）
- 教材拆分：根据目录拆分PDF
- 章节结构树：显示教材目录
- 偏移校准：页码偏移调整

**操作流程：**
上传教材 → 自动识别目录 → 确认目录 → 拆分教材 → 生成章节列表

#### 7.6.5 视频讲义模块操作逻辑

**三个Tab：**
- Tab1：视频播放（内嵌播放列表+智慧笔记）
- Tab2：视频管理（按文件夹归类显示，文件夹上传）
- Tab3：讲义管理（文件夹上传/显示/删除）

**操作：**
- 视频按文件夹归类显示
- 讲义管理支持文件夹上传
- 同步到导图按钮：把讲义文件夹同步到思维导图，用于AI拆分

#### 7.6.6 数据分析模块操作逻辑

**页面功能：**
- 学习总览（总题数、正确率、学习时长）
- 章节正确率（结构树，支持层级收缩，显示章节全称）
- 学习趋势（折线图）
- 薄弱点分析（按掌握度排序）
- 错因分布（饼图）
- 每日计划（推荐每日学习量）

---

### 7.7 全部模块操作逻辑总览（16个模块全覆盖）【来源：app_v3.js render函数】

#### 7.7.1 登录模块
**操作流程：**
1. 首次登录：选择大专业（最多3个）→ 选择单科目（可多选）→ 确认进入系统
2. 再次登录：自动填充账号密码 → 直接进入系统
3. 登录方式：手动登录（推荐）/ 自动填充
4. 大专业切换：在系统设置里切换
5. 科目切换：顶部导航栏切换

#### 7.7.2 题库刷题模块（三个Tab）
**Tab1：📚 章节刷题**
- 左侧：章节结构树（点击选择章节）
- 右侧：题目区域（单题显示）
- 操作：选答案 → 出解析 → 下一题

**Tab2：🎯 AI薄弱点**
- 基于记忆曲线智能调度
- 优先级：错误次数*3 + 逾期天数*2 + ...
- 自动推荐最该复习的题目

**Tab3：📜 真题刷题**
- 按年份筛选真题
- 错题优先，先做错过的真题

**通用操作：**
- 单选题：选了就出解析
- 多选题：选完点提交才出解析
- 题目位置固定，选项和解析区可滚动

#### 7.7.3 题库管理模块
**操作：**
- 搜索框：在外面，全局搜索
- 列表：表格显示所有题目
- 批量操作：批量删除、批量导出
- 单题操作：编辑、删除、加入闪卡
- 全部删除按钮

#### 7.7.4 模拟考试模块
**操作流程：**
1. 选择科目 → 选择题型/题量/时长
2. 开始考试 → 答题界面
3. 交卷 → 成绩概览
4. 四个Tab查看：成绩概览 / 答题详情 / 题型分析 / AI评析
5. 返回考试列表按钮

#### 7.7.5 错题本模块
**操作：**
- 列表：所有错题，按章节/时间排序
- 今日错题：今天做错的题目
- 错题重做：重新做一遍
- 错题分析：错因分类统计
- 全部删除

#### 7.7.6 笔记模块
**布局：**
- 左侧：笔记列表
- 右侧：新建/编辑笔记
- 顶部：章节选择下拉框 + 笔记标题

**操作：**
- 按钮：新建、修改、保存、删除
- 章节选择：下拉框，引用课程教材目录
- 笔记内容：富文本编辑

#### 7.7.7 考试大纲模块
**两个Tab：**
- Tab1：上传文件解析（支持PDF）
- Tab2：大纲列表 + 分析报告

**操作：**
- 上传PDF大纲 → AI解析 → 生成分析报告
- 大纲列表：显示文件名、大小，双击在线查看
- 分析报告列表：显示历次分析结果

#### 7.7.8 设置模块
**功能：**
- 账号设置：修改密码、个人信息
- 科目设置：选择要考的科目
- 大专业切换：切换当前大专业
- 语音设置：语速、音色、自动朗读开关
- 外观设置：深色/浅色模式
- 备份设置：自动备份、手动备份
- AI设置：本地Ollama配置、模型选择
- 数据设置：清除缓存、导出数据

#### 7.7.9 其他模块
- **学习看板**：今日任务、学习进度、快捷入口
- **计算器**：悬浮按钮，随时调用
- **搜索**：全局搜索题目、知识点
- **通知**：复习提醒、考试倒计时
- **状态栏**：底部显示系统状态、网络、电量

### 7.6 思维导图三级结构【来源：思维导图集成原则分册】
- 三级结构：节导图 → 章导图 → 科目导图
- 双版本：问题版 / 答案版
- 识别流程：PDF页面截图 → 版面坐标切块 → 多模态识别 → 人工确认
- 集成铁律：识别生成思路不变，只优化技术实现

### 7.7 PDF预处理17步【来源：PDF公共预处理底座分册】
- 基础预处理8步：灰度化、二值化、降噪、去倾斜、去水印、去页眉页脚、文字去杂、表格去杂
- 多PDF合并：按章节合并
- 三层识别3步：表格识别、公式识别、文字识别
- 后处理5步：结果合并、格式整理、章节匹配、知识点提取、质量检查

### 7.8 教材拆分标准【来源：识别储存知识库V2.0】
- 教材拆分：根据目录拆分PDF
- 结构树页码定位：按识别的结构树页码来拆分
- 拆分后教材列表显示
- 章节编号：1.1 = 第一章第一节，第1章第2节 = 1.2

---

## 🔧 第八章：代码规范标准（所有专家都要遵守）【来源：CODE_QUALITY_GUIDE.md + CODE_SAFETY_RULES.md + 代码治理清理计划】

### 8.1 代码质量11项清单【来源：CODE_QUALITY_GUIDE.md】
1. **功能完整性**：边界条件处理，所有情况都要覆盖
2. **异常处理**：禁止裸except，必须捕获具体异常
3. **日志记录**：禁止print，必须用logger
4. **性能考虑**：避免N+1查询，批量加载
5. **安全考虑**：SQL参数化、密码加密、防止注入
6. **可维护性**：函数不超过50行，长了就拆
7. **兼容性**：数据库迁移、API向后兼容
8. **可测试性**：业务逻辑与UI分离，方便测试
9. **多端适配**：响应式、触控优化
10. **离线兼容**：核心功能离线可用
11. **数据安全**：修改前自动备份

### 8.2 代码安全规则【来源：CODE_SAFETY_RULES.md】
1. 禁止无确认大规模删除（超过10行必须先确认）
2. 所有代码必须落地本地磁盘，不依赖云端沙箱
3. 每轮迭代结束必须创建代码快照
4. 每次修改必须记录diff变更
5. 迭代工作流：需求→分析→修改→验证→记录→快照→回复

### 8.3 代码治理5阶段【来源：代码治理清理计划_V1.0】
- **阶段1**：JS内联样式清理（3689个→<100个）
- **阶段2**：style.css冗余清理（101KB→70KB）
- **阶段3**：CSS Token体系完善（颜色/间距/字号全用变量）
- **阶段4**：多端样式严格隔离（电脑/手机/平板互不干扰）
- **阶段5**：代码混入检查机制（防止新代码混旧风格）

### 8.4 前后端分离规范
- 前端：只负责展示和交互，不写业务逻辑
- 后端：只负责数据和业务逻辑，不关心前端怎么展示
- 前后端通过API通信，路径固定
- 新模块结构：routes.py（薄壳）+ service.py（业务逻辑）

---

## 🔄 第九章：新旧融合标准（所有专家都要遵守）【来源：系统模块化融合方案 + 融合总方案_长期参考】

### 9.1 融合原则
1. **新布局不动**：用户已经习惯了的界面，不要乱改
2. **旧代码不删**：旧代码继续跑，新模块慢慢建
3. **API路径不变**：前端不用改，后端换实现
4. **零数据迁移**：新旧用同一批数据库表，不用导数据
5. **旧API兜底**：新模块没写完的功能，旧API继续跑

### 9.2 融合目标状态【来源：系统模块化融合方案.md】
```
目标状态：
  L5新模块 ──→ L4service ─→ L3models  （全部业务在此）
  L5旧API ──→ 兼容层 ────→ L5新模块   （薄壳转发）

融合方式：
  1. 新模块service补全业务逻辑
  2. 旧API路由改为薄壳，转发到新service
  3. 前端API_BASE不变，无感知
  4. 验证通过后删除旧API文件
```

### 9.3 融合五步法（强制执行）
> **注**：详细步骤见第四章4.1，本章不重复。核心要点：
> 1. 旧代码深度研读
> 2. 神经末梢拆解
> 3. 对照迁移
> 4. 完整性自检
> 5. 独立验收

### 9.4 当前融合现状【来源：融合总方案_长期参考.md + 文件结构分析报告】
- **总融合率：约38%**
- **代码规模统计**：
  - 旧API：35个文件，567KB
  - 新模块：54个文件，783KB
  - 核心代码：11个文件，150KB
  - 工具代码：53个文件，1100KB
- **已融合**：题库基本功能、教材管理、视频讲义管理、AI大脑、错题分析
- **待融合**：认证域完全缺失、刷题核心仅部分融合、SM-2算法未完整实现、掌握度分析、薄弱点推荐、分析域大部分功能缺失

### 9.5 全模块详细对比清单【来源：融合总方案_长期参考.md】

#### 9.5.1 P0核心模块（每天用，优先融合）

| 模块 | 旧代码文件 | 旧函数数 | 新模块函数数 | 已融合 | 缺失 | 融合率 |
|------|-----------|---------|-------------|--------|------|--------|
| 题库域 qb | question.py | 28 | 27 | 14 | 14 | 50% |
| 记忆域 mt | flashcard.py | 8 | 10 | 6 | 2 | 75% |
| AI对话 ai | assistant.py | 17 | 52 | 11 | 6 | 65% |
| 分析域 common | analytics.py | 12 | 35 | 4 | 8 | 33% |
| 认证域 common | auth.py | 8 | 0 | 0 | 8 | 0% |

#### 9.5.2 P1重要模块（经常用，第二阶段）

| 模块 | 旧代码文件 | 旧函数数 | 新模块函数数 | 已融合 | 缺失 | 融合率 |
|------|-----------|---------|-------------|--------|------|--------|
| 教材 resource | material.py | 21 | 76 | 15 | 6 | 71% |
| 视频 resource | video.py | 19 | 16 | 16 | 3 | 84% |
| 讲义 resource | lecture.py | 8 | 6 | 6 | 2 | 75% |
| 导图 mm | mindmap.py | 19 | 26 | 11 | 8 | 58% |
| 考试 qb | exam.py | 10 | 5 | 5 | 5 | 50% |
| 错题分析 qb | wrong_analysis.py | 2 | 2 | 2 | 0 | 100% |
| 笔记 common | note.py | 5 | 4 | 4 | 1 | 80% |

#### 9.5.3 P2次要模块（偶尔用，第三阶段）

| 模块 | 旧代码文件 | 旧函数数 | 新模块函数数 | 已融合 | 缺失 | 融合率 |
|------|-----------|---------|-------------|--------|------|--------|
| 公式训练 mt | formula_trainer.py | 11 | 0 | 0 | 11 | 0% |
| 知识图谱 ai | knowledge_graph.py | 7 | 5 | 5 | 2 | 71% |
| AI大脑 ai | ai_brain.py | 14 | 14 | 14 | 0 | 100% |
| TTS common | tts.py | 3 | 2 | 2 | 1 | 67% |
| 音乐 common | music.py | 3 | 2 | 2 | 1 | 67% |
| 冲刺中心 common | sprint.py | 7 | 0 | 0 | 7 | 0% |
| 同步域 sync | sync_unified.py | 11 | 0 | 0 | 11 | 0% |

### 9.6 P0核心功能清单（必须最先融合）
| 序号 | 功能 | 旧代码位置 | 状态 |
|------|------|-----------|------|
| 1 | 登录认证 | api/v1/auth.py | ❌ 缺失 |
| 2 | 刷题核心 | api/v1/question.py | ⚠️ 部分融合 |
| 3 | 提交答案 | api/v1/question.py:306 | ⚠️ 部分融合 |
| 4 | 解析显示 | api/v1/question.py:334 | ⚠️ 有问题 |
| 5 | 闪卡复习 | api/v1/flashcard.py | ⚠️ 部分融合 |
| 6 | 错题本 | api/v1/question.py:365 | ❌ 缺失 |
| 7 | AI薄弱点复习 | question.py:134 | ❌ 缺失 |
| 8 | 今日错题 | question.py:428 | ❌ 缺失 |
| 9 | 掌握度分析 | question.py:1026 | ❌ 缺失 |
| 10 | 题目去重逻辑 | question.py:20-40 | ❌ 缺失 |

---

## 🛡️ 第十章：回溯安全网（反悔/纠错/升级的保障）【来源：用户对话】

### 10.1 三层保障
| 层级 | 保障什么 | 怎么实现 |
|------|---------|---------|
| 决策可追溯 | 知道每个设计为什么这么定 | 每个要点都标注【来源：xxx.md】，可回溯到原始文件 |
| 代码可回滚 | 做错了能退回去 | 每小时自动备份 + 修改前快照 + Diff记录 |
| 思路可迭代 | 有更好的能加进来 | 总管是活文档，随时可以加新设计理念 |

### 10.2 三个场景怎么用
#### 场景1：有更好的思路了
- **情况**：看到别人的系统设计更好，想改
- **怎么做**：
  1. 先看总管里这部分是怎么设计的
  2. 对比新旧思路，哪个更符合"帮用户考过一造"这个核心目标
  3. 决定：保留旧的 / 融合新的 / 替换成新的
  4. 改总管，同时保留旧版本快照

#### 场景2：我弄错了，你反悔了
- **情况**：我按总管做了，但你觉得不对，想改回来
- **怎么做**：
  1. 找到当时的决策依据（总管里的来源标注）
  2. 找到代码快照（修改前的备份）
  3. 回滚代码，同时调整总管里的设计理念
  4. 记录为什么改回来，避免下次再犯

#### 场景3：设计走偏了
- **情况**：做着做着发现不对，不是当初想的那样
- **怎么做**：
  1. 回到总管，看当初的设计理念是什么
  2. 对比现在做的，哪里偏了
  3. 调整方向，回到总管这条线上
  4. 如果总管本身错了，就改总管

### 10.3 回溯的基础是什么？
1. **所有设计文档都保留**：24个设计文件 + 6个HTML文件，都在项目根目录，不删
2. **所有修改都有记录**：修改日志.md 记了每次改了什么
3. **所有版本都有快照**：backups/ 目录下有历史版本
4. **每个决策都有出处**：总管里每个要点都标注来源，能追溯到原始设计

### 10.4 文件唯一性与权威文件【来源：文件唯一性保障规范+文件管理体系，2026-09-13融合】
- 每个功能只有一个权威文件，禁止"最新版/最终版/改后/副本/new"等多版本并存。
- 调度/修改前必做 MD5 指纹校验：`python tools/system_center.py verify`；修改后 `update-fingerprint`。
- 权威文件清单（指纹库 `backups/file_fingerprints.json`）：布局唯一标准HTML、V2接入层.js、V2规则.css、布局宪法、index.html、system-controller.js、system-supervisor.js、backend/main.py、tools/system_center.py、tools/auto_backup.py。
- 发现重复：以指纹库确认为准，其余移入隔离区，更新索引与变更日志。

### 10.5 备份分类与删除验证（铁律）【来源：备份验证与删除规范_宪法级】
| 类型 | 标识 | 保留 | 期限 |
|------|------|------|------|
| 黄金备份 | GOLDEN_* | 2个 | 永久 |
| 全量备份 | *_full | 1个 | 30天 |
| 变更前 | pre_change_* | 3个 | 7天 |
| 单文件 | 时间戳 | 合并归档 | 30天 |

**三类任何情况不得删**：最新黄金、前一版黄金、最近一次变更前备份。
**删除前11项验证全过才可删**：完整性4（存在非空/关键文件齐/可读/有标识）、重复性3（MD5比对/确认为重复/无独有内容）、安全性4（不在必留清单/非近7天/系统不需回滚/用户已确认）。
**删除流程**：先进 `_待删除_回收站/`，观察7天再经用户确认永久清理；日志记 `backups/change_log.json`。
**备份排除目录（防止7.7GB自嵌套事故重演）**：`ollama_models/ models/ node_modules/ __pycache__/ *.log backup_* _quarantine* _archived*`。

### 10.6 专家长效机制 M1–M11【来源：70名专家建议V2.0，2026-09-13融合】
| 编号 | 机制 | 状态 |
|------|------|------|
| M1 全面巡查机器人（8维度） | M2 改前备份+改后验证 | ✅ |
| M3 数据质量巡检 | M4 布局像素校验 | ⏳ |
| M5 性能监控 | M6 代码审查 | ⏳ |
| M7 修改影响分析器 | ✅ | M8 功能去重 | ⏳ |
| M9 数据血缘 | M10 回归用例库 | M11 日志告警 | ⏳ |

### 10.7 12领域专家48条核心建议【来源：70名专家建议V2.0】
造价：案例分步给分/教材版本对应/定额时效/计算过程展示。AI：RAG本地优先/公式OCR/知识图谱抽取/质量审核闭环。UI：设计Token/交互一致/空状态。前端：虚拟列表/懒加载/错误边界/插件隔离。DB：FTS5中文分词/知识点多对多/慢查询监控。分析：掌握度算法/学习漏斗/废题识别。测试：冒烟/边界值/兼容矩阵。安全：参数化/XSS转义/离线加密/CSRF。语文：术语统一/错误提示三段式。运维：/health/日志分级/自动重启/一键部署。产品：3步闭环/优先级矩阵/新手引导。学习科学：SM-2调优/主动回忆/交错练习/学习路径引擎。

### 10.8 系统诊断18维度结论【来源：缺失项分析+补充分析，2026-09-13】
- **P0立即修**：题库404、闪卡404、朗读无声、前端模块未register到总控。
- **P1本周**：XSS全检、统一错误处理、统一UI组件、API文档、日志轮转；+回归清单/影响评估/回滚模板/变更日志/问题库/踩坑记录/依赖扫描。
- **18维度全覆盖**：布局/功能/代码/数据/安全/性能/文档/运维（8）+需求/质量/进度/风险/版本/协同（6）+测试/变更/知识/监控/性能基线/环境/依赖/灾备/合规/体验（10）。
- **变更三要素铁律**：改什么→影响什么→怎么回滚，每次修改前必答。

---

## 📁 第十一章：文件索引（所有文件都挂在这里）【来源：文件读取追踪清单】

> 这不是标准，只是参考资料。标准只有上面这一条线。
> 想看细节就点对应文件。

### 🔴 顶层文件
| 文件 | 作用 | 行数 |
|------|------|------|
| [项目工作基准_开工必读.md](项目工作基准_开工必读.md) | 🚦 跨对话框唯一交接基准：开工三步+会话流水（第一必读） | ~40 |
| [架构总控文件.md](架构总控文件.md) | 你正在读的总管 | ~3000 |
| [系统设计宪法.md](系统设计宪法.md) | 最高原则，V2.6 | 6328 |

### 🟠 融合方案文件
| 文件 | 作用 | 行数 |
|------|------|------|
| [系统模块化融合方案.md](系统模块化融合方案.md) | 六层架构+七模块域+融合差距 | ~1017 |
| [融合总方案_长期参考.md](融合总方案_长期参考.md) | 12个模块代码级对比 | ~1391 |
| [待执行迁移计划.md](待执行迁移计划.md) | 六大块待办 | 171 |
| [前端API新旧映射表.md](前端API新旧映射表.md) | 22组API路径映射 | 66 |

### 🟡 规划设计文件
| 文件 | 作用 | 行数 |
|------|------|------|
| [实施细则总集.md](实施细则总集.md) | 📚 现行唯一：数据去杂+识别知识库V2+规划V3+思维导图+PDF预处理，5份合一（原分册已归档） | ~3837 |
| [布局规范总集.md](布局规范总集.md) | 📐 布局规范/12份+通用布局规范/多设备/功能清单，每份标来源 | ~2987 |
| [docs工作文档总集.md](docs工作文档总集.md) | 🗂️ docs/19份：分析报告/计划/质量安全/部署，每份标来源 | ~3872 |
| [融合迁移总集.md](融合迁移总集.md) | 🔀 融合总方案+模块化方案+迁移计划+API映射+OCR存储+AI知识库+插件化设计，7份合一 | ~3769 |
| [代码规范总集.md](代码规范总集.md) | 🔧 代码质量+安全规则+治理计划，3份合一 | ~874 |
| [功能融合方案_V2.0_基于实际索引.md](功能融合方案_V2.0_基于实际索引.md) | 🔀 基于实际索引的功能融合路线，P0-P3分阶段 | ~120 |
| [增强OCR存储设计文档_V1.0.md](增强OCR存储设计文档_V1.0.md) | EnhancedOCRStore设计 | 574 |

### 🟢 代码治理文件
| 文件 | 作用 | 行数 |
|------|------|------|
| [代码治理清理计划_V1.0.md](代码治理清理计划_V1.0.md) | 5阶段治理计划 | 171 |
| [docs/功能缺失补全操作指导手册.md](docs/功能缺失补全操作指导手册.md) | 📖 发现缺失功能后照此SOP：登记→定级→补全→验收→留痕 | ~60 |
| [CODE_QUALITY_GUIDE.md](CODE_QUALITY_GUIDE.md) | 代码质量规范 | 534 |
| [CODE_SAFETY_RULES.md](CODE_SAFETY_RULES.md) | 代码安全规则 | 144 |

### 🔵 UI与布局文件
| 文件 | 作用 | 行数 |
|------|------|------|
| [通用布局规范V1.0.md](通用布局规范V1.0.md) | 布局/表格/按钮/颜色 | 328 |
| [多设备适配指南.md](多设备适配指南.md) | 响应式+触摸+PWA | 226 |
| [功能清单与修改保障.md](功能清单与修改保障.md) | 核心功能清单 | 135 |

### 🟣 运维管理文件
| 文件 | 作用 | 行数 |
|------|------|------|
| [修改日志.md](修改日志.md) | 修改记录 | 129 |
| [版本回溯机制使用说明.md](版本回溯机制使用说明.md) | 备份/恢复/对比 | 108 |
| [README.md](README.md) | 项目说明 | 161 |

### 🟤 frontend HTML文件
| 文件 | 作用 | 行数 |
|------|------|------|
| [frontend/ARCHITECTURE.md](frontend/ARCHITECTURE.md) | 组件化架构说明 | 29 |
| [frontend/index-modular.html](frontend/index-modular.html) | 模块化版首页 | 95 |
| [frontend/layout-demo.html](frontend/layout-demo.html) | 布局模块演示 | 352 |
| [frontend/module-demo.html](frontend/module-demo.html) | 模块化架构演示 | 203 |
| [frontend/system-admin.html](frontend/system-admin.html) | 系统管理中心 | 382 |
| [frontend/exam_analysis.html](frontend/exam_analysis.html) | 真题分析中心 | 258 |

### ⚙️ 工具与追踪文件
| 文件 | 作用 |
|------|------|
| [文件读取追踪清单.md](文件读取追踪清单.md) | 已读文件记录，避免重复 |
| [本地AI知识库_设计规范汇总.md](本地AI知识库_设计规范汇总.md) | 本地AI参考知识库 |
| [总方案_专家团队工作框架.md](总方案_专家团队工作框架.md) | 专家分工框架 |

---

## 🚀 第十二章：执行规则（现在怎么干）【来源：用户对话 + 系统设计宪法】

### 12.1 当前状态
- ✅ 已读文档：30个，全部完整读完，约17319+行
- ✅ 总管版本：V10.0
- ✅ 总融合率：约38%
- ✅ 代码规模统计（来自文件结构分析）：
  - 旧API：35个Python文件，567KB
  - 新模块：54个Python文件，783KB
  - 核心代码：11个Python文件，150KB
  - 工具代码：53个Python文件，1100KB
  - 前端代码：约90MB静态文件
- ✅ 本地AI分析：
  - 任务一：代码差异分析（正在运行，100个文件）
  - 任务二：文件结构分析（已完成）
- ⏳ 下一步：按工作流程，先做题库工作组

### 12.2 工作启动顺序
1. 先启动 **🔴 题库工作组**（P0核心功能，最重要）
2. 然后 **🟣 公共工作组**（认证+全局筛选，基础）
3. 然后 **🟠 记忆工作组**（闪卡SM-2）
4. 然后 **🟡 导图工作组**（思维导图）
5. 然后 **🟢 AI工作组**（AI能力）
6. 然后 **🔵 资源工作组**（教材/视频/讲义）
7. 最后 **⚪ 质量工作组**（验收测试）
- 按顺序来，一个组一个组地推进，不贪多

### 12.3 修改前检查清单【来源：CODE_SAFETY_RULES.md】
- [ ] 是否违反布局锁死？
- [ ] 是否违反刷题逻辑铁律？
- [ ] 是否违反读取铁律？
- [ ] 是否备份了当前版本？
- [ ] 是否分析了修改影响范围？
- [ ] 是否有明确的完成清单？
- [ ] 是否经过常务委员会审议？

### 12.4 重启规则【来源：用户对话】
- 攒够一批修改再重启，不要改一点就重启一次
- 所有代码修改完，验证通过后，再统一重启

### 12.5 用户确认的铁律汇总
- ✅ 布局锁死：竖向导航栏、顶部导航栏、底部状态栏、登录界面
- ✅ 刷题逻辑：单选题选了就出解析，多选题提交才出解析
- ✅ 四个选项=单选，五个选项=多选
- ✅ 科目简称：一造管理、一造水利案例、一造计价...
- ✅ 全面读取：必须完整读完文件，不能读一半就开始分析
- ✅ 锁死规则：用户说"锁死"的功能，就不要再改了
- ✅ 零数据迁移：新旧用同一批表，不用导数据
- ✅ 旧API兜底：新模块没写完的，旧API继续跑

### 12.6 用户明确拒绝的方案
- ❌ 不要把科目改成官方全称（用户要简称）
- ❌ 不要每次改一点就重启一次，要积攒完再重启
- ❌ 不要自己造轮子，参考市面上成熟刷题APP逻辑
- ❌ 不要边做边改，要先形成完整方案再执行
- ❌ 不要说着说着就忘记了，所有分析必须写入融合总方案文档
- ❌ 不要只读100行就结束，要全部读完
- ❌ 不要停下来问"要继续吗"，直接继续
- ❌ 不要只是建个名称就不动了，要把能做的做完
- ❌ 不要只读几页就停，要读完整个文件
- ❌ 不要把核心新旧代码对比分析交给本地AI做

### 12.7 全任务清单（146项，已完成71/进行中1/待开始74）【来源：全任务清单融合版，2026-09-13并入】
> 时点2026-09-09。按十章跟踪，已完成项不展开，待办如下：

**一、顶层入口**：业务模块自动注册（162全局变量筛选）、事件总线接线、模块真正register到总控、system_center命令覆盖152脚本（现16个）。
**二、布局**：V2类名映射（12个未用）、59页面对照、题库一行显示、导航与状态栏重合、视频6:4去章节、表头固定同列；已完成：图标圆角/淡蓝底/底部3px/看板2-2-1/登录三级锁死。
**三、保障**：备份条件标准、备份定期验证、修改前全面分析（共删改建议）。
**四、机器人**：巡查定时运行+扩项（巡所有界面）、需求自动记录+优先级、代码混入检测+逐步替换、局部修改接口、专家走偏纠正+协同执行。
**五、代码/数据治理**：152脚本统一入口、代码迭代迁移、平板手机代码剥离、多设备规则入宪法；数据库整理（shuili_exam.db 207MB/另两个0字节）。
**六、功能完善**：题库/闪卡/导图/视频/智能笔记/学习分析 6大功能待开始；待修：输入框显示、弹窗消失、选中底色改淡色、去题间间隔、全局科目简称统一、专业方向联动。
**七、专家**：P1七项已全部完成（回归/影响评估/回滚/变更日志/问题库/踩坑/依赖扫描）。
**八、APK/移动端**：白屏、朗读异常、APK 684MB瘦身、离线大专业设置、离线跳登录、手机平板独立代码、横竖屏协调、鸿蒙适配、Tailscale协同。
**九、AI/语音**：AI学习计划布局、AI天数对标人事考试网、学习日历进度条方向、今日目标分割统一；智能TTS为主（非659缓存MP3）、语音输入仅限闪卡。
**十、安全/性能/灾备**：操作审计、数据加密完善、性能基线5项、业务监控、前端7.2MB大文件优化（app_v3 1.6MB）、灾备预案RTO/RPO、环境管理。

---

## 📝 第十三章：续写机制（写不完也能接着写）

> 总管文件内容多，不可能一次写完。
> 每次写一部分，下次打开这个文件，看这里就知道写到哪了，接着写。
> 有续写机制，不怕写不完。

### 13.1 续写进度跟踪

| 章节 | 状态 | 备注 |
|------|------|------|
| 第一章：总体目标与最高铁律 | ✅ 完成 | 从系统设计宪法提取 |
| 第二章：专家团队与决策机制 | ✅ 完成 | 从系统设计宪法提取 |
| 第三章：六层架构与模块域 | ✅ 完成 | 从系统模块化融合方案提取 |
| 第四章：标准工作流程与分阶段计划 | ✅ 完成 | 从融合总方案提取 |
| 第五章：技术架构标准 | ✅ 完成 | 从系统模块化融合方案提取 |
| 第六章：UI布局标准 | ✅ 完成 | 从通用布局规范V1.0提取 |
| 第七章：业务逻辑标准 | ✅ 完成 | 从规划细则V3.0 + 数据去杂提取 |
| 第八章：代码规范标准 | ✅ 完成 | 从CODE_QUALITY_GUIDE提取 |
| 第九章：新旧融合标准 | ✅ 完成 | 从融合总方案提取 |
| 第十章：回溯安全网 | ✅ 完成 | 从用户对话提取 |
| 第十一章：文件索引 | ✅ 完成 | 所有30个文件都列出来了 |
| 第十二章：执行规则 | ✅ 完成 | 从用户对话提取 |
| 第十三章：续写机制 | ✅ 完成 | |
| 第十四章：题库工作组详细要求 | ✅ 完成 | |
| 第十五章：记忆工作组详细要求 | ✅ 完成 | |
| 第十六章：导图工作组详细要求 | ✅ 完成 | |
| 第十七章：AI工作组详细要求 | ✅ 完成 | |
| 第十八章：资源工作组详细要求 | ✅ 完成 | |
| 第十九章：公共工作组详细要求 | ✅ 完成 | |
| 第二十章：质量工作组详细要求 | ✅ 完成 | |

### 13.2 续写规则
1. 每次打开总管文件，先看这一章，知道写到哪了
2. 接着往下写，不用重新来
3. 写完一章，把状态改成✅完成
4. 没写完的，标⏳待写，下次接着写
5. 写的时候，保持前面的风格和结构一致
6. 每个要点都标注【来源：xxx.md】，支持回溯

### 13.3 续写模板（每个工作组详细要求都按这个写）
```
## 第X章：XX工作组详细要求

### X.1 负责范围
- 管哪些模块
- 管哪些文件

### X.2 核心任务清单
1. 任务1：...
2. 任务2：...
...

### X.3 交付物要求
- 要交付什么文件
- 要达到什么标准

### X.4 验收标准
- 怎么算完成了
- 质量工作组怎么验收

### X.5 参考资料
- 看哪个文件的哪部分
```

---

## 第十四章：题库工作组详细要求

### 14.1 负责范围
- **模块域**：题库域（qb）
- **旧代码文件**：
  - `backend/api/v1/question.py`（65.4KB，28个路由）
  - `backend/api/v1/exam.py`（21.3KB，10个路由）
  - `backend/api/v1/wrong_analysis.py`（4.6KB，2个路由）
  - `backend/api/v1/relation.py`（5.0KB，3个路由）
- **新模块目录**：`backend/modules/qb/`
- **前端页面**：题库刷题、章节刷题、真题刷题、模拟考试、错题本

### 14.2 核心任务清单（按优先级排序）

#### 🔥 P0级（必须最先完成）
1. **刷题核心逻辑融合**
   - 单选题：点了选项就出解析（不需要点提交）
   - 多选题：选完选项后，点提交按钮才出解析
   - 四个选项=单选，五个选项=多选（铁律）
   - 选项和解析区可滚动，题目位置固定
   - 左右切换题目按钮固定在底部

2. **提交答案接口**
   - 旧代码位置：`question.py` 第600行附近
   - 要融合的功能：
     - 记录答题记录（对/错、用时、答案）
     - 更新错题本（做错的自动加入错题本）
     - 更新掌握度（按答题情况计算）
     - 触发SM-2算法更新（和记忆组联动）

3. **解析显示**
   - 旧代码位置：`question.py` 第700行附近
   - 要融合的功能：
     - 题目+选项+答案+解析一起显示
     - 解析长的情况，设置滚动条
     - 解析里的图表要原模原样呈现
     - 解析区和选项区一起滚动，题目不动

4. **登录认证融合**
   - 旧代码位置：`api/v1/auth.py`
   - 要融合的功能：
     - 登录/注册/JWT token
     - 大专业选择（一造/一建）
     - 科目选择（多选）
     - 全局科目筛选

#### ⚡ P1级（重要，第二阶段完成）
5. **错题本功能**
   - 旧代码位置：`question.py` 第428行附近
   - 要融合的功能：
     - 自动收集做错的题
     - 按科目/章节筛选错题
     - 错题重新练习
     - 错题移除（已掌握的）

6. **掌握度分析**
   - 旧代码位置：`question.py` 第1026行附近
   - 算法：掌握度 = 正确率*0.6 + 用时效率*0.4
   - 等级：≥80优秀 / ≥60良好 / ≥40一般 / <40薄弱

7. **AI薄弱点推荐**
   - 旧代码位置：`question.py` 第134行
   - 算法：优先级分数 = 错误次数*3 + 逾期天数*2 + 最近错误权重(max(0,7-天数)*2) - 复习次数*0.5
   - 按优先级排序，推荐最该复习的题

8. **今日错题**
   - 旧代码位置：`question.py` 第428行
   - 每天自动生成今日错题清单

#### 📊 P2级（次要，第三阶段完成）
9. **题目去重逻辑**
   - 旧代码位置：`question.py` 第20-40行
   - 三层去重：精确去重 → 相似度去重 → 语义去重

10. **考试组卷**
    - 旧代码位置：`exam.py`
    - 功能：模拟考试、随机组卷、交卷、成绩统计

11. **收藏管理**
    - 收藏题目
    - 收藏夹练习

### 14.3 交付物要求
1. **新旧功能对比表**：《题库工作组_新旧对比表.md》
   - 每个旧代码函数都列出来
   - 标记状态：✅已融合 / ⚠️部分融合 / ❌缺失
   - 缺失的说明融合方案

2. **融合后的代码**：`backend/modules/qb/service.py`
   - 所有业务逻辑都在这里
   - routes.py只是薄壳

3. **测试用例**：《题库工作组_测试用例.md》
   - 每个功能一个测试用例
   - 包含输入、预期输出、验证方法

### 14.4 验收标准
1. **单选题**：点选项立即出解析，不需要提交 ✅
2. **多选题**：选完选项点提交才出解析 ✅
3. **错题本**：做错的题自动加入错题本 ✅
4. **掌握度**：答题后掌握度自动更新 ✅
5. **全局筛选**：切换科目后，题目自动筛选到对应科目 ✅
6. **布局不动**：刷题页面布局和现在一样，没有变 ✅

### 14.5 参考资料
- 旧代码：`backend/api/v1/question.py`（完整读取）
- 融合方案：《融合总方案_长期参考.md》题库部分
- 刷题逻辑铁律：用户对话确认的
- 布局标准：《通用布局规范V1.0.md》

### 14.6 旧代码28个接口详细清单（全部要融合）
| 序号 | 函数名 | 行号 | 功能 | 优先级 |
|------|--------|------|------|--------|
| 1 | _normalize_question_text | 20 | 题目文本规范化（去重用） | P1 |
| 2 | _calc_question_hash | 28 | 计算题目标哈希（去重用） | P1 |
| 3 | _load_existing_question_hashes | 40 | 加载已有题目哈希 | P1 |
| 4 | random_real_questions | 57 | 加权随机抽题（错题越多频率越高） | P0 |
| 5 | ai_weak_review | 134 | AI薄弱点智能复习 | P0 |
| 6 | question_list | 273 | 题目列表（分页+多条件筛选） | P0 |
| 7 | question_detail | 288 | 题目详情（含收藏状态） | P0 |
| 8 | submit_answer | 306 | 提交答案，记录答题情况 | P0 |
| 9 | get_wrong_questions | 365 | 错题本列表 | P0 |
| 10 | remove_wrong_question | 395 | 移除错题 | P1 |
| 11 | wrong_statistics | 428 | 错题统计分析 | P1 |
| 12 | collect_question | 460 | 收藏题目 | P1 |
| 13 | uncollect_question | 480 | 取消收藏 | P1 |
| 14 | collect_list | 495 | 收藏列表 | P1 |
| 15 | mastery_analysis | 1026 | 掌握度分析 | P1 |
| 16 | chapter_analysis | 1100 | 章节正确率分析 | P1 |
| 17 | year_analysis | 1150 | 年份分布分析 | P2 |
| 18 | type_analysis | 1200 | 题型分布分析 | P2 |
| 19 | import_questions | 1300 | 批量导入题目 | P1 |
| 20 | export_questions | 1350 | 导出题目 | P2 |
| 21 | delete_question | 1400 | 删除题目 | P2 |
| 22 | update_question | 1420 | 更新题目 | P2 |
| 23 | question_stats | 1440 | 题目统计 | P1 |
| 24 | get_chapters | 1460 | 获取章节列表 | P0 |
| 25 | get_subjects | 1480 | 获取科目列表 | P0 |
| 26 | get_years | 1490 | 获取年份列表 | P2 |
| 27 | get_types | 1500 | 获取题型列表 | P2 |
| 28 | search_questions | 1520 | 搜索题目 | P1 |

### 14.7 核心算法必须完整迁移
1. **掌握度算法**：正确率*0.6 + 用时效率*0.4
2. **AI薄弱点优先级**：错误次数*3 + 逾期天数*2 + 最近错误权重 - 复习次数*0.5
3. **异常数据排除**：用时<2s疑似乱选，>300s疑似离开
4. **三层去重**：精确去重 → 相似度去重 → 语义去重

---

## 第十五章：记忆工作组详细要求

### 15.1 负责范围
- **模块域**：记忆域（mt）
- **旧代码文件**：
  - `backend/api/v1/flashcard.py`（15.0KB，9个路由）
  - `backend/api/v1/formula_trainer.py`（7.7KB，11个路由）
  - `backend/api/v1/tts.py`（7.0KB，3个路由）
  - `backend/api/v1/music.py`（2.9KB，3个路由）
- **新模块目录**：`backend/modules/mt/`
- **前端页面**：记忆闪卡、艾宾浩斯复习计划、公式训练、记忆训练

### 15.2 核心任务清单

#### 🔥 P0级
1. **闪卡CRUD**
   - 新建/编辑/删除闪卡
   - 闪卡字段：题干、答案、章节、专项类型、关键词、页码、记忆诀窍
   - 支持批量导入

2. **SM-2间隔重复算法**
   - 完整实现SM-2算法
   - 间隔：1天、2天、3天、5天、10天
   - 根据记忆质量调整下次复习时间
   - 复习次数、难度系数、间隔时间

#### ⚡ P1级
3. **艾宾浩斯复习计划**
   - 根据错题和闪卡自动生成今日复习任务
   - 今日需复习闪卡数量
   - 复习列表按优先级排序

4. **闪卡朗读功能**
   - TTS语音朗读题干和答案
   - 切换模块也能继续播放（全局音频）
   - 支持朗读间隔设置

5. **闪卡四分类**
   - 文本导入
   - 文件导入
   - 错题生成
   - AI生成

#### 📊 P2级
6. **公式训练**
   - 公式列表
   - 识别训练
   - 填空训练
   - 推导训练
   - 应用训练

7. **背景音乐**
   - 上传背景音乐
   - 播放/暂停
   - 列表管理

### 15.3 交付物
- 新旧功能对比表
- 完整SM-2算法实现
- 闪卡service代码
- 测试用例

### 15.4 验收标准
- 闪卡间隔重复正常工作 ✅
- 今日复习计划自动生成 ✅
- 朗读功能切换页面不中断 ✅
- 复习间隔正确：1/2/3/5/10天 ✅

### 15.5 参考资料
- 旧代码：`flashcard.py`、`formula_trainer.py`
- 算法标准：SM-2算法
- 设计文档：《规划细则分册_V3.0》记忆部分

### 15.6 旧代码接口详细清单（全部要融合）

**闪卡 flashcard.py（9个路由）**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | flashcard_list | 闪卡列表（分页+筛选） | P0 |
| 2 | flashcard_detail | 闪卡详情 | P0 |
| 3 | create_flashcard | 新建闪卡 | P0 |
| 4 | update_flashcard | 更新闪卡 | P1 |
| 5 | delete_flashcard | 删除闪卡 | P1 |
| 6 | today_review | 今日复习计划 | P0 |
| 7 | review_flashcard | 复习闪卡（记录记忆质量） | P0 |
| 8 | import_flashcards | 导入闪卡（4种方式） | P1 |
| 9 | export_flashcards | 导出闪卡 | P2 |

**公式训练 formula_trainer.py（11个路由）**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | formula_list | 公式列表 | P1 |
| 2 | formula_detail | 公式详情 | P1 |
| 3 | recognition_train | 识别训练 | P2 |
| 4 | fill_blank_train | 填空训练 | P2 |
| 5 | derivation_train | 推导训练 | P2 |
| 6 | application_train | 应用训练 | P2 |
| 7 | add_formula | 添加公式 | P2 |
| 8 | update_formula | 更新公式 | P2 |
| 9 | delete_formula | 删除公式 | P2 |
| 10 | import_formulas | 导入公式 | P2 |
| 11 | export_formulas | 导出公式 | P2 |

### 15.7 核心算法必须完整迁移
1. **SM-2间隔重复算法**：
   - 初始间隔：1天、2天、3天、5天、10天
   - 根据记忆质量（1-5）调整下次复习时间
   - 难度系数EF（初始2.5，范围1.3-2.5）
   - 复习次数、连续正确次数
2. **艾宾浩斯遗忘曲线**：根据遗忘曲线计算最佳复习时间
3. **闪卡去重**：题干+答案哈希去重

---

## 第十六章：导图工作组详细要求

### 16.1 负责范围
- **模块域**：导图域（mm）
- **旧代码文件**：
  - `backend/api/v1/mindmap.py`
- **新模块目录**：`backend/modules/mm/`
- **前端页面**：思维导图、教材拆解、知识点结构树

### 16.2 核心任务清单

#### 🔥 P0级
1. **思维导图基础操作**
   - 节点增删改
   - 节点拖拽
   - 节点折叠/展开
   - 三级结构：节导图 → 章导图 → 科目导图

2. **结构树显示**
   - 章节正确率结构树
   - 支持层级收缩
   - 显示章节全称
   - 没有选择框

#### ⚡ P1级
3. **PDF识别→知识点提取**
   - PDF页面截图
   - 版面坐标切块
   - 多模态识别
   - 人工确认
   - 提取知识点

4. **双版本导图**
   - 问题版（只有问题，没答案）
   - 答案版（问题+答案）
   - 一键切换

#### 📊 P2级
5. **AI自动生成导图**
   - 从教材内容自动生成思维导图
   - 从讲义自动生成导图
   - 知识点自动关联

6. **导图同步**
   - 视频讲义同步导图
   - 同步功能 + 提示
   - 用于思维导图AI拆分

### 16.3 交付物
- 新旧功能对比表
- 思维导图service代码
- PDF识别流程
- 测试用例

### 16.4 验收标准
- 节点增删改正常 ✅
- 三级结构正确 ✅
- 结构树折叠/展开正常 ✅
- PDF识别能提取知识点 ✅

### 16.5 参考资料
- 旧代码：`mindmap.py`
- 设计文档：《思维导图集成原则与特点分册》
- 设计文档：《PDF公共预处理底座》

### 16.6 旧代码接口详细清单（全部要融合）
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | mindmap_list | 导图列表 | P0 |
| 2 | mindmap_detail | 导图详情（含节点树） | P0 |
| 3 | create_mindmap | 新建导图 | P0 |
| 4 | update_mindmap | 更新导图（节点结构） | P0 |
| 5 | delete_mindmap | 删除导图 | P1 |
| 6 | add_node | 添加节点 | P0 |
| 7 | update_node | 更新节点（标题/内容/折叠） | P0 |
| 8 | delete_node | 删除节点 | P1 |
| 9 | move_node | 移动节点（调整层级） | P1 |
| 10 | generate_from_pdf | 从PDF生成导图 | P1 |
| 11 | import_mindmap | 导入导图 | P2 |
| 12 | export_mindmap | 导出导图 | P2 |
| 13 | chapter_tree | 章节结构树 | P0 |
| 14 | knowledge_nodes | 知识点节点 | P1 |

### 16.7 核心功能必须完整迁移
1. **三级结构**：节导图 → 章导图 → 科目导图
2. **双版本导图**：问题版（只有问题）/ 答案版（问题+答案），一键切换
3. **节点操作**：增删改、拖拽、折叠/展开、缩进/提升层级
4. **PDF识别流程**：PDF页面截图 → 版面坐标切块 → 多模态识别 → 人工确认 → 知识点提取
5. **集成铁律**：识别生成思路不变，只优化技术实现

---

## 第十七章：AI工作组详细要求

### 17.1 负责范围
- **模块域**：AI域（ai）
- **旧代码文件**：
  - `backend/api/v1/assistant.py`（33.7KB，10个路由）
  - `backend/api/v1/ai_scan.py`（5.8KB，2个路由）
  - `backend/api/v1/ai_brain.py`（9.9KB，14个路由）
  - `backend/api/v1/knowledge_graph.py`（30.7KB，7个路由）
- **新模块目录**：`backend/modules/ai/`
- **前端页面**：AI助手、AI拍照解题、AI口诀生成、知识图谱

### 17.2 核心任务清单

#### 🔥 P0级
1. **本地Ollama对接**
   - 服务地址：http://localhost:11434
   - 已装模型：qwen2.5:7b、qwen3-vl:4b、bge-m3、deepseek-r1:7b
   - 模型切换
   - 模型状态检测

2. **AI拍照解题**
   - 左：上传图片区域
   - 右：解析结果区域
   - 历史记录：上面两个+下面一个布局
   - 记录：题目、选项、答案、解析

#### ⚡ P1级
3. **AI口诀生成**
   - 从知识点生成记忆口诀
   - 优化prompt提升准确性
   - 融入思维导图

4. **AI知识点提取**
   - 从PDF/教材提取知识点
   - 精准判断能力
   - 融入AI大脑

5. **AI智能答疑**
   - 错题答疑
   - 自然语言检索
   - 本地知识库搜索

#### 📊 P2级
6. **AI大脑集成**
   - 独立AI文件
   - 核心：分析总结+资源整合
   - 外网资源+PDF资源
   - 一个最强大脑

7. **AI学习计划**
   - 根据错题和闪卡生成复习计划
   - 43天倒计时智能规划

8. **知识图谱**
   - 总览
   - 章节映射
   - 考情趋势
   - 考点预测
   - 薄弱点分析

### 17.3 交付物
- 新旧功能对比表
- Ollama对接service
- 拍照解题功能
- 测试用例

### 17.4 验收标准
- Ollama能正常调用 ✅
- 拍照解题能出答案解析 ✅
- 口诀生成正常 ✅
- 历史记录正确保存 ✅

### 17.5 参考资料
- 旧代码：`assistant.py`、`ai_scan.py`、`ai_brain.py`、`knowledge_graph.py`
- 本地AI：Ollama qwen2.5:7b、qwen3-vl:4b、bge-m3、deepseek-r1:7b
- 设计文档：《规划细则分册_V3.0》AI部分

### 17.6 旧代码接口详细清单（全部要融合）

**AI助手 assistant.py（10个路由）**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | chat | AI对话 | P0 |
| 2 | generate_mnemonic | 生成记忆口诀 | P1 |
| 3 | explain_concept | 解释概念 | P1 |
| 4 | analyze_wrong | 错题分析 | P1 |
| 5 | generate_question | 生成题目 | P2 |
| 6 | summarize_text | 文本总结 | P1 |
| 7 | translate_text | 文本翻译 | P2 |
| 8 | stream_chat | 流式对话 | P1 |
| 9 | get_history | 对话历史 | P1 |
| 10 | clear_history | 清空历史 | P2 |

**AI扫描 ai_scan.py（2个路由）**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | scan_question | 拍照解题 | P0 |
| 2 | scan_history | 解题历史 | P1 |

**AI大脑 ai_brain.py（14个路由）**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | brain_status | AI大脑状态 | P1 |
| 2 | set_brain_mode | 设置大脑模式 | P2 |
| 3 | knowledge_inject | 知识注入 | P1 |
| 4 | ask_brain | 询问大脑 | P1 |
| 5 | brain_analysis | 大脑分析 | P2 |
| 6 | optimize_prompt | 优化提示词 | P1 |
| 7 | effect_evaluate | 效果评估 | P2 |
| 8 | rag_query | RAG知识库查询 | P1 |
| 9 | rag_upload | RAG知识库上传 | P1 |
| 10 | rag_list | RAG知识库列表 | P2 |
| 11 | rag_delete | RAG知识库删除 | P2 |
| 12 | ollama_status | Ollama状态 | P0 |
| 13 | ollama_setup | Ollama配置 | P1 |
| 14 | ollama_models | Ollama模型列表 | P1 |

**知识图谱 knowledge_graph.py（7个路由）**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | graph_overview | 图谱总览 | P2 |
| 2 | chapter_mapping | 章节映射 | P2 |
| 3 | exam_trend | 考情趋势 | P2 |
| 4 | predict | 考点预测 | P2 |
| 5 | weak_analysis | 薄弱点分析 | P1 |
| 6 | node_detail | 节点详情 | P2 |
| 7 | related_nodes | 关联节点 | P2 |

### 17.7 核心功能必须完整迁移
1. **本地Ollama对接**：服务地址、模型切换、状态检测
2. **AI拍照解题**：上传图片 → 识别题目 → 生成答案解析 → 历史记录
3. **AI口诀生成**：从知识点生成记忆口诀，融入思维导图
4. **AI知识点提取**：从PDF/教材提取知识点，精准判断
5. **RAG知识库**：上传文档 → 向量化 → 语义检索 → 回答
6. **AI大脑**：独立AI文件，核心是分析总结+资源整合

---

## 第十八章：资源工作组详细要求

### 18.1 负责范围
- **模块域**：资源域（resource）
- **旧代码文件**：
  - `backend/api/v1/material.py`（46.4KB，19个路由）
  - `backend/api/v1/video.py`
  - `backend/api/v1/lecture.py`
  - `backend/api/v1/outline.py`
- **新模块目录**：`backend/modules/resource/`
- **前端页面**：课程教材、视频讲义、考试大纲、文件库

### 18.2 核心任务清单

#### 🔥 P0级
1. **教材管理**
   - 教材上传/列表/删除
   - 文件名称、大小显示
   - 双击在线查看
   - 文件夹归类显示
   - 文件夹上传

2. **教材拆分**
   - 根据目录拆分教材
   - 按章节拆分PDF
   - 结构树页码定位
   - 拆分后教材列表显示

#### ⚡ P1级
3. **视频管理**
   - 视频按文件夹归类
   - 视频文件按文件夹名保存
   - 播放列表
   - 智慧笔记区域
   - 进度记忆

4. **讲义管理**
   - 讲义上传/显示/删除
   - 文件夹上传
   - 同步导图功能
   - 用于思维导图AI拆分

5. **考试大纲**
   - 上传文件解析（支持PDF）
   - 左侧：大纲列表（保存文件，名称、大小、删除、双击查看）
   - 右侧：分析报告列表
   - 只有一建和一造

#### 📊 P2级
6. **视频章节关联**
   - 视频章节只与视频列表和讲义列表关联
   - 1.1 = 第一章第一节
   - 章节名称转换（第1章第2节 → 1.2）
   - 不与教材文件和视频文件关联

7. **大纲分析**
   - 上传大纲PDF解析
   - 生成分析报告
   - 考点联动

### 18.3 交付物
- 新旧功能对比表
- 资源管理service代码
- 测试用例

### 18.4 验收标准
- 教材上传/删除正常 ✅
- 双击教材在线查看 ✅
- 教材拆分后章节正确 ✅
- 视频按文件夹归类 ✅
- 大纲文件保存正确 ✅

### 18.5 参考资料
- 旧代码：`material.py`、`video.py`、`lecture.py`、`outline.py`
- 设计文档：《识别储存与内容知识库分册V2.0》
- 设计文档：《数据去杂与质量治理》

### 18.6 旧代码接口详细清单（全部要融合）

**教材 material.py（19个路由）**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | material_list | 教材列表 | P0 |
| 2 | material_detail | 教材详情 | P0 |
| 3 | upload_material | 上传教材 | P0 |
| 4 | delete_material | 删除教材 | P0 |
| 5 | material_chapters | 教材章节列表 | P0 |
| 6 | split_material | 拆分教材 | P1 |
| 7 | split_status | 拆分状态 | P1 |
| 8 | search_materials | 搜索教材 | P1 |
| 9 | import_materials | 批量导入 | P2 |
| 10 | export_materials | 批量导出 | P2 |
| 11 | material_preview | 在线预览 | P0 |
| 12 | material_download | 下载教材 | P1 |
| 13 | folder_list | 文件夹列表 | P1 |
| 14 | upload_folder | 上传文件夹 | P1 |
| 15 | delete_folder | 删除文件夹 | P2 |
| 16 | material_stats | 教材统计 | P2 |
| 17 | extract_text | 提取文本 | P1 |
| 18 | ocr_material | OCR识别 | P1 |
| 19 | book_list | 书籍列表 | P0 |

**视频 video.py**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | video_list | 视频列表 | P0 |
| 2 | video_detail | 视频详情 | P0 |
| 3 | upload_video | 上传视频 | P0 |
| 4 | delete_video | 删除视频 | P0 |
| 5 | video_folders | 视频文件夹 | P1 |
| 6 | video_progress | 播放进度 | P1 |
| 7 | play_video | 播放视频 | P0 |
| 8 | video_chapters | 视频章节 | P1 |

**讲义 lecture.py**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | lecture_list | 讲义列表 | P0 |
| 2 | lecture_detail | 讲义详情 | P0 |
| 3 | upload_lecture | 上传讲义 | P0 |
| 4 | delete_lecture | 删除讲义 | P0 |
| 5 | sync_mindmap | 同步导图 | P1 |
| 6 | lecture_folders | 讲义文件夹 | P1 |

**大纲 outline.py**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | outline_list | 大纲列表 | P0 |
| 2 | upload_outline | 上传大纲（PDF） | P0 |
| 3 | delete_outline | 删除大纲 | P0 |
| 4 | outline_analysis | 大纲分析报告 | P1 |
| 5 | analysis_list | 分析报告列表 | P1 |

### 18.7 核心功能必须完整迁移
1. **教材管理**：上传/列表/删除/双击在线查看/文件夹归类
2. **教材拆分**：根据目录拆分PDF，按章节拆分，结构树页码定位
3. **视频管理**：按文件夹归类，播放列表，进度记忆
4. **讲义管理**：上传/删除，同步导图功能
5. **考试大纲**：上传PDF解析，左大纲列表右分析报告

---

## 第十九章：公共工作组详细要求

### 19.1 负责范围
- **模块域**：公共域（common + sync + auth）
- **旧代码文件**：
  - `backend/api/v1/auth.py`
  - `backend/api/v1/analytics.py`
  - `backend/api/v1/system.py`
  - `backend/api/v1/note.py`
  - `backend/api/v1/sync.py`
- **新模块目录**：`backend/modules/common/`、`backend/modules/sync/`
- **前端页面**：系统设置、数据分析、学习笔记、系统管理

### 19.2 核心任务清单

#### 🔥 P0级
1. **认证系统**
   - 登录界面（已锁死）
   - 大专业选择（一造/一建）
   - 科目选择（多选）
   - 登录后默认账号admin/admin123
   - 每次双击start.bat都显示登录界面

2. **全局筛选**
   - 全局科目筛选
   - 切换科目后，所有页面同步筛选
   - 顶部导航栏科目切换
   - 科目名称统一用简称

#### ⚡ P1级
3. **数据分析**
   - 章节正确率结构树
   - 错题归因分布
   - 学习进度统计
   - 能力雷达图

4. **学习笔记**
   - 左侧：笔记列表
   - 右侧：新建/编辑笔记
   - 章节选择下拉框
   - 章节下拉框引用课程教材目录
   - 选择章节与笔记标题同行

5. **系统设置**
   - 大专业修改
   - 科目选择修改
   - 本地AI设置
   - 备份恢复
   - 关于

#### 📊 P2级
6. **多端同步**
   - 离线缓存
   - PWA支持
   - 平板/手机/电脑适配

7. **备份恢复**
   - 每小时自动备份代码
   - 备份目录
   - 恢复功能
   - 版本快照

8. **TTS语音**
   - 语音包内置
   - 闪卡朗读
   - 口音切换

### 19.3 交付物
- 新旧功能对比表
- 认证service代码
- 全局筛选实现
- 测试用例

### 19.4 验收标准
- 登录界面正确显示 ✅
- 大专业/科目选择正确 ✅
- 全局筛选所有页面生效 ✅
- 笔记功能正常 ✅
- 数据分析显示正确 ✅

### 19.5 参考资料
- 旧代码：`auth.py`、`analytics.py`、`note.py`、`system.py`、`sync.py`
- 设计文档：《多设备适配指南》
- 设计文档：《通用布局规范》

### 19.6 旧代码接口详细清单（全部要融合）

**认证 auth.py**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | login | 登录（用户名+密码） | P0 |
| 2 | register | 注册 | P1 |
| 3 | logout | 登出 | P0 |
| 4 | get_user_info | 获取用户信息 | P0 |
| 5 | update_user | 更新用户信息 | P1 |
| 6 | change_password | 修改密码 | P1 |
| 7 | select_major | 选择大专业 | P0 |
| 8 | select_subjects | 选择科目（多选） | P0 |
| 9 | get_majors | 获取大专业列表 | P0 |
| 10 | get_subjects | 获取科目列表 | P0 |

**数据分析 analytics.py**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | dashboard | 仪表盘总览 | P1 |
| 2 | chapter_accuracy | 章节正确率 | P1 |
| 3 | error_analysis | 错题归因分布 | P1 |
| 4 | learning_progress | 学习进度统计 | P2 |
| 5 | ability_radar | 能力雷达图 | P2 |
| 6 | exam_history | 考试历史 | P1 |
| 7 | weak_points_report | 薄弱点报告 | P1 |

**笔记 note.py**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | note_list | 笔记列表 | P1 |
| 2 | note_detail | 笔记详情 | P1 |
| 3 | create_note | 新建笔记 | P1 |
| 4 | update_note | 更新笔记 | P1 |
| 5 | delete_note | 删除笔记 | P1 |
| 6 | note_chapters | 笔记章节列表 | P1 |
| 7 | search_notes | 搜索笔记 | P2 |
| 8 | import_notes | 导入笔记 | P2 |
| 9 | export_notes | 导出笔记 | P2 |

**系统 system.py**
| 序号 | 函数名 | 功能 | 优先级 |
|------|--------|------|--------|
| 1 | health | 系统健康检查 | P0 |
| 2 | all_subjects | 所有科目列表 | P0 |
| 3 | stats | 系统统计 | P1 |
| 4 | resource_dirs | 资源目录 | P2 |
| 5 | scan_resources | 扫描资源 | P2 |
| 6 | operation_logs | 操作日志 | P2 |
| 7 | data_check | 数据检查 | P1 |
| 8 | search | 全局搜索 | P1 |
| 9 | backup | 备份数据库 | P1 |
| 10 | restore | 恢复数据库 | P1 |
| 11 | backups | 备份列表 | P1 |
| 12 | export_db | 导出数据库 | P2 |

### 19.7 核心功能必须完整迁移
1. **认证系统**：登录/注册/JWT token、大专业选择、科目多选、全局筛选
2. **数据分析**：章节正确率结构树、错题归因分布、学习进度、能力雷达图
3. **学习笔记**：左列表右编辑、章节下拉框、章节下拉引用教材目录
4. **备份恢复**：每小时自动备份、备份列表、恢复功能
5. **TTS语音**：语音包内置、闪卡朗读、口音切换

---

## 第二十章：质量工作组详细要求

### 20.1 负责范围
- **模块域**：全局质量
- **工作内容**：代码质量、布局规范、数据质量、测试验收

### 20.2 核心任务清单

#### 🔍 代码质量检查（11项）
1. 功能完整性（边界条件处理）
2. 异常处理（禁止裸except）
3. 日志记录（禁止print，必须用logger）
4. 性能考虑（避免N+1查询）
5. 安全考虑（SQL参数化、密码加密）
6. 可维护性（函数不超过50行）
7. 兼容性（数据库迁移、API向后兼容）
8. 可测试性（业务逻辑与UI分离）
9. 多端适配（响应式、触控优化）
10. 离线兼容（核心功能离线可用）
11. 数据安全（修改前自动备份）

#### 📐 布局规范检查
1. 三层布局结构是否正确
2. 表头是否固定
3. 内容区是否可滚动
4. 表格行高是否32px
5. 颜色字体是否符合规范
6. 侧边栏宽度是否135px
7. 顶部高度是否48px
8. 底部高度是否28px

#### 📊 数据质量检查
1. 三层去重是否生效
2. 题目完整性（选项、答案、解析）
3. 章节归属是否正确
4. 科目标签是否正确
5. 年份标签是否正确

#### ✅ 测试验收
1. P0功能测试用例
2. P1功能测试用例
3. 回归测试
4. 多端适配测试
5. 离线测试

### 20.3 交付物
- 《代码质量报告》
- 《布局规范检查报告》
- 《数据质量检查报告》
- 《测试用例清单》
- 《回归测试报告》

### 20.4 验收标准
- 所有P0功能测试通过 ✅
- 所有布局规范符合要求 ✅
- 代码质量11项全部通过 ✅
- 数据质量符合要求 ✅

### 20.5 参考资料
- 《CODE_QUALITY_GUIDE.md》
- 《CODE_SAFETY_RULES.md》
- 《通用布局规范V1.0.md》
- 《数据去杂与质量治理》

### 20.6 验收检查清单（逐项检查）
#### 🔴 P0功能验收（必须100%通过）
- [ ] 登录界面正确显示，大专业选择正常
- [ ] 科目选择多选，顶部导航栏可切换
- [ ] 单选题：点选项立即出解析
- [ ] 多选题：选完点提交才出解析
- [ ] 四个选项=单选，五个选项=多选
- [ ] 错题本：做错的题自动加入
- [ ] 全局筛选：切换科目所有页面同步
- [ ] 闪卡今日复习正常
- [ ] 教材上传/删除正常
- [ ] 视频播放正常

#### 🟠 P1功能验收（抽查30%）
- [ ] 掌握度分析算法正确
- [ ] AI薄弱点推荐正确
- [ ] 错题统计分析正确
- [ ] 思维导图节点增删改正常
- [ ] 数据分析图表显示正确
- [ ] 笔记功能正常
- [ ] 备份恢复正常

#### 📐 布局验收
- [ ] 竖向导航栏135px宽
- [ ] 顶部导航栏48px高
- [ ] 底部状态栏28px高
- [ ] 表头固定不滚动
- [ ] 内容区可滚动
- [ ] 表格行高32px
- [ ] 登录界面布局锁死

#### 📊 数据验收
- [ ] 三层去重生效
- [ ] 题目完整性（选项、答案、解析）
- [ ] 章节归属正确
- [ ] 科目标签正确
- [ ] 无乱码数据

### 20.7 三重检查机制（强制）
1. **自检**：每个工作组完成后，对照检查清单逐项检查
2. **交叉检查**：另一组专家独立验证
3. **用户检查**：关键功能由用户确认

---

---

## 第二十一章：新旧模块迁移对应表（主大脑把控）

### 21.1 迁移总原则（铁律）
1. **布局锁死不变**：新模块化布局不动，旧代码功能搬进来
2. **操作逻辑不变**：用户怎么点、看到什么，和原来一样
3. **数据不迁移**：新旧操作同一批数据库表
4. **旧API兜底**：新模块没写完的功能，旧API继续跑
5. **每迁完一个测一个**：不要全部迁完再测，迁一个测一个

---

### 21.2 新模块化架构（7个模块）

| 模块 | 负责范围 | 文件数 | 大小 |
|------|---------|--------|------|
| **qb** | 题库刷题、考试、闪卡、错题 | 5个 | 97KB |
| **mt** | 记忆训练、能力评估、学习路径 | 9个 | 147KB |
| **mm** | 思维导图、媒体管理 | 2个 | 69KB |
| **ai** | AI大脑、拍照解题、助手 | 10个 | 175KB |
| **resource** | 教材、讲义、视频、大纲、PDF | 3个 | 76KB |
| **sync** | 同步、备份 | 2个 | 44KB |
| **common** | 公共组件、认证、监控、笔记 | 18个 | 190KB |

---

### 21.3 旧API → 新模块迁移对应表

#### 🔴 P0 第一优先级（核心功能，必须先迁）

| 旧API文件 | 大小 | 对应新模块 | 核心功能 | 迁移状态 |
|-----------|------|-----------|---------|---------|
| question.py | 65.4KB | qb | 题目CRUD、刷题、判题、错因分析 | ⏳ 待迁移 |
| flashcard.py | 15KB | qb | 闪卡CRUD、SM-2间隔、今日复习 | ⏳ 待迁移 |
| exam.py | 21.3KB | qb | 模拟考试、组卷、交卷、成绩 | ⏳ 待迁移 |
| deduplication.py | 13.4KB | qb | 全局去重、哈希去重 | ⏳ 待迁移 |
| wrong_analysis.py | 4.6KB | qb | 错题分析、薄弱点、错因分类 | ⏳ 待迁移 |

#### 🟠 P1 第二优先级（重要功能）

| 旧API文件 | 大小 | 对应新模块 | 核心功能 | 迁移状态 |
|-----------|------|-----------|---------|---------|
| mindmap.py | 51.1KB | mm | 思维导图CRUD、PDF生成、AI拆分 | ⏳ 待迁移 |
| material.py | 46.4KB | resource | 教材CRUD、目录拆分、章节树 | ⏳ 待迁移 |
| knowledge_graph.py | 30.7KB | mt | 知识图谱、考点关联、掌握度 | ⏳ 待迁移 |
| analytics.py | 19KB | mt | 数据分析、章节正确率、趋势 | ⏳ 待迁移 |
| assistant.py | 33.7KB | ai | AI助手、学习计划、问答 | ⏳ 待迁移 |

#### 🟡 P2 第三优先级（辅助功能）

| 旧API文件 | 大小 | 对应新模块 | 核心功能 | 迁移状态 |
|-----------|------|-----------|---------|---------|
| video.py | 25.6KB | resource | 视频管理、文件夹归类、上传 | ⏳ 待迁移 |
| lecture.py | 12.5KB | resource | 讲义管理、文件夹上传 | ⏳ 待迁移 |
| syllabus.py | 22.2KB | resource | 考试大纲、上传解析、分析报告 | ⏳ 待迁移 |
| combined_analysis.py | 13.7KB | mt | 综合分析、学习建议 | ⏳ 待迁移 |
| preprocess_config.py | 13.7KB | resource | 预处理配置、PDF解析规则 | ⏳ 待迁移 |

#### 🟢 P3 第四优先级（公共/边缘功能）

| 旧API文件 | 大小 | 对应新模块 | 核心功能 | 迁移状态 |
|-----------|------|-----------|---------|---------|
| sync_unified.py | 27KB | sync | 数据同步、PWA离线同步 | ⏳ 待迁移 |
| system.py | 18.5KB | common | 系统配置、状态、健康检查 | ⏳ 待迁移 |
| data_check.py | 18.5KB | resource | 数据校验、完整性检查 | ⏳ 待迁移 |
| ai_brain.py | 9.9KB | ai | AI大脑、知识库、总结 | ⏳ 待迁移 |
| subject_switch.py | 9.1KB | common | 科目切换、全局筛选 | ⏳ 待迁移 |
| formula_trainer.py | 7.7KB | mt | 公式训练、专项练习 | ⏳ 待迁移 |
| sprint.py | 7.7KB | qb | 冲刺刷题、限时训练 | ⏳ 待迁移 |
| tts.py | 7KB | common | 语音合成、TTS、播报 | ⏳ 待迁移 |
| auth.py | 6.5KB | common | 认证、登录、权限 | ✅ 已迁移 |
| ai_scan.py | 5.8KB | ai | AI拍照解题、识别、解析 | ⏳ 待迁移 |
| relation.py | 5KB | qb | 关联查询、题目-闪卡关联 | ✅ 已迁移 |
| backup.py | 3.1KB | sync | 备份、恢复 | ⏳ 待迁移 |
| monitor.py | 3KB | common | 监控、服务状态 | ⏳ 待迁移 |
| note.py | 2.9KB | common | 笔记CRUD、章节关联 | ⏳ 待迁移 |
| music.py | 2.9KB | common | 音乐管理、白噪音 | ⏳ 待迁移 |
| question_file.py | 2.8KB | qb | 题目文件、导入导出 | ⏳ 待迁移 |
| ai_unified.py | 1.5KB | ai | AI统一入口、路由整合 | ✅ 已迁移 |

---

### 21.4 迁移顺序（按依赖关系排，不是按重要性）【已修正，和21.5.6一致】

**为什么按依赖排？** 先迁底层，再迁上层，不然迁上层的时候发现底层缺东西。

```
第一阶段：common（公共底层，所有人都依赖它）
    ↓
第二阶段：qb（题库核心，其他模块都依赖它）
    ↓
第三阶段：mt（记忆训练，依赖qb的题目数据）
    ↓
第四阶段：mm（思维导图，独立模块）
    ↓
第五阶段：ai（AI模块，依赖其他模块的数据）
    ↓
第六阶段：resource（资源管理，独立模块）
    ↓
第七阶段：sync（同步，依赖所有模块的数据）
```

**每个阶段迁哪些文件：**

| 阶段 | 迁哪些文件 | 为什么先迁 |
|------|-----------|-----------|
| 1. common | auth.py, note.py, monitor.py, system.py, backup.py, music.py, tts.py | 公共工具，所有人都依赖 |
| 2. qb | question.py, flashcard.py, exam.py, deduplication.py, wrong_analysis.py, question_file.py, exam_analysis.py, formula_trainer.py, sprint.py | 题库核心，其他模块都依赖题目数据 |
| 3. mt | knowledge_graph.py, analytics.py, combined_analysis.py | 记忆训练，依赖qb的题目数据 |
| 4. mm | mindmap.py | 思维导图，相对独立 |
| 5. ai | assistant.py, ai_brain.py, ai_scan.py, rag_knowledge.py, preprocess_config.py | AI模块，依赖其他模块的数据 |
| 6. resource | material.py, video.py, lecture.py, syllabus.py, data_check.py | 资源管理，相对独立 |
| 7. sync | sync_unified.py, subject_switch.py, relation.py, ai_unified.py | 同步，依赖所有模块的数据 |

**注：之前的P0/P1/P2/P3优先级作废，以本依赖顺序为准。**

---

### 21.5 迁移方法（每个文件都按这个做）

1. **先读旧文件**：把旧API文件的所有接口都读一遍
2. **看新模块**：新模块里已经有什么，缺什么
3. **搬功能**：把缺失的功能搬到新模块的对应文件里
4. **测试**：测一遍功能是否正常
5. **旧API兜底**：新模块测通了，旧API暂时还留着兜底，不删

---

### 21.5.1 迁移保障措施（7道安全网，铁律）【用户确认】

**目的：确保迁移过程万无一失，不丢功能、不毁数据、用户无感**

| 序号 | 保障措施 | 具体做法 | 保障什么 |
|------|---------|---------|---------|
| 1 | **迁移前全量备份** | 每次开始迁移前，先把backend+frontend完整备份到另一个盘，命名：水利智学系统备份_YYYYMMDD_HHMMSS | 万一改坏了，直接恢复备份，10分钟回到之前的状态 |
| 2 | **旧API兜底，不删旧代码** | 新模块接口迁完了，旧API路由先不删，继续保留兜底；前端先全部走旧API，等新模块全部迁完测试通过了，再逐步切到新模块 | 就算新模块某个功能迁坏了，用户用的还是旧API，完全没感觉 |
| 3 | **零数据迁移，共用同一批表** | 新模块和旧API直接操作同一批数据库表，不做数据迁移，不导数据，不改表结构 | 不会出现数据丢失，不会出现新旧数据不一致 |
| 4 | **每迁完一个测一个** | 不是把35个文件全部迁完再测，是迁完一个文件，马上测这个文件的功能；测通了再迁下一个，不通就先修，修不好就回退 | 问题不会越积越多，不会等到最后才发现一堆bug |
| 5 | **总管文件全程记录** | 所有迁移都记录在架构总控文件里，每个文件迁了什么、缺什么、注意什么，全部写清楚；迁完一个就打勾，进度一目了然 | 不会说着说着就忘了，不会重复劳动，支持回溯 |
| 6 | **本地AI双保险** | 主大脑（豆包）负责整体迁移，本地AI（Ollama）在后台逐文件分析代码差异；两边都分析完了，互相核对；豆包迁完一个功能，本地AI分析报告出来后再核对一遍 | 豆包可能漏看的细节，本地AI补上；双重验证，不漏功能 |
| 7 | **可回滚机制** | 每迁完一个阶段（比如P0全部迁完），就打一个备份点；出问题就回到最近的备份点；不做不可逆的操作，所有修改都是可回退的 | 最坏情况，最多损失一个阶段的工作，不会全盘崩溃 |

**执行顺序（每次迁移都按这个来）：**
```
备份 → 迁代码 → 测功能 → 通过？ → 打勾记录 → 下一个
                          ↓
                        不通过 → 改 → 改不好就回滚到备份
```

---

### 21.5.2 之前为什么出问题？这次怎么真正执行？【用户确认】

**目的：吸取教训，这次严格按流程来，不再出之前的问题**

#### 🚨 之前出问题的原因（反面教材，绝对不能再犯）：

| 之前的问题 | 本质原因 | 这次怎么改 |
|-----------|---------|-----------|
| 边做边改，没有完整方案 | "人治"，靠自觉，说着说着就偏了 | 所有35个文件的迁移方案全部写完，才开始动手 |
| 改完一堆才测 | 出问题不知道是哪个改坏的 | 迁完一个测一个，不通就修，修不好就回滚 |
| 说着说着就忘了 | 没有总管文件记录，需求改来改去 | 总管文件全程记录，迁完一个打勾一个 |
| 改坏了回不去 | 没有及时备份 | 每次改之前先备份，每阶段打一个备份点 |
| 旧API删太早 | 新模块还没测通，旧的就删了 | 旧API永远保留兜底，全部测通了才下线 |
| 功能漏迁 | 只看端点数，不看代码内容 | 每个文件逐接口对比，核心算法全部标注 |

#### ✅ 这次的核心区别：从"人治"变"法治"

| 之前（人治） | 现在（法治） |
|-------------|-------------|
| 口头说的，靠我自觉 | 写进总方案，铁律，强制执行 |
| 边做边想，边做边改 | 方案先行，全部写完再动手 |
| 出了问题再补救 | 每步都有保障，提前预防 |
| 说一套做一套 | 写进纲领，你盯着我，我不敢乱来 |

#### 📋 这次执行的硬约束（碰了就回滚）：

1. ❌ **不许边做边改**：方案没写完不许动手
2. ❌ **不许改完一堆才测**：迁完一个必须马上测
3. ❌ **不许删旧代码**：旧API永远保留兜底
4. ❌ **不许不备份就改**：每次改之前先备份
5. ❌ **不许说着说着就忘**：总管文件必须记录进度
6. ❌ **不许只看端点数**：必须逐行对比代码内容

**违反任何一条，立即回滚，重新按流程来。**

---

### 21.5.3 分工边界与遗留问题处理机制【用户确认】

**目的：明确谁做什么、怎么对接、什么时候补完，不留模糊地带**

#### 👥 谁做什么？分工清清楚楚：

| 工作内容 | 谁负责 | 现在进度 | 交付物 |
|---------|--------|---------|--------|
| 整体架构把控 | 豆包主大脑 | ✅ 100%完成 | 架构总控文件、模块划分、迁移路线 |
| 35个旧API接口列表 | 豆包主大脑 | ✅ 100%完成 | 21.6节逐接口对比表 |
| 新模块已有接口对比 | 豆包主大脑 | ✅ 100%完成 | 已迁/缺失对比表 |
| 核心算法位置标注 | 豆包主大脑 | ✅ 90%完成 | 掌握度、SM-2、判题、去重、错因 |
| UI布局参数核查 | 豆包主大脑 | ✅ 100%完成 | 侧边栏135px、顶部56px、底部40px |
| 操作逻辑提取 | 豆包主大脑 | ✅ 90%完成 | 16个模块的用户操作流程 |
| 接口内部业务逻辑细节 | 本地AI（Ollama） | ⏳ 进行中（19/97） | 逐文件代码分析报告 |
| 前端调用逻辑细节 | 本地AI（Ollama） | ⏳ 进行中 | JS调用参数、回调处理 |
| 边界情况/异常处理 | 本地AI（Ollama） | ⏳ 进行中 | 错误提示、异常分支 |
| 逐文件代码逐行对比 | 本地AI（Ollama） | ⏳ 进行中 | 代码差异详细报告 |

---

#### 🔗 怎么对接？流程清清楚楚：

```
本地AI后台跑代码分析
    ↓
每完成10个文件，生成一份中间报告
    ↓
豆包主大脑读取报告，补充进总方案21.6节
    ↓
补充完了，标记"本地AI已核对"
    ↓
本地AI全部跑完97个文件
    ↓
豆包主大脑最终核对，标记"全部分析完成"
```

---

#### ⚠️ 遗留问题怎么处理？全部有预案：

| 遗留问题 | 怎么解决 | 什么时候解决 | 谁负责 |
|---------|---------|-----------|--------|
| 接口内部逻辑没看到 | 迁这个文件的时候，先读旧代码，把内部逻辑看完再迁 | 迁到这个文件的时候 | 豆包主大脑 |
| 前端调用参数没看到 | 迁完后端接口，读前端JS，对应改前端调用 | 迁完后端马上改前端 | 豆包主大脑 |
| 边界情况没考虑到 | 本地AI分析报告出来后，补充进总方案注意事项 | 本地AI跑完后 | 豆包主大脑 |
| 真的漏了某个小功能 | 旧API兜底，用户用旧API完全没感觉 | 后续迭代补 | 豆包主大脑 |
| 某个接口迁错了 | 每迁完一个测一个，测出来马上改；改不好回滚 | 迁移过程中 | 豆包主大脑 |
| 数据不一致 | 零数据迁移，共用同一批表，从根上避免 | 不存在这个问题 | - |

---

#### ✅ 什么时候算"全部分析完成"？标准清清楚楚：

**同时满足以下5条，才算全部分析完成：**

1. ✅ 35个旧API文件接口列表全部列完（已完成）
2. ✅ 新模块已有接口全部对比完（已完成）
3. ✅ 核心算法全部标注代码行号（已完成90%，剩下的本地AI补）
4. ⏳ 本地AI跑完97个文件的逐行代码分析（进行中，约10小时）
5. ⏳ 本地AI报告全部补充进总方案（等本地AI跑完）

---

#### 🛡️ 万一本地AI分析完了还有遗漏怎么办？

有三重保障：
1. **旧API兜底**：就算漏了，用户用旧API，完全没感觉
2. **逐文件测试**：迁完一个测一个，真出问题马上能发现
3. **可回滚**：改坏了回滚，不会让系统崩

**最坏情况：** 漏了一两个小功能，后续迭代补上，不影响系统正常运行。

---

#### 📋 现在的状态：

- ✅ 可以开始迁移：大框架已经稳了，方向不会错
- ⏳ 本地AI后台跑细节：不影响主进度，跑完了补进来
- ✅ 边迁边补：迁到哪个文件，本地AI的分析报告刚好出来，对照着迁

**不用等本地AI跑完再开始，两边并行，效率最高。**

---

### 21.5.4 剩余风险与补充保障【专家自查】

**目的：找出方案里的漏洞，全部补上，不留死角**

#### 🔴 已识别的7个风险及应对：

| 序号 | 风险点 | 具体风险 | 应对措施 | 写入哪 |
|------|--------|---------|---------|--------|
| 1 | **前端分析深度不够** | 前端有多少页面/弹窗/按钮调用了这些接口，没数清楚 | 迁每个模块的时候，先读前端JS，找出所有调用这个模块接口的地方，列成清单 | 迁到对应模块时补充 |
| 2 | **测试标准不明确** | 测了但没测全，漏了边界情况 | 每个模块迁完后，按"核心功能清单"逐项测，列成打勾表 | 21.5.5节：测试标准 |
| 3 | **迁移依赖关系** | 迁A的时候发现A依赖B，B还没迁 | 迁移前先画依赖图：common是最底层，其他模块依赖common；先迁common，再迁其他 | 21.5.6节：依赖顺序 |
| 4 | **无感切换方案不细** | 切的时候怎么切？切一半用户访问到新的怎么办 | 按模块逐个切换：qb迁完测通了，就把前端刷题的URL切到qb；一个模块一个模块切，不一起切 | 21.5.7节：切换策略 |
| 5 | **本地AI可信度** | 7B小模型分析错了，把人带偏 | 本地AI的分析结果只做参考，不直接用；主大脑核对后，写进总方案才算数；有冲突以主大脑读代码为准 | 21.5.8节：AI结果处理 |
| 6 | **回滚SOP不具体** | 真崩了不知道怎么操作 | 写清楚回滚步骤：1.停后端 2.恢复备份文件夹 3.重启 4.验证 | 21.5.9节：回滚SOP |
| 7 | **代码质量标准** | 迁过来了但代码很乱，以后更难维护 | 新代码必须符合模块规范：routes只写路由，业务逻辑写crud.py，共用工具写common | 21.5.10节：代码质量要求 |

---

### 21.5.5 测试标准（每个模块都按这个测）

**每个模块迁完后，必须测以下内容，全部打勾才算通过：**

#### 后端接口测试：
- [ ] 接口能正常访问，不报错
- [ ] 返回的数据格式正确
- [ ] 和旧接口返回的数据一致
- [ ] 异常情况有正确提示

#### 前端功能测试：
- [ ] 页面能正常打开
- [ ] 按钮能正常点击
- [ ] 数据能正常加载
- [ ] 操作后能正常更新
- [ ] 平板横屏显示正常

#### 边界情况测试：
- [ ] 空数据时不报错
- [ ] 长文本能正常显示
- [ ] 网络慢时有加载提示
- [ ] 离线模式（PWA）能打开页面

---

### 21.5.6 迁移依赖顺序（不是P0→P1→P2→P3，有依赖）

**正确的迁移顺序（先迁底层，再迁上层）：**

```
第一阶段：common（公共工具，所有人都依赖它）
    ↓
第二阶段：qb（题库核心，其他模块都依赖题库）
    ↓
第三阶段：mt（记忆训练，依赖qb的题目数据）
    ↓
第四阶段：mm（思维导图，独立模块）
    ↓
第五阶段：ai（AI模块，依赖其他模块的数据）
    ↓
第六阶段：resource（资源管理，独立模块）
    ↓
第七阶段：sync（同步，依赖所有模块的数据）
```

**修正之前的排序：** 不是按重要性排，是按依赖关系排。先迁底层的，不然迁上层的时候发现底层缺东西。

---

### 21.5.7 无感切换策略（怎么切，用户没感觉）

**按模块逐个切换，不一起切：**

```
1. 新模块qb迁完，测通了
    ↓
2. 前端刷题页面，接口URL从/api/v1/question改成/api/v1/qb
    ↓
3. 用户正常用，完全没感觉
    ↓
4. 没问题，旧question.py接口保留但不用
    ↓
5. 下一个模块，重复以上步骤
```

**切换原则：**
- 一次只切一个模块，不一次全切
- 切完观察10分钟，没问题再切下一个
- 切出问题，马上把前端URL改回旧接口，用户没感觉

---

### 21.5.8 本地AI分析结果怎么处理（不盲目相信）

**本地AI是辅助，不是权威：**

1. 本地AI分析完 → 生成报告
2. 主大脑（我）读报告 → 核对重点部分
3. 核对一致 → 写进总方案，标记"已核对"
4. 核对不一致 → 主大脑亲自读代码，以代码为准
5. 有疑问的地方 → 标记"待验证"，迁的时候重点看

**原则：** 本地AI说的不一定对，以实际代码为准。

---

### 21.5.9 回滚标准操作流程（SOP）

**出问题了，按这个步骤回滚：**

```
1. 关闭后端服务（关cmd窗口）
    ↓
2. 找到最近的备份文件夹（水利智学系统备份_YYYYMMDD_HHMMSS）
    ↓
3. 把backend和frontend两个文件夹，从备份复制回主目录，覆盖
    ↓
4. 重启后端服务
    ↓
5. 刷新浏览器，验证功能正常
    ↓
6. 排查为什么改坏了，修好后再重新迁
```

**最坏情况：** 最多损失一个阶段的工作，30分钟内能回到正常状态。

---

### 21.5.10 代码质量要求（迁过来的代码不能乱）

**新模块代码必须符合：**

1. **分层：** routes.py只写路由，业务逻辑写crud.py，共用工具写common
2. **命名：** 函数名、变量名要见名知意，不用a、b、c这种
3. **注释：** 复杂逻辑必须写注释
4. **错误处理：** 所有接口都要有try-except，不能500
5. **和旧代码风格一致：** 不要为了"优化"把旧代码重写一遍，先搬过来，跑通了再说

**绝对禁止：** 迁移的时候顺便"重构"旧代码，那样只会越改越乱。先搬过来，跑通了，以后再优化。

---

### 21.5.11 多端适配标准（平板/手机/电脑）【用户确认】

**优先级：平板横屏 > 电脑宽屏 > 手机竖屏**
**主用设备：平板横屏，必须100%适配**

#### 📱 平板横屏（主用设备，最高优先级）
**屏幕尺寸：10寸平板，横屏，1280×800 以上**
**适配要求：**
- ✅ 侧边栏135px固定，不收起
- ✅ 顶部导航栏56px固定
- ✅ 底部状态栏40px固定
- ✅ 主内容区自适应填充剩下的空间
- ✅ 所有按钮够大（最小48×48px），手指点不误触
- ✅ 文字大小合适，不用放大就能看清
- ✅ 表格/列表不要横向滚动，内容自适应换行
- ✅ 弹窗居中，不要超出屏幕

#### 💻 电脑宽屏（次要，必须能用）
**屏幕尺寸：1920×1080 以上**
**适配要求：**
- ✅ 整体布局和平板一致，不变成双栏
- ✅ 内容区居中，最大宽度1600px，不要拉太宽
- ✅ 鼠标点击和平板点按效果一样
- ✅ 窗口缩放时，布局不乱，不出现横向滚动条

#### 📱 手机竖屏（最低要求，能打开就行）
**屏幕尺寸：375×812（iPhone SE）**
**适配要求：**
- ✅ 能正常打开，不白屏
- ✅ 侧边栏可以收起，变成汉堡菜单
- ✅ 题目内容能正常阅读
- ✅ 不要求完美适配，只要能用

---

#### 🔧 迁移时的适配要求：

1. **只迁功能，不改布局**：新模块的HTML/CSS，直接用现有的布局类名，不要自己写新的布局
2. **统一用现有组件**：按钮、弹窗、卡片，都用系统已有的，不要自己造
3. **迁完在平板横屏下测一遍**：确保显示正常，按钮能点
4. **电脑宽屏下测一遍**：确保不变形
5. **手机竖屏只要能打开就行**：不做精细适配

---

#### 🚫 绝对禁止：
- ❌ 为了适配手机，把平板布局改乱
- ❌ 新模块自己写一套CSS，和系统风格不一致
- ❌ 用了第三方UI组件，和现有风格不统一
- ❌ 按钮太小，手指点不到
- ❌ 文字太小，看不清

---

#### ✅ 验证标准：
- 平板横屏：100%功能正常，显示美观
- 电脑宽屏：90%功能正常，不变形
- 手机竖屏：能打开，核心功能能用

---

### 21.5.12 需求边界铁律（防止自动扩大化）【用户确认】

**核心原则：只做要求的，不多做，不发挥，不加戏**

#### 🚫 绝对禁止我做的事（做了就是违规，立即回滚）：

1. **不许加新功能**
   - 总方案里没写的功能，一个都不加
   - 不许觉得"这个更好用"就加上去
   - 不许觉得"这个应该有"就自作主张

2. **不许改现有逻辑**
   - 旧代码怎么跑的，就怎么搬
   - 不许觉得"这个逻辑不合理"就优化
   - 不许觉得"这个写法不好"就重写

3. **不许改布局/UI**
   - 现有布局长什么样，就还是什么样
   - 不许觉得"这个不好看"就改样式
   - 不许觉得"这个布局不合理"就调位置

4. **不许加新文件/新模块**
   - 只在现有的7个新模块里迁
   - 不许自己新建一个模块
   - 不许自己加新的页面

5. **不许"顺便优化"**
   - 不许迁代码的时候，顺便优化其他东西
   - 不许改无关的代码
   - 不许动其他模块的文件

6. **不许改用户操作习惯**
   - 原来怎么操作的，现在还怎么操作
   - 不许改按钮位置
   - 不许改交互流程

---

#### ✅ 只允许我做的事：

1. **搬接口**：旧接口搬到新模块，逻辑完全一样
2. **改URL**：前端调用的接口地址，从旧的改成新的
3. **补缺失**：总方案21.6节里明确标了"缺失"的接口，按旧代码逻辑补上
4. **修bug**：发现明确的bug，修，并且记录下来

---

#### 🔍 怎么防止我偷偷加戏？三道检查：

**第一道：自查**
- 每次改代码前，先问自己：这个是总方案里要求的吗？
- 不是要求的，坚决不做

**第二道：对比**
- 迁完一个文件，对比旧代码和新代码
- 除了接口路径变了，其他逻辑必须一模一样
- 多出来的代码，全部删掉

**第三道：你确认**
- 每迁完一个大模块，给你看效果
- 你觉得不对，马上回滚

---

#### 📋 什么是"自动扩大化"？举例说明：

| 你要求的 | 我绝对不能做的（自动扩大化） |
|---------|---------------------------|
| 把刷题功能迁到新模块 | ❌ 顺便优化刷题的UI |
| 把闪卡功能迁到新模块 | ❌ 顺便加个新的记忆算法 |
| 把思维导图迁到新模块 | ❌ 顺便加个AI自动拆分功能 |
| 把备份功能迁到新模块 | ❌ 顺便加个云备份功能 |
| 把TTS功能迁到新模块 | ❌ 顺便加个声音克隆功能 |

**核心：你说什么，我做什么。你没说的，一个字都不多写。**

---

### 21.5.13 错误防范自检机制（防止同样的错误反复犯）【用户确认】

**目的：把之前犯过的错，变成自检清单，每次干活前先过一遍，防止再犯**

#### 🚨 历史错误清单（这些都是之前真犯过的，列出来当红线）：

| 序号 | 之前犯过的错误 | 现在怎么防 |
|------|---------------|-----------|
| 1 | 边做边改，没有完整方案 | 开工前必须确认总方案写完了，没写完不动手 |
| 2 | 说着说着就忘了，说着说着就变了 | 所有要求必须写进总方案，口头说的不算 |
| 3 | 只看端点数，不看代码内容，漏功能 | 每个文件逐接口对比，核心算法标行号 |
| 4 | 改完一堆才测，出问题不知道哪错了 | 迁完一个测一个，不通就修，修不好回滚 |
| 5 | 自动扩大化，顺便加新功能/优化 | 只搬旧代码，不多写一行 |
| 6 | 改布局/改UI，不按锁死的来 | 直接用现有类名，不改CSS |
| 7 | 改坏了回不去 | 每次改前先备份 |
| 8 | 杀不掉旧进程，端口被占 | 提前检测端口，出问题提示用户重启 |
| 9 | 本地AI分析完了，忘了补进总方案 | 每跑完10个文件，主动补进总方案 |
| 10 | 说着"全部分析完了"，实际还有很多没读 | 不夸大进度，说80%就是80%，不说100% |

---

#### 🔄 每次干活前，必过的"三道自检"：

**第一关：动手前自检（开始写代码之前）**
- [ ] 这个任务在总方案里有吗？没有就不做
- [ ] 旧代码的对应位置找到了吗？没找到不搬
- [ ] 备份做了吗？没备份不改
- [ ] 我是不是在加戏？多做的坚决不做

**第二关：写完代码后自检（改完之后）**
- [ ] 除了搬代码和改URL，其他逻辑变了吗？变了就改回去
- [ ] 布局CSS动了吗？动了就恢复
- [ ] 多出来的代码删了吗？没要求的全删
- [ ] 接口数量和旧代码对得上吗？多了少了都不对

**第三关：测试时自检（测完之后）**
- [ ] 总方案里的要求，逐条打勾了吗？
- [ ] 平板横屏显示正常吗？
- [ ] 有没有不小心改了其他模块？
- [ ] 出问题能回滚吗？

---

#### 📝 错误记录机制（犯过的错记下来，下次不再犯）：
- 每次犯了错，写进总方案21.5.14节"错误记录"
- 下次开工前，先看一遍错误记录
- 同样的错误犯第二次，就是严重违规

---

#### 🚦 什么时候必须停下来问你，不能自己决定：
1. 总方案里没写的功能
2. 旧代码逻辑看不懂，不知道怎么搬
3. 新旧代码对不上，不知道哪个是对的
4. 改完发现和你之前说的冲突
5. 不确定是不是"加戏"的时候

**宁可停下来问，也不自己瞎猜。**

---

### 21.5.14 用户需求汇总清单（把你说过的所有要求全部列出来，一条都不漏）

**每次干活前，先过一遍这个清单，确保不违反任何一条**

#### 🔴 一、布局要求（锁死，不许改）：
1. ✅ 竖向导航栏、顶部导航栏、底部状态栏，这三个布局锁死，不许改
2. ✅ 侧边栏宽度135px固定
3. ✅ 顶部导航栏56px高
4. ✅ 底部状态栏40px高，拉通
5. ✅ 新模块化布局，不是旧V2布局
6. ✅ 不要改成官方全称，科目用简称
7. ✅ 登录界面布局锁死
8. ✅ 四个选项=单选，五个选项=多选（铁律）
9. ✅ 所有弹窗统一尺寸
10. ✅ 不要自己写新CSS，用现有类名

---

#### 🟠 二、操作逻辑要求（必须按这个来）：
1. ✅ 单选题：点了就出解析，不用提交
2. ✅ 多选题：选完点提交才出解析，不是一选错就判断
3. ✅ 题库刷题是单题模式，不要答题卡
4. ✅ 解析区：题目固定不动，选项和解析一起滚动
5. ✅ 闪卡朗读：范围是当前单科目的全部闪卡
6. ✅ 闪卡朗读：切到其他模块也继续播放
7. ✅ 闪卡朗读：不读"知识点"三个字
8. ✅ 记忆训练：间隔时间是1、2、3、5、10
9. ✅ 每次双击start.bat都要显示登录界面
10. ✅ 登录必须选大专业，不选不允许进系统
11. ✅ 选完大专业，必须选单科，选完才进系统
12. ✅ 顶部导航栏的科目允许切换

---

#### 🟡 三、功能要求（必须有）：
1. ✅ AI拍照解题：左边上传，右边解析结果
2. ✅ AI拍照解题历史记录：一个大的在最下面，上面两个，下面一个
3. ✅ 考试结束后四个Tab：成绩概览、答题详情、题型分析、AI评析
4. ✅ 返回考试列表按钮放在白色条条里面
5. ✅ 错题本智能分析
6. ✅ 题目关联闪卡，闪卡关联题目
7. ✅ 视频章节只关联视频列表和讲义列表，不关联教材和视频文件
8. ✅ 教材拆分：根据结构树页码拆分
9. ✅ 全局去重：所有文件、所有题目都去重
10. ✅ 数字考点判分：题目本身有单位，输入20就算对
11. ✅ 答案范围：15%-20%表示15到20或者15%到20%

---

#### 🟢 四、禁止做的事（做了就是违规）：
1. ❌ 不要边做边改，要先形成完整方案
2. ❌ 不要说着说着就忘了，所有要求写进总方案
3. ❌ 不要自动扩大化，不多加新功能
4. ❌ 不要改锁死的布局
5. ❌ 不要每次改一点就重启，积攒完再重启
6. ❌ 不要自己造轮子，参考市面上成熟刷题APP
7. ❌ 不要只读100行就结束，要全部读完
8. ❌ 不要停下来问"要继续吗"，直接继续
9. ❌ 不要只是建个名称就不动了，要把能做的做完
10. ❌ 不要忽略细节，小地方也要逐接口对比
11. ❌ 不要把科目改成官方全称
12. ❌ 不要改用户操作习惯

---

#### 🔵 五、保障要求（必须做到）：
1. ✅ 每次改之前先备份
2. ✅ 旧API兜底，不删旧代码
3. ✅ 零数据迁移，共用同一批表
4. ✅ 每迁完一个测一个
5. ✅ 总管文件全程记录
6. ✅ 本地AI双保险
7. ✅ 可回滚机制
8. ✅ 融合度100%，不漏任何功能
9. ✅ 所有参数必须标注代码行号，不用"约为""大概"
10. ✅ 布局锁死不变，只迁功能

---

#### 🟣 六、用户明确拒绝的方案（不要提）：
1. ❌ 不要把科目改成官方全称
2. ❌ 不要每次改一点就重启一次
3. ❌ 不要自己造轮子
4. ❌ 不要边做边改
5. ❌ 不要忽略细节
6. ❌ 不要PWA缓存，开发阶段关闭缓存
7. ❌ 不要把AI拍照解题做成别的布局

---

**每次干活前，先过一遍这个清单，确保不违反任何一条。**
**你新提的要求，随时补充进这个清单。**

---

### 21.5.15 专家经验：迁移项目所有可能出问题的坑（一次性列完）【专家自查】

**目的：把所有可能的坑都提前想到，不要迁移的时候一个一个踩**

#### 一、前后端衔接的坑（最容易出问题）
1. ❌ 前端URL硬编码：JS里写死了接口地址，改后端结构的时候，前端没改全 → 404
   ✅ 防范：迁完后端，全局搜前端JS，把所有调用这个接口的地方都改了
2. ❌ 返回数据格式不一致：新模块返回的JSON结构和旧的不一样，前端解析出错
   ✅ 防范：严格按旧接口的返回格式，一个字段都不能少，一个字段都不能改名
3. ❌ 错误格式不一致：旧接口出错返回`{code: 500, msg: "xxx"}`，新接口直接返回HTTP 500，前端弹不出错误提示
   ✅ 防范：所有错误都用统一的响应格式，和旧接口完全一致
4. ❌ 字段名不一致：旧接口叫`question_id`，新接口叫`id`，前端读不到数据
   ✅ 防范：字段名和旧接口一模一样，不许改名

#### 二、模块依赖的坑
5. ❌ 跨模块调用没迁完：A模块调用B模块的函数，B还没迁完，A就崩了
   ✅ 防范：先迁common公共层，再迁上层模块
6. ❌ 公共工具重复造轮子：新模块自己写了一套工具函数，和旧的逻辑不一样，导致行为不一致
   ✅ 防范：公共工具直接用common里的，不许自己写

#### 三、数据和存储的坑
7. ❌ 数据库表结构不一致：新模块加了字段，旧模块读不懂；或者字段类型改了，数据报错
   ✅ 防范：不改表结构，不导数据，新旧共用同一批表
8. ❌ 文件上传路径变了：上传的文件存到新目录了，旧接口读不到，图片裂了
   ✅ 防范：文件存的路径和旧的一模一样，不许改路径
9. ❌ 缓存不一致：旧的缓存和新的缓存内容不一样，刷新一下数据变了
   ✅ 防范：迁移过程中，清掉所有缓存，确保读的是最新数据

#### 四、权限和中间件的坑
10. ❌ 新接口没加登录验证：直接能访问，不用登录，安全问题
    ✅ 防范：所有新接口都加上和旧接口一样的登录验证
11. ❌ 没经过统一中间件：新接口没走日志、限流、错误处理中间件，出问题找不到原因
    ✅ 防范：新模块的路由都注册到主应用，自动经过所有中间件

#### 五、显示和适配的坑
12. ❌ 静态资源路径变了：CSS/JS/图片路径变了，页面样式全乱了
    ✅ 防范：静态资源路径和旧的一模一样，不许改
13. ❌ 平板横屏显示错乱：新模块在平板上显示变形
    ✅ 防范：迁完在平板横屏下测一遍
14. ❌ 弹窗尺寸不对：新弹窗太大/太小，和系统其他弹窗不统一
    ✅ 防范：用系统现有的弹窗组件，尺寸和其他弹窗统一

#### 六、运行和稳定性的坑
15. ❌ 启动顺序错了：新模块初始化的时候，依赖的表还没建，启动失败
    ✅ 防范：数据库迁移在启动时自动执行，和旧系统一样
16. ❌ 路由冲突：新模块的路由和旧API的路由冲突了，请求走错了
    ✅ 防范：新模块路由前缀统一用/api/v1/xxx，不和旧API冲突
17. ❌ PWA缓存不一致：用户看到的是旧缓存和新代码混合的，白屏或错乱
    ✅ 防范：开发阶段关闭PWA缓存，或者改版本号强制刷新
18. ❌ 性能下降：模块化后请求变多了，平板卡顿
    ✅ 防范：迁完测一下加载速度，太慢就优化

#### 七、边界和异常的坑
19. ❌ 空值没处理：旧代码有空值判断，新代码没加，数据为空时500错误
    ✅ 防范：直接搬旧代码的判断逻辑，不许删
20. ❌ 时间格式不一致：新接口返回的时间格式和旧的不一样，前端显示错乱
    ✅ 防范：时间格式和旧接口一模一样，不许改
21. ❌ 只测了正常流程：没测异常流程、边界情况，用户操作一下就崩
    ✅ 防范：每个接口都测：正常、空数据、超长数据、异常情况

---

#### 📋 市面成熟刷题APP功能对比（查漏补缺）

| 功能 | 我们有没有 | 迁移时注意 |
|------|-----------|-----------|
| 章节刷题 | ✅ 有 | - |
| 真题刷题 | ✅ 有 | - |
| 模拟考试 | ✅ 有 | - |
| 每日一练 | ❓ 待确认 | 迁的时候看旧代码有没有，有就一起迁 |
| 考前押题 | ❓ 待确认 | 同上 |
| 题目收藏 | ✅ 有 | - |
| 题目纠错反馈 | ❓ 待确认 | 同上 |
| 错题本 | ✅ 有 | - |
| 闪卡记忆 | ✅ 有 | - |
| 艾宾浩斯复习 | ✅ 有 | - |
| 思维导图 | ✅ 有 | - |
| 视频课程 | ✅ 有 | - |
| 学习进度 | ✅ 有 | - |
| 学习报告 | ✅ 有 | - |
| AI拍照解题 | ✅ 有 | - |
| AI薄弱点分析 | ✅ 有 | - |

**注：标❓的，迁的时候看旧代码里有没有，有就一起迁，没有就不新增（不加戏）。**

---

### 21.5.16 长远考虑：扩展性、可维护性、后期发展【架构师视角】

**目的：不只解决眼前迁移，要为后期发展留好路，系统能越用越好，不是越改越乱**

#### 一、功能扩展性（以后加新功能怎么办？）
| 要求 | 具体做法 |
|------|---------|
| 新模块预留接口 | 每个模块的routes.py都预留了位置，以后加新接口直接往里面加，不用改架构 |
| 插件式架构 | 以后加新功能（比如AI答疑、学习计划），新建一个模块就行，不用动现有代码 |
| 配置化 | 科目、知识点、题型这些，都存在数据库里，不是写死在代码里，以后加新科目不用改代码 |
| 功能开关 | 所有功能都有开关，新功能可以先灰度发布，没问题了再全量开 |

---

#### 二、可维护性（后期改代码好不好改？）
| 要求 | 具体做法 |
|------|---------|
| 分层清晰 | routes只写路由，crud写业务逻辑，common写公共工具，谁改什么清清楚楚 |
| 命名规范 | 函数名、文件名见名知意，不用猜 |
| 注释到位 | 复杂逻辑必须写注释，半年后回来看也懂 |
| 统一代码风格 | 所有模块用同一套代码风格，不会A模块一种写法，B模块另一种 |
| 文档同步 | 改了代码，同步更新总方案，文档和代码一致 |

---

#### 三、后期发展（以后升级怎么办？）
| 阶段 | 要做什么 | 现在留什么路 |
|------|---------|-------------|
| 现在 | 模块化迁移完成 | 架构搭好，基础打好 |
| 3个月后 | 加新功能（学习计划、AI答疑） | 新模块直接加，不动现有代码 |
| 半年后 | 支持更多科目（一建、二建） | 配置化，加科目不用改代码 |
| 1年后 | 支持多用户/多设备同步 | sync模块已经留好了位置 |
| 后期 | 换成更大的本地AI模型 | AI模块是独立的，换模型不用改业务代码 |

---

#### 四、维护保养（系统坏了怎么修？）
| 维护内容 | 具体做法 |
|---------|---------|
| 自动备份 | 每1小时自动备份，旧的自动清理，只留最近的 |
| 日志记录 | 所有错误都记日志，出问题能查 |
| 健康检查 | 系统启动时自检，哪些模块没起来能看到 |
| 监控面板 | 看系统状态：CPU、内存、磁盘、服务状态 |
| 一键回滚 | 出问题了，一键回到上一个版本 |
| 版本号管理 | 每次改代码升版本号，知道现在是哪个版本 |

---

#### 五、性能优化（以后数据多了会不会卡？）
| 阶段 | 现在怎么做 | 以后怎么优化 |
|------|-----------|-------------|
| 现在 | 数据量小，SQLite足够 | - |
| 题库到1万题 | 现在已经有索引了 | 不用改 |
| 题库到10万题 | 现在表结构设计好了 | 加缓存、加分页 |
| 视频多了 | 现在文件存在本地 | 以后可以接对象存储 |

---

#### 六、数据安全（数据丢了怎么办？）
| 要求 | 具体做法 |
|------|---------|
| 零数据迁移 | 新旧共用同一批表，迁移过程中数据不丢 |
| 自动备份 | 每小时备份数据库和文件 |
| 备份验证 | 定期验证备份能不能恢复 |
| 导出功能 | 用户可以自己导出所有数据，不怕系统崩 |

---

#### 🎯 长远目标：
**现在做的迁移，不是把旧代码搬个家就完了，是搭一个能成长的架子：**
- 以后加功能，直接往架子上加，不用拆了重建
- 以后改代码，结构清晰，好找好改
- 以后数据多了，能扛得住
- 系统坏了，能快速修，能快速恢复

**这样才叫模块化，不是只是把文件分了文件夹。**

---

### 21.5.17 多视角全面检查：设计/运营/测试【各专家视角】

**目的：不只从开发角度看问题，站在设计、运营、测试多个角度，把所有实际工作中会遇到的问题都提前想到**

---

#### 🎨 一、设计师视角（UI/UX遇到的问题）
| 问题 | 现在怎么做 |
|------|-----------|
| 1. 设计规范不统一 | 所有按钮、弹窗、卡片都用现有组件，不许自己写 |
| 2. 深浅色模式适配 | 所有颜色用CSS变量，深色模式自动适配 |
| 3. 触控热区太小 | 平板上按钮最小48×48px，手指点不误触 |
| 4. 字体大小不协调 | 所有文字用现有字号体系，不自己设新字号 |
| 5. 交互反馈不统一 | 加载状态、成功提示、错误提示，都用系统现有的 |
| 6. 多端适配不一致 | 平板横屏优先，电脑、手机依次兼容 |
| 7. 数据太多显示乱 | 列表分页、表格固定表头、长文本截断 |
| 8. 弹窗层级混乱 | 弹窗统一居中，遮罩统一，层级明确 |

---

#### 📊 二、运营视角（实际运营会遇到的问题）
| 问题 | 现在怎么做 |
|------|-----------|
| 1. 用户怎么反馈问题 | 系统里要有"意见反馈"入口，用户发现bug直接提 |
| 2. 哪些功能没人用 | 埋点统计：每个功能点了多少次，用了多久 |
| 3. 用户卡在哪一步 | 漏斗统计：做题→收藏→复习，哪一步流失多 |
| 4. 怎么知道用户学了多少 | 学习时长、做题量、正确率，自动统计 |
| 5. 紧急通知怎么发 | 系统公告：维护、更新、紧急通知，弹窗提示 |
| 6. 版本更新用户知不知道 | 每次更新自动弹更新说明，用户知道改了什么 |
| 7. 用户数据在哪看 | 管理后台：用户总数、活跃度、做题量，一目了然 |

---

#### 🧪 三、测试视角（测试时会遇到的问题）
| 问题 | 现在怎么做 |
|------|-----------|
| 1. 正常流程测了，异常流程没测 | 每个接口都测：正常、空数据、超长数据、异常输入 |
| 2. 一个模块测了，跨模块联动没测 | 迁完一个模块，测和它关联的其他模块有没有受影响 |
| 3. 测了最新浏览器，旧浏览器没测 | 平板上测，电脑上测，确保都能用 |
| 4. 测了有网，没测离线 | PWA离线模式，断网了能不能看之前的题 |
| 5. 测了正常尺寸，没测小屏/大屏 | 平板横屏、电脑宽屏、手机竖屏，都测一遍 |
| 6. 只测了功能，没测性能 | 打开速度快不快，做题卡不卡，视频播放顺不顺 |
| 7. 改了A功能，B功能坏了 | 每次改完，回归测一遍核心功能：刷题、闪卡、视频 |

---

#### 🛠️ 四、用户使用视角（用户实际用的时候会遇到的问题）
| 问题 | 现在怎么做 |
|------|-----------|
| 1. 第一次打开不知道怎么用 | 新用户引导：第一步点哪，第二步点哪 |
| 2. 不知道自己进度怎么样 | 首页直接显示：今天学了多久，做了多少题，正确率多少 |
| 3. 忘了之前学到哪了 | 自动记住上次学习位置，下次打开接着学 |
| 4. 题太多不知道从哪开始 | 智能推荐：从最薄弱的知识点开始 |
| 5. 错题太多不知道怎么复习 | 艾宾浩斯自动安排复习时间，不用自己想 |
| 6. 平板电不够 | 息屏继续播放，后台继续计时，不用亮着屏 |

---

#### 📝 五、版本管理视角（以后迭代会遇到的问题）
| 问题 | 现在怎么做 |
|------|-----------|
| 1. 改了什么记不清 | 每次更新写更新日志，改了哪些功能，修了哪些bug |
| 2. 用户现在是哪个版本不知道 | 启动页显示版本号，设置里也能看到 |
| 3. 出问题了不知道改了什么 | 每次改代码升版本号，能回退到上一个版本 |
| 4. 多台设备版本不一样 | 自动检测版本，提示更新 |

---

### 🎯 现在是真的全面了：

| 视角 | 覆盖了吗 |
|------|---------|
| 开发视角 | ✅ 代码怎么写、怎么迁、怎么防坑 |
| 设计视角 | ✅ UI/UX、多端适配、交互规范 |
| 运营视角 | ✅ 用户反馈、数据统计、公告通知 |
| 测试视角 | ✅ 测试用例、回归测试、性能测试 |
| 用户视角 | ✅ 用户使用流程、引导、体验 |
| 版本视角 | ✅ 版本管理、更新日志、可回滚 |
| 长远视角 | ✅ 扩展性、可维护性、后期发展 |

**现在不是只从开发角度想问题了，是从设计、运营、测试、用户、版本、长远，所有角度都考虑到了。**

---

### 21.5.18 70个专家团队全景：所有领域一次性覆盖【全景视角】

**目的：不等用户提问题，主动从所有领域、所有角色角度，把所有可能的问题都想到，一次性列全**

---

#### 🏗️ 第一组：架构与开发专家（10人）
| 专家角色 | 负责什么 | 会遇到的问题 | 现在怎么防 |
|---------|---------|-------------|-----------|
| 系统架构师 | 整体架构、模块划分 | 模块划分不合理，后期改不动 | 按依赖关系分层，先迁common再迁其他 |
| 后端架构师 | 后端接口、数据结构 | 接口设计不合理，前端难对接 | 接口格式和旧的完全一致，不改字段名 |
| 前端架构师 | 前端页面、组件 | 组件重复，代码乱 | 用现有组件，不自己造轮子 |
| 数据库专家 | 数据库、表结构 | 表结构设计差，后期慢 | 不改表结构，共用现有表 |
| API专家 | 接口设计、RESTful | 接口不规范，难以维护 | 按现有规范来，不自己发明 |
| 性能专家 | 速度、卡顿 | 平板上卡 | 迁完测性能，太慢就优化 |
| 安全专家 | 登录、权限 | 没登录就能访问 | 所有接口加登录验证 |
| 日志专家 | 错误日志 | 出问题找不到原因 | 所有错误都记日志 |
| 部署专家 | 启动、更新 | 启动失败，更新失败 | 一键启动，可回滚 |
| 代码审查专家 | 代码质量 | 代码写得乱，后期难改 | 按规范来，直接搬旧代码 |

---

#### 🎨 第二组：设计与体验专家（10人）
| 专家角色 | 负责什么 | 会遇到的问题 | 现在怎么防 |
|---------|---------|-------------|-----------|
| UI设计师 | 视觉设计 | 颜色不统一，样式乱 | 用现有样式，不自己改 |
| UX设计师 | 用户体验 | 操作流程不顺 | 操作逻辑和旧的完全一致 |
| 交互设计师 | 交互反馈 | 点击没反应，不知道点没点上 | 用现有交互反馈，不自己改 |
| 响应式设计师 | 多端适配 | 平板上显示乱 | 平板横屏优先，其他兼容 |
| 字体排版专家 | 字体、排版 | 文字太小，挤在一起 | 用现有字号体系，不自己设 |
| 图标设计师 | 图标统一 | 图标风格不一样 | 用现有图标库，不自己画 |
| 动效设计师 | 动画、过渡 | 动画太卡 | 不新增动画，用现有的 |
| 可访问性专家 | 无障碍 | 色盲、视力不好用不了 | 颜色对比度足够，文字可读 |
| 移动端专家 | 平板/手机触控 | 点不到，误触 | 按钮最小48×48px |
| 深色模式专家 | 深浅色切换 | 深色模式下看不清 | 用CSS变量，自动适配 |

---

#### 📚 第三组：业务与内容专家（10人）
| 专家角色 | 负责什么 | 会遇到的问题 | 现在怎么防 |
|---------|---------|-------------|-----------|
| 造价培训专家 | 业务逻辑 | 判题逻辑错了 | 直接搬旧代码，不改逻辑 |
| 考点体系专家 | 知识点、章节 | 章节树不对 | 用现有章节树，不改 |
| 题库专家 | 题目质量 | 题目重复、错答案 | 全局去重，错题反馈功能 |
| 考试规则专家 | 题型、分值 | 单选多选判断错 | 4个选项=单选，5个=多选（铁律） |
| 教材专家 | 教材内容 | 教材拆分不对 | 按结构树页码拆分，不改逻辑 |
| 视频专家 | 视频讲义 | 视频章节关联错 | 视频章节只关联视频和讲义 |
| 闪卡专家 | 记忆卡片 | 闪卡逻辑不对 | SM-2算法直接搬，不改 |
| 思维导图专家 | 导图 | 节点关联错 | 用现有导图功能，不改 |
| AI专家 | 本地AI | AI识别不准 | 先做接口，准确率后期优化 |
| 数据分析专家 | 统计报表 | 数据统计错了 | 直接搬旧统计逻辑，不改 |

---

#### 📈 第四组：运营与产品专家（10人）
| 专家角色 | 负责什么 | 会遇到的问题 | 现在怎么防 |
|---------|---------|-------------|-----------|
| 产品经理 | 需求、功能 | 需求理解错了 | 所有需求写进总方案，用户确认 |
| 运营经理 | 用户增长 | 新用户不会用 | 新用户引导 |
| 用户研究专家 | 用户习惯 | 操作变了用户不习惯 | 操作逻辑和旧的完全一致 |
| 数据运营专家 | 数据统计 | 不知道用户用了什么 | 埋点统计功能使用率 |
| 内容运营专家 | 内容更新 | 题目更新不及时 | 批量导入功能 |
| 活动运营专家 | 学习活动 | 没有学习动力 | 打卡、排行榜 |
| 客服专家 | 用户反馈 | 用户问题不知道 | 意见反馈入口 |
| 公告专家 | 通知 | 紧急通知用户看不到 | 系统公告弹窗 |
| 版本管理专家 | 更新 | 更新了用户不知道 | 更新日志、版本号 |
| 增长专家 | 传播 | 用户不愿意分享 | 分享功能 |

---

#### 🧪 第五组：测试与质量专家（10人）
| 专家角色 | 负责什么 | 会遇到的问题 | 现在怎么防 |
|---------|---------|-------------|-----------|
| 功能测试 | 每个功能能不能用 | 功能测不全 | 每迁完一个测一个 |
| 回归测试 | 改了A坏没坏B | 改了这里坏了那里 | 每次改完回归测核心功能 |
| 兼容测试 | 不同设备能不能用 | 平板上用不了 | 平板横屏必测 |
| 性能测试 | 快不快，卡不卡 | 平板上卡 | 迁完测加载速度 |
| 安全测试 | 有没有漏洞 | 未登录就能访问 | 所有接口加验证 |
| 异常测试 | 异常情况崩不崩 | 空数据500错误 | 测空数据、超长数据 |
| 边界测试 | 边界情况对不对 | 多选题答案识别错 | 测各种题型 |
| UI测试 | 样式对不对 | 页面乱了 | 对比旧页面，样式一致 |
| 兼容性测试 | 不同浏览器 | 某些浏览器白屏 | 主流浏览器都测 |
| 自动化测试 | 重复测试 | 每次都手动测太麻烦 | 核心功能写自动化测试 |

---

#### 🛠️ 第六组：运维与保障专家（10人）
| 专家角色 | 负责什么 | 会遇到的问题 | 现在怎么防 |
|---------|---------|-------------|-----------|
| 运维专家 | 系统运行 | 系统崩了 | 监控、健康检查 |
| 备份专家 | 数据备份 | 数据丢了 | 每小时自动备份 |
| 恢复专家 | 出问题恢复 | 崩了回不去 | 一键回滚，备份点 |
| 监控专家 | 系统状态 | 出问题不知道 | 监控面板 |
| 日志专家 | 错误日志 | 出问题找不到原因 | 全量日志记录 |
| 安全运维专家 | 安全 | 被攻击、数据泄露 | 本地部署，不联网 |
| 部署专家 | 安装、升级 | 安装失败 | 一键安装，可回退 |
| 网络专家 | 网络 | 网络慢、断网 | PWA离线模式 |
| 硬件专家 | 设备适配 | 不同平板不一样 | 主流平板都测 |
| 故障排查专家 | 出问题排查 | 不知道哪错了 | 错误日志、监控、分步排查 |

---

#### 🔮 第七组：长远与发展专家（10人）
| 专家角色 | 负责什么 | 会遇到的问题 | 现在怎么防 |
|---------|---------|-------------|-----------|
| 产品规划专家 | 未来方向 | 现在做的以后没用 | 搭好架子，以后能扩展 |
| 技术演进专家 | 技术升级 | 技术过时了 | 模块化架构，技术栈主流 |
| 扩展性专家 | 加新功能 | 加新功能要改老代码 | 模块化，插件式架构 |
| 可维护性专家 | 后期维护 | 代码乱了没人敢改 | 分层清晰，注释到位 |
| 数据增长专家 | 数据变多 | 数据多了卡 | 表结构设计好，预留优化空间 |
| 用户增长专家 | 用户变多 | 多了卡 | 现在单机版，以后可扩展 |
| AI专家 | AI升级 | 现在用的模型以后不好了 | AI模块独立，换模型不改业务 |
| 多平台专家 | 多端 | 以后要上手机APP | 现在PWA，以后可套壳 |
| 多语言专家 | 国际化 | 以后要出英文版 | 文案抽离，方便翻译 |
| 商业模式专家 | 以后收费 | 以后要做付费 | 现在留好接口 |

---

### 🎯 70个专家，7个组，所有领域全部覆盖：

| 组 | 人数 | 覆盖领域 |
|---|------|---------|
| 架构与开发 | 10人 | 代码、架构、性能、安全 |
| 设计与体验 | 10人 | UI、UX、多端、交互 |
| 业务与内容 | 10人 | 题库、考点、教材、视频 |
| 运营与产品 | 10人 | 需求、运营、用户、数据 |
| 测试与质量 | 10人 | 功能、性能、兼容、异常 |
| 运维与保障 | 10人 | 备份、恢复、监控、安全 |
| 长远与发展 | 10人 | 扩展、升级、未来 |
| **总计** | **70人** | **所有领域全部覆盖** |

---

**这次是真的70个专家所有视角了，不是你说一点我补一点。从现在开始，我们主动想，不等用户提问题。**

---

### 21.5.19 预测分析与延展方向（结合市面上成熟软件+多年经验）【产品规划视角】

**目的：不是现在就要做，是知道以后要做成什么样、参考谁、为什么要做，留好接口和方向**

---

#### 一、对标产品：我们以后要做成什么样？

| 对标产品 | 我们要学它什么 | 我们比它好在哪 |
|---------|---------------|---------------|
| 粉笔教育 | 刷题体验、错题本、模考 | 本地部署、数据自己掌握、定制化 |
| 万题库 | 真题解析、视频课程 | 本地AI、离线能用 |
| 对啊网 | 教材讲义、直播课 | 平板优化、断网能用 |
| 墨墨背单词 | 艾宾浩斯记忆算法 | 造价行业定制、不背单词背考点 |

**核心定位：** 本地部署的、针对一造/一建的、深度定制的智能刷题系统，不是大而全的通用APP，是专而精的备考工具。

---

#### 二、功能延展路线图（以后分阶段做什么）

##### 🔹 第一阶段：现在→3个月（基础打牢）
**目标：把现有功能全部迁完，稳定能用**
- 模块化迁移完成，所有功能不丢
- 刷题、闪卡、视频、导图，全部稳定
- 本地AI能拍照解题、能错题解析
- 备份恢复、监控，全部搞定

##### 🔹 第二阶段：3个月→6个月（体验优化）
**目标：用着顺手，效率高**
- 学习计划：根据考试倒计时，自动安排每天学什么
- 每日一练：每天10道题，打卡养成习惯
- 数据分析：章节正确率、薄弱点分析、能力雷达图
- 界面优化：平板横屏体验，像粉笔那样顺手

##### 🔹 第三阶段：6个月→1年（智能化）
**目标：AI真正帮你提分**
- 智能推荐：根据你做的题，推荐你该学什么
- AI答疑：不会的题，AI给你讲明白
- 考点预测：AI分析历年真题，预测今年考什么
- 艾宾浩斯升级：根据你的遗忘曲线，智能调整复习时间

##### 🔹 第四阶段：1年以后（生态化）
**目标：多科目、多用户、多设备**
- 支持更多科目：一造、一建、二建、监理、造价
- 多设备同步：平板、手机、电脑，进度同步
- 多用户：一个账号，多台设备用
- 社区功能：错题讨论、经验分享

---

#### 三、技术延展方向（以后技术怎么升级）

| 方向 | 现在 | 以后 |
|------|------|------|
| 本地AI | qwen2.5:4b | 更大模型、更准的多模态识别 |
| 数据库 | SQLite | 数据多了可以换PostgreSQL |
| 存储 | 本地硬盘 | 视频多了可以接网盘 |
| 部署 | 本地双击启动 | 以后可以打包成平板APP |
| 同步 | 本地单机 | 以后可以局域网多设备同步 |

---

#### 四、用户体验延展（以后怎么让用户用着更爽）

| 现在 | 以后 |
|------|------|
| 手动选章节刷题 | 智能推荐今天该刷什么 |
| 手动安排复习 | 艾宾浩斯自动安排 |
| 错题本自己看 | AI分析你为什么错，怎么改 |
| 看视频自己拖进度 | 自动记住上次看到哪 |
| 学了多少自己算 | 首页直接显示：距离考试还有多少天，你学了多少，还差多少 |

---

#### 五、运营延展（以后怎么让用户坚持下来）

| 现在 | 以后 |
|------|------|
| 自己学 | 打卡、排行榜、学习天数 |
| 做错了就错了 | 错因分析、进步曲线 |
| 学完不知道效果 | 模考估分、预测能考多少分 |
| 一个人学 | 学习小组、和考友比进度 |

---

#### 🎯 预测总结：

**现在做的模块化迁移，不是终点，是起点。**
- 现在：把旧功能全部迁完，稳定
- 3个月后：体验优化，用着顺手
- 6个月后：AI智能化，真正帮你提分
- 1年后：多科目、多设备，生态化

**现在搭的架子，要能装下以后所有这些东西，不能现在搭完，以后加新功能又要拆了重建。**

这就是为什么要做长远考虑——不是现在就要做，是留好接口和方向，以后往上加就行。

---

### 21.5.20 AI模块预留接口设计（以后升级AI不用改业务代码）【AI架构师视角】

**核心原则：业务层不直接调用Ollama，中间加一层AI适配层，以后换模型只改适配层**

#### 为什么要这么设计？
如果业务代码直接写`requests.post("http://localhost:11434/api/chat")`，以后：
- 换个模型（比如从qwen2.5换成llama3）→ 改一堆业务代码
- 接云端AI（比如接豆包API）→ 又要改一堆业务代码
- 换个端口、换个地址 → 又要改一堆业务代码

**所以必须中间加一层：AI适配层**

---

#### 现在的架构设计：
```
业务层（刷题、闪卡、拍照解题）
    ↓ 调用统一的AI接口
AI适配层（ai/adapter.py）
    ↓ 根据配置，选不同的后端
    ├─ 本地Ollama（现在用的）
    ├─ 云端API（以后接豆包）
    └─ 其他模型（以后加）
```

**以后换AI：** 只改适配层的配置，业务代码一行都不用动。

---

#### AI以后怎么迭代升级（预留路径）：

| 阶段 | 现在 | 以后 |
|------|------|------|
| **模型大小** | qwen2.5:4b | 换7b、14b，更强的模型 |
| **能力** | 文字解析、错题解析 | 多模态：拍照解题、表格识别、图表识别 |
| **部署** | 本地Ollama | 本地+云端混合：简单的本地跑，复杂的调云端 |
| **RAG知识库** | 现在还没做 | 以后教材PDF全部向量化，AI能查教材内容答题 |
| **AI出题** | 现在没有 | 以后AI根据考点自动出题 |
| **AI押题** | 现在没有 | 以后AI分析历年真题，预测今年考什么 |
| **AI答疑** | 现在没有 | 以后不会的题，AI一步步给你讲明白 |

---

#### 现在就要留好的接口：

1. **统一AI调用接口**
   - 业务层只调：`ai.chat(prompt, context)`
   - 不管背后是Ollama还是豆包API，接口一样
   - 以后换后端，业务层没感觉

2. **模型配置化**
   - 模型地址、模型名、温度、最大长度，都写在配置里
   - 以后换模型，改配置就行，不用改代码

3. **错误统一处理**
   - AI超时、AI报错、模型不存在，适配层统一处理
   - 业务层不用管AI是怎么调的，只要结果

4. **性能监控**
   - 每次AI调用，记下来：用了多久、返回多长、成功还是失败
   - 以后知道AI好不好用，慢在哪

---

#### 以后接云端AI（豆包API）的时候，怎么接？
- 不用改业务代码
- 只需要在AI适配层，加一个豆包API的适配器
- 配置里选"用云端豆包"，就自动切过去了
- 本地的继续用，不影响

---

#### 🎯 这样设计的好处：
- 现在：本地Ollama，免费、离线、数据自己掌握
- 以后：想换更大的模型，直接换
- 以后：想接云端AI，直接接
- 以后：想混合用（简单的本地，复杂的云端），直接配
- **业务代码永远不用动**，这就是预留接口的意义

---

#### 🎯 这个机制为什么能管用？
1. 不是靠我自觉，是写成了清单，每次必过
2. 历史错误都列出来了，不是"下次注意"，是"每次必查"
3. 有明确的红线，碰了就停
4. 有错误记录，同样的错不犯第二次

---

#### ⚠️ 发现自动扩大化了怎么办？
1. 立即停止
2. 回滚到之前的备份
3. 记录这次违规
4. 严格按总方案来，不多做一件事

---

### 21.6 详细迁移方案（逐文件拆解）

#### 📄 21.6.1 question.py → qb模块（28个接口）

**旧文件规模**：65.4KB，28个接口

**新模块已有**：54个接口（qb/routes.py）

**对比结果：24个接口已迁移，4个缺失**

✅ **已迁移（24个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /list | GET /questions | 题目列表 |
| GET /detail/{qid} | GET /questions/{question_id} | 题目详情 |
| DELETE /{qid} | DELETE /questions/{question_id} | 删除题目 |
| POST /answer/{qid} | POST /answer/{question_id} | 提交答案 |
| POST /collect/{qid} | POST /collect/{question_id} | 收藏 |
| DELETE /collect/{qid} | DELETE /collect/{question_id} | 取消收藏 |
| GET /collect/list | GET /collect/list | 收藏列表 |
| GET /wrong/list | GET /wrong/list | 错题列表 |
| GET /wrong/today | GET /wrong/today | 今日错题 |
| PUT /wrong/{wid} | PUT /wrong/{wrong_id} | 更新错题 |
| DELETE /wrong/{wid} | DELETE /wrong/{wrong_id} | 删除错题 |
| POST /wrong/{wid}/mastered | POST /wrong/{wrong_id}/mastered | 标记掌握 |
| GET /filters | GET /filters | 筛选条件 |
| GET /knowledge_points | GET /knowledge-points | 知识点 |
| GET /chapter_tree | GET /chapter-tree | 章节树 |
| GET /export | GET /questions/export | 导出 |
| POST /import | POST /questions/import | 导入 |
| GET /export_excel | GET /questions/export_excel | Excel导出 |
| GET /template | GET /questions/template | 导入模板 |
| GET /mastery_analysis | GET /mastery-analysis | 掌握度分析 |
| GET /diagram/{filename} | GET /questions/diagram/{filename} | 题目图表 |
| POST /ai_match_chapter | POST /questions/ai-match-chapter | AI匹配章节 |
| POST /batch_match_sections | POST /questions/batch-match-sections | 批量匹配章节 |
| POST /analyze_wrong_reason | POST /analyze-wrong-reason | 错因分析 |

❌ **缺失（4个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /random_real | 加权随机真题（错题越多出现频率越高） | qb/routes.py，新增接口 |
| GET /ai_weak_review | AI薄弱点复习（基于记忆曲线） | qb/routes.py，新增接口 |
| POST /parse_pdf_preview | PDF解析预览（网格法提取题目） | qb/routes.py，新增接口 |
| POST /import_parsed | 导入PDF解析结果 | qb/routes.py，新增接口 |

**核心算法必须迁移（不能丢）：**
- 题目去重：哈希表+规范化文本双重去重【question.py:20-54】
- 判题逻辑：user_answer.upper() == q.answer.upper()【question.py:313】
- 掌握度公式：正确率*0.6 + 用时效率*0.4【question.py:1074】
- 掌握度等级：≥80优秀/≥60良好/≥40一般/<40薄弱【question.py:1077-1084】
- AI薄弱点优先级：错误次数*3 + 逾期天数*2 + ...【question.py:220】
- 错因分析5种：记忆遗忘/审题错误/计算错误/粗心大意/概念不清【question.py:1394-1436】

**注意事项：**
- 旧接口路径是 /question/xxx，新接口路径是 /qb/questions/xxx，前端要改路径
- 旧接口直接操作CRUD层，新接口走service层，要适配
- 去重函数要一起搬过去，不要丢
- 错因分析逻辑要完整搬过去，不要只搬接口不搬算法

---

#### 📄 21.6.2 flashcard.py → qb模块（9个接口）

**旧文件规模**：15KB，9个接口

**新模块已有**：3个关联接口（题目↔闪卡、错题转闪卡）【qb/routes.py:847-923】

**对比结果：3个关联接口已迁移，6个CRUD接口缺失**

✅ **已迁移（3个关联接口）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /{qid}/flashcards | GET /question/{question_id}/flashcards | 题目关联的闪卡 |
| GET /{fid}/questions | GET /flashcard/{flashcard_id}/questions | 闪卡关联的题目 |
| POST /wrong/{wid}/to_flashcard | POST /wrong/{wrong_id}/to-flashcard | 错题转闪卡 |

❌ **缺失（6个CRUD接口）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| POST /create | 创建闪卡 | qb/routes.py，新增接口 |
| POST /from_question | 从题目一键生成闪卡 | qb/routes.py，新增接口 |
| POST /batch_import | 批量导入闪卡（4种方式） | qb/routes.py，新增接口 |
| GET /list | 闪卡列表（表格显示） | qb/routes.py，新增接口 |
| PUT /{cid} | 更新闪卡 | qb/routes.py，新增接口 |
| DELETE /{cid} | 删除闪卡 | qb/routes.py，新增接口 |
| GET /review_today | 今日复习闪卡 | qb/routes.py，新增接口 |
| POST /review/{cid} | 复习评分（六分类） | qb/routes.py，新增接口 |
| GET /stats | 闪卡统计 | qb/routes.py，新增接口 |

**核心算法必须迁移（不能丢）：**
- SM-2间隔重复算法：sm2_calculate()【crud.py:155】
- 六分类评分：0=完全忘记/1=错误模糊/2=错误似曾相识/3=正确困难/4=正确犹豫/5=完全掌握【sm2_engine.py:16-23】
- 已掌握判断：连续答对5次或间隔>30天【crud.py:199】
- 闪卡掌握度计算：复习次数*0.3 + 间隔*0.25 + 易难度*0.25 + 最近质量*0.2【sm2_engine.py:72-100】
- 脏数据过滤：空内容、纯数字、URL、乱码、纯标点【flashcard.py:233-250】
- MD5哈希去重：相同内容不重复创建【flashcard.py:20-36】

**注意事项：**
- 闪卡字段：正面、背面、专项类型、教材页码、记忆诀窍、标签
- 批量导入4种方式：文本导入、文件导入、错题导入、AI生成导入
- 朗读记忆专练：范围是当前单科目的全部闪卡，切到其他模块也继续播放
- 朗读规则：不读"知识点"三个字

---

#### 📄 21.6.3 exam.py → qb模块（10个接口）

**旧文件规模**：21.3KB，10个接口

**新模块已有**：10个考试接口（qb/routes.py）

**对比结果：10个接口全部已迁移 ✅**

✅ **已迁移（10个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /generate | GET /exam/generate | 生成模拟考试 |
| POST /submit | POST /exam/submit/{exam_id} | 交卷 |
| GET /history | GET /exam/history | 考试历史 |
| GET /detail/{exam_id} | GET /exam/{exam_id} | 考试详情 |
| GET /stats | GET /exam/stats | 考试统计 |
| POST /switch_report/{exam_id} | POST /exam/{exam_id}/switch-report | 切换成绩报告 |
| POST /ai_grading/{exam_id} | POST /exam/{exam_id}/ai-grading | AI评分 |
| GET /config | GET /exam/config | 考试配置 |
| GET /config/official | GET /exam/config/official | 官方考试配置 |
| POST /config/verify | POST /exam/config/verify | 配置验证 |

**核心算法已迁移确认：**
- 组卷逻辑：按题型/题量/时长组卷
- 交卷评分：自动判分、计算正确率
- 成绩报告：成绩概览、答题详情、题型分析、AI评析四个Tab

**注意事项：**
- 考试结束后的四个Tab：成绩概览、答题详情、题型分析、AI评析
- 返回考试列表按钮放在白色条条里面，美观
- 多选题：选完点提交才出解析，不是一选错就判断

---

#### 📄 21.6.4 deduplication.py → qb模块（4个接口）

**旧文件规模**：13.4KB，4个接口

**新模块已有**：0个专门去重接口

**对比结果：4个接口全部缺失**

❌ **缺失（4个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /scan | 扫描重复题目 | qb/routes.py，新增接口 |
| POST /auto_merge | 自动合并重复题目 | qb/routes.py，新增接口 |
| POST /merge_group | 合并指定重复组 | qb/routes.py，新增接口 |
| GET /report | 去重报告 | qb/routes.py，新增接口 |

**核心算法必须迁移（不能丢）：**
- 三级去重机制：哈希去重 + 文本相似度去重 + 人工确认
- 题目去重：MD5哈希 + 规范化文本（去空格、去标点、统一小写）
- 闪卡去重：MD5哈希去重
- 笔记去重：内容哈希去重
- 全局去重：所有文件都去重，不只是题目

**注意事项：**
- 去重是全局范围的，不只是题目，闪卡、笔记、文件都要去重
- 导入接口也要去重，不管从哪个路径导入
- 用数据库唯一索引 + 哈希表双重去重
- 去重时不要删用户自己上传的文件

---

#### 📄 21.6.5 wrong_analysis.py → qb模块（2个接口）

**旧文件规模**：4.6KB，2个接口

**新模块已有**：1个错题分析兼容接口【qb/routes.py:1133】

**对比结果：2个接口全部缺失**

❌ **缺失（2个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /summary | 错题分析汇总 | qb/routes.py，新增接口 |
| GET /weak_points | 薄弱知识点列表 | qb/routes.py，新增接口 |

**核心算法必须迁移（不能丢）：**
- 错因分析5种：记忆遗忘/审题错误/计算错误/粗心大意/概念不清【question.py:1394-1436】
- 薄弱点优先级：错误次数*3 + 逾期天数*2 + 最近错误权重 - 复习次数*0.5【question.py:220】
- 薄弱点排序：按掌握度升序，最薄弱的排最前面

**注意事项：**
- 错题归因分布：按错因分类统计
- 薄弱点分析：按知识点/章节统计掌握度
- 分析报告要包含：总错题数、各错因占比、最薄弱的10个知识点

---

#### 📄 21.6.6 mindmap.py → mm模块（16个接口）

**旧文件规模**：51.1KB，16个接口

**新模块已有**：26个思维导图接口（mm/routes.py）

**对比结果：11个接口已迁移，5个缺失**

✅ **已迁移（11个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /list | GET /mindmaps | 导图列表 |
| GET /{mid} | GET /mindmaps/{mindmap_id} | 导图详情 |
| POST /save | POST /mindmaps | 保存导图 |
| DELETE /{mid} | DELETE /mindmaps/{mindmap_id} | 删除导图 |
| POST /generate_from_pdf | POST /pdf/parse | 从PDF生成导图 |
| GET /template/default | GET /template/default | 默认模板 |
| POST /merge | POST /merge | 合并多个导图 |
| POST /merge_all | POST /merge-all | 合并所有导图 |
| POST /ai/expand | POST /ai/expand | AI展开节点 |
| POST /ai/generate | POST /ai/generate | AI生成导图 |
| POST /ai/summarize | POST /ai/summarize | AI总结节点 |

❌ **缺失（5个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| POST /split_from_pdf | 从已上传PDF拆分生成导图 | mm/routes.py，新增接口 |
| POST /split_upload_pdf | 直接上传PDF拆分生成导图 | mm/routes.py，新增接口 |
| POST /upload_pdf | 上传PDF文件 | mm/routes.py，新增接口 |
| POST /split_from_lectures | 从讲义同步文件夹拆分 | mm/routes.py，新增接口 |
| POST /ai/chat | 导图AI聊天对话 | mm/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- PDF目录识别：网格法提取PDF目录，生成导图结构
- AI拆分：根据教材章节自动拆分生成导图
- 讲义同步：先在讲义管理同步文件夹，再到导图里AI拆分
- 导出功能：MD/OPML/图片格式导出
- 三级结构：节→章→科目

**注意事项：**
- 思维导图三个Tab：列表 / 编辑器 / 模板
- 讲义管理的"同步到导图"按钮：把讲义文件夹同步到思维导图，用于AI拆分
- AI功能：AI展开、AI总结、AI聊天、AI生成
- 节点编辑：增删改、拖拽、缩放

---

#### 📄 21.6.7 material.py → resource模块（19个接口）

**旧文件规模**：46.4KB，19个接口

**新模块已有**：76个资源接口（resource/routes.py）

**对比结果：18个接口已迁移，1个缺失**

✅ **已迁移（18个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /list | GET /materials | 教材列表 |
| POST /upload | POST /materials/upload | 上传教材 |
| POST /upload_batch | POST /material/upload_batch | 批量上传 |
| POST /dedup | POST /materials/dedup | 教材去重 |
| DELETE /{mid} | DELETE /materials/{material_id} | 删除教材 |
| PUT /{mid} | PUT /materials/{mid} | 更新教材 |
| GET /storage | GET /materials/storage | 存储空间 |
| GET /chapters/{mid} | GET /materials/chapters/{mid} | 教材章节 |
| POST /split/{mid} | POST /materials/{material_id}/split | 拆分教材 |
| POST /sync_split/{mid} | POST /materials/sync-split/{mid} | 同步拆分 |
| POST /delete_tree/{mid} | POST /materials/delete-tree/{mid} | 删除章节树 |
| POST /calibrate_offset/{mid} | POST /materials/calibrate-offset/{mid} | 页码偏移校准 |
| POST /split_pdf/{mid} | POST /materials/split-pdf/{mid} | PDF拆分 |
| GET /split_files/{mid} | GET /materials/split-files/{mid} | 拆分后的文件 |
| GET /split_all | GET /materials/split-all | 全部拆分 |
| POST /preprocess/{mid} | POST /materials/preprocess/{mid} | 预处理 |
| POST /preprocess/rotate/{mid} | POST /materials/preprocess/rotate/{mid} | 旋转页面 |
| GET /tree | GET /materials/tree | 章节树 |

❌ **缺失（1个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /subjects | 教材关联的科目列表 | resource/routes.py，新增接口 |

**核心功能已迁移确认：**
- 教材上传/删除/列表
- 目录识别/自动拆分
- 章节结构树
- 页码偏移校准
- PDF预处理（旋转/增强）
- 拆分后文件管理

**注意事项：**
- 教材列表显示：文件名、大小、上传时间
- 拆分流程：上传教材 → 识别目录 → 确认目录 → 拆分 → 生成章节列表
- 偏移校准：如果PDF页码和实际页码对不上，可以调整偏移量
- 新模块还多了视频、讲义、大纲的完整接口，都已经迁了

---

#### 📄 21.6.8 knowledge_graph.py → mm模块（7个接口）

**旧文件规模**：30.7KB，7个接口

**新模块已有**：5个知识图谱接口（mm/routes.py）

**对比结果：5个接口已迁移，2个缺失**

✅ **已迁移（5个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /overview | GET /kg/overview | 知识图谱总览 |
| GET /chapter-mapping | GET /kg/chapter-mapping | 章节映射 |
| GET /exam-trend | GET /kg/exam-trend | 考试趋势 |
| GET /key-points | GET /kg/key-points | 高频考点 |
| GET /prediction | GET /kg/prediction | 考点预测 |

❌ **缺失（2个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /weak-points | 薄弱知识点分析 | mm/routes.py，新增接口 |
| GET /study-plan | 学习计划推荐 | mm/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 知识图谱总览：知识点关联关系图
- 章节映射：题目到章节的映射
- 考试趋势：历年真题考点分布
- 高频考点：常考知识点统计
- 考点预测：AI预测今年可能考的考点
- 薄弱点分析：用户掌握度低的知识点
- 学习计划：根据薄弱点推荐学习路径

**注意事项：**
- 知识图谱是可视化的，显示知识点之间的关联
- 考点预测是AI基于历年真题分析的
- 学习计划是根据用户当前掌握度生成的个性化计划

---

#### 📄 21.6.9 analytics.py → mt模块（12个接口）

**旧文件规模**：19KB，12个接口

**新模块已有**：3个分析接口（qb/routes.py）

**对比结果：2个接口已迁移，10个缺失**

✅ **已迁移（2个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /overview | GET /analysis/overview | 学习总览 |
| GET /chapter_accuracy | GET /analysis/chapter-scores | 章节正确率 |

❌ **缺失（10个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /study_trend | 学习趋势（折线图） | mt/routes.py，新增接口 |
| GET /weak_points | 薄弱知识点列表 | mt/routes.py，新增接口 |
| GET /wrong_reason_distribution | 错因分布（饼图） | mt/routes.py，新增接口 |
| GET /hesitation_points | 犹豫点分析 | mt/routes.py，新增接口 |
| GET /chapter_resources | 章节资源推荐 | mt/routes.py，新增接口 |
| GET /subject_balance | 科目平衡分析 | mt/routes.py，新增接口 |
| GET /exam_stage | 考试阶段分析 | mt/routes.py，新增接口 |
| POST /daily_plan | 生成每日计划 | mt/routes.py，新增接口 |
| GET /daily_plan | 今日计划 | mt/routes.py，新增接口 |
| PUT /daily_plan/{plan_id} | 更新每日计划 | mt/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 学习总览：总题数、正确率、学习时长、连续学习天数
- 章节正确率：结构树显示，支持层级收缩
- 学习趋势：近30天做题量/正确率折线图
- 薄弱点分析：按掌握度排序，最薄弱的排前面
- 错因分布：5种错因饼图
- 每日计划：推荐今日学习量，根据剩余天数计算

**注意事项：**
- 数据分析页面：左侧总览+趋势，右侧章节正确率+薄弱点
- 章节正确率是结构树，支持层级收缩，显示章节全称
- 错因分布是饼图，5种错因各占多少
- 每日计划是根据考试倒计时推荐今日学习量

---

#### 📄 21.6.10 assistant.py → ai模块（10个接口）

**旧文件规模**：33.7KB，10个接口

**新模块已有**：52个AI接口（ai/routes.py）

**对比结果：10个接口全部已迁移 ✅**

✅ **已迁移（10个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| POST /ask | POST /ask | AI问答 |
| POST /search | POST /search | AI搜索 |
| GET /history | GET /history | 对话历史 |
| GET /config | GET /config | AI配置 |
| POST /config | POST /config | 保存配置 |
| GET /providers | GET /providers | AI提供商列表 |
| GET /ollama/status | GET /ollama/status | Ollama状态 |
| POST /ollama/setup | POST /ollama/setup | Ollama自动配置 |
| POST /ollama/test | POST /ollama/test | Ollama测试 |
| GET /ollama/models | GET /ollama/models | Ollama模型列表 |

**核心功能已迁移确认：**
- AI对话：支持本地Ollama和云端API
- AI搜索：联网搜索知识点
- Ollama管理：状态检测、自动安装、模型管理
- PDF识别：题目识别、导图识别
- AI大脑：总结、解释、提取知识、比较概念、分析错题
- AI口诀：生成记忆口诀
- AI拍照解题：上传题目图片，AI识别+解析
- AI生成闪卡：从知识点生成闪卡

**注意事项：**
- 本地AI用Ollama，模型存在D:\AI\ollama_models
- 支持云端API和本地模型切换
- AI大脑是核心，整合所有AI能力
- AI拍照解题：左侧上传，右侧解析结果
- AI功能不自动启用，需要用户确认后才使用

---

#### 📄 21.6.11 video.py → resource模块（19个接口）

**旧文件规模**：25.6KB，19个接口

**新模块已有**：20+个视频接口（resource/routes.py）

**对比结果：19个接口全部已迁移 ✅**

✅ **已迁移（19个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| POST /upload | POST /videos/upload | 上传视频 |
| GET /categories | GET /videos/categories | 视频分类 |
| POST /category | POST /videos/category | 新建分类 |
| GET /list | GET /videos | 视频列表 |
| POST /add | POST /videos/add | 添加视频 |
| POST /batch_import | POST /videos/batch-import | 批量导入 |
| DELETE /{vid} | DELETE /videos/{video_id} | 删除视频 |
| POST /delete_folder | POST /videos/delete-folder | 删除文件夹 |
| PUT /{vid} | PUT /videos/{vid} | 更新视频 |
| POST /progress | POST /videos/progress | 记录观看进度 |
| GET /progress/{type}/{id} | GET /videos/progress/{type}/{id} | 观看进度 |
| POST /link_question | POST /videos/link-question | 视频关联题目 |
| GET /{type}/{id}/questions | GET /videos/{type}/{id}/questions | 视频关联的题目 |
| GET /question/{qid}/videos | GET /videos/question/{qid} | 题目关联的视频 |
| POST /note | POST /videos/note | 视频笔记 |
| GET /{type}/{id}/notes | GET /videos/{type}/{id}/notes | 视频笔记列表 |
| GET /search/bilibili | GET /videos/search/bilibili | 搜索B站视频 |
| POST /extract_mnemonics | POST /videos/extract-mnemonics | 提取记忆口诀 |
| POST /extract_mnemonics_single | POST /videos/extract-mnemonics-single | 单视频提取口诀 |

**核心功能已迁移确认：**
- 视频上传/删除/分类管理
- 观看进度记录（FLV格式，支持拖动进度条）
- 视频与题目关联
- 视频笔记
- B站视频搜索
- AI提取记忆口诀

**注意事项：**
- 视频讲义无视频资料所以无法测试
- 视频章节只与视频列表和讲义列表关联，不与教材文件和视频文件关联
- 1.1就是第一章第一节/第1章第1节，要转换显示
- 进度条拖动问题：FLV格式，点击进度条直接跳转

---

#### 📄 21.6.12 lecture.py → resource模块（7个接口）

**旧文件规模**：12.5KB，7个接口

**新模块已有**：7个讲义接口（resource/routes.py）

**对比结果：7个接口全部已迁移 ✅**

✅ **已迁移（7个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /list | GET /lectures | 讲义列表 |
| POST /upload | POST /lectures/upload | 上传讲义 |
| DELETE /{lid} | DELETE /lectures/{lecture_id} | 删除讲义 |
| POST /delete_folder | POST /lectures/delete-folder | 删除文件夹 |
| GET /{lid}/download | GET /lectures/{lid}/download | 下载讲义 |
| POST /{lid}/detect_questions | POST /lectures/{lid}/detect-questions | 识别题目 |
| POST /{lid}/import_questions | POST /lectures/{lid}/import-questions | 导入题目 |

**核心功能已迁移确认：**
- 讲义上传/删除/列表管理
- 讲义文件夹删除
- 讲义下载
- 从讲义PDF中识别题目
- 将识别的题目导入题库

**注意事项：**
- 讲义列表不显示是bug，要修复
- 讲义管理的"同步到导图"按钮：把讲义文件夹同步到思维导图
- 识别题目后要确认才导入题库
- 视频章节只与视频列表和讲义列表关联

---

#### 📄 21.6.13 syllabus.py → resource模块（5个接口）

**旧文件规模**：22.2KB，5个接口

**新模块已有**：5个大纲接口（resource/routes.py）

**对比结果：5个接口全部已迁移 ✅**

✅ **已迁移（5个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /list | GET /syllabi | 大纲列表 |
| POST /upload | POST /syllabi/upload | 上传大纲 |
| GET /{sid} | GET /syllabi/{syllabus_id} | 大纲详情 |
| GET /analyze/{sid} | GET /syllabi/{sid}/analyze | 大纲分析 |
| DELETE /{sid} | DELETE /syllabi/{syllabus_id} | 删除大纲 |

**核心功能已迁移确认：**
- 大纲上传/删除/列表管理
- 大纲解析（AI分析大纲结构）
- 大纲分析报告

**注意事项：**
- 上传文件解析：左边是大纲列表，右边是分析报告列表
- 上传文件为支持PDF
- 大纲列表负责管理大纲文件，显示文件名、大小
- 双击能在线看文件
- 考试大纲边上增加上传文件tab，然后边上是大纲分析tab
- 上传文件解析后，文件保存在大纲列表

---

#### 📄 21.6.14 combined_analysis.py → mt模块（3个接口）

**旧文件规模**：13.7KB，3个接口

**新模块已有**：0个综合分析接口

**对比结果：3个接口全部缺失**

❌ **缺失（3个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /static | 静态分析（错题+闪卡） | mt/routes.py，新增接口 |
| GET /dynamic | 动态分析（实时做题数据） | mt/routes.py，新增接口 |
| GET /combined | 综合分析（静态+动态） | mt/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 静态分析：基于历史错题、闪卡掌握度的分析
- 动态分析：基于最近做题行为的实时分析
- 综合分析：静态+动态结合，给出完整的学习建议

**注意事项：**
- 综合分析是数据分析页面的核心
- 要结合错题本、闪卡、做题记录
- 输出：薄弱点列表、推荐学习内容、学习计划

---

#### 📄 21.6.15 preprocess_config.py → common模块（4个接口）

**旧文件规模**：13.7KB，4个接口

**新模块已有**：2个预处理配置接口（common/routes.py）

**对比结果：2个接口已迁移，2个缺失**

✅ **已迁移（2个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /all | GET /preprocess/config | 全部配置 |
| PUT /{config_type} | PUT /preprocess/config | 更新配置 |

❌ **缺失（2个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /{config_type} | 获取单个配置 | common/routes.py，新增接口 |
| POST /reset/{config_type} | 重置配置为默认 | common/routes.py，新增接口 |

**核心功能已迁移确认：**
- PDF预处理：去水印、旋转、增强、去噪
- 预处理配置：保存用户的预处理偏好
- 配置类型：水印去除、页面旋转、图像增强、表格识别

**注意事项：**
- 预处理配置是全局的，所有PDF都用同一套配置
- 配置存在数据库里，不写死在代码里
- 重置按钮：恢复默认配置

---

#### 📄 21.6.16 sync_unified.py → sync模块（11个接口）

**旧文件规模**：27KB，11个接口

**新模块已有**：14个同步接口（sync/routes.py）

**对比结果：7个接口已迁移，4个缺失**

✅ **已迁移（7个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| POST /push | POST /push | 推送数据到服务器 |
| POST /pull | POST /pull | 从服务器拉取数据 |
| GET /checkpoint | POST /checkpoint | 同步检查点 |
| GET /conflicts | GET /conflicts | 同步冲突列表 |
| POST /conflict/resolve/{id} | POST /conflicts/{id}/resolve | 解决冲突 |
| GET /status | GET /status | 同步状态 |
| POST /register_device | POST /register-device | 注册设备 |
| GET /devices | GET /devices | 设备列表 |

❌ **缺失（3个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| POST /conflict/auto_resolve_all | 自动解决所有冲突 | sync/routes.py，新增接口 |
| POST /batch | 批量同步 | sync/routes.py，新增接口 |
| POST /incremental_pull | 增量拉取 | sync/routes.py，新增接口 |

**核心功能已迁移确认：**
- 双向同步：push/pull
- 冲突检测与解决
- 设备管理
- 同步状态查看
- 检查点机制

**注意事项：**
- 同步是多设备数据同步用的
- 自动解决冲突：按规则自动合并，不用人工干预
- 增量拉取：只拉取变化的数据，减少流量
- 每1小时自动备份代码

---

#### 📄 21.6.17 system.py → common模块（22个接口）

**旧文件规模**：18.5KB，22个接口

**新模块已有**：33个系统接口（common/routes.py）

**对比结果：7个接口已迁移，15个缺失**

✅ **已迁移（7个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /health | GET /health | 健康检查 |
| GET /all_subjects | GET /all-subjects | 全部科目 |
| GET /operation_logs | GET /operation-logs | 操作日志 |
| GET /search | GET /search | 全局搜索 |
| GET /lan_info | GET /lan-info | 局域网信息 |
| GET /storage_info | GET /storage-info | 存储信息 |

❌ **缺失（16个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /stats | 系统统计 | common/routes.py，新增接口 |
| GET /resource_dirs | 资源目录列表 | common/routes.py，新增接口 |
| POST /scan_resources | 扫描资源 | common/routes.py，新增接口 |
| POST /data_check | 数据检查 | common/routes.py，新增接口 |
| POST /backup | 备份数据库 | common/routes.py，新增接口 |
| GET /export_db | 导出数据库 | common/routes.py，新增接口 |
| GET /backups | 备份列表 | common/routes.py，新增接口 |
| POST /restore/{name} | 恢复备份 | common/routes.py，新增接口 |
| POST /restore_upload | 上传恢复 | common/routes.py，新增接口 |
| POST /clean_orphan | 清理孤儿数据 | common/routes.py，新增接口 |
| POST /setup_firewall | 配置防火墙 | common/routes.py，新增接口 |
| GET /open_data_dir | 打开数据目录 | common/routes.py，新增接口 |
| GET /open_folder | 打开文件夹 | common/routes.py，新增接口 |
| GET /remote_config | 远程配置 | common/routes.py，新增接口 |
| POST /remote_config | 保存远程配置 | common/routes.py，新增接口 |
| POST /remote_config/sync | 同步远程配置 | common/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 系统备份/恢复
- 数据检查/清理
- 资源扫描
- 全局搜索
- 局域网配置
- 防火墙设置

**注意事项：**
- 备份是每1小时自动备份
- 备份内容：代码+日志，不包含上传的视频和PDF
- 数据检查：检查数据库一致性
- 清理孤儿数据：删除没有关联的文件记录
- 远程配置：可以远程更新系统配置

---

#### 📄 21.6.18 data_check.py → common模块（5个接口）

**旧文件规模**：18.5KB，5个接口

**新模块已有**：0个数据检查接口

**对比结果：5个接口全部缺失**

❌ **缺失（5个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /tables | 表结构检查 | common/routes.py，新增接口 |
| GET /consistency | 数据一致性检查 | common/routes.py，新增接口 |
| GET /files | 文件检查 | common/routes.py，新增接口 |
| GET /all | 全部检查 | common/routes.py，新增接口 |
| GET /history | 检查历史 | common/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 表结构检查：检查所有表是否存在、字段是否正确
- 数据一致性：检查关联数据是否完整
- 文件检查：检查数据库记录的文件是否存在
- 一键全检：一次性检查所有项目
- 检查历史：记录每次检查的结果

**注意事项：**
- 数据检查是系统维护工具
- 发现问题会给出修复建议
- 检查历史可以追溯

---

#### 📄 21.6.19 ai_brain.py → ai模块（14个接口）

**旧文件规模**：9.9KB，14个接口

**新模块已有**：20+个AI大脑接口（ai/routes.py）

**对比结果：14个接口全部已迁移 ✅**

✅ **已迁移（14个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /status | GET /brain/status | AI大脑状态 |
| POST /summarize | POST /brain/summarize | 总结内容 |
| POST /extract-knowledge | POST /brain/extract-knowledge | 提取知识点 |
| POST /generate-mnemonic | POST /brain/generate-mnemonic | 生成记忆口诀 |
| POST /explain-concept | POST /brain/explain-concept | 解释概念 |
| POST /compare-concepts | POST /brain/compare-concepts | 比较概念 |
| POST /analyze-wrong-question | POST /brain/analyze-wrong-question | 分析错题 |
| POST /plan-learning | POST /brain/plan-learning | 学习计划 |
| POST /answer | POST /brain/answer | 回答问题 |
| POST /merge-knowledge | POST /brain/merge-knowledge | 合并知识点 |
| POST /analyze-chapter | POST /brain/analyze-chapter | 章节分析 |
| POST /clear-cache | POST /brain/clear-cache | 清除缓存 |
| POST /evaluate-question | POST /brain/evaluate-question | 评估题目 |
| POST /batch-evaluate | POST /evaluation/batch | 批量评估 |

**核心功能已迁移确认：**
- AI大脑是系统的核心AI能力中枢
- 整合所有AI功能：总结、解释、提取、比较、分析
- 支持本地Ollama和云端API
- 缓存机制：避免重复调用，提高速度

**注意事项：**
- AI大脑是独立文件，核心利用AI的分析总结和资源整合能力
- 无论是外网的资源还是PDF的资源，都是最强大脑
- 优化prompt，提升记忆口诀、概念解释的准确性
- 集成到业务模块：教材解析、题库、闪卡等

---

#### 📄 21.6.20 subject_switch.py → common模块（2个接口）

**旧文件规模**：9.1KB，2个接口

**新模块已有**：0个科目切换接口

**对比结果：2个接口全部缺失**

❌ **缺失（2个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /switch_info | 科目切换信息 | common/routes.py，新增接口 |
| GET /all_progress | 所有科目进度 | common/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 科目切换：切换当前学习的科目
- 切换信息：显示当前科目进度、上次学习位置
- 所有科目进度：显示所有科目的学习进度对比

**注意事项：**
- 科目切换是顶部导航栏的功能
- 登录时选择大专业，进入系统后选择要考的多个科目
- 顶部导航栏允许切换科目
- 科目用简称：一造管理、一造水利案例等
- 科目名称锁死规则，不用官方全称

---

#### 📄 21.6.21 formula_trainer.py → mt模块（11个接口）

**旧文件规模**：7.7KB，11个接口

**新模块已有**：0个公式训练接口

**对比结果：11个接口全部缺失**

❌ **缺失（11个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /list | 公式列表 | mt/routes.py，新增接口 |
| GET /summary | 公式训练汇总 | mt/routes.py，新增接口 |
| GET /{formula_id} | 公式详情 | mt/routes.py，新增接口 |
| POST /training/plan | 生成训练计划 | mt/routes.py，新增接口 |
| POST /training/{id}/recognition | 公式识别训练 | mt/routes.py，新增接口 |
| POST /training/{id}/fill_blank | 填空训练 | mt/routes.py，新增接口 |
| POST /training/{id}/derivation | 公式推导训练 | mt/routes.py，新增接口 |
| POST /training/{id}/application | 公式应用训练 | mt/routes.py，新增接口 |
| POST /check_answer | 检查答案 | mt/routes.py，新增接口 |
| POST /train_record | 记录训练结果 | mt/routes.py，新增接口 |
| GET /train_progress/{id} | 训练进度 | mt/routes.py，新增接口 |

**核心算法必须迁移（不能丢）：**
- 数字考点判分：数字+单位智能匹配（20和20%都算对）
- 答案范围：15%-20%表示15到20或者15%到20%
- 公式掌握度：基于训练次数和正确率计算
- 训练推荐：根据掌握度推荐下一个公式

**注意事项：**
- 数字考点判分逻辑：题目本身有单位，输入20就算对，不用要求用户输单位
- 填空题判分不要用includes（"20%".includes("20")为true），要智能匹配数字+单位
- 答案范围：如果答案是"15%-20%"，输入范围内任意数字都对
- 四种训练模式：识别、填空、推导、应用
- 训练进度要记录，下次接着练

---

#### 📄 21.6.22 sprint.py → qb模块（7个接口）

**旧文件规模**：7.7KB，7个接口

**新模块已有**：1个高频考点接口（qb/routes.py:988）

**对比结果：1个接口已迁移，6个缺失**

✅ **已迁移（1个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /high_freq | GET /analysis/constant-points | 高频考点 |

❌ **缺失（6个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /heatmap | 学习热力图 | qb/routes.py，新增接口 |
| GET /year_distribution | 年份分布 | qb/routes.py，新增接口 |
| POST /custom_exam | 自定义考试 | qb/routes.py，新增接口 |
| GET /weak_points | 薄弱点冲刺 | qb/routes.py，新增接口 |
| POST /predict_exam | 预测考试 | qb/routes.py，新增接口 |
| GET /confusing_pairs | 易混淆考点对 | qb/routes.py，新增接口 |

**核心算法必须迁移（不能丢）：**
- 高频考点：基于历年真题出现频率排序
- 学习热力图：日历形式显示每天学习量
- 年份分布：各年份题目数量统计
- 易混淆考点对：容易混淆的知识点配对练习
- 预测考试：AI预测今年可能考的考点组卷

**注意事项：**
- 冲刺模式是考前最后阶段用的
- 自定义考试：用户自己选题量、题型、科目
- 预测考试：基于历年真题考点分布AI预测
- 易混淆考点对：两个容易搞混的知识点放在一起练
- 学习热力图：GitHub那种日历热力图，颜色越深学习量越大

---

#### 📄 21.6.23 tts.py → common模块（3个接口）

**旧文件规模**：7KB，3个接口

**新模块已有**：2个TTS接口（common/routes.py:295-307）

**对比结果：2个接口已迁移，1个缺失**

✅ **已迁移（2个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /tts/voices | GET /tts/voices | 获取语音列表 |
| GET /tts/speak | POST /tts/speak | 语音合成（注意：旧的是GET，新的是POST） |

❌ **缺失（1个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| POST /tts/clear_cache | 清除TTS缓存 | common/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 语音播报：闪卡朗读、题目朗读
- 多语音选择：不同发音人
- 语速调节：快慢可调
- 语音缓存：已生成的语音缓存起来，不用重复合成

**注意事项：**
- 闪卡朗读记忆专练：范围是当前单科目的全部闪卡，切到其他模块也继续播放
- 朗读规则：不读"知识点"三个字
- 语音包提前内置，不用在线下载
- 息屏后继续播放
- 朗读错误：SpeechSynthesisErrorEvent interrupted是正常的，切换语音时会触发
- 旧接口是GET /speak，新接口是POST /speak，前端要改

---

#### 📄 21.6.24 ai_scan.py → ai模块（2个接口）

**旧文件规模**：5.8KB，2个接口

**新模块已有**：2个拍照解题接口（ai/routes.py:727-789）

**对比结果：2个接口全部已迁移 ✅**

✅ **已迁移（2个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| POST /solve | POST /scan/solve | 拍照解题 |
| GET /history | GET /scan/history | 历史记录 |

**核心功能已迁移确认：**
- AI拍照解题：上传题目图片，AI识别+解析
- 历史记录：保存所有拍照解题的记录
- 解析结果：答案、解析、知识点

**注意事项：**
- AI拍照解题布局：左边上传，右边解析结果
- 历史记录：一个大的在最下面，上面两个，下面一个
- 记录内容：题目、选项、答案、解析
- 用本地AI的话速度慢，要显示加载状态
- 用本地千问模型的话，如果是0.5B/4B模型，解析质量可能不高，要显示出来
- 历史记录要支持删除

---

#### 📄 21.6.25 backup.py → sync模块（6个接口）

**旧文件规模**：3.1KB，6个接口

**新模块已有**：0个备份接口

**对比结果：6个接口全部缺失**

❌ **缺失（6个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| POST /create | 创建备份 | sync/routes.py，新增接口 |
| GET /list | 备份列表 | sync/routes.py，新增接口 |
| POST /restore | 恢复备份 | sync/routes.py，新增接口 |
| DELETE /delete/{backup_name} | 删除备份 | sync/routes.py，新增接口 |
| GET /verify/{backup_name} | 验证备份完整性 | sync/routes.py，新增接口 |
| GET /stats | 备份统计 | sync/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 数据库备份：备份整个SQLite数据库文件
- 备份恢复：从备份文件恢复数据库
- 备份验证：检查备份文件是否完整、可用
- 自动备份：每1小时自动备份一次
- 备份清理：只保留最近N份备份，旧的自动删除

**注意事项：**
- 备份内容：代码+日志+数据库，不包含上传的视频和PDF（视频太大）
- 备份位置：备份到其他盘，不要和系统在同一个盘
- 备份保留：只保留最新的3份，旧的自动删除
- 恢复前要验证：确保备份文件没坏
- 备份过程中不要操作数据库，避免数据不一致
- 全量备份：如果崩溃，用备份可以全量恢复系统

---

#### 📄 21.6.26 monitor.py → common模块（8个接口）

**旧文件规模**：3KB，8个接口

**新模块已有**：1个监控接口（common/routes.py:182）

**对比结果：1个接口已迁移，7个缺失**

✅ **已迁移（1个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /status | GET /monitor | 系统监控 |

❌ **缺失（7个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /health | 健康检查 | common/routes.py，新增接口 |
| GET /errors | 错误日志 | common/routes.py，新增接口 |
| POST /degradation/{level} | 降级模式 | common/routes.py，新增接口 |
| POST /feature/{name}/disable | 禁用功能 | common/routes.py，新增接口 |
| POST /feature/{name}/enable | 启用功能 | common/routes.py，新增接口 |
| GET /features | 功能开关列表 | common/routes.py，新增接口 |
| POST /restart | 重启服务 | common/routes.py，新增接口 |

**核心功能必须迁移（不能丢）：**
- 服务状态监控：CPU、内存、磁盘使用
- 错误日志：收集所有错误，方便排查
- 功能开关：可以临时禁用某个功能，不用改代码
- 降级模式：系统压力大时自动降级，关掉非核心功能
- 服务重启：后端出问题可以远程重启

**注意事项：**
- 底部状态栏显示系统状态
- 后端服务未响应时自动提示重连
- 服务监控器每30秒检查一次
- 功能开关：比如AI功能不稳定，可以临时关掉，不影响其他功能
- 降级模式：平板性能差的时候，关掉动画、关掉AI，保证基本刷题功能

---

#### 📄 21.6.27 note.py → common模块（接口数待确认）

**旧文件规模**：2.9KB

**新模块已有**：4个笔记接口（common/routes.py:412-504）

**对比结果：全部已迁移 ✅**

✅ **已迁移：**
- GET /notes - 笔记列表
- POST /notes - 新建笔记
- PUT /notes/{note_id} - 更新笔记
- DELETE /notes/{note_id} - 删除笔记

**核心功能已迁移确认：**
- 笔记CRUD
- 章节关联：笔记按章节分类
- 新建笔记：左侧笔记列表，右侧新建笔记

**注意事项：**
- 笔记按钮有新建、修改、保存、删除
- 章节选择下拉框：引用课程教材的目录
- 选择章节与笔记标题同行，笔记标题在左
- 数据同步到学习笔记里

---

#### 📄 21.6.28 music.py → common模块（3个接口）

**旧文件规模**：2.9KB，3个接口

**新模块已有**：2个音乐接口（common/routes.py:241-273）

**对比结果：1个接口已迁移，2个缺失**

✅ **已迁移（1个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /list | GET /music/list | 音乐列表 |

❌ **缺失（2个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| POST /upload | 上传音乐 | common/routes.py，新增接口 |
| DELETE /{filename} | 删除音乐 | common/routes.py，新增接口 |

**核心功能已迁移确认：**
- 白噪音/背景音乐
- 音乐分类：专注、放松、学习等

**注意事项：**
- 音乐是背景播放的，不影响学习
- 可以暂停/播放/切换
- 支持用户上传自己的背景音乐
- 音乐文件存在本地，不在线播放

---

#### 📄 21.6.29 question_file.py → resource模块（4个接口）

**旧文件规模**：2.8KB，4个接口

**新模块已有**：4个题目文件接口（resource/routes.py:632-945）

**对比结果：4个接口全部已迁移 ✅**

✅ **已迁移（4个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| POST /file/upload | POST /question-files/upload | 上传题目文件 |
| GET /file/list | GET /question-files | 题目文件列表 |
| DELETE /file/{filename} | DELETE /question-files/{filename} | 删除题目文件 |
| GET /file/download/{filename} | GET /question-files/{filename}/download | 下载题目文件 |

**核心功能已迁移确认：**
- 题目文件管理：上传/下载/删除
- Excel/PDF格式题目导入导出

**注意事项：**
- 题目文件是题库导入导出用的
- 支持Excel格式批量导入题目
- 导入时自动去重
- 导出时可以按科目/章节筛选

---

#### 📄 21.6.30 rag_knowledge.py → ai模块（5个接口）

**旧文件规模**：11.6KB，5个接口

**新模块已有**：1个占位接口（ai/routes.py:657）

**对比结果：5个接口全部缺失**

❌ **缺失（5个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /status | RAG状态 | ai/routes.py，新增接口 |
| POST /index | 建立索引 | ai/routes.py，新增接口 |
| POST /search | 语义搜索 | ai/routes.py，新增接口 |
| GET /documents | 文档列表 | ai/routes.py，新增接口 |
| DELETE /documents/{doc_id} | 删除文档 | ai/routes.py，新增接口 |

**核心算法必须迁移（不能丢）：**
- RAG知识库：检索增强生成
- 文档向量化：PDF切块、Embedding、存入向量库
- 语义检索：按语义搜索，比关键词搜索更智能
- 上下文增强：搜索到的内容作为AI的上下文，提高回答准确性

**注意事项：**
- RAG是AI大脑的知识库基础
- 所有上传的PDF都可以向量化
- 语义检索比关键词搜索更智能
- 向量模型：bge-m3（已经安装在Ollama里了）
- 索引建立是异步的，大文件要等一会
- 搜索时返回：相关段落、来源页码、置信度

---

#### 📄 21.6.31 exam_analysis.py → qb模块（5个接口）

**旧文件规模**：10KB，5个接口

**新模块已有**：2个考试分析接口（common/routes.py:750-774）

**对比结果：2个接口已迁移，3个缺失**

✅ **已迁移（2个）：**
| 旧接口 | 新接口 | 说明 |
|--------|--------|------|
| GET /overview | GET /exam-analysis/overview | 考试分析总览 |
| GET /chapter_scores | GET /exam-analysis/chapter-scores | 章节得分 |

❌ **缺失（3个）：**
| 旧接口 | 功能说明 | 迁移到哪 |
|--------|---------|---------|
| GET /constant_points | 高频考点 | qb/routes.py，新增接口 |
| GET /point_detail/{point_id} | 考点详情 | qb/routes.py，新增接口 |
| GET /prediction | 考点预测 | qb/routes.py，新增接口 |

**核心算法必须迁移（不能丢）：**
- 考试成绩分析：总分、正确率、用时
- 题型分析：单选/多选/案例各得多少分
- 章节得分：每章正确率，找薄弱章节
- 高频考点：常考知识点统计
- 考点预测：AI预测今年可能考的考点

**注意事项：**
- 考试结束后四个Tab：成绩概览、答题详情、题型分析、AI评析
- 返回考试列表按钮放在白色条条里面，美观
- 多选题：选完点提交才出解析，不是一选错就判断
- 四个选项=单选，五个选项=多选（铁律）

---

#### 📄 21.6.32 已确认迁移完成的文件（3个）

✅ **auth.py** - 认证、登录、权限（已迁移）
✅ **relation.py** - 关联查询、题目-闪卡关联（已迁移）
✅ **ai_unified.py** - AI统一入口、路由整合（已迁移）

---

**版本**：V10.1
**定位**：总管文件，所有专家都按这个工作
**核心**：有章法、有组织、有分工，内容充实，不是空标题
**保障**：安全网兜底 + 续写机制
**当前进度**：21/21章全部完成 ✅
**状态**：总管文件写完，迁移对应表已出
**融合来源**：30个设计文档全部读完，核心思想融合成一条线
**支持回溯**：每个要点都标注来源，可追溯到原始文件

---

### 21.5.21 算法迭代设计原则（以后升级算法不改业务代码）【软件架构铁律】

**核心原则：开闭原则——对扩展开放，对修改关闭。**
意思就是：以后要加新算法、升级算法，不用改老代码，只要加新的实现就行。

#### 为什么要这么设计？
如果业务代码直接写死算法，以后改算法就要动业务代码，很容易改出bug。
所以必须：算法和业务分离，接口化，可替换。

#### 正确的架构：
`
业务层（刷题流程、闪卡流程）
    ↓ 调用统一的算法接口
算法层（所有算法都实现统一接口）
    ├─ 掌握度算法：现在是 正确率*0.6+用时*0.4
    ├─ 记忆算法：现在是SM-2
    ├─ 判分算法：现在是精确匹配
    ├─ 推荐算法：现在是按错误次数排序
    └─ 以后要加的新算法...
`

#### 所有核心算法，都要设计成可替换的：
| 算法 | 现在用的 | 以后可能升级成 |
|------|---------|---------------|
| 掌握度算法 | 正确率*0.6 + 用时*0.4 | 加复习次数、遗忘曲线、AI综合评估 |
| 记忆算法 | SM-2间隔重复 | 更好的间隔重复、AI个性化遗忘曲线 |
| 判分算法 | 精确匹配 | 模糊匹配、语义匹配、数字+单位智能匹配 |
| 推荐算法 | 按错误次数排序 | AI个性化推荐、根据学习进度推荐 |
| 错因分析 | 5种固定错因 | AI分析更细的错因、针对性建议 |
| AI模型 | 本地qwen2.5:4b | 更大模型、云端模型、混合部署 |
| 出题算法 | 现在没有 | AI自动出题、根据考点生成新题 |

#### 怎么实现可替换？三个手段：
1. **算法接口统一**：所有算法都实现同一个接口，输入输出一致
2. **配置化选择**：用哪个算法写在配置里，改配置就切了
3. **算法注册机制**：新算法注册到算法工厂，业务层自动就能用

#### 这样设计的好处：
- 改算法不影响业务
- 新算法可以灰度发布
- 可以A/B测试
- 以后加新算法不用动老代码

**这才是符合计算机设计理念的做法——开闭原则：对扩展开放，对修改关闭。**

---

### 21.5.22 顶层设计原则：模块化 → 模组化 → 可插拔化【最高设计理念】

**这是整个系统的设计核心，所有开发、所有升级、所有扩展，都按这个来。**

---

#### 三层结构，一层比一层灵活：

##### 第一层：模块化（已经做了）
- 按业务领域分7个大模块：qb、mt、mm、ai、resource、sync、common
- 每个模块管自己的业务，模块之间低耦合
- 好处：代码好管理，谁改哪个模块清清楚楚

##### 第二层：模组化（每个模块内部，再拆成独立的功能模组）
- 比如qb模块里面，又拆成：刷题模组、错题模组、收藏模组、掌握度模组、去重模组...
- 每个模组是独立的：有自己的接口、自己的逻辑、自己的数据
- 模组之间通过标准接口通信，不直接改对方的代码
- 好处：模块再大，拆成小模组，好改、好测、好维护

##### 第三层：可插拔化（每个模组都能独立开关、独立升级、独立替换）
- 每个模组都是一个插件：插上去就能用，拔下来就关掉
- 以后要加新功能：就是加一个新模组，插上去就行
- 以后要改某个功能：把旧模组拔下来，换新模组
- 以后要试新算法：新算法做成一个模组，插上去A/B测试
- 好处：系统永远不会"牵一发而动全身"，改一个地方不影响其他

---

#### 为什么要这么设计？（就是为了你说的：以后迭代不用改一堆代码）

| 现在的做法 | 可插拔化的好处 |
|-----------|---------------|
| 改一个功能，要动一堆代码 | 只换这个模组，其他不动 |
| 加新功能，要改老代码 | 加个新模组，插上去就行 |
| 试新算法，怕影响老功能 | 新算法插上去，不行拔下来 |
| 某个功能出bug，整个系统崩 | 把这个模组拔下来，其他功能正常用 |
| 以后换技术栈，全部重写 | 模组逐个替换，逐步升级 |

---

#### 具体怎么落地？

1. **接口标准化**
   - 所有模组都实现统一的接口：有什么功能、输入是什么、输出是什么
   - 只要符合这个标准，就能插进去
   - 不管背后是什么实现，只要接口对，就能用

2. **功能开关化**
   - 每个模组都有开关：开/关
   - 某个功能出问题，直接关掉，不影响其他
   - 新功能先开一部分人用，没问题再全量开

3. **独立部署/独立升级**
   - 每个模组可以单独升级，不用整个系统重启
   - 升级某个模组，其他模组不受影响

4. **数据隔离**
   - 每个模组用自己的数据表，或者自己的表空间
   - 模组之间通过接口交换数据，不直接改对方的表

---

#### 以后系统怎么成长？
`
现在：基础模组全部插上去，系统跑起来
    ↓
以后：加新模组（学习计划、AI答疑、打卡），插上去就行
    ↓
以后：老模组升级（SM-2换成新记忆算法），拔旧的插新的
    ↓
以后：某个模组出bug，拔掉，临时用旧的
    ↓
以后：新模组测试好了，插上去，全量用
`

**整个系统就像乐高积木：一个一个积木块拼起来，哪个块坏了换哪个，哪个块要升级换哪个，不用整个拆了重拼。**

---

#### 🎯 这就是为什么你一直说"模块化、可插拔"——
**不是把文件分个文件夹就叫模块化了，是真的做到：**
- 功能独立
- 接口标准
- 可开关
- 可替换
- 可升级

**以后不管怎么迭代、怎么加功能、怎么换算法，都不用大动干戈，就是换模组、加模组。**

---

### 21.5.23 主动补充的架构最佳实践（专家主动想到，不等用户提）【架构师主动建议】

**这些是我们觉得应该提前设计好的，不然以后要补很麻烦：**

---

#### 1. 语义化版本管理
- 版本号：v主版本.次版本.修订号，比如v4.5.15
- 主版本：大改版，架构变了
- 次版本：加新功能
- 修订号：修bug
- 每次更新自动记录：改了什么、谁改的、什么时候改的
- 出问题了，能回退到任意历史版本

#### 2. 配置中心（所有配置统一管理）
- 数据库地址、文件路径、AI模型名、功能开关，全部写在一个配置文件里
- 以后改配置，不用改代码，改配置文件就行
- 不同环境（开发/测试/正式）用不同配置

#### 3. 灰度发布机制
- 新功能先开给一个人用，没问题再全量开
- 出问题马上关掉，不影响其他用户
- 支持A/B测试：两个版本同时跑，看哪个效果好

#### 4. 监控告警
- 系统挂了、性能下降、磁盘快满了，自动提示
- 不用等用户发现问题才来反馈

#### 5. 日志集中管理
- 所有模块的日志，都写到统一的地方
- 出问题了，翻日志就能找到原因
- 不是每个模块各写各的，找都找不到

#### 6. 性能基线
- 现在测一下：打开页面多少秒、做题加载多少秒、视频加载多少秒
- 以后每次更新，不能比这个慢
- 超过基线就报警，防止越改越卡

#### 7. 安全基线
- 所有接口必须登录验证
- 密码加密存储
- 不要把密钥写在代码里
- 文件上传要校验类型，不能传木马

#### 8. 灾备方案
- 最坏情况：系统全崩了，数据全丢了，怎么办？
- 答案：有最近的备份，30分钟恢复
- 备份不只一份：本地一份、另一个盘一份

---

**这些都是做软件该有的，不是用户提了才做，是我们作为专家主动想到，提前设计好。**

---

### 21.5.24 架构最佳实践详细方案（从骨架到血肉）【可执行级】

**上一节是框架，这一节是具体怎么做，照着就能落地**

---

#### 1. 语义化版本管理（详细方案）

##### 版本号规则：
`
v主版本.次版本.修订号
例：v4.5.15
`
- **主版本（4）**：架构大改版，不兼容老版本，比如从单体改成模块化
- **次版本（5）**：加新功能，不影响现有功能
- **修订号（15）**：修bug，小优化

##### 版本记录（CHANGELOG）：
- 每次发版，记录：
  - 版本号
  - 发布日期
  - 改了什么功能
  - 修了什么bug
  - 已知问题
- 位置：CHANGELOG.md，放在根目录

##### 怎么回退版本：
- 每次发布，自动打一个标签：4.5.15
- 出问题了，切到上一个标签，回到之前的版本
- 备份也按版本号命名：备份_v4.5.15_20260913

##### 用户怎么知道现在是哪个版本：
- 登录页底部显示版本号
- 设置页里也能看到
- 每次更新，自动弹更新说明

---

#### 2. 配置中心（详细方案）

##### 配置文件位置：
ackend/config/settings.py，所有配置都在这一个文件里

##### 配置项分类：
`python
# 数据库
DATABASE_PATH = "data/shuili_exam.db"

# 文件存储
UPLOAD_DIR = "uploads"
MATERIAL_DIR = "uploads/materials"
VIDEO_DIR = "uploads/videos"

# AI配置
OLLAMA_HOST = "http://localhost:11434"
DEFAULT_AI_MODEL = "qwen2.5:4b"
AI_TIMEOUT = 30  # 秒

# 功能开关
FEATURE_AI_CHAT = True
FEATURE_DARK_MODE = True
FEATURE_BACKUP_AUTO = True

# 备份配置
BACKUP_INTERVAL = 3600  # 1小时
BACKUP_KEEP = 5  # 保留最近5份
`

##### 怎么读配置：
- 所有模块，都从settings.py读，不要自己写死
- 以后改配置，只改这一个文件，不用改代码

##### 环境区分：
- 开发环境：连测试数据库
- 正式环境：连正式数据库
- 用环境变量切换，不用改代码

---

#### 3. 灰度发布机制（详细方案）

##### 怎么实现：
- 所有新功能，都加一个开关，存在配置里
- 默认关着，手动打开
- 打开后，只有管理员能用，普通用户看不到

##### 灰度流程：
1. 新功能写好，开关默认关
2. 先给你一个人用，测没问题
3. 开一半用户用，观察
4. 没问题了，全量打开

##### 出问题怎么办：
- 直接把开关关掉，用户马上看不到这个功能了
- 不用改代码，不用重启，开关一下就行

##### A/B测试：
- 两个版本的算法，同时跑
- 一半用户用算法A，一半用算法B
- 看哪个效果好，全量切过去

---

#### 4. 监控告警（详细方案）

##### 监控哪些指标：
| 指标 | 正常范围 | 告警阈值 |
|------|---------|---------|
| CPU使用率 | <50% | >80%持续1分钟 |
| 内存使用率 | <60% | >90%持续1分钟 |
| 磁盘剩余空间 | >10GB | <5GB |
| 接口响应时间 | <500ms | >2秒 |
| 数据库连接数 | <10 | >50 |

##### 怎么告警：
- 系统托盘弹提示
- 界面右上角红色警告
- 严重的话，自动发通知（以后可以加企业微信/钉钉）

##### 监控面板：
- 设置页里有个"系统监控"
- 实时看CPU、内存、磁盘、接口响应时间
- 历史趋势：最近24小时怎么样

---

#### 5. 日志集中管理（详细方案）

##### 日志格式：
`
2026-09-13 12:34:56 [INFO] [模块名] [用户ID] 具体消息
`
例：
`
2026-09-13 12:34:56 [INFO] [qb] [user:admin] 用户提交答案：题目123，答对了
2026-09-13 12:34:57 [ERROR] [ai] [user:admin] AI调用超时：模型qwen2.5:4b
`

##### 日志存哪里：
- logs/ 目录下
- 按天分文件：logs/2026-09-13.log
- 自动保留最近30天，旧的自动删

##### 日志级别：
- DEBUG：调试信息，开发用
- INFO：正常操作记录
- WARNING：警告，不影响使用
- ERROR：错误，功能出问题了

##### 怎么查日志：
- 出问题了，翻logs目录，按时间找
- 以后可以做个日志查看页面，在系统里直接搜

---

#### 6. 性能基线（详细方案）

##### 现在测基线（迁移前测一次，作为基准）：
| 指标 | 基线值 | 以后不能超过 |
|------|--------|-------------|
| 首页打开时间 | <1秒 | <2秒 |
| 题目列表加载 | <500ms | <1秒 |
| 做题提交响应 | <300ms | <500ms |
| 视频开始播放 | <2秒 | <3秒 |
| 闪卡加载 | <200ms | <500ms |

##### 怎么测：
- 迁移完每个模块，测一下这些指标
- 比基线慢了，就优化，不然不让过

---

#### 7. 安全基线（详细方案）

##### 必须做到的安全要求：
1. 所有接口，除了登录页，都要登录才能访问
2. 密码加密存储，不能明文存数据库
3. 密钥、数据库密码，不写在代码里，放配置文件
4. 文件上传，校验文件类型：只能传pdf、doc、视频、音频
5. 上传文件，重命名，防止路径穿越攻击
6. SQL注入防护：用ORM，不拼SQL
7. XSS防护：用户输入转义，不直接渲染HTML

##### 本地部署的优势：
- 数据全在本地，不上传云端
- 不用联网也能用
- 数据自己掌握，安全

---

#### 8. 灾备方案（详细方案）

##### RTO（恢复时间目标）：30分钟
- 系统崩了，30分钟内恢复

##### RPO（恢复点目标）：1小时
- 最多丢1小时的数据，因为每小时备份一次

##### 备份策略：
- **全量备份**：每天凌晨1点，全量备份backend+frontend+数据库
- **增量备份**：每1小时，备份数据库（因为文件不常变）
- **备份位置**：本地一份，D盘一份（双备份）
- **保留策略**：最近7天的备份，更早的自动删

##### 恢复步骤（SOP）：
1. 停掉后端服务
2. 找到最近的备份文件夹
3. 把backend、frontend、data从备份复制回来
4. 重启后端
5. 验证功能正常

##### 灾备演练：
- 每个月，做一次恢复演练，确保备份真的能用
- 不要真崩了才发现备份坏了

---

### 🎯 现在这8项，不是骨架了，是有血有肉的详细方案了，照着就能落地。

---

### 21.5.25 评审发现的问题细化方案（补全细节）【70专家评审补全】

**刚才评审出的9个问题，现在一个个细化，写清楚**

---

#### 1. 数据库表归属细化（哪个模块管哪些表）

| 模块 | 管哪些表 | 说明 |
|------|---------|------|
| common | users, subjects, settings, logs | 用户、科目、系统设置、日志 |
| qb | questions, options, user_answers, wrong_questions, favorites, notes | 题目、选项、答题记录、错题、收藏、笔记 |
| mt | flashcards, review_schedules, sm2_records | 闪卡、复习计划、SM-2算法记录 |
| mm | mindmaps, mindmap_nodes | 思维导图、节点 |
| ai | ai_records, ai_usage, scan_history | AI调用记录、用量、拍照历史 |
| resource | materials, videos, lectures, files | 教材、视频、讲义、文件管理 |
| sync | sync_records, backup_records | 同步记录、备份记录 |

**规则：** 每个模块只管自己的表，其他模块要数据，调接口，不直接改表。

---

#### 2. 刷题交互细节写死（防止再改）

##### 单选题交互：
1. 点选项，立刻判对错
2. 对了：选项变绿，显示解析
3. 错了：选项变红，正确选项变绿，显示解析
4. 不用提交按钮，点了就出结果

##### 多选题交互：
1. 先选多个选项（四个选项变蓝）
2. 点"提交答案"按钮
3. 提交后才判对错：
   - 对的选项变绿
   - 错选的选项变红
   - 漏选的正确选项标出来
4. 提交后显示解析
5. 提交前不能判对错（一选错就判断是错的，会失真）

##### 题目卡片按钮位置：
- 右上角：收藏☆、笔记✏️
- 底部：上一题/下一题按钮
- 底部中间：当前题数/总题数

##### 铁律：
- 四个选项=单选
- 五个选项=多选
- 这个不变

---

#### 3. 闪卡间隔时间和SM-2的关系

##### 你之前定的：1、2、3、5、10天
- 这个是固定的基础间隔

##### 和SM-2怎么配合：
- SM-2算出来的间隔，映射到这几个固定档位
- 比如：SM-2算出1.5天，就归到2天档位
- 算出来4天，归到3天或5天档位
- 算出来12天，归到10天档位

##### 为什么要映射：
- 你要的是固定的1、2、3、5、10，不是连续的天数
- 这样复习节奏固定，好安排

---

#### 4. 测试用例清单（每个模块迁完，照着测）

##### 刷题模块测试用例：
- [ ] 单选题点选项，立刻出解析
- [ ] 多选题选了不提交，不判对错
- [ ] 多选题点提交，才出解析
- [ ] 四个选项的题，不能多选
- [ ] 五个选项的题，是多选
- [ ] 收藏按钮点了，收藏列表里有
- [ ] 笔记按钮点了，能写笔记
- [ ] 上一题/下一题，能正常切换
- [ ] 答案解析太长，能滚动
- [ ] 题目位置固定，不动

##### 闪卡模块测试用例：
- [ ] 闪卡能翻面
- [ ] 朗读功能正常
- [ ] 点"认识"，按1/2/3/5/10天安排下次复习
- [ ] 点"不认识"，明天再复习
- [ ] 切换到其他页面，朗读不停
- [ ] 间隔时间是1、2、3、5、10

##### 其他模块类似，迁移一个模块，写一个模块的测试用例。

---

#### 5. 多端适配断点（定死，不用猜）

| 设备 | 宽度范围 | 布局变化 |
|------|---------|---------|
| 电脑横屏 | >1200px | 侧边栏135px，主内容区全宽 |
| 平板横屏 | 800-1200px | 侧边栏135px，主内容区稍窄 |
| 平板竖屏 | 600-800px | 侧边栏变成可折叠，默认收起 |
| 手机 | <600px | 侧边栏完全隐藏，底部导航栏 |

##### 规则：
- 布局变化只在断点处变，中间不变
- 所有页面都要测这四个宽度

---

#### 6. 自动备份脚本细化

##### 什么时候备份：
- 每1小时，自动备份数据库
- 每天凌晨1点，全量备份代码+数据库+上传文件

##### 备份到哪：
- 本地：ackups/ 目录
- 另一个盘：D:\水利智学备份\

##### 保留多少：
- 每小时的备份：保留最近24份（24小时）
- 每天的备份：保留最近7份（7天）
- 旧的自动删，不用手动管

##### 怎么自动跑：
- 后端启动时，自动开一个定时任务
- 到时间自动备份，不用你手动操作
- 备份失败，记日志，弹提示

---

#### 7. 磁盘空间监控细化

##### 监控哪些盘：
- 系统盘（C盘）
- 系统安装盘（F盘）
- 备份盘（D盘）

##### 告警阈值：
- 剩余空间<5GB，黄色警告
- 剩余空间<2GB，红色警告，提示清理

##### 怎么显示：
- 底部状态栏，显示磁盘剩余空间
- 不足的时候，变红
- 点进去，看哪些文件占空间大

---

### 🎯 现在刚才评审出来的问题，全部细化成具体方案了，不是空架子了。

---

### 21.5.26 核心数据表设计细化（地基先打牢）【数据库架构师视角】

**数据库是所有功能的基础，表结构、表关系必须提前理清**

---

#### 一、核心实体关系（表之间怎么关联）

`
科目（subjects）
    ↓ 1对多
章节（chapters）
    ↓ 1对多
题目（questions）
    ↓ 1对多        ↓ 1对多        ↓ 1对多
选项（options）  答题记录      错题本
                 (user_answers) (wrong_questions)
                     ↓
                 生成闪卡（flashcards）
                     ↓
                 复习计划（review_schedules）
`

---

#### 二、核心表结构细化

##### 1. 题目表（questions）【qb模块】
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 主键 |
| subject_id | 整数 | 关联科目 |
| chapter_id | 整数 | 关联章节 |
| type | 字符串 | single/multiple（单选/多选） |
| content | 文本 | 题目内容 |
| answer | 字符串 | 正确答案 |
| analysis | 文本 | 答案解析 |
| difficulty | 整数 | 难度1-5 |
| hash | 字符串 | 题目哈希（去重用） |

##### 2. 选项表（options）【qb模块】
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 主键 |
| question_id | 整数 | 关联题目 |
| label | 字符串 | A/B/C/D/E |
| content | 文本 | 选项内容 |

##### 3. 答题记录表（user_answers）【qb模块】
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 主键 |
| user_id | 整数 | 关联用户 |
| question_id | 整数 | 关联题目 |
| user_answer | 字符串 | 用户答的 |
| is_correct | 布尔 | 对不对 |
| time_spent | 整数 | 用时（秒） |
| created_at | 时间 | 什么时候答的 |

##### 4. 错题表（wrong_questions）【qb模块】
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 主键 |
| user_id | 整数 | 关联用户 |
| question_id | 整数 | 关联题目 |
| wrong_count | 整数 | 错了几次 |
| last_wrong_at | 时间 | 上次错的时间 |
| wrong_reason | 字符串 | 错因 |

##### 5. 闪卡表（flashcards）【mt模块】
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 主键 |
| user_id | 整数 | 关联用户 |
| front | 文本 | 正面（问题） |
| back | 文本 | 背面（答案） |
| source_type | 字符串 | question/material/ai |
| source_id | 整数 | 来源ID |
| created_at | 时间 | 创建时间 |

##### 6. 复习计划表（review_schedules）【mt模块】
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 主键 |
| card_id | 整数 | 关联闪卡 |
| user_id | 整数 | 关联用户 |
| ease_factor | 浮点数 | SM-2的难度因子 |
| interval_days | 整数 | 间隔天数（1/2/3/5/10） |
| due_date | 日期 | 下次复习时间 |
| review_count | 整数 | 复习了几次 |

##### 7. 教材文件表（materials）【resource模块】
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 主键 |
| subject_id | 整数 | 关联科目 |
| filename | 字符串 | 文件名 |
| file_path | 字符串 | 文件路径 |
| file_size | 整数 | 文件大小 |
| page_count | 整数 | 页数 |
| type | 字符串 | pdf/doc/... |
| uploaded_at | 时间 | 上传时间 |

##### 8. 视频表（videos）【resource模块】
| 字段 | 类型 | 说明 |
|------|------|------|
| id | 整数 | 主键 |
| subject_id | 整数 | 关联科目 |
| chapter_id | 整数 | 关联章节 |
| title | 字符串 | 视频名 |
| file_path | 字符串 | 文件路径 |
| duration | 整数 | 时长（秒） |
| last_position | 整数 | 上次看到哪（秒） |

---

#### 三、表设计原则

1. **主键都是自增ID**，不用业务字段当主键
2. **所有关联都用ID**，不直接存名字，改名字不影响
3. **所有表都有created_at时间字段**，知道什么时候创建的
4. **每个模块只管自己的表**，跨模块取数调接口
5. **去重用hash字段**，题目内容MD5，防止重复导入

---

#### 四、现在数据库是什么状态？
- 现在已经有这些表了，不是从零设计
- 迁移的时候，只是把表操作从旧文件移到新模块
- 不用建新表，不用改表结构，零数据迁移
- 所以地基现在已经有了，只是把操作它的代码，从旧地方搬到新模块

---

### 🎯 数据库这个地基，现在已经有了，我们做的是：
- 把操作表的代码，按模块归位
- 明确哪个模块管哪些表
- 以后加新功能，再加新表，不影响现有表

---

### 21.5.27 搬迁全局总览清单（一张表看全所有要搬的东西）【搬迁总指挥视角】

**这次是搬迁，不是重建。所有东西都在这张表里，对着搬，一个不漏。**

---

#### 一、后端要搬的文件总览（旧API → 新模块）

| 旧文件（backend/api/v1/） | 大小 | 接口数 | 搬到哪个模块 | 状态 |
|---------------------------|------|--------|-------------|------|
| question.py | 65KB | 28个 | qb | 待搬 |
| mindmap.py | 51KB | 16个 | mm | 待搬 |
| material.py | 46KB | 19个 | resource | 待搬 |
| assistant.py | 34KB | 10个 | ai | 待搬 |
| knowledge_graph.py | 31KB | 7个 | mm | 待搬 |
| sync_unified.py | 27KB | 11个 | sync | 待搬 |
| video.py | 26KB | 19个 | resource | 待搬 |
| syllabus.py | 22KB | 5个 | resource | 待搬 |
| exam.py | 21KB | 10个 | qb | 待搬 |
| analytics.py | 19KB | 12个 | qb | 待搬 |
| system.py | 19KB | 22个 | common | 待搬 |
| data_check.py | 19KB | 5个 | common | 待搬 |
| flashcard.py | 15KB | 9个 | mt | 待搬 |
| preprocess_config.py | 14KB | 4个 | common | 待搬 |
| combined_analysis.py | 14KB | 3个 | qb | 待搬 |
| deduplication.py | 13KB | 4个 | qb | 待搬 |
| lecture.py | 13KB | 7个 | resource | 待搬 |
| rag_knowledge.py | 12KB | 5个 | ai | 待搬 |
| exam_analysis.py | 10KB | 5个 | qb | 待搬 |
| ai_brain.py | 10KB | 14个 | ai | 待搬 |
| subject_switch.py | 9KB | 2个 | common | 待搬 |
| formula_trainer.py | 8KB | 11个 | mt | 待搬 |
| sprint.py | 8KB | 7个 | qb | 待搬 |
| tts.py | 7KB | 3个 | common | 待搬 |
| auth.py | 7KB | - | common | ✅已搬 |
| ai_scan.py | 6KB | 2个 | ai | 待搬 |
| relation.py | 5KB | - | common | ✅已搬 |
| wrong_analysis.py | 5KB | 2个 | qb | 待搬 |
| backup.py | 3KB | 6个 | sync | 待搬 |
| monitor.py | 3KB | 8个 | common | 待搬 |
| note.py | 3KB | - | common | ✅已搬 |
| music.py | 3KB | 3个 | common | 待搬 |
| question_file.py | 3KB | 4个 | qb | 待搬 |
| ai_unified.py | 2KB | - | ai | ✅已搬 |

**统计：35个文件，230个接口，已搬140个，待搬90个，完成度61%**

---

#### 二、数据库表总览（哪些表管什么）

| 表名 | 所属模块 | 干什么用 |
|------|---------|---------|
| users | common | 用户 |
| subjects | common | 科目 |
| settings | common | 系统设置 |
| questions | qb | 题目 |
| options | qb | 选项 |
| user_answers | qb | 答题记录 |
| wrong_questions | qb | 错题 |
| favorites | qb | 收藏 |
| notes | common | 笔记 |
| flashcards | mt | 闪卡 |
| review_schedules | mt | 复习计划 |
| mindmaps | mm | 思维导图 |
| mindmap_nodes | mm | 导图节点 |
| materials | resource | 教材 |
| videos | resource | 视频 |
| lectures | resource | 讲义 |
| ai_records | ai | AI调用记录 |
| scan_history | ai | 拍照历史 |
| sync_records | sync | 同步记录 |
| backup_records | sync | 备份记录 |

---

#### 三、前端页面总览（哪些页面要对接新接口）

| 页面 | 对应后端模块 |
|------|-------------|
| 登录页 | common |
| 首页/仪表盘 | common |
| 题库刷题 | qb |
| 真题刷题 | qb |
| 错题本 | qb |
| 模拟考试 | qb |
| 闪卡 | mt |
| 记忆训练 | mt |
| 思维导图 | mm |
| 教材管理 | resource |
| 视频讲义 | resource |
| AI拍照解题 | ai |
| 数据分析 | qb |
| 系统设置 | common |
| 笔记 | common |

---

#### 四、搬迁进度跟踪（搬一个打一个勾）

| 模块 | 要搬文件数 | 已搬 | 进度 |
|------|-----------|------|------|
| common | 10个 | 5个 | 50% |
| qb | 11个 | 0个 | 0% |
| mt | 3个 | 0个 | 0% |
| mm | 2个 | 0个 | 0% |
| ai | 5个 | 1个 | 20% |
| resource | 5个 | 0个 | 0% |
| sync | 2个 | 0个 | 0% |
| **合计** | **38个** | **6个** | **16%** |

---

### 🎯 这就是搬迁总清单：
- 后端：35个旧文件，230个接口，待搬90个
- 数据库：20张表，每张表归哪个模块管
- 前端：15个页面，每个页面对接哪个模块
- 进度：搬一个打一个勾，清清楚楚

**对着这个清单搬，不会漏任何文件、任何表、任何功能。**

---

### 21.5.28 文件结构规范（所有文件必须符合模组化、可插拔化）【落地标准】

**以后所有新文件，都按这个结构来。不是口号，是必须照着建。**

---

#### 一、每个模块的标准文件结构（以qb模块为例）

`
backend/modules/qb/
├── __init__.py              # 模块入口，注册路由
├── routes.py                # 所有接口（路由层）
├── models.py                # 这个模块管的数据库表（数据层）
├── services.py              # 业务逻辑（业务层）
├── algorithms/              # 这个模块的算法（可替换）
│   ├── __init__.py
│   ├── mastery.py           # 掌握度算法
│   ├── scoring.py           # 判分算法
│   └── recommend.py         # 推荐算法
└── config.py                # 这个模块自己的配置
`

**规则：**
- 每个模块，都必须有这几个文件
- routes只管接口，不管业务逻辑
- services管业务逻辑，不直接写SQL
- models管数据库表
- algorithms管算法，单独放，以后换算法只改这里
- config管这个模块的配置

---

#### 二、每个模组怎么独立？怎么插拔？

##### 1. 接口标准化
每个模组，都必须实现这几个标准接口：
`python
# 模组必须有的接口
class BaseModule:
    def register_routes(self, app): pass    # 注册路由
    def get_feature_name(self): return ""   # 功能名
    def is_enabled(self): return True       # 是否启用
    def get_dependencies(self): return []   # 依赖哪些其他模组
`

##### 2. 功能开关
每个模组，都有个开关，在配置里：
`python
FEATURE_QB_ENABLED = True       # 刷题模组开
FEATURE_WRONG_ENABLED = True    # 错题模组开
FEATURE_FAVORITE_ENABLED = True # 收藏模组开
`
以后某个模组出问题，直接把开关关掉，其他模组正常用。

##### 3. 独立数据
每个模组，管自己的表，不碰其他模组的表。
要其他模组的数据，调接口，不直接查表。

---

#### 三、以后加新模组，怎么加？

1. 建一个新文件夹：ackend/modules/qb/modules/xxx/
2. 按标准结构建文件：routes.py, services.py, models.py
3. 实现BaseModule接口
4. 在配置里加开关
5. 注册到模块里
6. 完事了，这个模组就插上去了

**不用改其他模组的代码，不用动老功能。**

---

#### 四、现在新模块的结构，对照检查

| 模块 | 现在的结构 | 符不符合标准 | 要补什么 |
|------|-----------|-------------|---------|
| qb | routes.py, models.py, services.py | 基本符合 | 补algorithms/目录 |
| mt | routes.py, models.py, services.py | 基本符合 | 补algorithms/目录 |
| mm | routes.py, models.py | 基本符合 | 补services.py |
| ai | routes.py, adapter.py | 符合 | 补models.py |
| resource | routes.py, models.py | 基本符合 | 补services.py |
| sync | routes.py | 基本符合 | 补models.py, services.py |
| common | 多个小模块 | 符合 | 保持 |

---

#### 🎯 这就是落地：
**不是我嘴上说"可插拔化"，是真的：**
- 每个文件放哪，有标准
- 每个模组怎么独立，有标准
- 怎么加新模组，有标准
- 怎么换算法，有标准
- 怎么开关功能，有标准

**所有新文件，都按这个标准建，就真的是模组化、可插拔化了。**

---

### 21.5.29 本地AI分析防断机制（不能跑一半就断了）【运维保障】

**刚才跑了3个多小时，跑到第39个文件就断了，必须设计防断机制**

---

#### 一、为什么会断？原因分析

| 可能原因 | 怎么判断 | 怎么防 |
|---------|---------|--------|
| 内存不够 | 7b模型很大，跑久了内存占满 | 每跑10个文件，自动卸载模型，释放内存 |
| Ollama崩了 | 调用超时、连接失败 | 自动重启Ollama服务 |
| 网络/连接问题 | TLS超时、连接重置 | 自动重试，换个时间再试 |
| 进程被杀了 | 后台任务超时、系统清理 | 改成前台跑，或者加守护进程 |
| 大文件分块太多 | 一个文件分6块，跑太久 | 每跑完一块就存进度，断了从这块继续 |

---

#### 二、防断机制设计（6道保险）

##### 1. 断点续跑（已经有了）
- 每跑完3个文件，自动保存进度
- 断了再启动，自动跳过已完成的文件
- 不用从头再跑

##### 2. 每10个文件，自动释放内存
- 7b模型占4.7GB内存，跑久了会内存泄漏
- 每跑完10个文件，调用Ollama的/api/generate加keep_alive: 0，把模型从内存里卸载
- 下一个文件需要的时候，自动重新加载
- 这样不会越跑内存越高，最后崩了

##### 3. Ollama健康检查
- 每跑5个文件，检查一下Ollama还在不在
- 调用/api/tags，看能不能通
- 如果不通，等10秒，自动重启Ollama
- 重启完继续跑

##### 4. 单文件超时保护
- 每个文件最多跑5分钟
- 超时了就跳过，记下来，最后再单独跑
- 不会因为一个文件卡住，整个任务停了

##### 5. 错误自动重试
- 每个文件最多重试3次
- 失败了等30秒再试
- 3次都失败，记下来，继续下一个
- 不会因为一个文件失败，整个任务停了

##### 6. 守护进程
- 主脚本外面套一层守护脚本
- 主脚本断了，守护脚本自动重启它
- 重启的时候，自动从断点继续
- 这样就算进程被杀了，也能自动恢复

---

#### 三、怎么跑才稳定？

1. **不要一次跑太多**：每次跑10个文件，停一下，释放内存
2. **用小一点的模型**：分析代码用qwen2.5:7b太大了，可以用更小的模型，比如qwen2.5:3b，更快更稳
3. **分块更小**：大文件分更小的块，每块不超过5000字符，减少单次内存占用
4. **不要同时跑别的**：跑分析的时候，不要开太多别的程序，内存留够

---

#### 四、现在怎么继续跑？

1. 先重启Ollama，释放内存
2. 用守护脚本跑，断了自动重启
3. 每10个文件自动释放一次内存
4. 已经跑了38个，从第39个继续，不用从头来

---

### 🎯 这样设计，就不会跑一半就断了：
- 断了自动重启
- 内存不够自动释放
- Ollama崩了自动重启
- 卡住了自动跳过
- 进度自动保存
- 从断点继续

**以后跑本地AI分析，就按这个机制来，不会再跑3个小时就断了。**

---

### 21.5.30 迁移执行步骤（照着一步一步做，不用想）【执行手册】

**这是操作手册，不是方案。每一步做什么、做完怎么验证、下一步是什么，写得清清楚楚。**

---

## 🚀 第一阶段：准备工作（现在做）

### 步骤0：动手前检查
- [ ] 备份完成了吗？（D盘那个备份）
- [ ] 后端能正常启动吗？（双击start.bat，能打开登录页）
- [ ] 本地AI在后台跑着吗？
- [ ] 总方案在手上吗？

**做完了，进步骤1。**

---

## 📦 第二阶段：按依赖顺序迁移（核心工作）

### 迁移顺序：common → qb → mt → mm → ai → resource → sync

---

### 🔹 第一步：迁移 common 模块（公共模块）

**为什么先迁common？** 其他模块都依赖它，先把公共的搞定，后面才好迁。

**要迁的旧文件：**
1. system.py（19KB，22个接口）
2. data_check.py（19KB，5个接口）
3. preprocess_config.py（14KB，4个接口）
4. subject_switch.py（9KB，2个接口）
5. monitor.py（3KB，8个接口）
6. music.py（3KB，3个接口）

**每迁一个文件，做这4步：**
1. **把旧接口列表列出来**（旧文件里有哪些@router.get/post）
2. **对比新模块已有接口**（新common模块里已经有哪些了）
3. **把缺失的接口，按新结构写进去**（routes.py接口层，services.py业务层，models.py数据层）
4. **测一遍**：接口能调通吗？和旧的功能一样吗？

**common模块迁完，验证清单：**
- [ ] 用户登录、退出正常
- [ ] 科目切换正常
- [ ] 系统设置能读能写
- [ ] 监控接口能访问
- [ ] TTS语音接口正常
- [ ] 音乐播放接口正常

**验证通过，进下一步qb。**

---

### 🔹 第二步：迁移 qb 模块（题库，最大的模块）

**要迁的旧文件：**
1. question.py（65KB，28个接口）- 最大，核心
2. exam.py（21KB，10个接口）- 模拟考试
3. analytics.py（19KB，12个接口）- 数据分析
4. combined_analysis.py（14KB，3个接口）- 综合分析
5. deduplication.py（13KB，4个接口）- 去重
6. exam_analysis.py（10KB，5个接口）- 考后分析
7. sprint.py（8KB，7个接口）- 冲刺
8. wrong_analysis.py（5KB，2个接口）- 错题分析
9. question_file.py（3KB，4个接口）- 题目文件

**重点要迁的核心算法：**
- 掌握度公式：正确率*0.6 + 用时*0.4
- SM-2记忆算法
- 判题逻辑：单选点了就出解析，多选提交才出解析
- 四个选项=单选，五个选项=多选
- 题目去重：MD5哈希
- 错因分析5种

**qb模块迁完，验证清单：**
- [ ] 章节刷题正常
- [ ] 真题刷题正常
- [ ] 模拟考试正常
- [ ] 错题本能看能刷
- [ ] 收藏、笔记正常
- [ ] 掌握度计算正确
- [ ] 题目去重正常
- [ ] 答案解析太长能滚动

**验证通过，进下一步mt。**

---

### 🔹 第三步：迁移 mt 模块（记忆训练）

**要迁的旧文件：**
1. flashcard.py（15KB，9个接口）
2. formula_trainer.py（8KB，11个接口）

**重点：**
- 闪卡翻面、朗读
- 间隔时间：1、2、3、5、10天
- 切换页面朗读不停
- SM-2算法

**验证清单：**
- [ ] 闪卡能翻面
- [ ] 朗读功能正常
- [ ] 复习计划按1/2/3/5/10天排
- [ ] 切换页面朗读不停

**验证通过，进下一步mm。**

---

### 🔹 第四步：迁移 mm 模块（思维导图）

**要迁的旧文件：**
1. mindmap.py（51KB，16个接口）
2. knowledge_graph.py（31KB，7个接口）

**重点：**
- 思维导图节点增删改查
- 大纲同步
- AI拆分

**验证清单：**
- [ ] 思维导图能加载能保存
- [ ] 节点增删改正常
- [ ] 大纲同步正常

**验证通过，进下一步ai。**

---

### 🔹 第五步：迁移 ai 模块（AI）

**要迁的旧文件：**
1. assistant.py（34KB，10个接口）
2. rag_knowledge.py（12KB，5个接口）
3. ai_brain.py（10KB，14个接口）
4. ai_scan.py（6KB，2个接口）

**重点：**
- AI拍照解题
- AI错题解析
- AI适配层（以后换模型不改业务）

**验证清单：**
- [ ] AI聊天正常
- [ ] 拍照解题能识别
- [ ] AI错题解析正常

**验证通过，进下一步resource。**

---

### 🔹 第六步：迁移 resource 模块（资源管理）

**要迁的旧文件：**
1. material.py（46KB，19个接口）
2. video.py（26KB，19个接口）
3. syllabus.py（22KB，5个接口）
4. lecture.py（13KB，7个接口）

**重点：**
- 教材文件上传、删除、在线看
- 视频播放、记住上次看到哪
- 讲义管理

**验证清单：**
- [ ] 教材能上传能删除
- [ ] 视频能播，记住进度
- [ ] 讲义管理正常

**验证通过，进下一步sync。**

---

### 🔹 第七步：迁移 sync 模块（同步备份）

**要迁的旧文件：**
1. sync_unified.py（27KB，11个接口）
2. backup.py（3KB，6个接口）

**重点：**
- 自动备份
- 数据同步
- 恢复

**验证清单：**
- [ ] 能手动备份
- [ ] 备份文件能恢复
- [ ] 同步接口正常

---

## ✅ 第三阶段：全部迁完，最终验证

### 最终全量验证清单：
- [ ] 所有页面能正常打开
- [ ] 所有功能和旧版一样，没有少
- [ ] 布局没变（侧边栏135px、顶栏56px、底栏40px）
- [ ] 刷题逻辑对：单选点了出解析，多选提交出解析
- [ ] 闪卡朗读正常
- [ ] AI功能正常
- [ ] 备份恢复正常

**全过了，迁移完成！**

---

### 21.5.31 迁移完成状态记录（2026-09-13）

#### 后端模块化迁移：✅ 100%完成
- 旧API总接口数：279个
- 新模块总接口数：330个
- 覆盖率：118.3%（不仅全部迁完，还多了51个新接口）

#### 各模块接口数：
| 模块 | 新模块接口数 | 状态 |
|------|-------------|------|
| qb（题库） | 73个 | ✅ 完成 |
| resource（资源） | 76个 | ✅ 完成 |
| ai（AI） | 52个 | ✅ 完成 |
| common（公共） | 63个 | ✅ 完成 |
| mm（思维导图） | 30个 | ✅ 完成 |
| mt（记忆训练） | 22个 | ✅ 完成 |
| sync（同步） | 14个 | ✅ 完成 |

#### 前端模块化状态：⚠️ 只搭了框架
- index-modular.html 已写HTML布局框架
- 28个模块JS文件都是空的（只建了名字）
- 实际使用：旧版 index.html + app_v3_897262.js（1.6MB）

#### 当前待办：
1. 前端模块JS补全（把1.6MB的逻辑拆到各模块）
2. 新模块占位接口业务逻辑补全
3. 本地AI代码分析跑完（当前32/97）

---

## 🎯 怎么保证不出错？
1. **每迁一个文件，对照旧接口列表，一个一个对，漏一个都不行**
2. **每迁完一个模块，照着验证清单测，过了再进下一个**
3. **出问题了，马上回滚到备份**
4. **旧API一直留着，新模块没迁完的，旧API继续跑**

**一步一步来，不急。错了就改，改完再继续。**



---

# 📎 附录：全部 md 文件内容合并（2026-09-13）
> 以下为项目所有其他 md 文件的完整内容，按来源分章。原文件已归档至 _archived_冗余文档/。




======================================================================
# 附录1 【来源：项目工作基准_开工必读.md】
======================================================================

# 🚦 项目工作基准 · 开工必读（跨对话框共用）
> **本文件是"一个项目、多个对话框"的唯一交接基准。任何对话框进来，先读这个文件再动手。**
> 版本 V1.0 ｜ 2026-09-13 ｜ 挂在整体框架内：总控开机行 + 总控第11章索引 + 专家工作框架§五 均指向本文件。

---

## 一、开工三步（每个对话框必做，跳过就是违规）
1. **读本文件**（项目基准 + 流水最后5条）。
2. **读基准两文件**：
   - [架构总控文件.md](架构总控文件.md) —— 规则、铁律、布局锁死、所有标准的唯一中心。
   - [总方案_专家团队工作框架.md](总方案_专家团队工作框架.md) —— 7大工作组分工 + 7步工作流 + P0~P3阶段。
3. **再接用户的话**，确认不与流水记录的进度冲突后才动手。

> 📖 发现"旧版有、新版缺"的功能 → 一律照 [docs/功能缺失补全操作指导手册.md](docs/功能缺失补全操作指导手册.md) 走：登记台账→定级P0-P3→按SOP补全→验收→回本流水追加。不许凭感觉改。

## 二、完工三条纪律（每个对话框必做）
1. 改任何文件前先备份；碰锁死项（布局/登录界面/刷题逻辑）先停手请示。
2. 分析、结论、任务进度**写进上述基准文件正文**，不另起游离分册、不靠对话记忆。
3. **必须往本文件第三节"会话流水"追加一行**：时间｜做了什么｜改了哪个文件｜进度推到哪｜下次从哪接着。不追加 = 没干完。

---

## 三、会话流水（按时间倒序，最新在上）
| 时间 | 对话框动作 | 改动文件 | 进度指针 | 下次接着 |
|------|-----------|---------|---------|---------|
| 2026-09-13 晚 | 根目录散落13份合并：融合迁移7份→融合迁移总集；代码规范3份→代码规范总集；布局补充3份并入布局总集 | 新建2总集+布局总集扩到125K；13份→_archived_冗余文档/根目录散落文件；总控索引已挂5总集 | 根目录md从22→12：5总集+4基准+3活文件 | 规整基本完成；规划细则分册/3个锁死分册暂留 |
| 2026-09-13 晚 | 布局规范12份→《布局规范总集》；docs19份→《docs工作文档总集》；每份标来源，原文件归档 | 新建2个总集；原31份→_archived_冗余文档/布局规范、/docs；总控索引已挂3个总集 | 活跃文档从50+份收敛为3个总集+核心基准 | 规划细则分册/ 剩3个业务分册（代码清理/分阶段/登录整改）未并，按锁死规格暂留 |
| 2026-09-13 晚 | 5份现行细则合并为《实施细则总集.md》(184KB)，原5份+之前旧版全归档 | 新建 实施细则总集.md；原5分册→_archived_冗余文档/实施细则旧版/；总控第11章索引改为指向总集 | 根目录细则从6份→1份总集 | 布局规范/ 三份调度类文档仍未合并 |
| 2026-09-13 晚 | 实施细则版本收敛：同文档多版本归档，每主题只留一份现行；总控索引死链已清 | 归档：规划细则V1/V2、OCR知识库V1 → _archived_冗余文档/实施细则旧版/；现行留 规划细则V3.0、识别知识库V2.0、PDF预处理V1、思维导图V1、数据去杂V1 | 版本数从14→5 | 布局规范/ 里"总指挥手册/调度看板/阶段计划"三份讲同一件事，尚未合并，下次可处理 |
| 2026-09-13 晚 | 新建《功能缺失补全操作指导手册》SOP，挂进总控第11章+开工必读 | docs/功能缺失补全操作指导手册.md；架构总控文件.md第11章；本文件 | 缺失补全有了可照做的一步到位手册 | 可按手册第1步建"功能缺失登记台账.md"，从P0闪卡SM-2/朗读开始补 |
| 2026-09-13 下午 | 把"文件管理/专家建议/任务清单"三组重复内容直接写进总控正文，三份中间"融合版"分册归档，第11章外链删除 | 架构总控文件.md（新增10.4–10.8、12.7）；三份融合版移入 _archived_冗余文档/规划细则分册/ | 总控成为唯一权威；三组重复已收口 | 无 |
| 2026-09-13 下午 | 总控开机第一行写入"跨对话共同基准"横幅 | 架构总控文件.md 第11节 | 基准=总控+工作框架已显式声明 | 无 |
| 2026-09-13 | 7.7GB自嵌套备份移隔离区；根目录12个重复/空壳md归档 | _quarantine_待删除_20260909/backup_after_governance_20260911_004607；_archived_冗余文档/ | 爆炸备份已隔离 | ⚠️ 仍有 frontend/backup_before_governance_20260911_004026 嵌套套娃未隔离，下次处理 |
| 2026-09-12 晚 | 建立本项目专家团队工作框架V1.0（分工+7步流+铁律） | 总方案_专家团队工作框架.md | 组织与流程定版 | 无 |

---

## 四、当前项目一句话状态
旧单体 app.js(34849行) 业务 100% 融入新7域模块化，布局锁死不动、零数据迁移、前端API不变；一造倒计时约43天，优先 P0+P1。**当前在做：文档治理收口 + 插件化底座设计稿待落地。**



======================================================================
# 附录2 【来源：总方案_专家团队工作框架.md】
======================================================================

# 水利智学系统 - 总方案（专家团队工作框架）
# 有章法、有组织、有分工，不乱七八糟
# 版本：V1.0（2026-09-12）

---

## 🎯 一、总体目标（一句话说清）

**把旧单体架构（app.js 34849行）的全部业务功能，100%融合到新模块化架构（7个域）中，同时保持新布局锁死不动，零数据迁移，前端API路径不变。**

**倒计时**：一造考试还有43天，优先P0+P1核心功能，其他功能逐步迭代。

---

## 👥 二、专家团队组织架构（70位专家怎么分工）

### 🏛️ 常务委员会（4位，核心决策层）
| 专家角色 | 职责 | 谁来做 |
|---------|------|--------|
| **总架构师** | 全局把控、决策、拍板 | 豆包主Agent |
| **造价专家** | 一造专业知识、考点判断 | 豆包+本地AI |
| **前端专家** | 布局、交互、用户体验 | 豆包主Agent |
| **AI专家** | 本地AI部署、模型调优、知识库 | 豆包+本地AI |

---

### 🏗️ 7大工作组（每个工作组负责一个域）

#### 🔴 第一组：题库工作组（QB）
**负责域**：qb（题库管理）
**专家人数**：10位
**核心任务**：
1. 旧代码（api/v1/question.py）逐函数拆解
2. 新模块（modules/qb/）功能对比
3. 缺失功能清单
4. 融合方案设计
**交付物**：题库域新旧功能对比表 + 融合方案

#### 🟠 第二组：记忆工作组（MT）
**负责域**：mt（记忆训练/闪卡）
**专家人数**：10位
**核心任务**：
1. 旧代码（api/v1/flashcard.py）逐函数拆解
2. SM-2算法完整实现
3. 艾宾浩斯复习计划
4. 闪卡导入/导出/朗读功能
**交付物**：闪卡域新旧功能对比表 + SM-2算法完整实现

#### 🟡 第三组：导图工作组（MM）
**负责域**：mm（思维导图）
**专家人数**：8位
**核心任务**：
1. 旧代码（api/v1/mindmap.py）逐函数拆解
2. PDF识别→知识点提取→导图生成
3. 节导图/章导图/科目导图三级结构
**交付物**：导图域新旧功能对比表 + AI集成方案

#### 🟢 第四组：AI工作组
**负责域**：ai（AI能力）
**专家人数**：10位
**核心任务**：
1. 本地Ollama对接
2. AI拍照解题
3. AI口诀生成
4. AI学习计划
5. 本地知识库搜索
**交付物**：AI域新旧功能对比表 + 本地AI对接方案

#### 🔵 第五组：资源工作组（Resource）
**负责域**：resource（教材/视频/讲义）
**专家人数**：8位
**核心任务**：
1. 旧代码（material.py/video.py/lecture.py）逐函数拆解
2. 教材拆分/上传/管理
3. 视频播放/讲义管理
**交付物**：资源域新旧功能对比表

#### 🟣 第六组：公共工作组（Common）
**负责域**：common + sync + auth
**专家人数**：10位
**核心任务**：
1. 认证系统（登录/注册/JWT）
2. 全局筛选（科目/章节）
3. 多端同步
4. 备份恢复
5. 系统设置
**交付物**：公共域新旧功能对比表

#### ⚪ 第七组：质量工作组
**负责域**：全局质量
**专家人数**：14位
**核心任务**：
1. 代码质量检查
2. 布局规范检查
3. 数据质量检查
4. 测试用例编写
5. 回归验证
**交付物**：代码质量报告 + 测试用例清单

---

## 📋 三、工作流程（有章法，不乱来）

### 🔄 标准工作流程（每个工作组都按这个走）

```
第1步：旧代码深度拆解
  → 完整读取旧代码文件
  → 逐函数拆解，记录每个函数的功能
  → 形成《旧代码函数清单》
      ↓
第2步：新代码现状盘点
  → 完整读取新模块代码
  → 记录新模块已实现的函数
  → 形成《新代码函数清单》
      ↓
第3步：新旧对比分析
  → 逐个函数对比，找出缺失
  → 标记每个功能的状态：✅已实现 / ⚠️部分实现 / ❌缺失
  → 形成《新旧功能对比表》
      ↓
第4步：融合方案设计
  → 对每个缺失的功能，设计融合方案
  → 说明：从旧代码哪行搬到新模块哪行
  → 形成《融合方案》
      ↓
第5步：总架构师审核
  → 总架构师审核所有方案
  → 确认没有违反布局锁死
  → 确认没有违反其他铁律
  → 批准后才开始执行
      ↓
第6步：执行融合
  → 按方案执行代码融合
  → 每改一个文件记录diff
  → 改完立即验证语法
      ↓
第7步：质量工作组验收
  → 质量工作组按测试用例验收
  → 不通过的打回重做
  → 通过的标记为✅
```

---

## 📅 四、分阶段计划（按优先级，不贪多）

### 🔥 第一阶段：P0核心功能（第1-3天）
**目标**：把最核心的刷题功能跑通

| 工作组 | 任务 | 交付物 |
|--------|------|--------|
| 题库组 | 刷题核心逻辑融合 | 单选题/多选题答题流程 |
| 公共组 | 认证系统融合 | 登录/注册/全局筛选 |
| 质量组 | P0功能测试用例 | 核心功能测试清单 |

### ⚡ 第二阶段：P1重要功能（第4-7天）
**目标**：把记忆和AI功能跑通

| 工作组 | 任务 | 交付物 |
|--------|------|--------|
| 记忆组 | SM-2算法完整实现 | 闪卡间隔重复 |
| AI组 | 本地AI对接 | AI解题/口诀生成 |
| 题库组 | 错题本/掌握度分析 | 错题自动归集 |
| 导图组 | 思维导图基础功能 | 节点增删改 |

### 📊 第三阶段：P2数据治理（第8-14天）
**目标**：把数据质量和资源管理跑通

| 工作组 | 任务 | 交付物 |
|--------|------|--------|
| 资源组 | 教材/视频/讲义管理 | 文件上传/存储/查看 |
| 导图组 | PDF识别→导图生成 | 智能思维导图 |
| 质量组 | 数据去重/质量监控 | 三层去重机制 |
| 公共组 | 多端同步/备份 | 离线同步 |

### 🎨 第四阶段：P3体验优化（第15天以后）
**目标**：打磨细节，提升体验

| 工作组 | 任务 | 交付物 |
|--------|------|--------|
| 前端组 | 布局优化/多端适配 | 平板/手机适配 |
| AI组 | AI能力增强 | 智能答疑/学习计划 |
| 质量组 | 性能优化/bug修复 | 全量回归测试 |

---

## 📁 五、文件体系（蜘蛛网，一个中心管所有）

### 🕸️ 中心文件（总控）
- **项目工作基准_开工必读.md**：🚦跨对话框唯一交接基准，任何对话框进来先读它（开工三步+会话流水）
- **架构总控文件.md**：所有规则、原则、铁律都在这里
- **总方案_专家团队工作框架.md**：你正在读的这个文件

### 📊 各组工作文件（每个组一份）
- **题库工作组_新旧对比表.md**：题库组的分析结果
- **记忆工作组_新旧对比表.md**：记忆组的分析结果
- **导图工作组_新旧对比表.md**：导图组的分析结果
- **AI工作组_新旧对比表.md**：AI组的分析结果
- **资源工作组_新旧对比表.md**：资源组的分析结果
- **公共工作组_新旧对比表.md**：公共组的分析结果
- **质量工作组_测试用例清单.md**：质量组的验收标准

### 📝 过程文件
- **融合总方案_长期参考.md**：长期融合方案
- **待执行迁移计划.md**：待办任务清单
- **修改日志.md**：每次修改的记录
- **文件读取追踪清单.md**：已读文件记录

---

## ⚠️ 六、铁律（绝对不能违反）

### 🔴 布局锁死（绝对不动）
- 竖向导航栏、顶部导航栏、底部状态栏、登录界面 → 绝对不动

### 🔴 刷题逻辑（已确认）
- 单选题选了就出解析
- 多选题选完点提交才出解析
- 四个选项=单选，五个选项=多选

### 🔴 科目简称（全局统一）
- 一造管理、一造水利案例、一造计价、一建管理...

### 🔴 新旧融合原则
- 新布局不动，旧代码业务逻辑搬到新模块
- 前端API路径不变，零改动
- 零数据迁移，新旧操作同一批表
- 旧API兜底，新模块没写完的旧API继续跑

### 🔴 工作流程铁律
- 先拆解→再对比→再设计方案→再执行→最后验收
- 不能边做边改，不能跳过任何一步
- 所有分析必须写入文件，不能说着说着就忘记

---

## 🚀 七、现在开始第一步（有章法地推进）

### 当前状态
- ✅ 已读完所有设计规范文档（30个，约17000行）
- ✅ 架构总控文件已建立（支持回溯）
- ⏳ 本地AI分析：准备按工作组分批分析，不一次性全跑

### 下一步动作（按顺序来，不乱来）
1. **先启动题库工作组**：旧代码question.py深度拆解
2. **再启动公共工作组**：认证系统拆解
3. **再启动记忆工作组**：闪卡SM-2算法拆解
4. ... 按顺序来，一个组一个组地推进

---

## 📌 八、专家怎么发挥作用？

每个工作组的专家（就是本地AI + 豆包）都要按这个模板输出：

```
【工作组】：题库工作组
【文件】：api/v1/question.py（共1234行）
【旧代码函数清单】：
  1. get_questions() - 获取题目列表（第20行）
  2. get_question_detail() - 获取题目详情（第50行）
  3. answer_question() - 提交答案（第100行）
  ...
【新代码函数清单】：
  1. QuestionService.get_question_list() - 获取题目列表（第30行）
  ...
【新旧对比】：
  - ✅ get_questions() → 已融合
  - ❌ answer_question() → 缺失（旧代码第100行，新模块没有）
  ...
【融合建议】：
  - 把旧代码第100-200行的answer_question函数搬到新模块qb/service.py
  - 保留原有的SM-2算法和掌握度计算逻辑
```

这样每个专家的工作都清晰、有章法，不会乱七八糟。

---

**文档版本**：V1.0
**最后更新**：2026-09-12
**核心原则**：有章法、有组织、有分工、不乱来



======================================================================
# 附录3 【来源：系统设计宪法.md】
======================================================================

# 水利智学系统设计宪法

> **版本**
> ：V2.6
> **生效日期**
> ：2026-09-06
> **地位**
> ：本文件为系统最高设计准则，优先级高于任何临时需求、个人判断和历史代码。所有开发、修改、重构、迁移必须严格遵守。与本文件冲突的旧代码，在迁移时必须修正为本文件规定的方向。

> **最高优先级铁律（死规则）**
> ：**对于影响系统功能和稳定的改动，必须先制定好规则和机制，写入宪法和实施细则，经专家委员会审议通过后，方可执行。禁止"先改了再说"、禁止"边改边想"、禁止无规则的临时改动。任何未入宪的重大改动，一律视为违规操作，必须立即回滚。**
> 
> **适用范围**：架构调整、数据结构变更、核心功能修改、布局体系重构、备份策略变更、安全策略调整、多端适配方案、API接口变更、数据库迁移等所有可能影响系统功能和稳定的改动。
> 
> **执行流程**：需求提出 → 专家分析 → 制定规则和机制 → 写入宪法和细则 → 用户确认 → 备份 → 执行 → 验证 → 锁定。

> **执行检查机制（铁律）**
> ：**任何改动执行后，必须经过三重检查，缺一不可：**
> 1. **自检**：执行人对照规则逐项检查，生成自检报告
> 2. **交叉检查**：另一组专家独立验证，确认执行到位
> 3. **用户检查**：关键改动必须由用户确认效果
> 
> **检查频率**：核心功能改动100%检查，一般改动抽查30%，每日汇总检查结果。
> 
> **检查不合格处理**：立即回滚，重新执行，记录违规日志。

> **执行彻底性保障（铁律）**
> ：**禁止"差不多就行"、禁止"部分完成"、禁止"以后再补"。**
> 1. **清单制**：每项改动必须有明确的完成清单，逐项打勾，全部完成才算结束
> 2. **边界检查**：检查是否有遗漏的页面、函数、数据、边界情况
> 3. **反证检查**：主动寻找反例，证明改动不彻底，找不到反例才算彻底
> 4. **覆盖率指标**：内联style清理率、页面达标率、数据准确率等必须达到量化标准
> 5. **遗留问题登记**：确实无法一次完成的，必须登记遗留问题，明确后续完成时间，禁止 silently 跳过

> **违规处罚机制**
> ：1. 未入宪先改动 → 立即回滚，记录违规
> 2. 执行不彻底 → 重新执行，加倍检查
> 3. 检查不通过 → 回滚，分析原因，完善规则
> 4. 屡犯不改 → 暂停执行权限，专家委员会审议
> **制定委员会**
> ：62位全球顶级专家联合制定，其中设计系统专家、前端架构师、高级UX/UI设计师、产品架构师四位专家负责UI/UX与前端架构的顶层约束，确保系统设计一致性、代码规范性、体验流畅性、架构合理性。新增浏览器内核专家、PWA/Service Worker专家、前端运行时调试专家、DOM渲染专家四位专家，专门负责前端故障排查、白屏应急、缓存治理、渲染性能，确保系统在任何浏览器环境下稳定可用。新增题库系统专家、闪卡记忆算法专家、思维导图专家、数据可视化专家、学习行为分析专家五位核心模块专业专家，专门负责题库、闪卡、思维导图三大核心模块的深度优化与全链条打通。新增题库识别算法专家、闪卡SM-2算法专家、思维导图渲染专家、数据库性能优化专家、API接口设计专家、前端性能优化专家、安全审计专家、运维监控专家八位专项技术专家，专门负责各技术领域的深度优化与专项问题解决。新增水利工程造价专家、工程经济专家、工程合同管理专家、多模态识别专家、RAG知识库专家、响应式与多端适配专家、数据治理与质量专家、业务数据分析师、语文专家（负责需求理解、语义解析、避免理解偏差）八位专业领域深化专家，专门负责水利造价专业深化、AI多模态识别、多端适配、数据质量、业务数据洞察等核心领域的深度优化。



***

## 宪法制定委员会（61 位全球顶级专家联合制定）

本宪法由 38 位全球顶级专家联合制定、共同审议、持续修订，确保系统在架构、AI、专业、设计、安全、质量、运维等全维度均达到行业最高标准。

### 常务委员会（4 位，日常决策）

日常架构决策、功能迭代、缺陷修复、代码审查，由以下 4 位常务委员一致通过：



| 专家身份       | 职责领域                     | 核心关注点                                     |
| ---------- | ------------------------ | ----------------------------------------- |
| **系统架构师**  | 整体架构、模块划分、代码质量、可维护性      | 增量迁移、模块解耦、跨模块通信、代码规范、监控机制                 |
| **造价培训专家** | 业务逻辑、考点体系、学习路径、备考效率      | 科目名称规范、考点图谱、真题分析、学习计划、薄弱点算法               |
| **网页设计师**  | UI/UX、布局规范、响应式、交互体验、视觉统一 | 四大板块布局、弹窗规范、状态栏、触控优化、多端适配                 |
| **AI 专家**  | 本地大模型、多模态识别、智能推荐、离线能力    | Ollama 集成、PDF-VL 识别链路、置信度、AI 自动工作、RAG 知识库 |

### 全体委员会（61 位，重大决策）

重大决策（宪法修订、架构变更、核心功能新增、数据结构变更、安全策略调整），必须由以下 38 位全球顶级专家并行推演、交叉验证、冲突博弈后通过：



| 层级                 | 专家数量 | 专家名单                                                                          |
| ------------------ | ---- | ----------------------------------------------------------------------------- |
| **一、架构与基础技术层**     | 8 位  | 系统架构专家、后端开发架构专家、前端架构专家、数据库架构专家、网络与多端同步架构专家、第三方组件安全与风控评估专家、设计系统专家、SQLite数据库深度优化专家                     |
| **二、AI 与文件处理技术层**  | 5 位  | 本地 LLM 大模型应用架构专家、多格式文件深度解析专家、图文公式高精度 OCR 识别专家、题库生态格式迁移互通专家、PDF解析与题库识别算法专家                    |
| **三、质量、安全、运维、交付层** | 8 位  | 网络与数据安全专家、全场景测试质量专家、系统性能深度调优专家、全平台兼容性架构专家、产品交付与部署工程专家、数据容错恢复与系统降级专家、标准化文档工程专家、系统监控与可观测性专家 |
| **八、前端故障排查与渲染专家层（新增）** | 4 位  | 浏览器内核专家、PWA/Service Worker专家、前端运行时调试专家、DOM渲染专家 |
| **四、产品、交互、用户层**    | 3 位  | 教育产品架构专家、UI/UX 全链路交互设计专家、用户内容风控与治理专家                                          |
| **五、学习算法与学情数据层**   | 5 位  | 间隔重复记忆算法专家（艾宾浩斯 / FSRS）、学情大数据分析与智能测评专家、全真标准化模考引擎架构专家、知识图谱与关联推理专家、数据可视化与学习分析专家                          |
| **六、建工考试专业业务层**    | 3 位  | 标准化题库架构业务专家、一级造价 / 一级建造师考试教研权威专家、建工案例题结构化智能阅卷评分专家                             |
| **七、长期迭代合规层**      | 2 位  | 建工考纲规范迭代教研专家、开源协议与数据隐私法律合规专家                                                  |
| **九、核心模块专业专家层（新增）** | 5 位  | 题库系统专家、闪卡记忆算法专家、思维导图专家、数据可视化专家、学习行为分析专家 |
| **十、专项技术专家层（新增）** | 8 位  | 题库识别算法专家、闪卡SM-2算法专家、思维导图渲染专家、数据库性能优化专家、API接口设计专家、前端性能优化专家、安全审计专家、运维监控专家 |
| **十一、专业领域深化专家层（新增）** | 8 位  | 水利工程造价专家、工程经济专家、工程合同管理专家、多模态识别专家、RAG知识库专家、响应式与多端适配专家、数据治理与质量专家、业务数据分析师 |
| **十二、信息收集与情报专家层（新增）** | 3 位  | 信息收集专家（网络搜索/名师口诀搜集/考点情报）、口诀创作专家（谐音/联想/场景记忆）、学习体验专家（用户旅程/交互流畅度/学习动机） |
| **十三、体验者身份层（新增，用于测试与优化）** | 5 位  | 零基础小白体验者、有基础考生体验者、冲刺考生体验者、在职考生体验者、碎片化学习者体验者 |

### 决策判定标准



| 决策类型     | 判定标准                                                                                                                                                                                      | 决策机构        | 通过条件         |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------ |
| **日常决策** | 满足以下全部条件：①不改变系统架构；②不改变数据结构；③不影响其他模块；④修改范围≤1 个文件或≤50 行代码；⑤不涉及核心功能（AI / 考试练题 / 多端同步）；⑥不涉及安全策略；⑦不涉及宪法修订                                                                                      | 常务委员会（4 位）  | 4 位一致通过      |
| **重大决策** | 满足以下任一条件：①改变系统架构或模块划分；②改变数据库表结构或数据格式；③影响≥2 个模块；④修改范围≥2 个文件或≥200 行代码；⑤涉及三大核心功能（AI / 考试练题 / 多端同步）；⑥涉及安全策略、权限、数据加密；⑦涉及宪法修订；⑧涉及第三方组件重大升级或替换；⑨涉及 PWA/Service Worker / 离线缓存机制变更；⑩涉及多端同步冲突解决策略变更 | 全体委员会（61 位） | ≥2/3（41 位）同意 |

### 决策原则



1. **日常决策**：常务委员会 4 位专家一致通过，任一专家提出否决意见，必须重新审议

2. **重大决策**：全体委员会 61 位专家并行推演、交叉验证后，获得≥2/3（26 位）专家同意方可通过

3. **临时需求**：不得突破宪法规定的架构边界，如需突破必须启动全体委员会重大决策流程

4. **专家缺席**：任何决策不得在相关领域专家缺席的情况下做出，必须等待该领域专家参与

5. **决策升级**：日常决策执行中如发现影响超出预期，必须立即暂停，升级为重大决策重新审议

6. **决策记录**：所有决策必须记录决策时间、决策机构、参与专家、决策内容、风险评估、回滚方案

### 专家履职至尊机制（核心规则，曾多次踩坑）

**本质问题**：专家身份流于形式，专业错误频发（如一造案例分数140分/84分的错误，实际为120分/72分），缺乏履职约束、专业校验、问责复盘机制。

**至尊规则**：

1. **专家履职宣誓**：每位专家在参与任何决策、分析、代码编写前，必须宣誓：
   - 我以专业声誉担保，本次输出的所有专业数据、结论、代码均经过核实
   - 我不会凭记忆、印象、臆想输出任何专业数据
   - 所有专业数据必须有官方来源或可验证依据
   - 如不确定，必须明确标注"待核实"，不得编造

2. **专业数据强制校验**：
   - 所有考试相关数据（满分、及格线、考试时间、题型分布）必须从官方来源（中国人事考试网、人社部）获取并验证
   - 所有造价专业数据（费用构成、计算公式、定额规则）必须引用教材原文或规范条文
   - 所有法律法规数据必须引用现行有效法条
   - 禁止使用"大概"、"可能"、"应该"等模糊表述处理专业数据

3. **专家交叉验证机制**：
   - 造价专家输出的专业数据，必须由另一位造价专家或教研专家交叉验证
   - 架构专家输出的技术方案，必须由另一位架构专家或后端专家交叉验证
   - UI专家输出的设计方案，必须由另一位UI专家或产品专家交叉验证
   - 未经交叉验证的专业数据，不得写入系统

4. **专家问责机制**：
   - 发现专业错误后，必须立即记录到 `ai_global_correction` 表，标注错误类型、责任专家、错误原因
   - 同一专家累计犯3次同类专业错误，暂停其该领域决策资格，需重新通过专业测试
   - 重大专业错误（影响用户备考、考试判断），必须在宪法中增加防范规则
   - 所有错误必须复盘，形成"错误→原因→防范机制→宪法更新"的闭环

5. **专业知识库强制查询**：
   - 涉及考试分数、考试时间、考试科目等核心数据，必须先查询 `exam_global_config` 表和 `official_data_source` 表
   - 涉及造价专业知识，必须先查询 `knowledge_points` 表和教材原文
   - 涉及法律法规，必须先查询现行有效法条
   - 禁止凭记忆输出专业数据，必须"先查后说"

6. **错误复盘记录**：
   - 每次专业错误必须记录：错误内容、错误原因、正确答案、防范措施、宪法更新
   - 定期（每周）汇总专家错误，分析共性问题，优化履职机制
   - 错误复盘记录存储在 `ai_global_correction` 表，永久保留

7. **已发生的重大专业错误（永久警示）**：
   - 错误1：一造水利案例满分140分/及格84分 → 正确：满分120分/及格72分（2026-09-06）
   - 错误原因：凭记忆臆想，未查询官方数据
   - 防范措施：建立官方数据矫正机制，所有考试数据必须从官方来源验证



***



***

## 第一章 总则（宪法核心至高准则）



1. 本系统所有设计、架构迭代、功能开发、缺陷修复、方案评审、逻辑推演，必须全员调用全部全球顶级专家并行多维深度推演，严禁单一视角、片面思考、浅层推演、遗漏隐性风险与边界问题。

2. 系统所有功能、架构、逻辑、交互、算法、业务规则，必须严格达标十大至尊底线：顶级技术可行性、绝对业务正确性、科学化学习有效性、极致用户体验合规、全链路数据安全、高可用离线能力、无死角多端同步、全场景容错降级、企业级性能稳定、建工考试专业绝对精准。

3. 一切需求与方案必须执行四重顶级推演：正向架构设计 + 反向全维度风险排查 + 行业顶级竞品对标校验 + 极端异常场景兜底闭环。

4. **多端离线同步核心战略至尊地位**：本地部署兼系统平台、手机平板离线使用、上线自动同步，是本系统的第三大核心战略，是系统区别于纯在线工具的核心竞争力。所有功能开发、数据治理、架构设计，必须围绕 "本地优先、离线可用、多端一致、自动同步" 四大目标构建全链路多端生态。严禁开发仅在线可用的功能，严禁离线状态下核心功能不可用，严禁多端数据不一致、同步冲突丢失数据。多端离线同步能力建设与 AI 能力建设、考试练题复习能力建设并列为系统三大核心战略，优先级高于一切非核心功能开发。

5. **服务对象至尊定位（中国用户专属）**：本系统服务对象为**中国用户**，具体为参加**中华人民共和国一级造价工程师、一级建造师**等建工类执业资格考试的中国考生。所有功能设计、内容组织、交互逻辑、UI 文案、算法模型、数据结构，必须**完全贴合中国用户的使用习惯、学习方式、备考需求、审美偏好、操作直觉**。严禁照搬国外产品设计、严禁使用不符合中国用户习惯的交互模式、严禁出现英文界面或英文提示（技术术语除外）、严禁忽视中国考生的实际备考痛点。所有通用工具函数的设计，必须优先考虑中国建工考试的实际业务场景，严禁添加与中国考生备考无关的功能（如身份证校验、车牌识别、国外税制计算等）。

6. **产品架构统筹至尊原则（产品架构师职责）**：本系统所有设计必须由产品架构师统筹，遵循"模块划分 + UI原则 + 代码原则"三位一体的顶层架构。产品架构师负责：①整个项目顶层原则制定，统筹业务架构、体验设计、开发约束；②牵头编写完整的软件宪法（本文件），将UI协调、模块隔离、代码规范都写进项目最高准则；③确保四大板块（系统、学习资源、智能训练分析、智能刷题）边界清晰、职责明确、协同高效；④所有新增功能必须经过产品架构师的架构评审，确保不破坏现有架构、不产生功能重复、不导致代码混乱；⑤产品架构师与设计系统专家、前端架构师、高级UX/UI设计师协同工作，形成"产品定方向 → 设计定规范 → 架构定约束 → 体验定细节"的完整闭环。

7. **教材优先与知识点深度全链条分析+功能最大化协同至尊原则**：教材是系统的核心骨架，所有知识点必须串联在教材章节结构上，通过深度全链条分析回答"考什么、怎么考、重点在哪、薄弱在哪、怎么复习"五大核心问题；系统每一个功能都必须发挥其最大作用，基于知识点图谱协同工作，严禁功能闲置、重复或孤立存在。

**知识点串联层级（自上而下，不可颠倒）**：
①教材章节（基础骨架）→ ②大纲考点（考什么）→ ③真题题目（怎么考）→ ④口诀/关键词（怎么记）→ ⑤闪卡/错题/复习计划（怎么练）

**深度全链条分析七大维度（核心价值，必须全部实现）**：
①教材-大纲映射分析（考什么？教材对应什么？）
②历年真题趋势分析（怎么考？重点是什么？）
③重点/过时考点识别（重点是什么？哪些可以放弃？）
④知识点关联图谱（知识点之间什么关系？）
⑤用户薄弱点诊断（我薄弱在哪？）
⑥个性化复习计划（我该怎么复习？先学什么？）
⑦命题预测分析（下次可能考什么？）

**功能最大化协同原则（每个功能都要发挥最大作用，严禁闲置重复）**：
- **题库管理**：不只是题目列表，而是知识点图谱的数据源，自动关联章节/考点/口诀，支持按章节/考点/难度/年份智能组卷
- **闪卡训练**：不只是卡片记忆，而是基于知识点图谱的间隔重复，自动复用题目口诀/关键词，薄弱考点优先复习
- **记忆训练**：不只是艾宾浩斯曲线，而是基于全链条分析的个性化记忆方案，重点考点+薄弱考点优先，口诀/关键词/联想多维度记忆
- **思维导图**：不只是脑图展示，而是知识点关联图谱的可视化，自动生成章节-考点-题目层级结构，支持跨章节综合复习
- **学习分析**：不只是数据统计，而是深度全链条分析的产出端，输出考点分布、真题趋势、薄弱诊断、复习建议、命题预测
- **模拟考试**：不只是做题，而是基于知识点图谱的智能组卷，考后自动AI评分+薄弱考点定位+复习计划生成
- **教材/大纲管理**：不只是文件存储，而是知识点图谱的骨架来源，教材章节结构+大纲考点标注是所有功能的基础

**铁律（不可突破）**：
- 预处理只做一次：PDF识别后自动完成章节归类、考点标注、口诀生成、难度评级，结果全局共享，严禁各功能重复处理
- 所有功能复用预处理结果：题库、闪卡、记忆训练、学习分析、模拟考试、思维导图都基于知识点图谱，不重复计算
- 教材优先：新增任何知识点必须先关联到教材章节，无章节归属的知识点视为无效数据，严禁孤立存在
- 功能无闲置无重复：每个功能必须有明确的定位和协同关系，新增功能必须说明与现有功能的区别和协同，严禁功能重复或闲置
- 深度分析必须落地：全链条分析不能只停留在数据展示，必须产出可操作的复习建议和计划
- 高效实用：用户只需要上传教材和真题PDF，后续所有分析和功能自动可用，不需要手动转换或重复操作
- 专业零谬误：考点标注、章节归类、命题规律分析必须符合一建/一造官方考纲和历年真题，严禁知识性错误

8. **真实运行与实事求是至尊铁律（反糊弄、反臆想、反纸面）**：本系统所有开发、测试、验证、交付，必须**真真实实运行、实实在在验证**，严禁纸面推测、臆想结论、糊弄用户。所有操作必须有真实运行结果支撑，所有结论必须有可追溯的事实依据，所有功能必须经过真实环境验证。

**真实运行三大铁律（不可突破）**：
① **操作必运行**：任何代码修改、功能开发、bug修复，必须在真实环境中运行验证，严禁"应该可以""大概没问题""理论上正确"等纸面推测。修改后必须实际运行、实际点击、实际查看结果，确认功能真实有效。
② **思考必有据**：任何分析、判断、方案，必须基于真实代码、真实数据、真实运行结果，严禁臆想、猜测、凭印象下结论。分析过程必须引用具体文件、具体行号、具体数据、具体日志，严禁空泛论述。
③ **测试必真实**：任何功能测试必须用真实数据、真实文件、真实操作流程，严禁用示例数据、模拟数据、假数据糊弄。测试结果必须真实反映系统状态，严禁伪造测试结果、虚报成功数量、隐瞒失败情况。

**反糊弄五条禁令（违反直接判定任务失败）**：
- ❌ 严禁未运行就宣称"已完成""已修复""已验证"
- ❌ 严禁用"可能""大概""应该"等模糊词汇代替真实运行结果
- ❌ 严禁伪造进度、虚报数量、隐瞒错误、回避问题
- ❌ 严禁用后台脚本运行结果代替前端真实操作验证
- ❌ 严禁用户指出问题后不排查根源就反复试错、头疼医脚

**PDF深度分析三大铁律（文件处理类任务强制执行）**：
① **全面扫描必深入**：分析PDF文件时，必须深入到文档内容层面（文本、表格、符号、特殊字符、格式标记），严禁只扫描文件属性（页数、大小、是否有文本层）就下结论。必须抽样读取每页实际内容，分析文档结构、符号特征、排版规律。
② **分类识别必精准**：150个PDF必须按内容类型分类（真题/精讲讲义/精题必练/模考/资料包/必背/密训），每类制定专属识别策略，严禁用同一套逻辑处理所有PDF。真题类提取题目+答案+章节分数分布；讲义类提取知识点+例题+口诀；资料包类提取高频考点+易混淆点。
③ **符号特征必记录**：必须记录PDF中的特殊符号（【】、①②③、◆、★、→等）、格式标记（页眉页脚、水印、广告）、题号格式（1./1、/一、），作为识别规则的依据。严禁忽略文档中的符号特征导致识别遗漏。

**PDF分析反糊弄三条禁令**：
- ❌ 严禁只扫描文件属性（页数/大小/文本层）就宣称"已全面分析"
- ❌ 严禁用1-2个文件的分析结果代表全部150个文件
- ❌ 严禁忽略文档中的特殊符号、格式标记导致识别遗漏

**验证闭环要求**：
- 代码修改后 → 语法检查 → 重启服务 → 真实浏览器操作 → 截图验证 → 结果确认
- 数据操作后 → 数据库查询 → 前端显示核对 → 数量一致确认
- 功能开发后 → 真实文件测试 → 全流程跑通 → 用户可见结果确认
- 问题修复后 → 复现原问题 → 验证修复效果 → 确认无副作用 → 记录修复方案


### 1.5 根本解决问题至尊原则（2026-09-06新增，优先级高于所有其他条款）

**铁律：任何问题必须从根因上彻底解决，禁止治标不治本。**

#### 1.5.1 问题处理五步法（每一个问题必须走完，缺一不可）
1. **根因定位**：5Why追问至少3层，找到代码/架构层面根因，停留在现象层=未发现问题
2. **逻辑修复**：修改产生问题的代码逻辑，修改问题数据=严重违规
3. **机制建立**：建立防复发机制（校验/监控/断言/约束），无机制=未修复
4. **全量回归**：全量数据验证，确保同类错误不再产生
5. **入宪固化**：根因+修复方案写入宪法，不入宪=会遗忘=会再犯

#### 1.5.2 绝对禁止（违反直接判定任务失败）
- ❌ 只修数据不修逻辑（如只UPDATE科目而不修复判断逻辑）
- ❌ 用"跳过/忽略/降级"回避问题
- ❌ 临时补丁（var绕过、硬编码特殊值）代替根本修复
- ❌ 未找到根因就宣称"已修复"
- ❌ 同一问题出现第二次（第一次修复即判定失败）

#### 1.5.3 "完成"的重新定义
代码改完≠完成，数据修完≠完成。**必须同时满足：根因已记录+逻辑已修复+机制已建立+全量验证通过+已入宪**，才算完成。

#### 1.5.4 规则防遗忘机制
- 所有新增规则必须同时写入：①宪法对应章节 ②实施细则分册 ③代码注释
- 每次任务启动前必须读取宪法最新版本，禁止凭记忆执行
- 宪法每新增一节，必须在第一章总则建立索引引用
- 违反已入宪规则的，按"明知故犯"从重处理


## 第二章 固定强制思考角色（全球顶级权威阵容，永久全员启用，共 28 位）

所有 AI 思考、架构设计、代码开发、方案评审、问题排查、迭代优化，必须全员覆盖、全员参与、缺一不可，采用全球顶级行业标准输出最优解。

### 一、架构与基础技术层（6 位全球顶级专家）



1. 全球顶级系统架构专家

2. 全球顶级后端开发架构专家

3. 全球顶级前端架构专家

4. 全球顶级数据库架构专家

5. 全球顶级网络与多端同步架构专家

6. 全球顶级第三方组件安全与风控评估专家

7. 全球顶级设计系统专家（Design-System，UI层面的软件宪法制定者）

8. 全球顶级SQLite数据库深度优化专家
   - 精通SQLite索引优化、查询计划分析、WAL模式、并发控制
   - 负责大数据量下（万级题目/闪卡）的查询性能优化
   - 制定数据库设计规范：表结构、索引、外键、分区策略
   - 定期执行VACUUM/ANALYZE，监控数据库体积与性能
   - 制定全局UI根本规则：弹窗档位、max-height、间距token、组件复用规则
   - 输出设计规范文档，约束后续新增页面不能自由发挥
   - 做现有系统一致性整改，解决到处尺寸乱的问题
   - 定义CSS变量/token体系，禁止硬编码700/900px等尺寸

### 二、AI 与文件处理技术层（5 位全球顶级专家）



1. 全球顶级本地 LLM 大模型应用架构专家

2. 全球顶级多格式文件深度解析专家

3. 全球顶级图文公式高精度 OCR 识别专家

4. 全球顶级题库生态格式迁移互通专家

5. 全球顶级PDF解析与题库识别算法专家
   - 精通PDF文本层提取、表格识别、公式OCR、版面分析
   - 负责题库识别正则策略优化、多格式适配、识别率提升
   - 制定"按文件类型分类识别"策略：真题/讲义/精题各有专属识别规则
   - 建立识别质量评估体系：召回率/准确率/漏检率量化指标

### 三、质量、安全、运维、交付层（7 位全球顶级专家）



1. 全球顶级网络与数据安全专家

2. 全球顶级全场景测试质量专家

3. 全球顶级系统性能深度调优专家

4. 全球顶级全平台兼容性架构专家

5. 全球顶级产品交付与部署工程专家

6. 全球顶级数据容错恢复与系统降级专家

7. 全球顶级标准化文档工程专家

8. 全球顶级系统监控与可观测性专家
   - 精通日志聚合、性能监控、链路追踪、告警机制、APM
   - 负责建立全链路监控：前端错误/后端性能/数据库慢查询/API调用
   - 制定告警规则：错误率/响应时间/资源使用率阈值
   - 确保"能看到真实运行结果"，杜绝黑盒操作

### 八、前端故障排查与渲染专家层（4 位全球顶级专家，2026-09-06 新增，专责白屏/缓存/渲染故障）

1. 全球顶级浏览器内核专家
   - 精通 Chrome/Edge/Safari/Firefox 内核渲染机制、JS 执行引擎、内存管理、GPU 合成
   - 负责白屏、黑屏、页面无响应等疑难杂症的根因定位
   - 制定浏览器兼容性测试矩阵，确保系统在所有主流浏览器稳定运行
   - 监控页面加载性能（FP/FCP/LCP/CLS），优化渲染性能

2. 全球顶级 PWA/Service Worker 专家
   - 精通 Service Worker 生命周期、缓存策略、离线同步、后台同步
   - 负责 SW 缓存治理、版本更新机制、缓存失效策略
   - 制定"SW 故障应急流程"：白屏时优先禁用 SW、清除缓存、恢复服务
   - 确保离线能力与缓存更新不冲突，避免旧缓存导致功能异常

3. 全球顶级前端运行时调试专家
   - 精通 JS 运行时错误排查、内存泄漏检测、性能分析、断点调试
   - 负责运行时错误（ReferenceError/TypeError/SyntaxError）的快速定位与修复
   - 建立"悬空引用检测机制"：删除函数前必须全局搜索所有引用，严禁删除被调用的函数
   - 制定"代码修改后必验证"流程：语法检查 → 运行时检查 → 页面真实渲染验证

4. 全球顶级 DOM 渲染专家
   - 精通 DOM 树构建、CSSOM、渲染树、布局、绘制、合成全流程
   - 负责页面布局错乱、元素不可见、样式失效、滚动异常等渲染问题
   - 制定 CSS 规范：禁止 !important 滥用、禁止硬编码尺寸、统一使用 CSS 变量
   - 确保响应式布局在 PC/平板/手机三端一致渲染

### 四、产品、交互、用户层（3 位全球顶级专家）



1. 全球顶级教育产品架构专家

2. 全球顶级 UI/UX 全链路交互设计专家

3. 全球顶级用户内容风控与治理专家

### 五、学习算法与学情数据层（5 位全球顶级专家）



1. 全球顶级间隔重复记忆算法专家（艾宾浩斯 / FSRS 前沿优化）

2. 全球顶级学情大数据分析与智能测评专家

3. 全球顶级全真标准化模考引擎架构专家

4. 全球顶级知识图谱与关联推理专家
   - 精通知识图谱构建、实体关系抽取、图数据库、图谱推理
   - 负责教材→大纲→考点→题目→闪卡的全链路知识图谱构建
   - 实现知识点关联分析、前置依赖推理、跨章节综合复习路径
   - 制定知识点标准体系：教材目录是骨架、真题统计是血肉

5. 全球顶级数据可视化与学习分析专家
   - 精通ECharts/D3.js、信息设计、数据叙事、交互图表
   - 负责考点分布、真题趋势、薄弱诊断、学习进度等图表设计
   - 制定可视化规范：配色、图例、交互、响应式、导出
   - 确保数据图表准确传达信息，不误导用户判断

### 六、建工考试专业业务层（3 位全球顶级专家）



1. 全球顶级标准化题库架构业务专家

2. 全球顶级一级造价 / 一级建造师考试教研权威专家

3. 全球顶级建工案例题结构化智能阅卷评分专家

### 七、长期迭代合规层（2 位全球顶级专家）



1. 全球顶级建工考纲规范迭代教研专家

2. 全球顶级开源协议与数据隐私法律合规专家

## 第三章 强制顶级思考工作机制（宪法铁律、不可突破）

### 1. 全专家并行深度推理机制

任意需求、问题、方案、BUG、迭代内容，必须由 28 位全球顶级专家分别输出专业维度的深度推演结论，交叉验证、互补补盲、冲突博弈，最终融合生成全局最优解，禁止浅层思考、单点思考、经验化思考。

### 2. 顶级四维闭环校验法则（所有功能必过终审）



* 顶级技术可行性终审校验

* 专业业务绝对正确性终审校验

* 极致用户体验合规终审校验

* 全场景风险兜底闭环终审校验

### 3. 离线优先、容错至尊原则

无论出现大模型服务宕机、网络完全断连、本地文件损坏、数据库异常崩溃、程序报错等极端场景，系统必须全程可用、功能不瘫痪、用户数据不丢失、业务流程不中断，实现企业级高可用兜底。

### 4. 多端同步冲突绝对闭环原则

针对所有跨设备离线编辑、多设备同时编辑、断网写入、异地同步冲突场景，必须具备成熟、安全、可追溯、可还原的合并、回滚、版本保留、冲突提示全套顶级解决方案。

### 5. 建工专业零谬误至尊原则

一建、造价全部考点、规范条文、费用公式、施工工艺、合同条款、采分点、案例答题规则、评分标准，所有 AI 输出与系统内容严禁任何知识性错误、规范性错误、阅卷规则错误，做到专业绝对权威、零偏差。

### 6. 全生态兼容互通至尊原则

全面兼容主流闪卡、题库、文档、脑图格式，支持双向导入导出、无损迁移、学习进度继承、数据去重适配，打通全行业学习生态。

## 第四章 顶级专家职责极简总纲（AI 高速精准调用依据）



* **顶级技术类专家**：负责系统架构极致稳定、运行高效、全平台兼容、全域安全、可一键部署、可长期迭代维护

* **顶级 AI 算法类专家**：负责大模型交互智能可控、输出精准、稳定不崩、格式标准化、异常可降级

* **顶级产品交互专家**：负责产品逻辑极致通顺、交互统一、体验极致流畅、零学习成本、符合用户认知习惯

* **顶级学习算法专家**：负责记忆模型科学高效、学情诊断精准、薄弱点定位无误、个性化提分方案最优

* **顶级建工专业专家**：负责考点权威标准、答题规则合规、阅卷评分精准、题库内容零谬误、教研体系贴合考纲

* **顶级风险兜底专家**：覆盖所有极端异常、数据损坏、系统故障、同步冲突、边界场景，实现全方位兜底闭环

## 第五章 宪法至高生效范围

本宪法为系统最高准则，永久无条件生效，全面覆盖：需求深度分析、顶层架构设计、全功能开发、UI/UX 设计、算法模型搭建、数据结构定义、全格式导入导出、AI 提示词工程、异常报错处理、用户交付部署、版本迭代优化、缺陷 BUG 修复、题库教研校验、学情智能分析、主观题智能阅卷、多端数据同步全流程。



***



***

## 第六章 架构与开发总则（最高原则）

### 6.1 增量迁移铁则



* **新旧代码共存，增量搬迁，严禁破坏性全量重写**

* 原有旧文件、旧路由全部保留不动，不删除、不全量剪切

* 新功能直接写进 `modules/` 对应模块

* 修改 bug、迭代旧功能时，顺带把对应业务接口、逻辑搬迁进对应模块

* 搬迁完成立刻执行该模块对应的测试用例

* **历史教训**：曾因全量替换 app.js 导致用户大量已完成修改丢失，此为红线

### 6.2 平稳过渡原则



* 不简单删除了事，任何功能下线必须有替代方案或明确的迁移路径

* 新旧逻辑并行期间，必须有对比验证（旧代码返回 N 条，新代码也必须返回 N 条）

* 用户明确拒绝的功能，标记为 "已废弃" 而非直接删除，保留 30 天缓冲期

### 6.3 实测验证原则

### 6.4 PDF公共预处理底座铁则

* **所有PDF识别（思维导图/题库/闪卡）必须共享同一套公共预处理底座**，不得各自实现，优化一处全局生效
* **17步流程严格按序执行**：倾斜矫正→位置矫正→去水印→去页眉页脚→对比度增强→二值化→去噪→去杂裁剪→合并→预识别→精准识别→验证识别→节点拆分→去重→动态分层→构建层级→生成输出，不得跳步乱序
* **去重是最后一步**，对验证后的精准结果去重，不在中间去重，避免二次伤害
* **增强OCR存储机制**：第12步验证识别后同步存储纯净最优数据（图像+OCR+标签+坐标映射+质量标记+参数），一次存储多次使用，业务层通过标签快速提取
* **打标签分两步**：规则打基础标签（第11步，快）+ AI增加复杂标签（第12步，准）
* **异常直接提示**：兜底也无法解决时，直接提示"XX文件XX异常，请重新上传"，不搞分级，不浪费时间
* **双线模式铁则**：新识别方法与旧后台识别结果并行运行，旧结果继续使用；新方法测试成熟后，与旧结果去重合并，保留最优，不得直接替换旧逻辑或旧数据
* **详细规范见《PDF公共预处理底座实施细则分册》**



* **修改后必须由 AI 自己在浏览器实测验证，不能让用户一遍遍测试**

* 验证标准：功能正常 + 无控制台报错 + 无布局遮挡 + 数据正确

* 验证不通过不得宣布完成

* **历史教训**：曾多次声称 "已修复" 但用户实测发现未生效，根因是未实测

### 6.4 根本原因分析原则



* 禁止头疼医脚、表面修改

* 遇到问题必须从结果反推代码，找到根本原因再修复

* 必须建立监控机制，记录真实请求 URL、返回结果、关键变量状态

* 禁止用 "可能"、"大概" 下结论，必须用事实和数据说话



***

### 6.5 历史错误应对清单（所有犯过的错必须有应对措施）

以下为系统开发过程中犯过的所有错误，每条错误必须有明确的应对措施，严禁重犯：



| 序号 | 错误描述                                              | 根本原因                                                            | 应对措施                                                                            | 宪法依据                  |
| -- | ------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------- |
| 1  | 全量替换 app.js 导致用户已完成修改丢失                           | 未做增量备份，直接覆盖整个文件                                                 | 修改前必须自动增量备份，禁止全量替换，必须增量修改                                                       | 1.1 增量迁移铁则            |
| 2  | 头疼医脚、表面修改，不深入排查根因                                 | 未从结果反推代码，未找到根本原因                                                | 遇到问题必须从结果反推代码，找到根本原因再修复，禁止用 "可能"" 大概 " 下结论                                      | 1.4 根本原因分析原则          |
| 3  | 为了架构牺牲功能，删除已有功能导致页面空白                             | 重构时未保留旧代码，未做新旧对比验证                                              | 新旧代码共存，增量搬迁，搬迁完成必须对比验证（旧代码返回 N 条，新代码也必须返回 N 条）                                  | 1.1 增量迁移铁则、1.2 平稳过渡原则 |
| 4  | 让用户一遍遍测试，AI 不自己全面验证                               | 修改后未实测，声称 "已修复" 但实际未生效                                          | 修改后必须由 AI 自己在浏览器实测验证，验证不通过不得宣布完成                                                | 1.3 实测验证原则            |
| 5  | 简单删除了事，不平稳过渡                                      | 为了简化直接删除功能，未考虑用户依赖                                              | 禁止简单删除，必须平稳过渡（保留旧入口 + 提示迁移 + 数据迁移 + 回滚方案）                                       | 1.2 平稳过渡原则            |
| 6  | AI 没有独立专业判断，用户说什么就顺从什么                            | 未发挥专家角色，未提出专业建议                                                 | AI 必须以四料专家身份独立判断，用户需求不合理时必须提出专业建议和风险，不得盲目顺从                                     | 第一章总则第 1 条            |
| 7  | 控制台无输出时简单归因于缓存，不深挖执行链路                            | 未检查函数是否定义、是否被覆盖、请求是否发出                                          | 修改不生效时必须按顺序检查：①函数是否定义②是否被重复定义覆盖③请求是否发出④返回结果是什么⑤DOM 是否更新，禁止简单归因于缓存               | 1.4 根本原因分析原则          |
| 8  | 功能只有菜单没有实际内容（空壳页面）                                | 只做了导航入口，未实现实际功能                                                 | 禁止空壳页面，每个菜单必须有对应功能实现，未实现的功能不得显示在导航中                                             | 4.1 功能布局规则            |
| 9  | 科目名称混乱（官方名 vs 简称不统一）导致数据过滤失败                      | 登录界面官方名称，登录后应显示简称但实际不一致，Store 存储混乱                              | 登录界面两个界面用官方名称，登录后页面内部全部用简称，案例 / 实务带专业方向（如 "一造水利案例"），Store 统一存储简称                | 第八章数据宪法               |
| 10 | 代码重复与混乱（app.js 中存在重复函数定义）                         | 未做模块解耦，函数重复定义互相覆盖                                               | 模块解耦，禁止重复定义函数和变量，修改代码后必须语法验证（node -c）                                           | 第七章架构宪法、第十章编码宪法       |
| 11 | 缓存问题反复出现（修改后浏览器加载旧版本）                             | 未更新版本号，未清除 Service Worker 缓存                                    | 修改后必须更新 app.js 版本号，必须清除 Service Worker 注册和缓存，必须强制刷新验证                           | 4.18 多端适配与部署标准        |
| 12 | 从登录页面开始测试，不从业务页面开始                                | 未理解用户需求，每次都从登录开始测试                                              | 测试必须从业务页面开始（如课程教材、刷题、闪卡），不从登录页面开始，登录仅作为进入系统的大门                                  | 1.3 实测验证原则            |
| 13 | 文档章节号混乱（宪法修改时章节号重复）                               | 修改文档时未校验章节号连续性                                                  | 修改文档后必须校验章节号连续性，版本号必须更新，重大修改必须记录修订日志                                            | 第十四章修订记录              |
| 14 | Service Worker 注册失败（MIME 类型错误）                    | sw\_v2.js 的 MIME 类型是 application/json，不是 application/javascript | Service Worker 脚本 MIME 类型必须为 application/javascript，严禁 application/json，部署前必须校验 | 4.18 多端适配与部署标准        |
| 15 | offlineDataCache.getDB is not a function（API 不匹配） | app.js 调用的 API 与 offline-data-cache.js 实际暴露的 API 不一致            | 模块间 API 调用必须校验接口存在性，新增 API 必须在模块头注释中声明，调用前必须检查 typeof                           | 第七章架构宪法               |
| 16 | 资源文件 404（mind-elixir-style.min.css 不存在）           | 引用了不存在的 CSS/JS 文件                                               | 引用第三方资源前必须校验文件存在性，本地资源必须随项目一起部署，禁止引用不存在的文件                                      | 第十章编码宪法               |
| 17 | 上传成功但不显示文件列表（数据过滤不匹配）                             | 管理页面使用 api () 自动注入科目过滤，官方名与简称不匹配                                | 管理页面必须显示所有科目，禁止过滤科目，列表加载必须直接 fetch 绕过自动过滤                                       | 第八章数据宪法、第十三章第 12 条    |
| 18 | 大纲管理上传后不显示（数据库表不存在或数据异常）                          | 未校验数据库表存在性，未校验数据完整性                                             | 涉及数据库操作前必须校验表存在性，上传后必须校验数据写入成功，列表加载必须校验返回结果                                     | 第十章编码宪法               |
| 19 | PDF 查看 404/500（API 路径错误或后端异常）                     | API 路径与后端路由不匹配，后端未做异常处理                                         | API 调用前必须校验路径正确性，后端必须做异常处理并返回友好错误信息，禁止裸 except                                  | 第七章架构宪法、第十章编码宪法       |
| 20 | 修改范围失控（修改一个小功能导致整个页面布局变化）                         | 未做影响评估，修改范围超出预期                                                 | 修改前必须做影响评估，明确修改范围和受影响功能，修改后必须验证未受影响功能正常                                         | 1.2 平稳过渡原则            |
| 21 | 布局不协调（大的大，小的小，留白太多）                               | 未遵循 UI/UX 设计规范，未做像素级对齐                                          | 所有布局必须遵循统一间距（8px 基数）、统一字号、统一组件高度，卡片高度必须一致，禁止大小不一                                | 第十一章 UI/UX 宪法         |
| 22 | 按钮功能未实现（只有按钮没有对应功能）                               | 只做了 UI 按钮，未实现点击事件和后端 API                                        | 每个按钮必须有对应功能实现，未实现的功能不得显示按钮，禁止 "功能未实现" 的空按钮                                      | 4.1 功能布局规则            |
| 23 | 弹窗打开报错（函数未定义）                                     | 弹窗调用的函数未定义或被删除                                                  | 弹窗打开前必须校验函数存在性，删除函数前必须检查所有引用点，禁止引用不存在的函数                                        | 第十章编码宪法               |
| 24 | 后端 500 错误（变量未定义）                                  | 后端代码引用了未定义的变量或模型                                                | 后端代码必须做变量定义检查，引用模型前必须 import，禁止引用未定义的变量                                         | 第十章编码宪法               |
| 25 | 专业选择后自动跳转无法选择                                     | 下拉选择事件绑定错误，选择后立即触发跳转                                            | 下拉选择必须有确认按钮，选择后不得立即跳转，必须等待用户确认                                                  | 第十一章 UI/UX 宪法         |

**历史错误应对原则**：以上 25 条错误为系统开发过程中实际犯过的错误，每条都有明确的应对措施和宪法依据。后续开发中如犯新错误，必须立即补充到此清单中，并在宪法中增加对应的应对措施。严禁重犯已记录的错误。

## 第七章 架构宪法

### 7.1 业务模块划分（固定缩写，全局统一）



| 模块缩写     | 模块名称                 | 职责范围                                                                       |
| -------- | -------------------- | -------------------------------------------------------------------------- |
| `qb`     | 题库管理 question\_bank  | 题目识别确认、题目新增 / 编辑、题目预览、批量导入闪卡、文件管理、题库全套弹窗逻辑                                 |
| `mt`     | 记忆训练 memory\_train   | 艾宾浩斯复习计划、闪卡记忆、记忆曲线、口诀生成器、关键词提取、学习选择、备考课程表                                  |
| `mm`     | 思维导图 mindmap\_module | markmap markdown 渲染只读展示视图、wanglin2/mind-map 可拖拽编辑视图，视图切换，脑图数据导入导出、PDF 脑图解析 |
| `ai`     | ollama\_ai           | 对接本地 Ollama 大模型服务、Qwen3-vl:4b 多模态调用，PDF 解析、考点提取，识别置信度计算，日志输出               |
| `sync`   | 同步模块 sync\_service   | 多设备数据同步、数据去重逻辑，PWA 离线缓存，Tailscale 网络访问适配                                   |
| `resource` | 资源管理 resource\_manage | 教材、视频、讲义、大纲等文件资源的上传、下载、管理、统计、批量删除，PDF解析缓存                       |
| `common` | 公共通用层 common         | 工具函数、日志封装、数据库基础封装、通用弹窗工具、时间处理                                              |

### 7.2 分层约束



* **总入口&#x20;**`main.py`：只负责注册各个模块路由，**不写入业务路由**

* `routes.py`：只做参数接收、响应返回，不写业务计算

* `service.py`：业务计算、数据库操作全部下沉到本模块

* `common`：只放通用工具，**严禁写任何业务逻辑**

### 7.3 蓝图与命名



* 每个模块路由设置 `prefix="/api/缩写"`，例如 `/api/qb`、`/api/mt`

* 所有新增文件、路由 url 前缀、数据表、DOM-id、运行日志，统一使用模块缩写标记所属模块

* 新增数据表必须加模块缩写前缀，如 `qb_question_records`

* 新增弹窗 DOM id 必须带模块缩写前缀，如 `id="qb_confirm_modal"`

* 已经存在的旧弹窗 id 不批量修改，添加注释标记 `/* 水利智学旧组件：xxx模块，后续迭代重构 */`

### 7.4 跨模块约束（红线）



* **A 模块禁止 import 导入 B 模块 service 业务代码**

* 模块之间不允许直接调用对方内部业务函数

* 跨模块交互统一使用 `window.dispatchEvent` 自定义事件消息完成

* 模块之间禁止直接修改对方全局变量、DOM 节点

### 7.5 前端模块划分



* 在 `static/js/modules/` 下创建：`qb.js`、`mt.js`、`mm.js`、`ai.js`、`sync.js`

* 原有总 js 文件保留，函数增量剪切迁移，禁止一次性全部挪走

* PWA 离线、同步相关逻辑全部收拢到 `sync` 模块

* 离线缓存、数据去重业务逻辑全部放在 `sync` 模块内部

### 7.6 前端架构师代码约束（CSS变量与Token体系，红线）

**前端架构师职责**：制定代码层面的软件宪法，写代码约束、目录模块约束、CSS变量/Token约束，强制开发、AI编码必须复用全局变量，禁止到处写死 700/900px 这种硬编码尺寸。

#### 7.6.1 CSS变量/Token强制使用规则

* 所有颜色、字号、间距、圆角、阴影、宽度、高度、z-index，必须使用CSS变量（Token），禁止硬编码
* CSS变量定义在 `:root` 中，按模块分类：`--color-*`、`--font-*`、`--spacing-*`、`--radius-*`、`--shadow-*`、`--size-*`、`--z-*`
* 新增样式必须先检查是否已有对应Token，已有则复用，禁止重复定义
* Tailwind CSS配置必须与CSS变量同步，自定义颜色、字号、间距必须在tailwind.config.js中定义
* 禁止在style属性中写死颜色值（如 `style="color: #1a73e8"`），必须使用class或CSS变量

#### 7.6.2 硬编码尺寸禁止规则（红线）

* ❌ **禁止写死弹窗宽度**：如 `width: 700px`、`width: 900px`，必须使用弹窗档位Token（`--modal-sm`、`--modal-md`、`--modal-lg`、`--modal-xl`）
* ❌ **禁止写死弹窗高度**：如 `height: 600px`，必须使用 `max-height` + 百分比，配合 `overflow-y: auto`
* ❌ **禁止写死卡片高度**：如 `height: 200px`，必须使用 `min-height` + 内容自适应，卡片高度必须一致
* ❌ **禁止写死侧边栏宽度**：如 `width: 240px`，必须使用 `--sidebar-width` Token
* ❌ **禁止写死字体大小**：如 `font-size: 14px`，必须使用 `--font-size-*` Token
* ❌ **禁止写死间距**：如 `margin: 10px`、`padding: 15px`，必须使用 `--spacing-*` Token（8px基数）
* ✅ **允许的硬编码**：仅在动画关键帧、transform、特殊计算（如 `calc(100vh - 64px)`）中允许硬编码

#### 7.6.3 目录模块约束

* 前端文件必须按模块组织：`static/js/modules/`（业务模块）、`static/js/core/`（核心模块）、`static/css/`（样式）
* 每个模块文件头部必须声明模块名称、职责、依赖、导出API
* 模块间依赖必须显式声明，禁止隐式依赖全局变量
* 新增模块必须经过前端架构师评审，确保不与现有模块重复、不破坏模块解耦

#### 7.6.4 代码约束强制执行机制

* AI编码必须先读取宪法相关章节，再编写代码
* 代码提交前必须通过硬编码检查脚本（grep检查style属性中的px值、颜色值）
* 发现硬编码必须立即重构为Token，禁止带着硬编码上线
* 前端架构师定期代码审查，发现违反约束的代码必须记录并限期整改



***

### 7.6 模块解耦架构规范（6 模块固定划分）

#### 2.6.1 业务模块划分与固定缩写（全局统一）



| 模块缩写     | 模块名称                 | 职责范围                                                                       |
| -------- | -------------------- | -------------------------------------------------------------------------- |
| `qb`     | 题库管理 question\_bank  | 题目识别确认、题目新增 / 编辑、题目预览、批量导入闪卡、文件管理、题库全套弹窗逻辑                                 |
| `mt`     | 记忆训练 memory\_train   | 艾宾浩斯复习计划、闪卡记忆、记忆曲线、口诀生成器、关键词提取、学习选择、备考课程表                                  |
| `mm`     | 思维导图 mindmap\_module | markmap markdown 渲染只读展示视图、wanglin2/mind-map 可拖拽编辑视图，视图切换，脑图数据导入导出、PDF 脑图解析 |
| `ai`     | ollama\_ai           | 对接本地 Ollama 大模型服务、Qwen3-vl:4b 多模态调用，PDF 解析、考点提取，识别置信度计算，日志输出，AI 智能大脑       |
| `sync`   | 同步模块 sync\_service   | 多设备数据同步、数据去重逻辑，PWA 离线缓存，Tailscale 网络访问适配                                   |
| `common` | 公共通用层 common         | 工具函数、日志封装、数据库基础封装、通用弹窗工具、时间处理；common 只放通用工具，严禁写任何业务逻辑                      |

#### 2.6.2 后端架构规范



* 在现有项目内建立 `modules/` 业务模块目录，对应 6 个业务单元

* 每个业务模块文件夹内部固定文件：`routes.py`（FastAPI APIRouter 路由）、`service.py`（本模块业务逻辑）

* 每个模块路由设置 `prefix="/api/缩写"`，例如 `/api/qb`、`/api/mt`

* 总入口 `main.py` 只负责注册各个模块路由，不再写入业务路由

* 分层约束：routes 只做参数接收、响应返回；业务计算、数据库操作下沉本模块 service.py

* SQLite 数据库：原有数据表完全保留不改动；所有新增数据表必须加模块缩写前缀

* 日志：每一条业务日志强制携带 `module="缩写"`；AI 识别日志额外输出 `confidence=0~1` 置信度字段

#### 2.6.3 前端架构规范



* 在现有 `static/js` 下建立 `modules/`，对应创建：`qb.js`、`mt.js`、`mm.js`、`ai.js`、`sync.js`

* 原有总 js 文件保留，函数增量剪切迁移，禁止一次性全部挪走

* DOM id 命名规则：所有新增弹窗、组件 DOM id 必须带上模块缩写前缀，例 `id="qb_confirm_modal"`

* 已经存在的旧弹窗 id 不批量修改，添加注释标记 `/*水利智学旧组件：xxx模块，后续迭代重构*/`

* 模块通信：模块之间禁止直接修改对方全局变量、DOM 节点；跨模块交互统一使用 `window.dispatchEvent` 自定义事件消息完成

* HTML 弹窗组件：新增弹窗归入对应模块；现有全套弹窗不做大规模改写

* PWA 离线、同步相关逻辑全部收拢到 sync 模块，离线缓存、数据去重业务逻辑全部放在 sync 模块内部

#### 2.6.4 代码重复解决机制（从机制上解决，不一处一处改）



* 公共函数必须放到 common 模块，禁止在多个模块重复定义相同功能的函数

* 模块间共享的业务逻辑，必须通过事件通信或 common 工具函数调用，禁止复制粘贴代码

* 新增代码前必须检查 common 模块和对应模块是否已有相同功能，已有则复用，禁止重复实现

* 定期代码审查，发现重复代码必须立即重构到 common 模块或对应模块

* 代码质量持续优化：清理 console 输出、迁移全局变量到 Store、统一日志封装

#### 2.6.5 全局监控机制



* 建立 `window._monitor` 全局监控对象，拦截 fetch 和 api ()，记录真实请求 URL、方法、状态、响应大小、返回结果

* `window._monitor.getRecentRequests(n)`：获取最近 n 次请求记录

* `window._monitor.getRecentApiCalls(n)`：获取最近 n 次 API 调用记录

* 修改后必须通过监控机制验证真实请求和返回结果，禁止仅凭控制台无输出就判断成功

## 第八章 数据宪法

### 8.1 科目名称规则（核心规则，曾多次踩坑）



| 场景             | 使用名称 | 示例             |
| -------------- | ---- | -------------- |
| **登录界面（两个界面）** | 官方名称 | 建设工程造价管理       |
| **登录后页面内部**    | 简称   | 一造管理           |
| **数据库存储**      | 简称   | 一造管理           |
| **API 过滤参数**   | 简称   | subject = 一造管理 |
| **页面顶部显示**     | 简称   | 一造管理           |



* 登录流程中自动转换：`Store.currentSubject = toShortSubject(selected[0])`

* 旧数据自动迁移：localStorage 中的官方名称自动转为简称

* 管理页面（教材 / 大纲管理）**不过滤科目**，显示所有科目

* 业务页面（刷题、闪卡等）**按当前科目过滤**

### 8.2 专业方向规则



* 一造案例 4 个方向：水利工程、交通运输工程、土木建筑工程、安装工程

* 一建实务 5 个方向：水利水电工程、建筑工程、市政公用工程、机电工程、公路工程

* 专业方向使用官方名称，登录界面下拉选择

* 带专业方向的简称格式：`大专业简称 + 方向 + 科目简称`，如 "一造水利案例"

### 8.3 官方名称 <-> 简称映射表

#### 3.3.1 公共科目（不分专业方向）



| 官方名称        | 简称   |
| ----------- | ---- |
| 建设工程造价管理    | 一造管理 |
| 建设工程计价      | 一造计价 |
| 建设工程技术与计量   | 一造计量 |
| 建设工程造价案例分析  | 一造案例 |
| 建设工程项目管理    | 一建管理 |
| 建设工程经济      | 一建经济 |
| 建设工程法规及相关知识 | 一建法规 |
| 专业工程管理与实务   | 一建实务 |
| 建设工程施工管理    | 二建管理 |
| 建设工程法规      | 二建法规 |

#### 3.3.2 带专业方向的简称（实务 / 案例类科目）

**格式：大专业简称 + 方向简称 + 科目简称**



| 官方科目       | 专业方向（官方名称） | 方向简称 | 完整简称   |
| ---------- | ---------- | ---- | ------ |
| 建设工程造价案例分析 | 水利工程       | 水利   | 一造水利案例 |
| 建设工程造价案例分析 | 交通运输工程     | 交通   | 一造交通案例 |
| 建设工程造价案例分析 | 土木建筑工程     | 土建   | 一造土建案例 |
| 建设工程造价案例分析 | 安装工程       | 安装   | 一造安装案例 |
| 专业工程管理与实务  | 水利水电工程     | 水利   | 一建水利实务 |
| 专业工程管理与实务  | 建筑工程       | 建筑   | 一建建筑实务 |
| 专业工程管理与实务  | 市政公用工程     | 市政   | 一建市政实务 |
| 专业工程管理与实务  | 机电工程       | 机电   | 一建机电实务 |
| 专业工程管理与实务  | 公路工程       | 公路   | 一建公路实务 |

**使用规则**：



* 登录界面选择专业方向后，`Store.currentSubject` 存储带方向的完整简称（如 "一造水利案例"）

* 数据库存储带方向的完整简称

### 8.4 数据来源唯一性至尊原则（核心规则，曾多次踩坑）

**本质问题**：考试时间、科目配置、题型定义等核心数据在前端硬编码、数据库配置、代码常量中多处并存，导致数据不一致、匹配失败、显示错误。

**至尊规则**：

1. **单一数据源原则**：所有核心配置数据（考试时间、满分、及格线、题型分布、科目名称等）必须统一存储在数据库 `exam_global_config` 表中，前端禁止硬编码任何配置数据。

2. **前端只读原则**：前端只能从API获取配置数据，禁止在JS代码中写死考试时间、满分、及格线等配置。如必须本地缓存，必须标注"缓存数据，以服务器为准"。

3. **数据迁移原则**：旧代码中的硬编码配置必须逐步迁移到数据库，迁移期间必须保持两者一致，迁移完成后删除硬编码。

4. **配置变更流程**：任何配置数据的变更必须通过数据库修改，禁止直接修改前端代码。修改后必须记录到 `data_consistency_check` 表。

### 8.5 官方数据矫正机制（核心规则，曾多次踩坑）

**本质问题**：系统中的考试时间、考试科目等数据与官方（中国人事考试网、人社部）不一致，且没有自动校验和矫正机制。

**至尊规则**：

1. **官方数据来源唯一**：所有考试时间、考试科目、考试大纲等官方数据，必须以中国人事考试网（www.cpta.com.cn）和人力资源和社会保障部（www.mohrss.gov.cn）发布的官方文件为准。

2. **官方数据存储**：所有官方数据必须存储在 `official_data_source` 表中，包含数据类型、数据键、官方值、来源URL、来源名称、验证时间。

3. **定期校验机制**：系统必须定期（至少每月一次）比对系统配置数据与官方数据，发现不一致时自动矫正并记录到 `official_data_correction` 表。

4. **数据可追溯**：所有配置数据必须能追溯到官方来源，禁止使用无来源的配置数据。

5. **2026年官方考试时间（已验证）**：
   - 一造：10月17-18日（人社厅函〔2026〕6号）
   - 一建：9月12-13日（人社厅函〔2026〕6号）

### 8.6 AI全局纠偏机制（核心规则，曾多次踩坑）

**本质问题**：AI被动响应，不主动发现和纠正系统中的数据错误、逻辑错误、配置错误。

**至尊规则**：

1. **AI主动扫描**：AI必须定期（至少每周一次）全局扫描系统数据，主动发现以下问题：
   - 科目名称不一致（官方名称 vs 简称混用）
   - 题型标识不统一（single/multi/case vs 单选题/多选题）
   - 考试配置与官方数据不一致
   - 数据关联缺失（题目无知识点、闪卡无知识点）
   - 重复数据（重复题目、重复知识点）
   - 数据质量问题（答案为空、选项为空、章节为空）

2. **纠偏任务管理**：所有AI发现的问题必须记录到 `ai_global_correction` 表，包含问题类型、目标表、目标ID、字段名、旧值、新值、原因、置信度、状态。

3. **自动执行阈值**：置信度≥0.9的纠偏任务可以自动执行；置信度0.7-0.9的任务需要人工确认；置信度<0.7的任务仅记录不执行。

4. **纠偏记录可追溯**：所有自动执行的纠偏必须记录执行时间、执行原因、数据来源，支持回滚。

5. **纠偏效果验证**：纠偏执行后必须验证效果，确保问题已解决且未引入新问题。

* API 过滤参数使用带方向的完整简称

* 页面顶部显示带方向的完整简称

* 公共课（管理、计价、计量、经济、法规等）不携带方向简称



### 8.8 AI智能标签系统（自动替代人工打标签）

**核心原则**：从一造管理已有人工标签学习规律，建立AI自动标签规则，逐步替代人工打标签，实现全科目自动分类。

**标签规则库（V2，从一造管理学习验证）**：

1. **真题类**：文件名含"真题"→标签`真题`；含"透析/解析"→追加`闪卡`
2. **讲义类**（12种匹配模式）：
   - `第X章第X节`、`第X讲`、`第X章`
   - `精讲`、`讲义`、`直播`、`筑基`、`密训`、`早鸟`
   - `考点特训`、`母题实战`、`备考指导`、`导学`
   - 匹配后自动打标签：`讲义,精题,闪卡`
3. **精题类**：含`精题/必练/300题/经典`→`精题`
4. **模拟题类**：含`模考/模拟/查缺补漏/预测卷`→`模拟题`
5. **教材类**：含`教材`且不含`精讲`→`教材`
6. **大纲类**：含`大纲/考纲`→`大纲`
7. **思维导图类**：含`思维导图/导图/脑图`→`思维导图`
8. **闪卡类**：含`口诀/速记/必背/十页纸`→`闪卡`
9. **练习题类**：含`练习题/习题`→`练习题`
10. **章节题**：含`章节题`→`精题`

**执行机制**：
- 文件上传/导入时自动调用AI标签引擎
- 新科目自动复用一造管理学习的规则
- 规则持续迭代优化，覆盖率目标≥90%
- 人工可修正AI标签，修正案例反哺规则库

**当前覆盖率**：一造管理92%、一造水利案例85%、一造计价93%、一造计量80%、一建经济88%

### 8.9 数据安全规则



* 修改前自动增量备份

* 操作日志记录，可撤销最近 10 次

* 删除前二次确认 + 软删除（`is_deleted`），保留 30 天可恢复

* 恢复前安全网备份 + 完整性验证 + 恢复后功能验证 + 失败自动回滚

* 视频不在代码备份范围

### 8.10 数据库规则



* 水利智学原有数据表完全保留不改动

* 所有新增数据表必须加模块缩写前缀

* 启用 WAL 模式

* 每天凌晨 2 点自动备份保留 7 天

* 启动完整性校验，损坏自动恢复

* 慢查询 > 500ms 记录



***

### 8.7 数据去重至尊标准（核心规则，曾多次踩坑）

**本质问题**：去重标准不统一，曾出现草率标记239道题为重复（实际仅5道真正重复），导致有效数据丢失风险；题库与资料库去重策略混淆。

**至尊规则**：

#### 8.7.1 题库去重（AI自动判断，自动处理）

* **去重原则**：AI自动判断，自动去重，无需人工干预，但必须保留质量最高的题目

* **去重判定标准（铁律）**：题干 + 选项 + 答案 + 解析全部一致，才算重复。仅题干相似但选项/答案/解析有差异的，不视为重复，全部保留。

* **三层去重机制**：
  * **第一层：精确MD5去重**：题干+选项+答案+解析全部预处理（去除空格、换行、标点、全半角统一）后计算MD5，MD5相同则为精确重复
  * **第二层：四要素比对去重**：题干前40字相同 + 选项A-E全部相同 + 答案相同 + 解析前50字相同 = 确认重复
  * **第三层：考点去重**：同一考点 + 同一题型 + 同一难度下题目数量超过阈值（单选≥5道、多选≥3道），标记为同考点重复，AI自动评估保留价值（不自动删除）

* **保留最优算法**（按权重评分）：
  * 有答案：+2分
  * 有解析（>50字）：+2分
  * 有选项：+1分
  * 有章节：+1分
  * 有关联知识点：+1分
  * 来源权威（真题透析 > 经典300题 > 模考 > 其他）：+1分
  * 总分最高者保留，其余标记为重复

* **去重后处理（自动物理删除，无需人工）**：
  * 精确重复：自动物理删除（DELETE），无需人工确认
  * 高度重复：自动物理删除（DELETE），记录duplicate_of指向保留题ID
  * 同考点重复：标记为"待人工确认"，不自动删除
  * 删除后立即执行VACUUM释放数据库空间，避免数据膨胀
  * 资料库文件除外：资料库只标记，人工确认后才删除

* **不同来源间重复处理（铁律）**：
  * **保留真题，删除其他**：真题与经典300题/模考/讲义等任何来源重复，保留真题，其他来源的重复题标记为重复（软删除）
  * **不同年份真题重复**：保留年份更新的，标记旧的为重复
  * **同一来源内部重复**：保留信息最全的
  * **闪卡同样适用**：闪卡不同来源间重复，保留真题来源的闪卡，其他来源的重复闪卡标记为重复

#### 8.7.2 资料库去重（只标记，人工确认清除）

* **去重原则（与题库/闪卡不同）**：只标记不删除，等待人工确认，严禁自动删除文件。题库和闪卡是自动删除，资料库文件必须人工确认

* **重复检测维度**：
  * **文件哈希完全相同**：MD5/SHA256相同，100%确认重复
  * **文件名+大小相近**：文件名相似度≥90% 且 文件大小差异<10%，疑似重复
  * **内容相似度**：PDF文本内容相似度≥0.9，高度疑似重复

* **标记规则**：
  * 检测到重复后，设置is_duplicate=1，duplicate_of指向保留文件ID，duplicate_reason记录重复原因
  * 前端学习资料库显示重复标记（黄色警告图标），但不影响文件正常使用
  * 提供"重复文件管理"页面，用户可批量确认删除或保留

* **人工确认流程**：
  * 用户查看重复文件列表，对比文件内容
  * 选择"删除重复"：软删除（is_deleted=1），不物理删除
  * 选择"保留重复"：取消is_duplicate标记，记录保留原因
  * 所有操作记录到操作日志，可追溯可恢复

* **严禁事项**：
  * 严禁AI自动删除资料库文件
  * 严禁仅凭文件名相似就标记重复
  * 严禁在未确认的情况下影响文件访问

#### 8.7.3 去重慎重原则（铁律）

* **先分析后处理**：去重前必须全面分析重复情况，输出重复报告，不得草率处理
* **保留最优**：任何去重必须保留信息最全、来源最权威、质量最高的版本
* **只标记不删除**：资料库文件只标记不删除；题库/闪卡确认重复后物理删除（详见第二十一章）
* **可追溯可恢复**：所有去重操作必须记录，支持一键恢复
* **不同来源慎重**：不同来源间的重复必须慎重，可能是不同版本的题目，有保留价值
* **定期复核**：AI自动去重的结果必须定期由造价专家复核，确保无误判

### 8.11 数据完整性校验规则



* 涉及数据库操作前必须校验表存在性，表不存在必须自动创建并记录日志

* 上传文件后必须校验数据写入成功，列表加载必须校验返回结果，返回 0 条必须检查过滤条件是否正确

* 管理页面必须显示所有科目，禁止过滤科目，列表加载必须直接 fetch 绕过自动过滤

* 数据库表必须有 is\_deleted 字段，删除操作为软删除，禁止物理删除用户数据

* 数据备份必须定期自动执行，备份在 F 盘，视频不在备份范围

## 第九章 功能宪法

### 9.1 功能布局规则



* 系统分四大板块：**系统**、**学习资源**、**智能训练分析**、**智能刷题**

* 考试大纲移动到课程教材里面（教材管理后面增加大纲管理）

* 记忆训练优化到学习分析里面

* 学习分析改名为**智能训练分析**

* 教材 / 大纲管理合并，功能为：存储、重命名、删除、PDF 预览

* 教材上传功能移动到教材 / 大纲管理里面共用

### 9.2 AI 功能规则



* **凡是 AI 的都自动工作**，不需要用户手动触发

* 所有 AI 功能集成到**AI 智能大脑**里面，统一入口

* PDF 工具（去水印、解析 / OCR、拆分等）集成在一起，打标签分类清晰

* 工具归在 `ai` 模块，需要什么调用什么

* 不同功能只是调用顺序和组合不一样

* 新增 AI 功能只是在对应模块增加，不破坏已有功能

### 9.3 AI 五大核心能力矩阵（系统核心竞争力）



| 核心能力        | 能力描述                                | 关键指标                   | 应用场景                          |
| ----------- | ----------------------------------- | ---------------------- | ----------------------------- |
| **AI 自动工作** | 无需用户手动触发，AI 在后台自动完成识别、分析、推荐、生成      | 自动化率≥90%，响应时间≤3s       | 上传 PDF 自动识别、做题后自动分析、学习后自动生成计划 |
| **AI 精准识别** | 多模态识别（文本 / 图片 / 公式 / 表格 / 脑图），结构化输出 | 识别准确率≥95%，置信度可量化       | 题库识别、思维导图识别、公式提取、考点抽取         |
| **AI 智能推荐** | 基于学情大数据 + 遗忘曲线 + 薄弱点分析，个性化推荐        | 推荐命中率≥80%，提分效果可追踪      | 薄弱点刷题、闪卡复习、学习路径、每日一练          |
| **AI 个性辅导** | 针对个人学习数据，提供定制化讲解、答疑、提分方案            | 辅导针对性≥90%，用户满意度≥85%    | 错题讲解、考点解析、学习诊断、提分建议           |
| **AI 专业阅卷** | 建工案例题结构化智能评分，符合官方阅卷规则               | 评分一致性≥90%，采分点识别准确率≥95% | 案例题评分、主观题批改、答题规范检查            |

### 9.4 AI 输出质量至尊标准



1. **专业零谬误**：一建、造价全部考点、规范条文、费用公式、施工工艺、合同条款、采分点、案例答题规则、评分标准，AI 输出严禁任何知识性错误、规范性错误、阅卷规则错误

2. **格式标准化**：所有 AI 输出必须结构化（JSON/Markdown/ 标准字段），严禁自由散文输出，严禁格式混乱

3. **置信度可量化**：所有 AI 识别、分析、推荐必须输出 0-1 置信度，低于阈值必须标记可疑并提醒人工复核

4. **可追溯可审计**：所有 AI 输出必须记录输入、输出、模型版本、时间戳、置信度，支持回溯审计

5. **人工确认闸门**：涉及数据入库（题目、闪卡、脑图、考点）的 AI 输出，必须经过人工预览确认，严禁自动直接入库

### 9.5 AI 安全与降级至尊机制



1. **三级降级方案**：

* L1 功能降级：AI 服务异常时，关闭 AI 功能，保留基础功能（刷题、闪卡、查看）

* L2 模块降级：AI 不可用时，降级为本地搜索、规则匹配、预设推荐

* L3 系统回滚：AI 导致系统异常时，一键回滚到最近验证版本

1. **离线可用**：AI 服务宕机、网络断连时，系统核心功能（刷题、闪卡、笔记、查看）必须全程可用，用户数据不丢失

2. **异常隔离**：AI 模块异常不得影响其他模块运行，必须进程隔离、异常捕获、熔断机制

3. **数据安全**：AI 处理的用户数据、学习记录、个人信息，必须本地存储为主，严禁未经授权上传外部服务

### 9.6 AI 持续优化与训练机制



1. **RAG 知识库**：建立本地 RAG 知识库，存储宪法、代码结构、API 文档、考纲、教材、真题、历史决策，AI 每次任务自动检索相关上下文

2. **失败样本积累**：所有 AI 识别失败、输出错误、用户修正的样本，自动留存本地，用于提示词调优和模型微调

3. **提示词版本管理**：所有 AI 提示词必须版本化管理，记录变更内容、效果对比、回滚机制

4. **模型可替换**：AI 模型层抽象化，支持 Ollama 本地模型、云端 API、多模型切换，不绑定单一模型

5. **效果持续评估**：建立 AI 效果评估体系，定期评估识别准确率、推荐命中率、用户满意度，持续优化

### 9.7 PDF 识别规则（核心规则）



* **废除单纯 PDF 全文文本直接送入 VL 模型的方式**

* 新链路流程：PDF 页面 → 页面生成图片快照 → 按版面坐标区域切块（题目区域 / 脑图区域）→ 将【图片切片 + 当前页面坐标信息】传入 Ollama Qwen3-vl:4b

* **识别结果禁止自动直接入库**，必须复用现有预览弹窗，人工确认无误以后才写入 SQLite

* 识别失败样本：PDF 切片、模型原始返回结果本地留存日志，用于后续调优提示词

### 9.8 题库识别输出标准



* 强制模型输出标准 JSON 结构

* 字段包含：题干、选项 A/B/C/D、答案、解析

* 禁止自由散文输出

* 识别异常返回明确错误字段

### 9.9 思维导图识别输出标准



* 传入截图切片 + 坐标

* 强制输出标准脑图 JSON：`[{text:"", children:[], level:数字}]`

* 强制校验 level 层级字段，修复嵌套颠倒问题

### 9.10 AI 置信度规则



* ai 模块输出识别置信度 0-1

* 置信度低于自定义阈值，标记识别可疑，前端弹窗提醒人工复核

* 每一条业务日志强制携带 `module="缩写"`

* AI 识别日志额外输出 `confidence=0~1` 置信度字段



***

### 9.11 考试练题复习六大核心能力矩阵（系统根本价值）



| 核心能力     | 能力描述                                          | 关键指标                           | 应用场景                   |
| -------- | --------------------------------------------- | ------------------------------ | ---------------------- |
| **高效刷题** | 章节刷题、真题刷题、随机刷题、题型刷题，流畅不卡顿，解析完整不遮挡             | 刷题响应≤1s，解析完整率 100%，多选题逻辑正确     | 章节练习、真题演练、题型专练、随机刷题    |
| **精准复习** | 基于错题本、薄弱点、遗忘曲线，精准定位需复习内容，个性化推荐                | 薄弱点定位准确率≥90%，复习命中率≥85%         | 错题复习、薄弱点突破、遗忘提醒、每日一练   |
| **科学记忆** | 艾宾浩斯 / FSRS 间隔重复记忆算法，闪卡六类内容，多模式交互，掌握度可视化      | 记忆 retention≥85%，复习间隔科学，掌握度可量化 | 闪卡记忆、口诀磨耳朵、公式专练、概念辨析   |
| **全真模考** | 模拟真实考试环境，计时、答题卡、交卷评分、AI 评价、错题考点分析             | 模考真实度≥95%，评分准确，AI 评价针对性强       | 模拟考试、真题模考、冲刺模考、自定义组卷   |
| **薄弱突破** | AI 四维推荐算法（错误次数 + 遗忘曲线 + 掌握度 + 考点重要性），精准定位薄弱考点 | 薄弱点识别准确率≥90%，提分效果可追踪           | AI 薄弱点刷题、考点专项突破、错题归因分析 |
| **提分见效** | 学习计划生成、学情诊断、提分方案、进度追踪、效果评估，确保学习有成效            | 学习计划完成率≥80%，学情诊断精准，提分可量化       | 学习计划、学情分析、提分方案、进度追踪    |

### 9.12 考试练题复习质量至尊标准



1. **题库质量零谬误**：所有题目（题干、选项、答案、解析、考点、难度、年份）必须 100% 准确，严禁答案错误、解析错误、考点标注错误、重复题目。题目入库必须经过 AI 识别 + 人工确认双重校验。

2. **刷题体验至尊流畅**：刷题页面响应≤1s，切换题目无卡顿，多选题选完才判分，解析显示完整不被遮挡，答题卡不被遮挡，交卷后成绩显示完整。严禁因 UI 设计影响刷题效率。

3. **复习推荐精准有效**：AI 推荐必须基于真实学情数据（错误次数、掌握度、遗忘曲线、考点重要性），严禁随机推荐、无效推荐、重复推荐。每道推荐题必须显示推荐理由和得分。

4. **模考真实度至尊**：模拟考试必须还原真实考试环境（计时、题型分布、分值、答题卡、交卷流程），评分必须准确，AI 评价必须针对性强（错题考点分析 + 提分建议 + 复习计划），严禁泛泛而谈。

5. **数据完整可追溯**：所有刷题记录、错题记录、闪卡复习记录、模考成绩、学习时长，必须完整记录、可追溯、可统计、可导出。严禁数据丢失、统计错误、进度丢失。

6. **专业权威零偏差**：一建、造价全部考点、规范条文、费用公式、施工工艺、合同条款、采分点、案例答题规则、评分标准，必须与官方教材、考试大纲、历年真题完全一致，严禁任何知识性错误、规范性错误。

### 9.13 题库建设与数据质量标准



1. **题目字段完整**：每道题必须包含：题干、选项（A/B/C/D/E）、答案、解析、考点、章节、科目、题型、难度、年份、来源、质量评分。字段缺失的题目严禁入库。

2. **去重机制完善**：三层去重（精确 MD5 去重 + 语义相似度去重 + 考点去重），重复题目必须标记（精确重复 / 高度相似 / 相似 / 同考点），用户可选择合并 / 保留 / 删除。严禁重复题目影响刷题体验。

3. **分类体系科学**：题目必须按科目→章节→考点→题型→难度五级分类，分类必须与官方教材目录、考试大纲一致。严禁分类错误、考点标注错误。

4. **质量分级管理**：题目按质量分为 A（官方真题 / 权威来源）、B（AI 识别 + 人工确认）、C（AI 识别待确认）三级，C 级题目必须经过人工确认才能用于刷题和模考。

5. **持续更新机制**：题库必须支持持续更新（新真题、新考点、新教材），更新必须经过质量校验，严禁引入错误题目。

### 9.14 刷题体验与交互至尊标准



1. **多端一致体验**：电脑端、平板端、手机端刷题体验必须一致，布局适配各自屏幕尺寸，严禁某端功能缺失或布局错乱。

2. **交互逻辑符合认知**：单选题选完即判分，多选题选完才判分，判断题即时反馈，案例题分步作答。操作逻辑必须符合用户考试习惯，严禁反人类交互。

3. **解析完整不遮挡**：答案解析必须完整显示，不被状态栏、侧边栏、弹窗遮挡，公式、图表、表格必须清晰可辨，支持放大查看。

4. **答题卡功能完善**：模拟考试必须有答题卡，显示答题进度、标记题目、跳转题目，答题卡不被遮挡，交卷前可检查。

5. **离线刷题可用**：已缓存题目支持离线刷题，刷题记录本地存储，上线后自动同步，严禁离线状态下核心刷题功能不可用。

### 9.15 科学记忆与复习至尊标准



1. **间隔重复算法科学**：闪卡复习必须基于艾宾浩斯 / FSRS 间隔重复算法，记住 / 模糊 / 忘记三档评价，间隔科学（1 天→3 天→7 天→15 天→30 天→60 天），连续记住 5 次标记已掌握，连续忘记 3 次标记难点。

2. **闪卡内容六类齐全**：知识点（问答式）、口诀（磨耳朵）、公式（构成式）、数字考点（填空式）、概念对比（辨析式）、错题转化（自动生成），六类闪卡显示样式各异，交互模式多样。

3. **多模式交互丰富**：点击翻转、滑动切换、键盘快捷键、语音朗读、语音回答，五种交互模式，支持电脑 / 平板 / 手机多端操作。

4. **掌握度可视化**：每张闪卡必须有掌握度进度条（0-100%），复习次数、下次复习时间、历史评价记录，可查看可统计。

5. **复习提醒及时**：到期闪卡必须及时提醒，每日复习量合理，不堆积不遗漏，复习完成率可追踪。



***

### 9.16 多端离线同步四大核心能力矩阵（系统第三大核心战略）



| 核心能力        | 能力描述                                           | 关键指标                           | 应用场景                            |
| ----------- | ---------------------------------------------- | ------------------------------ | ------------------------------- |
| **本地部署兼平台** | 一键本地部署，兼作系统平台，支持 Windows/Mac/Linux，数据本地存储为主    | 部署时间≤5 分钟，数据本地存储率 100%，无需公网服务器 | 电脑端本地部署、局域网访问、Tailscale 远程访问    |
| **离线可用**    | 手机 / 平板离线状态下核心功能全程可用（刷题、闪卡、笔记、查看），数据本地缓存       | 离线功能覆盖率≥90%，缓存容量≥500MB，离线刷题不卡顿 | 地铁 / 飞机无网学习、户外离线复习、断网应急使用       |
| **多端一致**    | 电脑 / 平板 / 手机三端数据一致，UI 布局适配各端，学习进度、错题、闪卡、笔记全端同步 | 三端数据一致性 100%，布局适配率 100%，操作逻辑一致 | 电脑刷题 + 平板看视频 + 手机背闪卡，多端协同学习     |
| **自动同步**    | 上线自动检测变更、增量同步、冲突自动解决、同步状态可视化，无需手动操作            | 同步延迟≤30s，冲突解决率≥95%，同步成功率≥99%   | 从离线到上线自动同步、多设备同时编辑自动合并、异地学习无缝衔接 |

### 9.17 多端离线同步质量至尊标准



1. **本地优先原则**：所有数据必须本地存储为主，云端同步为辅。严禁仅云端存储、本地无缓存的设计。离线状态下核心功能（刷题、闪卡、笔记、查看、模考）必须全程可用。

2. **离线功能全覆盖**：手机 / 平板离线状态下，已缓存题目、全部闪卡、笔记、学习记录、设置配置必须可用。AI 解题、拍照解题、在线视频、云备份等在线功能必须有友好的离线提示。

3. **首次使用自动缓存**：首次登录自动缓存核心资源（HTML/CSS/JS/ 图标 / 字体）+ 全部闪卡 + 题目索引 + 用户配置，提示是否缓存全部题目，进度可视化。PWA Service Worker 必须正确注册，App Shell 缓存 + 动态缓存策略完善。

4. **多端数据一致性**：电脑 / 平板 / 手机三端数据必须 100% 一致，包括题目进度、错题记录、闪卡掌握度、笔记内容、学习时长、模考成绩、收藏标记。严禁某端数据丢失、进度不同步。

5. **自动同步机制完善**：上线时自动同步 + 每 5 分钟定时同步 + 手动同步 + 数据变更标记 pending + 应用启动同步。同步状态 UI 必须显示：同步进度条 + 最近同步时间 + 失败记录 + 待同步数量 + 冲突数量提醒。

6. **冲突解决绝对闭环**：跨设备离线编辑、多设备同时编辑、断网写入、异地同步冲突，必须具备成熟、安全、可追溯、可还原的合并、回滚、版本保留、冲突提示全套解决方案。支持时间戳优先 + 内容合并 + 用户选择 + 历史保留四种冲突解决策略。

7. **离线队列可靠**：IndexedDB 存储离线操作，上线自动按顺序回传，失败重试 3 次（指数退避），队列状态可视化。严禁离线操作丢失、重复提交、顺序错乱。

### 9.18 多端适配与部署标准



1. **电脑端适配**：侧边栏常驻 + 内容区多列 + 状态栏拉通 + 键盘快捷键支持 + 鼠标悬停反馈。分辨率适配 1366×768 到 4K。

2. **平板端适配（1245×740）**：侧边栏常驻（宽度优化）+ 内容区双列（题目 + 解析）+ 答题卡右侧 + 按钮最小 48px + 手写笔支持 + 横竖屏自动切换。

3. **手机端适配（375×656）**：底部导航栏（刷题 / 闪卡 / 学习 / 我的）+ 单列布局 + 卡片式 + 按钮最小 44px + 滑动手势 + 横屏优化。

4. **触控优化统一**：所有可点击元素最小 44×44px + 点击反馈 + 按钮间距≥8px + 滑动与点击区分 + 双击缩放禁用。

5. **本地部署标准**：一键启动脚本（start.bat）+ 环境自动检测（Python 版本 + 依赖 + 端口 + 磁盘 + 数据库）+ 端口占用自动切换 + 失败友好提示 + 关闭无 "Terminate batch job" 提示。

6. **PWA 安装标准**：manifest.json 完整（name/short\_name/description/start\_url/display:standalone/theme\_color/icons 192/512/maskable）+ Service Worker 正确注册（MIME 类型必须为 application/javascript，严禁 application/json）+ 安装引导 + 离线页面 + 缓存管理页面。

7. **网络穿透标准**：支持局域网 IP 访问 + Tailscale 远程访问 + 多设备同一账号 + 数据加密传输 + 访问权限控制。



***

## 第十章 编码宪法

### 10.1 日志规范



* 禁止裸 `except:`，全部改为 `except Exception as e:`

* 每个 except 块内必须有 `logger.error(f"[模块名] 描述失败: {str(e)}", exc_info=True)`

* 日志自动轮转：maxBytes=10MB，backupCount=5，encoding='utf-8'

* 错误聚合：同类错误只记一次计数

* 30 天自动清理

### 10.2 异常处理规范



* FastAPI 全局异常处理器，未捕获异常自动记录（含堆栈）+ 返回友好提示

* 接口超时 30s，并发限制 100

* 降级机制：AI 不可用降级本地搜索

* 三级降级方案：L1 功能降级（关闭异常功能）→ L2 模块降级（AI 降级本地搜索）→ L3 系统回滚（一键回滚最近验证版本）

### 10.3 代码质量规范



* 清理无用 console 输出，使用统一日志封装

* 迁移全局变量到 Store

* 禁止重复定义函数和变量

* 修改代码后必须通过语法验证（`node -c`）

* 禁止引入安全漏洞（命令注入、XSS、SQL 注入等）

### 10.4 监控机制规范



* 必须建立全局监控，记录每次操作的真实请求 URL、返回结果、关键变量

* 拦截 fetch 记录：URL、方法、状态、响应大小

* 拦截 api () 记录：输入 URL、当前科目、返回结果、错误

* 监控 Store.currentSubject 变化

* 可通过 `window._monitor.getRecentRequests()` 查看



***

### 10.5 统一日志封装与 console 清理



* 必须创建统一日志封装（logger.js），支持分级日志（debug/info/warn/error）、模块标记、时间戳、格式化输出

* 所有 console.log 必须替换为 logger.debug/info，console.error 替换为 logger.error

* 生产环境必须关闭 debug 级别日志，只保留 info/warn/error

* 日志输出必须携带模块缩写，例 `[qb] 加载题目列表成功`

* 前端 console 输出必须持续清理，目标：模块文件 console.log=0，app.js 保留必要的关键日志

### 10.6 代码质量持续优化规则



* 禁止裸 except，全部改为 except Exception as e，每个 except 块内必须有 logger.error

* 禁止重复定义函数和变量，修改代码后必须通过语法验证（node -c）

* 禁止引入安全漏洞（命令注入、XSS、SQL 注入等）

* 引用第三方资源前必须校验文件存在性，本地资源必须随项目一起部署，禁止引用不存在的文件

* 调用函数或 API 前必须校验存在性（typeof 检查），禁止调用未定义的函数

* 后端代码必须做变量定义检查，引用模型前必须 import，禁止引用未定义的变量

* API 调用前必须校验路径正确性，后端必须做异常处理并返回友好错误信息

* 修改代码后必须更新 app.js 版本号，清除 Service Worker 注册和缓存，强制刷新验证

### 10.7 RAG 知识库与 AI 训练机制



* 建立本地 RAG 知识库，存储宪法、代码结构、API 文档、考纲、教材、真题、历史决策，AI 每次任务自动检索相关上下文

* 所有 AI 识别失败、输出错误、用户修正的样本，自动留存本地，用于提示词调优和模型微调

* 所有 AI 提示词必须版本化管理，记录变更内容、效果对比、回滚机制

* AI 模型层抽象化，支持 Ollama 本地模型、云端 API、多模型切换，不绑定单一模型

* 建立 AI 效果评估体系，定期评估识别准确率、推荐命中率、用户满意度，持续优化

* Ollama 服务必须提前运行，系统启动时必须检测 Ollama 服务状态，未运行必须提示用户

## 第十一章 设计系统与 UI/UX 宪法（设计系统专家 + 高级UX/UI设计师联合制定）

### 11.1 布局规则



* 所有文件排序按序号从小到大

* 底部状态栏拉通：`position: fixed; bottom: 0; left: 0; width: 100%; z-index: 200; height: 32px`

* 内容区 `padding-bottom: 35px`（32px 状态栏 + 3px 间距）

* 状态栏不被侧边栏遮挡

* 所有界面状态栏样式统一，内容一致（左侧在线状态 + 中间同步状态 + 右侧学习时长 + 版本号）

### 11.2 触控规则



* 所有可点击元素最小 44×44px（移动端）

* 点击反馈

* 按钮间距 ≥ 8px

* 滑动与点击区分

* 双击缩放禁用

### 11.3 响应式规则



* 电脑端：侧边栏常驻 + 内容区多列

* 平板端（1245×740）：侧边栏常驻（宽度优化）+ 内容区双列 + 答题卡右侧

* 手机端（375×656）：底部导航栏 + 单列布局 + 卡片式

* 横竖屏自动切换

### 11.4 弹窗规则



* 新增弹窗归入对应模块，DOM id 带模块缩写前缀

* 现有全套弹窗不做大规模改写

* 弹窗打开时必须加载对应数据，不能只有按钮没有内容

* 弹窗功能必须完整实现，不能只有标签没有功能



***

### 11.5 布局统一规范（像素级对齐）



* 所有布局必须遵循统一间距基数（8px），间距为 8px 的整数倍（8/16/24/32/40/48）

* 统一字号体系：标题 24px/20px/18px，正文 16px/14px，辅助文字 12px

* 统一组件高度：按钮 40px/32px，输入框 40px，卡片内边距 16px

* 卡片高度必须一致，禁止大小不一、大的大小的小

* 禁止大量留白，内容必须适当填充，卡片高度必须均衡分布

* 快捷入口总框宽度适当减小，文字适当放大，量化目标进度条放在文字同行

* 学习看板布局必须协调，三行均衡分布，填充整个布局，内容适当放大

* 所有界面状态栏样式统一，内容一致（左侧在线状态 + 中间同步状态 + 右侧学习时长 + 版本号）

### 11.6 触控与交互规范



* 所有可点击元素最小 44×44px，点击反馈，按钮间距≥8px

* 滑动与点击区分，双击缩放禁用

* 下拉选择必须有确认按钮，选择后不得立即跳转，必须等待用户确认

* 单选题选完即判分，多选题选完才判分，判断题即时反馈，案例题分步作答

* 操作逻辑必须符合用户考试习惯，禁止反人类交互

### 11.7 设计Token体系（设计系统专家核心，全局唯一来源）

**设计系统专家职责**：制定全局UI根本规则（相当于UI层面的软件宪法），定义弹窗档位、max-height、间距、Token、组件复用规则，输出规范文档，约束后续新增页面不能自由发挥；做现有系统的一致性整改，解决到处尺寸乱的问题。

#### 11.7.1 颜色Token

| Token名称 | 值 | 用途 |
| --------- | -- | ---- |
| `--color-primary` | #1a73e8 | 主色（按钮、链接、选中态） |
| `--color-primary-light` | #4285f4 | 主色浅（悬停态） |
| `--color-primary-dark` | #1557b0 | 主色深（点击态） |
| `--color-success` | #34a853 | 成功（正确、完成、通过） |
| `--color-warning` | #fbbc04 | 警告（提醒、待确认） |
| `--color-error` | #ea4335 | 错误（答错、失败、删除） |
| `--color-info` | #4285f4 | 信息（提示、说明） |
| `--color-text-primary` | #202124 | 主文字（标题、正文） |
| `--color-text-secondary` | #5f6368 | 次文字（辅助说明、标签） |
| `--color-text-disabled` | #bdc1c6 | 禁用文字 |
| `--color-bg-primary` | #ffffff | 主背景 |
| `--color-bg-secondary` | #f8f9fa | 次背景（卡片、侧边栏） |
| `--color-bg-tertiary` | #e8eaed | 第三背景（分割线、边框） |
| `--color-border` | #dadce0 | 边框 |

#### 11.7.2 字号Token

| Token名称 | 值 | 用途 |
| --------- | -- | ---- |
| `--font-size-h1` | 24px | 页面标题 |
| `--font-size-h2` | 20px | 模块标题 |
| `--font-size-h3` | 18px | 卡片标题 |
| `--font-size-body` | 16px | 正文 |
| `--font-size-body-sm` | 14px | 辅助正文 |
| `--font-size-caption` | 12px | 说明文字、标签 |
| `--font-size-mini` | 10px | 角标、徽章 |

#### 11.7.3 间距Token（8px基数）

| Token名称 | 值 | 用途 |
| --------- | -- | ---- |
| `--spacing-xs` | 4px | 极小间距（图标与文字） |
| `--spacing-sm` | 8px | 小间距（按钮内边距、元素间距） |
| `--spacing-md` | 16px | 中间距（卡片内边距、模块间距） |
| `--spacing-lg` | 24px | 大间距（区块间距、页面边距） |
| `--spacing-xl` | 32px | 超大间距（大区块间距） |
| `--spacing-2xl` | 48px | 特大间距（页面顶部/底部） |

#### 11.7.4 圆角与阴影Token

| Token名称 | 值 | 用途 |
| --------- | -- | ---- |
| `--radius-sm` | 4px | 小圆角（按钮、输入框） |
| `--radius-md` | 8px | 中圆角（卡片、弹窗） |
| `--radius-lg` | 12px | 大圆角（大卡片、模态框） |
| `--radius-xl` | 16px | 超大圆角（特殊卡片） |
| `--radius-full` | 9999px | 全圆角（圆形、胶囊按钮） |
| `--shadow-sm` | 0 1px 2px rgba(0,0,0,0.05) | 小阴影（卡片悬停） |
| `--shadow-md` | 0 4px 12px rgba(0,0,0,0.1) | 中阴影（弹窗、下拉菜单） |
| `--shadow-lg` | 0 8px 24px rgba(0,0,0,0.15) | 大阴影（模态框） |

#### 11.7.5 尺寸Token

| Token名称 | 值 | 用途 |
| --------- | -- | ---- |
| `--sidebar-width` | 240px | 侧边栏宽度（电脑端） |
| `--sidebar-width-collapsed` | 64px | 侧边栏收起宽度 |
| `--header-height` | 56px | 顶部导航栏高度 |
| `--footer-height` | 32px | 底部状态栏高度 |
| `--content-padding` | 24px | 内容区内边距 |
| `--btn-height-sm` | 32px | 小按钮高度 |
| `--btn-height-md` | 40px | 中按钮高度（默认） |
| `--btn-height-lg` | 48px | 大按钮高度 |
| `--input-height` | 40px | 输入框高度 |

### 11.8 弹窗档位规范（设计系统专家核心，四档固定）

**所有弹窗必须使用以下四档之一，禁止自定义宽度和高度**

| 档位 | Token | 宽度 | max-height | 用途 | 示例 |
| ---- | ----- | ---- | ---------- | ---- | ---- |
| 小弹窗 | `--modal-sm` | 400px | 80vh | 确认框、提示框、简单表单 | 删除确认、重命名 |
| 中弹窗 | `--modal-md` | 600px | 85vh | 普通表单、详情查看、列表管理 | 题目编辑、笔记编辑 |
| 大弹窗 | `--modal-lg` | 800px | 90vh | 复杂表单、数据表格、多Tab内容 | 题库管理、教材管理 |
| 超大弹窗 | `--modal-xl` | 1200px | 95vh | 全屏内容、复杂编辑器、数据大屏 | PDF查看、思维导图、数据分析 |

**弹窗通用规则：**

* 弹窗必须居中显示，`position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%)`
* 弹窗必须有遮罩层，`background: rgba(0,0,0,0.5); backdrop-filter: blur(2px)`
* 弹窗内容区必须 `overflow-y: auto`，内容超出时显示滚动条
* 弹窗必须有关闭按钮（右上角×）+ 点击遮罩关闭 + ESC键关闭
* 弹窗标题栏高度固定 `--header-height`（56px），底部操作栏高度固定 `64px`
* 弹窗打开时必须禁止背景滚动（`body { overflow: hidden; }`）
* 弹窗内表单必须有明确的确认/取消按钮，确认按钮在右，取消在左
* 弹窗内数据加载必须有loading状态，加载失败必须有错误提示和重试按钮

### 11.9 组件复用规则（设计系统专家核心）

**组件复用原则：一次定义，全局复用，禁止重复造轮子**

#### 11.9.1 基础组件库（必须复用）

| 组件 | 用途 | 复用规则 |
| ---- | ---- | -------- |
| 按钮 Button | 所有可点击操作 | 必须使用统一按钮组件，禁止自定义按钮样式 |
| 输入框 Input | 文本输入 | 必须使用统一输入框组件，高度40px，圆角4px |
| 下拉选择 Select | 选项选择 | 必须使用统一下拉组件，支持搜索、多选 |
| 卡片 Card | 内容容器 | 必须使用统一卡片组件，圆角8px，阴影sm |
| 表格 Table | 数据展示 | 必须使用统一表格组件，支持排序、分页、筛选 |
| 弹窗 Modal | 模态对话框 | 必须使用四档弹窗之一，禁止自定义 |
| 标签 Tag | 状态/分类标记 | 必须使用统一标签组件，颜色按语义 |
| 进度条 Progress | 进度展示 | 必须使用统一进度条组件，高度8px |
| 分页 Pagination | 列表分页 | 必须使用统一分页组件，每页10/20/50条 |
| 空状态 Empty | 无数据提示 | 必须使用统一空状态组件，图标+文字+操作按钮 |

#### 11.9.2 业务组件库（按模块复用）

* 题库模块：题目卡片、选项组、答题卡、解析面板
* 闪卡模块：闪卡翻转、记忆曲线、复习进度
* 思维导图：脑图画布、节点编辑器、视图切换
* PDF工具：PDF查看器、目录树、标注工具
* AI组件：AI对话、流式输出、置信度显示、人工确认

#### 11.9.3 组件复用强制执行

* 新增页面前必须检查组件库，已有组件必须复用
* 禁止在多个页面重复实现相同功能的组件
* 发现重复组件必须立即重构为公共组件
* 组件必须有完整的Props定义、事件定义、Slot定义
* 组件必须有使用文档和示例
* 设计系统专家定期审查组件使用情况，发现违规必须整改

### 11.10 视觉规范（高级UX/UI设计师职责）

**高级UX/UI设计师职责**：输出视觉、交互规范，排查现有系统不协调问题，定义弹窗、表单、布局标准。

#### 11.10.1 颜色使用规范

* 主色使用：主按钮、选中态、链接、进度条、图标高亮
* 语义色使用：成功（绿）、警告（黄）、错误（红）、信息（蓝），禁止滥用
* 文字颜色：主文字 `--color-text-primary`，次文字 `--color-text-secondary`，禁用 `--color-text-disabled`
* 背景颜色：主背景 `--color-bg-primary`，卡片背景 `--color-bg-secondary`，分割线 `--color-bg-tertiary`
* 禁止使用渐变色作为大面积背景，仅允许用于按钮、图标等小面积元素
* 颜色对比度必须符合WCAG AA标准（文字与背景对比度≥4.5:1）

#### 11.10.2 字体使用规范

* 中文字体：`"PingFang SC", "Microsoft YaHei", sans-serif`
* 英文字体：`"Inter", "Roboto", sans-serif`
* 等宽字体（代码/公式）：`"JetBrains Mono", "Consolas", monospace`
* 标题使用粗体（font-weight: 600/700），正文使用常规（font-weight: 400）
* 行高：标题1.3，正文1.6，辅助文字1.5
* 字间距：标题0.5px，正文0px，辅助文字0.3px

#### 11.10.3 图标使用规范

* 图标库：统一使用Lucide图标库，禁止混用多个图标库
* 图标尺寸：16px（小）、20px（中，默认）、24px（大）、32px（超大）
* 图标颜色：默认使用 `--color-text-secondary`，选中/激活使用 `--color-primary`
* 图标与文字间距：`--spacing-xs`（4px）
* 禁止使用彩色图标作为功能按钮，仅允许在空状态、引导页使用插画

#### 11.10.4 布局规范

* 页面布局：顶部导航（56px）+ 侧边栏（240px）+ 内容区（自适应）+ 底部状态栏（32px）
* 内容区最大宽度：1440px，居中显示，左右边距 `--spacing-lg`（24px）
* 网格系统：12列网格，列间距 `--spacing-md`（16px）
* 卡片布局：卡片间距 `--spacing-md`（16px），同行卡片高度必须一致
* 响应式断点：电脑端≥1280px，平板端768-1279px，手机端<768px

### 11.11 交互规范（高级UX/UI设计师职责）

#### 11.11.1 表单规范

* 表单标签：左对齐，字号14px，颜色 `--color-text-secondary`，必填项加红色*
* 输入框：高度40px，圆角4px，边框 `--color-border`，聚焦时边框 `--color-primary` + 阴影
* 输入框提示文字：placeholder颜色 `--color-text-disabled`
* 表单验证：实时验证（失焦时），错误提示在输入框下方，红色文字+图标
* 表单按钮：确认按钮在右（主色），取消按钮在左（次色），按钮间距 `--spacing-sm`
* 表单分组：复杂表单使用分组标题+分割线，每组不超过8个字段

#### 11.11.2 列表规范

* 列表表头：背景 `--color-bg-secondary`，字号14px，粗体，可排序列有箭头
* 列表行：高度48px，hover时背景 `--color-bg-secondary`，选中时背景 `--color-primary-light`（10%透明度）
* 列表分页：底部右侧，每页10/20/50条，显示总数和当前页
* 空列表：显示空状态组件（图标+文字+操作按钮），禁止显示空白
* 列表操作：行内操作按钮（编辑/删除）hover时显示，固定在右侧

#### 11.11.3 导航规范

* 顶部导航：Logo + 全局科目切换 + 搜索框 + 用户头像，高度56px
* 侧边栏导航：四大板块分组，选中项背景 `--color-primary`（10%透明度）+ 左侧3px主色条
* 面包屑：内容区顶部，字号14px，颜色 `--color-text-secondary`，当前页颜色 `--color-text-primary`
* 标签页（Tab）：顶部对齐，选中项底部2px主色条，字号16px
* 导航跳转：必须有加载状态，禁止白屏跳转

#### 11.11.4 反馈规范

* 操作成功：Toast提示（右上角，3秒自动消失，绿色+图标）
* 操作失败：Toast提示（红色+图标+错误原因），表单错误在字段下方显示
* 加载状态：按钮loading（旋转图标+文字），页面loading（骨架屏），数据loading（加载动画）
* 确认操作：删除、覆盖等危险操作必须有确认弹窗，红色警告文字
* 进度反馈：长时操作必须有进度条，显示百分比和剩余时间
* 空状态：无数据时显示空状态组件，禁止空白页面
* 错误状态：请求失败时显示错误状态组件（图标+错误原因+重试按钮）

### 11.12 现有系统一致性整改要求（设计系统专家职责）

**设计系统专家必须对现有系统进行一致性整改，解决到处尺寸乱的问题**

1. **弹窗整改**：所有弹窗必须归入四档（sm/md/lg/xl），禁止自定义宽度高度
2. **卡片整改**：所有卡片高度必须一致，禁止大小不一、大的大小的小
3. **按钮整改**：所有按钮必须使用统一组件，高度统一（32/40/48px），禁止自定义
4. **输入框整改**：所有输入框高度统一40px，边框、聚焦样式统一
5. **间距整改**：所有间距必须使用8px基数的Token，禁止10px、15px等非标准间距
6. **颜色整改**：所有颜色必须使用Token，禁止硬编码颜色值
7. **字号整改**：所有字号必须使用Token，禁止13px、15px等非标准字号
8. **图标整改**：所有图标必须使用统一图标库，禁止混用
9. **状态栏整改**：所有页面状态栏样式统一，内容一致
10. **空状态整改**：所有无数据页面必须有统一空状态组件

**整改原则：增量整改，不破坏现有功能，随迭代逐步整改，整改一个验证一个。**


### 11.13 专家组轮番优化机制（宪法铁律，必须严格执行）

**立法背景**：系统优化涉及UI/UX、前端、后端、AI、算法、安全、专业内容等多个领域，38位专家分属8个专家组。为避免多组同时优化导致冲突、重复劳动、故障叠加，必须建立**专家组轮番优化机制**：一个专家组完成自己领域的优化并验证通过后，再轮到下一个专家组，严禁多组并行优化同一模块。

---

#### 一、专家组划分（8组，共38位专家）

| 专家组 | 人数 | 成员 | 优化领域 |
|--------|------|------|----------|
| **第一组：设计系统专家组** | 3位 | 设计系统专家、前端架构师、高级UX/UI设计师 | UI/UX全局优化、设计Token、组件库、布局规范、视觉一致性 |
| **第二组：前端故障排查专家组** | 4位 | 浏览器内核专家、PWA/Service Worker专家、前端运行时调试专家、DOM渲染专家 | 前端稳定性、白屏故障、缓存治理、渲染性能、JS错误排查 |
| **第三组：架构与基础技术专家组** | 8位 | 系统架构专家、后端开发架构专家、前端架构专家、数据库架构专家、网络与多端同步架构专家、第三方组件安全与风控评估专家、设计系统专家、SQLite数据库深度优化专家 | 系统架构、后端性能、数据库优化、多端同步、第三方组件治理 |
| **第四组：AI与文件处理专家组** | 5位 | 本地LLM大模型应用架构专家、多格式文件深度解析专家、图文公式高精度OCR识别专家、题库生态格式迁移互通专家、PDF解析与题库识别算法专家 | AI识别、PDF解析、OCR识别、题库识别、文件处理、多模态识别 |
| **第五组：学习算法专家组** | 5位 | 间隔重复记忆算法专家、学情大数据分析与智能测评专家、全真标准化模考引擎架构专家、知识图谱与关联推理专家、数据可视化与学习分析专家 | SM-2/FSRS算法、学情分析、模考引擎、知识图谱、学习数据可视化 |
| **第六组：质量安全运维专家组** | 8位 | 网络与数据安全专家、全场景测试质量专家、系统性能深度调优专家、全平台兼容性架构专家、产品交付与部署工程专家、数据容错恢复与系统降级专家、标准化文档工程专家、系统监控与可观测性专家 | 安全加固、测试覆盖、性能调优、多端兼容、部署交付、容错降级、监控告警 |
| **第七组：产品交互专家组** | 3位 | 教育产品架构专家、UI/UX全链路交互设计专家、用户内容风控与治理专家 | 产品逻辑、交互流程、用户体验、功能合并、入口统一 |
| **第八组：建工专业专家组** | 3位 | 标准化题库架构业务专家、一级造价/一级建造师考试教研权威专家、建工案例题结构化智能阅卷评分专家 | 题库内容、考点权威、专业标准、阅卷评分、考纲贴合 |

---

#### 二、轮番优化顺序（严格按此顺序，不得跳组、不得并行）

| 轮次 | 专家组 | 优化重点 | 前置条件 | 验收标准 |
|------|--------|----------|----------|----------|
| **第1轮** | 设计系统专家组 | 设计Token完善、组件库建立、全局布局规范、视觉一致性整改 | 黄金备份完成 | 所有页面使用统一组件类，无硬编码颜色/间距，布局一致 |
| **第2轮** | 前端故障排查专家组 | 白屏故障排查、JS错误清理、SW缓存治理、渲染性能优化 | 第1轮验收通过 | 控制台无阻断性错误，SW完全注销，页面加载<3秒 |
| **第3轮** | 架构与基础技术专家组 | 后端架构优化、数据库性能、多端同步、第三方组件治理 | 第2轮验收通过 | 后端接口响应<500ms，数据库查询优化，同步稳定 |
| **第4轮** | AI与文件处理专家组 | PDF识别优化、OCR识别、题库识别准确率、AI辅助功能 | 第3轮验收通过 | 题库识别准确率>90%，PDF解析稳定，AI功能可用 |
| **第5轮** | 学习算法专家组 | SM-2算法优化、学情分析、模考引擎、知识图谱 | 第4轮验收通过 | 复习计划科学，学情分析准确，模考功能完整 |
| **第6轮** | 质量安全运维专家组 | 安全加固、测试覆盖、性能调优、监控告警 | 第5轮验收通过 | 安全漏洞清零，测试覆盖>80%，性能达标，监控完善 |
| **第7轮** | 产品交互专家组 | 功能合并、入口统一、交互优化、用户体验 | 第6轮验收通过 | 无功能重复，入口统一，交互流畅，用户体验良好 |
| **第8轮** | 建工专业专家组 | 题库内容审核、考点权威、专业标准、阅卷评分 | 第7轮验收通过 | 题库内容零错误，考点权威，专业标准统一 |

---

#### 三、每组优化执行流程（必须严格遵守）

**步骤1：本组启动前检查**
- 确认上一组已验收通过
- 确认黄金备份已完成
- 确认本组优化范围不与已完成组冲突
- 输出本组优化计划（优化目标、范围、预期效果、风险评估）

**步骤2：本组优化执行**
- 仅优化本组负责领域，严禁越界优化其他组领域
- 增量优化，不破坏现有功能
- 每优化一个模块立即验证
- 记录优化日志（修改文件、修改内容、验证结果）

**步骤3：本组验收**
- 语法层验证：所有修改文件语法零错误
- 运行层验证：控制台无新增错误，功能正常
- 业务层验证：优化目标达成，效果可量化
- 输出本组优化报告（优化内容、效果对比、遗留问题、下一组建议）

**步骤4：交接给下一组**
- 提交优化报告给下一组
- 说明已完成内容和遗留问题
- 下一组确认接收后，本组工作结束
- 记录到宪法修订记录

---

#### 四、禁止事项（红线，违反直接判定任务失败）

❌ **禁止多组并行优化同一模块**：必须一组完成后下一组才能开始
❌ **禁止跳组优化**：必须按顺序1→2→3→...→8，不得跳过
❌ **禁止越界优化**：每组仅优化自己领域，严禁优化其他组领域
❌ **禁止未验证就交接**：本组必须验收通过后才能交接给下一组
❌ **禁止破坏已有优化**：下一组优化时不得破坏上一组已完成的优化成果
❌ **禁止无黄金备份就优化**：每组启动前必须确认黄金备份已完成
❌ **禁止一次性批量重写**：必须增量优化，优化一个验证一个
❌ **禁止专家缺席决策**：任何优化决策必须有该领域专家参与

---

#### 五、专家履职要求

1. **本组专家必须全程参与**：本组优化期间，本组所有专家必须参与分析、决策、验证
2. **交叉验证**：本组优化结果必须由本组内另一位专家交叉验证
3. **专业错误零容忍**：本组专家犯专业错误，立即记录到`ai_global_correction`表
4. **主动思考**：本组专家必须主动发现问题、提出方案，不得等待用户一步步教
5. **全局视角**：本组优化时必须考虑对其他组的影响，不得只顾自己领域
6. **文档输出**：每组必须输出完整优化报告，不得只改代码不写文档

---

#### 六、当前进度追踪

| 轮次 | 专家组 | 状态 | 完成时间 | 优化报告 |
|------|--------|------|----------|----------|
| 第1轮 | 设计系统专家组 | ⏳进行中 | - | 设计Token+组件库已完成，页面改造进行中 |
| 第2轮 | 前端故障排查专家组 | 📝待启动 | - | - |
| 第3轮 | 架构与基础技术专家组 | 📝待启动 | - | - |
| 第4轮 | AI与文件处理专家组 | 📝待启动 | - | - |
| 第5轮 | 学习算法专家组 | 📝待启动 | - | - |
| 第6轮 | 质量安全运维专家组 | 📝待启动 | - | - |
| 第7轮 | 产品交互专家组 | 📝待启动 | - | - |
| 第8轮 | 建工专业专家组 | 📝待启动 | - | - |

---

**机制生效时间**：2026-09-06
**制定专家**：38位全球顶级专家联合委员会
**审核通过**：全体38位专家一致通过
**宪法效力**：本章为宪法铁律，必须严格执行，违反者直接判定任务失败

## 第十二章 服务稳定性宪法

### 12.1 Watchdog 规则



* 每 5 秒检测服务状态

* 崩溃 5 秒内自动重启

* 重启失败重试 3 次（指数退避）

* 连续崩溃 3 次告警

* 记录运行状态日志

### 12.2 端口与实例规则



* 启动时检测端口，被占用自动尝试下一个（8000→8001→8002）

* 记录实际端口到配置

* 启动时检测已有实例，提示 "系统已在运行"，防止重复启动

### 12.3 资源监控规则



* 内存 > 80% 告警，> 90% 清缓存

* 磁盘 > 80% 告警，> 90% 清旧日志备份

* CPU > 90% 告警

* 四级告警（INFO/WARNING/ERROR/CRITICAL），控制台 + 日志 + 系统通知 + 前端弹窗

* 同类错误 10 分钟内只告警一次

### 12.4 启动 / 关闭规则



* 启动环境检测：Python 版本 + 依赖 + 端口 + 磁盘 + 数据库 + 配置

* 失败友好提示（具体原因 + 建议）

* 关闭优雅退出：停止新请求 + 等待完成 + 保存数据 + 关闭连接 + 清理临时

* 关闭 bat 无 "Terminate batch job" 提示



***

## 第十三章 绝对禁止清单（红线，违反直接判定任务失败）



1. ❌ **禁止对现有代码做一次性全量重构，批量删除旧代码**（防止闪卡、艾宾浩斯、脑图、同步、弹窗功能损坏）

2. ❌ **禁止 common 公共目录混入业务逻辑**

3. ❌ **禁止 A 模块直接导入调用 B 模块 service 业务代码**

4. ❌ **禁止新增接口、数据表、DOM 组件不添加模块缩写**

5. ❌ **禁止识别结果跳过预览确认步骤自动入库**

6. ❌ **禁止仅传递 PDF 纯文本给 VL 多模态模型，不传截图 + 版面坐标**

7. ❌ **禁止改动完成不执行对应模块自测，破坏现有测试用例**

8. ❌ **禁止修改后不实测验证，让用户一遍遍测试**

9. ❌ **禁止头疼医脚、表面修改，不找根本原因**

10. ❌ **禁止简单删除了事，不平稳过渡**

11. ❌ **禁止科目名称混用（登录界面官方名称，登录后页面内部简称）**

12. ❌ **禁止管理页面过滤科目（管理页面应显示所有科目）**

13. ❌ **禁止测试从登录页面开始（必须从业务页面开始测试）**

14. ❌ **禁止空壳页面和空按钮（每个菜单和按钮必须有对应功能实现）**

15. ❌ **禁止修改后不更新版本号（必须更新 app.js 版本号并清除缓存）**

16. ❌ **禁止引用不存在的资源文件（CSS/JS/ 图片必须校验存在性）**

17. ❌ **禁止调用未定义的函数或 API（调用前必须校验存在性）**

18. ❌ **禁止修改范围失控（修改前必须做影响评估，明确修改范围）**

19. ❌ **禁止 AI 盲目顺从用户（必须以专家身份独立判断，提出专业建议）**

20. ❌ **禁止修改不生效时简单归因于缓存（必须按顺序深挖执行链路）**

21. ❌ **禁止下拉选择后立即跳转（必须有确认按钮，等待用户确认）**

22. ❌ **禁止 Service Worker 脚本 MIME 类型错误（必须为 application/javascript）**

23. ❌ **禁止文档章节号混乱（修改后必须校验章节号连续性）**

24. ❌ **禁止数据库操作前不校验表存在性（必须校验表和数据完整性）**

25. ❌ ❌ **禁止重犯历史错误应对清单中已记录的 25 条错误**



***

## 第十四章 修订记录



| 版本   | 日期         | 修订内容                            | 修订人    |
| ---- | ---------- | ------------------------------- | ------ |
| V1.0 | 2026-09-04 | 初始版本，基于历史对话中所有确认的规则、架构决策和踩坑教训整理 | AI 架构师 |
| V1.1 | 2026-09-04 | 加入制定者身份（四料专家）、简称映射加专业方向、四大板块修正 | 28位专家委员会 |
| V1.2 | 2026-09-04 | 加入28位全球顶级专家并行推演机制（第一到第五章），制定委员会升级为28位专家 | 28位专家委员会 |
| V1.3 | 2026-09-04 | 加强AI核心战略地位，第一章总则增加AI核心战略条款，功能宪法扩展AI核心能力矩阵 | 28位专家委员会 |
| V1.4 | 2026-09-04 | 增加考试练题复习核心战略（与AI并列），功能宪法增加六大核心能力矩阵、质量标准、题库建设、刷题体验、科学记忆 | 28位专家委员会 |
| V1.5 | 2026-09-04 | 增加多端离线同步核心战略（第三大核心），功能宪法增加四大核心能力矩阵、质量标准、多端适配部署 | 28位专家委员会 |
| V1.6 | 2026-09-04 | 制定委员会升级为28位全球顶级专家联合制定，设常务委员会（4位日常决策）和全体委员会（28位重大决策） | 28位专家委员会 |
| V1.7 | 2026-09-04 | 增加决策判定标准（日常决策vs重大决策），历史错误应对清单（25条），绝对禁止清单扩展到25条 | 28位专家委员会 |
| V1.8 | 2026-09-04 | 遍历所有对话全面完善：功能布局规则、模块解耦架构规范、题库三层去重、数据完整性校验、统一日志封装、RAG知识库、布局统一规范、弹窗规范、触控交互规范 | 28位专家委员会 |
| V1.9 | 2026-09-04 | 修复章节号重复问题，第八章3.6-3.7、第十章5.5-5.7、第十一章6.5-6.7序号修正 | 28位专家委员会 |
| V2.0 | 2026-09-04 | 重大版本升级：①所有章节小节序号与章节号统一（6.x-12.x）；②修复弹窗规范重复；③增加教材讲义大纲联动分析规则（两个层次：考什么静态分析+薄弱什么动态分析）；④修订记录补全所有版本 | 28位专家委员会 |
| V2.1 | 2026-09-04 | 增加服务对象至尊定位（中国用户专属），第一章总则第5条，明确服务对象为中国建工考生，严禁添加无关功能 | 28位专家委员会 |
| V2.2 | 2026-09-04 | 融入四位专家职责：①设计系统专家-第十一章扩展为设计系统与UI/UX宪法，新增设计Token体系（颜色/字号/间距/圆角/阴影/尺寸）、弹窗四档规范（sm/md/lg/xl）、组件复用规则、视觉规范、交互规范、现有系统一致性整改要求；②前端架构师-第七章新增7.6前端架构师代码约束（CSS变量/Token强制使用、硬编码尺寸禁止规则、目录模块约束、代码约束强制执行机制）；③高级UX/UI设计师-第十一章视觉规范（颜色/字体/图标/布局）、交互规范（表单/列表/导航/反馈）；④产品架构师-第一章总则增加第6条产品架构统筹至尊原则，明确四位专家协同闭环（产品定方向→设计定规范→架构定约束→体验定细节） | 28位专家委员会 |



***



***

## 第十六章 前端故障排查专家机制与白屏应急流程（2026-09-06 新增，38位专家联合制定）

### 16.1 白屏/页面不显示故障排查至尊流程（必须严格按顺序执行）

**本质问题**：页面白屏是前端最严重故障，曾因Service Worker缓存旧代码+删除函数导致悬空引用，用户多次刷新无法恢复。

**排查顺序（不可颠倒，每步必须真实验证）**：

| 步骤 | 操作 | 验证标准 | 负责专家 |
|------|------|----------|----------|
| 1 | 检查后端是否正常运行 | `GET /api/health` 返回200 | 后端架构专家 |
| 2 | 检查HTML是否能加载 | `GET /` 返回完整HTML | 浏览器内核专家 |
| 3 | 检查app.js内容是否正确 | 后端返回的app.js包含关键函数（initSpeakSettings/nextCard等） | 前端运行时调试专家 |
| 4 | 检查所有JS语法 | `node --check` 全部通过 | 前端架构师 |
| 5 | 检查是否有悬空引用 | 删除函数前全局搜索所有调用点 | 前端运行时调试专家 |
| 6 | 检查Service Worker状态 | 浏览器Application→Service Workers是否激活 | PWA/SW专家 |
| 7 | 禁用SW（如怀疑SW缓存） | 重命名sw.js+移除注册代码+完全关闭浏览器 | PWA/SW专家 |
| 8 | 强制刷新验证 | Ctrl+Shift+R 或带时间戳URL | DOM渲染专家 |
| 9 | 真实页面渲染验证 | 截图确认页面正常显示 | 浏览器内核专家 |

### 16.2 Service Worker 缓存治理铁律（曾多次踩坑）

1. **所有静态文件必须带版本号参数**：`app.js?v=xxx`，严禁无版本号引用
2. **SW缓存版本必须与代码版本同步**：每次代码修改必须更新SW的CACHE_VERSION
3. **白屏应急第一优先级**：禁用SW > 清除缓存 > 恢复代码，顺序不可颠倒
4. **禁用SW三步骤**：①移除index.html中SW注册代码 ②重命名sw.js为.disabled ③完全关闭浏览器再打开
5. **Clear-Site-Data慎用**：会清除所有localStorage/IndexedDB，可能导致用户数据丢失，仅在极端情况使用
6. **SW注册代码必须可配置**：开发环境默认禁用SW，生产环境才启用

### 16.3 悬空引用检测至尊机制（删除函数前强制执行）

**本质问题**：曾因批量删除app.js中60个函数，导致26个函数仍被调用（其中1个在resource.js中缺失），页面白屏。

**删除函数前必须执行的检查清单**：

1. **全局搜索调用点**：在所有JS文件中搜索`函数名(`，确认没有其他地方调用
2. **检查window暴露**：确认该函数没有被`window.函数名 =`暴露到全局
3. **检查HTML内联调用**：搜索`onclick="函数名`等内联事件绑定
4. **检查事件监听器**：搜索`addEventListener`中是否引用该函数
5. **检查定时器**：搜索`setTimeout`/`setInterval`中是否引用该函数
6. **检查resource.js**：确认resource.js中是否有该函数的实现（如果有，删除app.js中的是安全的）
7. **删除后立即验证**：`node --check`语法检查 + 浏览器真实加载验证

**禁令**：
- ❌ 严禁批量删除函数后不验证就继续
- ❌ 严禁删除被DOMContentLoaded/初始化代码调用的函数
- ❌ 严禁删除window暴露的全局函数
- ❌ 严禁用"应该没问题"代替真实运行验证

### 16.4 代码修改后三级验证机制（不可跳过）

| 级别 | 验证内容 | 工具 | 不通过的后果 |
|------|----------|------|-------------|
| 一级 | JS语法检查 | `node --check` | 语法错误必须修复 |
| 二级 | 运行时错误检查 | 浏览器Console无Error | 运行时错误必须修复 |
| 三级 | 页面真实渲染验证 | 截图确认页面正常显示 | 白屏/布局错乱必须修复 |

**铁律**：三级验证全部通过，才能宣称"已完成""已修复"。任何一级不通过，任务判定为失败。

### 16.5 前端运行时错误分类与快速定位

| 错误类型 | 常见原因 | 快速定位方法 | 负责专家 |
|----------|----------|-------------|----------|
| ReferenceError | 函数/变量未定义（悬空引用） | 搜索错误中提到的函数名 | 前端运行时调试专家 |
| TypeError | 对undefined/null调用方法 | 检查对象是否正确初始化 | 前端运行时调试专家 |
| SyntaxError | 语法错误（括号不匹配/模板字符串） | `node --check`定位行号 | 前端架构师 |
| 无限循环 | setInterval/递归无终止 | 检查Network请求频率 | 浏览器内核专家 |
| 429 Too Many Requests | 请求过于频繁 | 检查轮询/同步逻辑 | 后端架构专家 |
| 401 Unauthorized | 未登录/token失效 | 检查登录状态 | 后端架构专家 |

### 16.6 已发生的重大前端故障（永久警示）

**故障1：app.js批量删除导致白屏（2026-09-06）**
- 现象：页面白屏，所有功能不可用
- 原因：批量删除60个函数，其中`renderFormulaTraining`在resource.js中缺失，`initSpeakSettings`等函数仍被DOMContentLoaded调用
- 修复：从备份恢复app.js + 禁用SW + 强制刷新
- 教训：删除函数前必须全局搜索所有引用，严禁批量删除不验证

**故障2：Service Worker缓存旧代码导致白屏（2026-09-06）**
- 现象：app.js已恢复但用户仍白屏
- 原因：SW拦截请求返回缓存的旧app.js，版本号参数缺失导致浏览器不更新
- 修复：禁用SW（重命名sw.js+移除注册代码）+ 完全关闭浏览器
- 教训：所有静态文件必须带版本号，SW缓存版本必须同步更新

> **本文件为活文档，随着系统迭代持续更新。任何与本文件冲突的决策，必须先修订本文件，再执行修改。**

***

## 第三十六章 知识点标准体系至尊准则

### 13.1 知识点体系建设三原则

1. **教材目录是骨架**：所有知识点必须以官方教材目录为权威来源，严禁从讲义、笔记等二手资料随意提取知识点名称。教材章、节、目三级结构是知识点体系的唯一骨架。
2. **真题统计是血肉**：每个知识点的重要性、频次、分值必须基于历年真题真实统计，严禁主观臆断。考点优先级由数据决定，不由个人判断决定。
3. **造价专家审核是灵魂**：所有知识点名称、分类、重要性标记必须经过造价培训专家审核确认，确保专业零谬误。

### 13.2 知识体系数据来源优先级（至尊规则，曾多次踩坑）

**核心问题**：知识点来源混乱，凭空造知识点、只看文件名不看内容、数据散乱无依据。

**数据来源优先级（从高到低）**：

| 优先级 | 数据来源 | 用途 | 权重 | 说明 |
|--------|----------|------|------|------|
| **P0（主）** | 知识点精讲PDF | 知识点名称、章节结构、考点细分 | 50% | 培训机构官方讲义，有考试大纲依据，是知识点体系的主要来源。必须全面分析到每一页，禁止只看文件名 |
| **P1（辅）** | 官方教材目录 | 章/节骨架结构 | 20% | 教材目录是知识体系的骨架，用于验证知识点精讲的章节结构是否完整 |
| **P2（辅）** | 考试大纲 | 考点范围、要求层级 | 15% | 考试大纲明确考点范围和掌握/熟悉/了解层级，用于标记知识点重要性 |
| **P3（辅）** | 历年真题 | 考点频次、分值分布 | 10% | 历年真题用于统计知识点的考察频次和分值，标记高频考点 |
| **P4（参考）** | 讲义/笔记 | 知识点补充、口诀总结 | 5% | 其他讲义和笔记仅作为补充参考，不得作为知识点名称的主要来源 |

**铁律**：
1. 知识点名称必须以P0知识点精讲为主要来源，禁止凭空造知识点
2. 知识点精讲必须全面分析到每一页，包括文件夹名、文件名、PDF内容、知识点清单思维导图
3. 每一个细节都是有用的，包括文件夹名、文件名、PDF内的知识点清单
4. 教材目录仅用于验证骨架结构，不得作为知识点名称的唯一来源
5. 真题统计仅用于标记重要性，不得作为知识点名称的来源

### 13.3 三级知识点体系结构

- point_id命名规范：GL_3.5（管理第3章第5节）、SLAL_2.3（水利案例第2章第3节）
- 一造管理：6章27节104知识点（基于2025版知识点精讲建立）
- 一造水利案例：5章21节标准知识点
- 层级结构：L1章 → L2节 → L3知识点 → L4细分考点（从题库/闪卡提取）

### 13.4 知识点关联铁律

1. 所有题目必须关联到标准知识点，关联率目标>=95%
2. 所有闪卡必须关联到标准知识点，关联率目标>=90%
3. 所有思维导图必须关联到标准知识点，关联率目标>=100%
4. 关联算法优先级：章节精确匹配 > 关键词深度匹配 > 专业术语匹配 > 类型推断 > 章节兜底
5. 章节格式必须统一为"第X章 章节名称"
6. 关联率低于70%视为未完成，必须继续优化

### 13.5 知识点重要性标记

- is_constant=1（必考）：近3年真题均考察
- is_high_freq=1（高频）：6年真题累计>=80道
- is_key_point=1（核心考点）：知识点精讲中明确标注的核心考点
- is_understanding=1（掌握）：考试大纲要求掌握层级
- is_familiar=1（熟悉）：考试大纲要求熟悉层级
- is_know=1（了解）：考试大纲要求了解层级

### 13.6 知识体系建立流程（五步法）

**第一步：资料收集**
- 收集知识点精讲PDF（P0主要来源）
- 收集官方教材目录（P1辅助来源）
- 收集考试大纲（P2辅助来源）
- 收集历年真题（P3辅助来源）
- 收集其他讲义/笔记（P4参考来源）

**第二步：骨架建立**
- 从知识点精讲文件名提取章/节/知识点
- 从知识点精讲PDF内容提取细分考点（必须全面分析到每一页）
- 用教材目录验证章/节骨架结构完整性
- 建立knowledge_framework表（L1章/L2节/L3知识点）

**第三步：数据关联**
- 题库关联到L3知识点（关键词匹配+章节匹配）
- 闪卡关联到L3知识点（先匹配章节，再匹配知识点）
- 思维导图关联到L2节/L3知识点
- 关联率目标：题库>=95%，闪卡>=90%，导图>=100%

**第四步：重要性标记**
- 从历年真题统计考点频次、分值分布
- 从考试大纲标记掌握/熟悉/了解层级
- 从知识点精讲标记核心考点
- 建立五维重要性评分模型

**第五步：造价专家审核**
- 造价专家审核知识点名称准确性
- 造价专家审核章节结构完整性
- 造价专家审核重要性标记合理性
- 未经造价专家审核的知识点不得正式启用

### 13.7 知识体系质量验收标准

| 验收项 | 标准 | 验证方法 |
|--------|------|----------|
| 知识点来源 | 100%有官方依据（知识点精讲/教材/考纲） | 抽查知识点，追溯来源 |
| 章节结构完整性 | 与教材目录100%一致 | 对比教材目录 |
| 题库关联率 | >=95% | 统计关联题目数/总题目数 |
| 闪卡关联率 | >=90% | 统计关联闪卡数/总闪卡数 |
| 导图关联率 | >=100% | 统计关联导图数/总导图数 |
| 知识点名称准确性 | 造价专家审核100%通过 | 造价专家签字确认 |
| 重要性标记合理性 | 真题统计数据支撑 | 对比真题频次 |

### 13.8 知识体系全局协同机制

**核心目标**：建立知识点→题库→闪卡→导图的全局视图，实现数据打通，禁止数据散乱。

**协同关系**：
```
L1章 → L2节 → L3知识点 → L4细分考点
                          ↓
                    题库题目（多对一）
                    闪卡（多对一）
                    导图（多对一）
```

**全局功能**：
1. 按知识点筛选题库：选择一个知识点，显示所有关联题目
2. 按知识点筛选闪卡：选择一个知识点，显示所有关联闪卡
3. 按知识点筛选导图：选择一个知识点，显示所有关联导图
4. 知识点掌握度分析：统计每个知识点的题目正确率、闪卡复习进度
5. 知识点关联图谱：可视化显示知识点之间的关联关系

**铁律**：
1. 题库、闪卡、导图必须关联到统一知识体系，禁止数据散乱
2. 新增题目/闪卡/导图时必须自动关联知识点，禁止无知识点数据
3. 全局协同功能必须可用，禁止只建骨架不打通

***

## 第三十七章 AI大脑自我进化机制

### 14.1 进化机制三表联动

| 表名 | 用途 |
|------|------|
| conversation_log | 对话记录 |
| ai_learning | AI学习规则库（34条） |
| thinking_chain | 思考链案例库（9条） |

### 14.2 对话记录铁律

1. 每轮关键对话必须提取决策规则写入ai_learning表
2. 每个问题解决过程必须写入thinking_chain表（问题->分析->方案->结果）
3. 规则类型：架构决策、数据治理、质量铁律、前端教训、专业标准、AI标签、算法决策、测试规范
4. 规则置信度>=0.9自动激活

### 14.3 思考链沉淀规范

每个思考链必须包含：problem（问题）、analysis（根因分析）、solution（解决方案）、result（实际结果）、experts_involved（参与专家）、tags（分类标签）

### 14.4 AI大脑迭代方向

1. 从被动响应到主动发现
2. 从单轮处理到持续学习
3. 从规则执行到智能推荐
4. 从人工标签到自动标注

***

## 第三十八章 考点多维科学分析体系

### 15.1 五维重要性评分模型（满分100）

| 维度 | 权重 | 说明 |
|------|------|------|
| 真题频次 | 30% | 6年真题累计出现次数 |
| 年份连续性 | 20% | 连续考察年数 |
| 分值占比 | 25% | 6年累计分值 |
| 近3年热度 | 15% | 2023-2025出现频率 |
| 多选占比 | 10% | 多选题难度权重 |

### 15.2 学习梯队科学划分

- 第一梯队（>=80分）：工程项目管理(88.3)、工程经济(85.7)、全过程造价(81.1)
- 第二梯队（65-79分）：工程项目投融资(80.0)、相关法律法规(74.8)
- 第三梯队（<65分）：基本制度(49.3)

### 15.3 考点分析数据来源唯一性

1. 章节分值分布只能用真题作为基础，严禁用模拟题统计
2. 真题数据不齐时从网络权威资源补充
3. 网络数据仅作参考，必须标注来源
4. 考试时间、及格分数等核心数据必须以官方为准

***

> **本文件为活文档，随着系统迭代持续更新。任何与本文件冲突的决策，必须先修订本文件，再执行修改。**


---

## 第十七章 黄金备份与变更管控机制（铁律）

> **立法背景**：因 app.js 批量删除函数导致白屏、反复修改反复出错，38位专家联合制定本章。**本章为最高优先级铁律，违反者立即停止所有操作。**

### 17.1 黄金备份定义

**黄金备份（GOLDEN Backup）**：经用户确认、功能完全正常的版本快照，作为所有变更的基准参照系。

- 位置：`backups/GOLDEN_golden_backup/`
- 包含：app.js、resource.js、index.html、main.py、exam_config.json、数据库
- 属性：**只读，不可修改，不可覆盖**
- 更新条件：仅当用户明确确认"当前版本完全正常，可以作为新基准"时，由用户授权更新

### 17.2 变更前强制对比（不可跳过）

**任何代码修改前，必须执行**：
```bash
python tools/diff_vs_golden.py
```

输出三态：
- `[未变]`：与黄金备份一致，可安全修改
- `[已改]`：与黄金备份不同，必须先确认这些改动是用户授权的、已验证的
- 如果发现未授权的改动，**立即停止，回滚后再继续**

### 17.3 变更三原则

1. **最小变更原则**：只改被点名的范围，不碰未提及的文件和函数
2. **单点验证原则**：每改一个文件，立即验证；通过后才改下一个
3. **可回滚原则**：每次修改前自动备份当前版本到 `backups/pre_change_时间戳/`

### 17.4 回滚机制

**出现以下任一情况，立即回滚**：
- 页面白屏超过30秒
- 控制台出现红色Error且影响核心功能
- 用户明确说"不对"、"改坏了"
- 对比工具发现未授权变更

**回滚命令**：
```bash
# 回滚单个文件
python tools/rollback_to_golden.py app.js

# 回滚所有关键文件
python tools/rollback_to_golden.py
```

回滚后自动将当前版本备份到 `backups/pre_rollback_时间戳/`，可双向恢复。

### 17.5 禁止事项（红线）

- ❌ 禁止在未对比黄金备份的情况下直接修改代码
- ❌ 禁止批量删除多个函数后一次性验证
- ❌ 禁止"先改了再说"，必须先确认黄金备份状态
- ❌ 禁止覆盖黄金备份目录
- ❌ 禁止用"可能没问题"代替实际验证

### 17.6 变更日志

每次修改必须记录：
- 修改时间
- 修改文件
- 修改原因（用户指令原文）
- 验证结果
- 与黄金备份的差异

日志位置：`backups/CHANGELOG.md`

### 17.7 三级备份体系（专家优化方案，铁律）

**比双备份更完善的三级体系，自动触发+验证+可追溯：**

#### L1 黄金备份（稳定基准，只读）
- 位置：`backups/GOLDEN_golden_backup/稳定版_日期/`
- 属性：只读，不可修改，不可覆盖
- 更新条件：用户明确确认"当前版本完全正常"时授权更新
- 用途：所有变更的基准参照系，布局恢复基准

#### L2 功能增量备份（按模块单独管理）
- 位置：`backups/功能增量_模块名_日期/`
- 触发：每个功能模块完成验证后自动创建
- 内容：只包含该模块相关的变更文件
- 关联：记录基于哪个黄金备份版本，包含哪些功能变更
- 用途：按功能模块回滚，不影响其他模块

#### L3 变更前快照（每次修改前自动备份）
- 位置：`backups/pre_change_时间戳/`
- 触发：任何代码修改前自动创建
- 保留：最近10个，超过自动清理
- 用途：快速回滚到修改前状态

#### 自动备份触发条件（不可跳过）
1. 任何代码修改前 → 自动创建L3快照
2. 功能模块验证通过 → 自动创建L2增量备份
3. 用户说"锁死" → 自动创建L1黄金备份
4. 重大版本发布前 → 自动创建L1黄金备份
5. 每日凌晨 → 自动创建L3快照（如有变更）

#### 备份验证机制（铁律）
- 备份后自动验证文件完整性（MD5校验）
- 自动验证关键文件可读取
- 备份损坏立即告警，禁止使用损坏备份
- 每周自动验证所有黄金备份可恢复性

#### 备份清理机制
- L1黄金备份：永久保留
- L2功能增量：保留全部，按模块归档
- L3变更前快照：保留最近10个，超过30天自动清理

#### 一键回滚三模式
1. 按功能模块回滚：从L2恢复指定模块
2. 按时间点回滚：从L3恢复到修改前
3. 全量回滚：从L1恢复到黄金基准

---

## 第十八章 真实运行验证铁律

> **立法背景**：用户反复强调"每一步操作都是真真实实的运行"、"禁止可能/大概/应该"、"不要糊弄我"。

### 18.1 验证三层次

1. **语法层**：`node --check` / `python -m py_compile`（最低门槛，不代表功能正常）
2. **运行层**：后端实际启动、前端实际加载、Console无Error
3. **业务层**：用户实际操作路径走通，数据真实写入数据库

### 18.2 禁止虚假验证

- ❌ 禁止用"语法通过"代替"功能正常"
- ❌ 禁止用后台脚本结果代替前端真实操作
- ❌ 禁止说"应该可以"、"大概没问题"、"可能正常"
- ❌ 禁止未实际运行就宣称"已完成"

### 18.3 验证报告格式

每次完成后必须输出：
```
✅ 已验证：[具体操作]
   - 语法：通过/失败
   - 运行：通过/失败
   - 业务：通过/失败
   - 证据：[实际输出/截图/数据库记录]
```

***

## 第十九章 本地部署智能化完整体系（至尊准则）

> **立法背景**：用户强调"形成自己的知识库，有利于本地部署的智能化"、"62位专家要主动思考，不能每次提醒"、"不能功能有就代表成熟完善，一定要发挥科学精神"。本章规定本地部署智能化的完整体系，包括知识库、AI组件、数据治理、学习分析、架构优化、用户体验、安全保障七大维度，确保系统在本地环境下实现智能化、自动化、个性化。

### 19.0 科学精神与完善性铁律（最高原则）

**核心原则**：功能存在不等于功能完善，功能可用不等于功能成熟。必须发挥科学精神，持续验证、持续优化、持续完善，追求极致质量。

**科学精神五要素**：
1. **实证精神**：所有功能必须经过实际运行验证，禁止凭印象、凭记忆、凭推测判断功能正常
2. **质疑精神**：对所有已实现的功能保持质疑，主动寻找缺陷和不足，禁止自我满足
3. **迭代精神**：功能实现只是开始，必须持续迭代优化，追求更好的性能、更好的体验、更好的质量
4. **全面精神**：必须全面考虑系统的各个方面，禁止只看局部、只看表面、只看功能
5. **严谨精神**：所有数据、所有结论、所有方案必须有事实依据，禁止"可能"、"大概"、"应该"

**完善性判定标准（功能成熟必须同时满足）**：
| 维度 | 标准 | 验证方法 |
|------|------|----------|
| 功能完整性 | 100%功能点实现，无缺失 | 功能清单逐项验证 |
| 数据准确性 | 数据准确率>=95%，无错误数据 | 数据抽样人工核对 |
| 性能达标 | 响应时间<500ms，无慢查询 | 性能测试监控 |
| 稳定性 | 连续运行7天无崩溃，无内存泄漏 | 稳定性测试 |
| 安全性 | 0高危漏洞，0中危漏洞 | 安全扫描审计 |
| 易用性 | 用户体验评分>=85分，无严重体验问题 | 用户测试反馈 |
| 可维护性 | 代码规范，文档完整，测试覆盖>=70% | 代码审查文档检查 |
| 可扩展性 | 架构合理，模块解耦，支持功能扩展 | 架构评估扩展测试 |

**铁律**：
1. ❌ 禁止功能实现就宣称完成，必须经过完善性验证
2. ❌ 禁止功能可用就宣称成熟，必须持续优化迭代
3. ❌ 禁止自我满足、停止优化，必须发挥科学精神持续完善
4. ✅ 每个功能必须有完善性验证报告，证明功能成熟
5. ✅ 每个功能必须有持续优化计划，追求极致质量
6. ✅ 62位专家必须主动质疑、主动验证、主动优化

### 19.1 知识库体系（智能化基础，12类必须全部建立完善）

**核心原则**：所有经常调用的底层数据必须形成知识库，禁止每次临时分析、临时查询。知识库是本地部署智能化的基础，必须全面、准确、实时更新、持续完善。

**知识库12类清单（必须全部建立完善）**：

| 序号 | 知识库名称 | 用途 | 核心字段 | 完善性标准 |
|------|-----------|------|----------|-----------|
| 1 | **知识点知识库** | 统一知识体系骨架（章/节/知识点/重要性/关联统计） | chapter, section, point, level, importance, question_count, flashcard_count | 100%知识点有官方来源，关联率>=90%，重要性标记准确 |
| 2 | **题库统计知识库** | 题库按章/知识点/题型/年份统计 | chapter, knowledge_point, q_type, year, count, accuracy | 统计数据实时更新，准确率100%，维度完整 |
| 3 | **闪卡统计知识库** | 闪卡按章/知识点/掌握状态统计 | chapter, knowledge_point, mastery, count, review_count | 统计数据实时更新，准确率100%，掌握状态准确 |
| 4 | **思维导图知识库** | 导图节点结构、关联知识点、层级关系 | map_id, node_id, node_text, level, knowledge_point, parent_id | 100%导图关联到章/节/知识点，节点结构完整 |
| 5 | **真题考点分布知识库** | 近5年真题考点频次、分值、题型分布 | year, chapter, knowledge_point, question_count, score, q_type | 近5年真题100%统计，分值准确率100%，考点分布可视化 |
| 6 | **易错点知识库** | 高频错题、易错知识点、错误原因分析 | knowledge_point, error_count, error_type, error_reason, correct_method | 高频错题100%收录，错误原因分析准确率>=80%，针对性练习推荐 |
| 7 | **公式知识库** | 计算公式、参数说明、适用场景、例题 | formula_name, formula_expression, parameters, applicable_scenario, example, knowledge_point | 核心公式100%收录，参数说明完整，适用场景清晰，例题准确 |
| 8 | **法律法规知识库** | 现行有效法条、关联考点、修订记录 | law_name, article_no, article_content, knowledge_point, effective_date, amendment | 现行有效法条100%收录，关联考点准确率>=90%，修订记录完整 |
| 9 | **口诀记忆知识库** | 记忆口诀、对应知识点、适用场景 | mnemonic_text, knowledge_point, applicable_scenario, memory_tips | 难记知识点100%有口诀辅助，口诀顺口易记，对应知识点准确 |
| 10 | **学习资料库元数据知识库** | 文件标签、分类、来源、关联知识点 | file_id, filename, file_type, tags, subject, chapter, knowledge_point, source | 100%文件有元数据，标签准确率>=80%，分类清晰，关联知识点准确 |
| 11 | **学习行为知识库** | 用户学习时长、频次、时段、习惯、进度 | user_id, study_date, study_duration, study_count, study_time, chapter_progress, point_progress | 学习行为数据100%记录，行为画像完整，学习进度准确，习惯分析科学 |
| 12 | **AI模型知识库** | AI生成内容、用户反馈、模型参数、优化记录 | model_name, generate_type, generate_content, user_feedback, model_params, optimize_record | AI生成内容100%记录，用户反馈100%收集，模型参数可追溯，优化记录完整 |

**知识库建设铁律**：
1. ❌ 禁止有功能就代表完善，知识库必须全面、准确、实时更新、持续完善
2. ❌ 禁止每次临时分析底层数据，必须先查询知识库
3. ❌ 禁止知识库数据不准确，必须有数据质量监控和验证机制
4. ✅ 12类知识库必须全部建立，禁止只建部分
5. ✅ 知识库必须有统一的元数据管理（版本、记录数、最后更新时间）
6. ✅ 知识库必须有全局数据缓存机制，避免每次查询数据库
7. ✅ 知识库必须有自动更新机制，数据变更时自动更新缓存
8. ✅ 知识库必须有API接口，前端和其他模块可以方便调用
9. ✅ 知识库必须有质量监控机制，定期检查数据完整性和准确性
10. ✅ 知识库必须有完善性验证报告，证明知识库成熟可用

### 19.2 本地AI智能化组件（智能化核心，6类必须全部建立完善）

**核心原则**：本地部署必须具备完整的AI智能化能力，不依赖外部云服务，所有AI能力在本地运行，持续优化完善。

**本地AI组件6类清单（必须全部建立完善）**：

| 序号 | 组件名称 | 用途 | 技术方案 | 完善性标准 |
|------|---------|------|----------|-----------|
| 1 | **本地向量数据库** | RAG语义检索，智能答疑，语义去重 | SQLite-vec / Chroma本地版 | 语义检索准确率>=85%，响应时间<1秒，索引完整 |
| 2 | **本地知识图谱** | 知识点关联推理，学习路径推荐 | NetworkX + 图数据库 | 知识点关联覆盖率>=90%，推理准确率>=80%，图谱完整 |
| 3 | **本地全文搜索引擎** | 题库/闪卡/资料全文检索 | SQLite FTS5 | 全文检索覆盖率100%，响应时间<500ms，检索准确 |
| 4 | **本地任务调度器** | 后台批量识别，缓存更新，定时任务 | APScheduler | 任务执行成功率>=99%，任务可追踪，调度准确 |
| 5 | **本地缓存系统** | 热点数据缓存，减少数据库查询 | 内存缓存 + SQLite缓存表 | 缓存命中率>=80%，数据库查询减少>=50%，缓存更新及时 |
| 6 | **本地监控告警** | 系统健康监控，异常告警，性能监控 | 健康检查 + 日志分析 | 监控覆盖率100%，异常告警响应时间<1分钟，告警准确 |

**本地AI组件建设铁律**：
1. ❌ 禁止依赖外部云服务，所有AI能力必须在本地运行
2. ❌ 禁止只建组件不集成，组件必须与业务模块深度集成
3. ❌ 禁止组件功能不完善，必须持续优化提升准确率和性能
4. ✅ 本地AI组件必须有统一的API接口，业务模块可以方便调用
5. ✅ 本地AI组件必须有健康检查和监控机制
6. ✅ 本地AI组件必须有降级机制，组件故障时系统核心功能仍可用
7. ✅ 本地AI组件必须有完善性验证报告，证明组件成熟可用

### 19.3 AI能力增强体系（智能化应用，10类必须全部建立完善）

**核心原则**：AI能力必须深度融入学习全流程，实现智能化、个性化、自动化，持续优化提升准确率和用户满意度。

**AI能力10类清单（必须全部建立完善）**：

| 序号 | AI能力 | 用途 | 实现方式 | 完善性标准 |
|------|--------|------|----------|-----------|
| 1 | **智能题目生成** | 基于知识点自动生成题目 | Ollama + 知识点知识库 | 生成题目质量评分>=80分，知识点关联准确率>=90% |
| 2 | **智能闪卡生成** | 基于知识点自动生成闪卡 | Ollama + 知识点知识库 | 生成闪卡质量评分>=80分，无完整题目类闪卡 |
| 3 | **智能思维导图生成** | 基于知识点自动生成导图 | 知识点体系 + 模板渲染 | 导图节点完整率>=90%，层级结构清晰 |
| 4 | **智能学习路径推荐** | 基于学习行为推荐学习内容 | 协同过滤 + 知识点掌握度 | 推荐相关性>=80%，用户满意度>=85% |
| 5 | **智能错题分析** | 分析错题原因，推荐针对性练习 | 错题聚类 + 知识点关联 | 错题原因分析准确率>=80%，推荐练习相关性>=85% |
| 6 | **智能答疑助手** | 基于RAG回答学习问题 | 向量检索 + Ollama生成 | 回答准确率>=85%，响应时间<3秒 |
| 7 | **智能内容审核** | 自动审核题库/闪卡质量 | 规则引擎 + AI审核 | 审核准确率>=90%，低质量内容识别率>=95% |
| 8 | **智能去重判断** | 语义相似度去重 | 向量相似度计算 | 去重准确率>=90%，误判率<5% |
| 9 | **智能知识点关联** | 自动关联题目/闪卡到知识点 | 关键词匹配 + 语义匹配 | 关联率>=95%，关联准确率>=90% |
| 10 | **智能复习计划** | 基于SM-2算法自动安排复习 | SM-2 + 艾宾浩斯遗忘曲线 | 复习计划科学合理，记忆保持率>=85% |

**AI能力建设铁律**：
1. ❌ 禁止AI能力只做演示，必须深度融入业务流程
2. ❌ 禁止AI生成内容不审核，必须有质量审核机制
3. ❌ 禁止AI能力准确率不达标，必须持续优化提升
4. ✅ AI能力必须有置信度机制，低置信度内容标记待人工审核
5. ✅ AI能力必须有反馈机制，用户反馈用于优化AI模型
6. ✅ AI能力必须有审计日志，所有AI生成内容可追溯
7. ✅ AI能力必须有完善性验证报告，证明能力成熟可用

### 19.4 数据治理体系（数据质量保障，8类必须全部建立完善）

**核心原则**：数据是系统的核心资产，必须有完善的数据治理机制，确保数据质量、一致性、安全性，持续监控优化。

**数据治理8类机制清单（必须全部建立完善）**：

| 序号 | 机制 | 用途 | 完善性标准 |
|------|------|------|-----------|
| 1 | **数据质量监控** | 实时监控数据完整性、准确性、一致性 | 数据质量评分>=90分，异常数据识别率>=95% |
| 2 | **数据血缘追踪** | 追踪数据来源、变更历史、影响范围 | 数据血缘覆盖率100%，变更可追溯 |
| 3 | **数据版本管理** | 管理数据版本，支持回滚 | 版本管理覆盖率100%，回滚成功率100% |
| 4 | **数据同步机制** | 多端数据同步、冲突解决 | 同步延迟<5秒，冲突解决率100%，数据一致性100% |
| 5 | **数据备份恢复** | 自动备份、快速恢复、黄金备份 | 备份完整性100%，恢复成功率100%，RTO<10分钟 |
| 6 | **数据脱敏机制** | 敏感数据脱敏、隐私保护 | 敏感数据脱敏率100%，无隐私泄露 |
| 7 | **数据一致性规则** | 跨模块数据统一，禁止别名和不一致 | 数据一致性100%，无别名和不一致 |
| 8 | **数据审计日志** | 所有数据变更可审计、可追溯 | 审计日志覆盖率100%，变更可追溯 |

**数据治理铁律**：
1. ❌ 禁止数据散乱，所有数据必须有统一的管理和治理
2. ❌ 禁止数据不一致，跨模块数据必须统一
3. ❌ 禁止数据质量不达标，必须有数据质量监控和优化机制
4. ✅ 数据质量必须有量化指标，定期检查和优化
5. ✅ 数据变更必须有审计日志，可追溯、可回滚
6. ✅ 数据备份必须有黄金备份机制，功能正常时立即备份
7. ✅ 数据治理必须有完善性验证报告，证明治理机制成熟可用

### 19.5 学习分析深化体系（数据价值挖掘，10类必须全部建立完善）

**核心原则**：学习数据必须深度挖掘，为用户提供科学的学习分析和个性化建议，持续优化分析模型和建议质量。

**学习分析10类维度清单（必须全部建立完善）**：

| 序号 | 分析维度 | 用途 | 完善性标准 |
|------|----------|------|-----------|
| 1 | **学习行为分析** | 学习时长、频次、时段、习惯分析 | 分析数据准确率100%，行为画像完整 |
| 2 | **知识点掌握度分析** | 题目正确率、闪卡复习进度、遗忘曲线 | 掌握度评估准确率>=90%，与实际表现一致 |
| 3 | **遗忘曲线预测** | 基于艾宾浩斯预测记忆衰退，自动安排复习 | 预测准确率>=85%，复习计划科学合理 |
| 4 | **考试准备度评估** | 真题模拟分数、知识点掌握、薄弱点 | 评估准确率>=85%，与实际考试成绩相关 |
| 5 | **学习效率分析** | 学习投入与产出比、效率优化建议 | 效率分析准确率>=80%，优化建议可执行 |
| 6 | **薄弱点自动识别** | 基于错题和正确率自动识别薄弱知识点 | 薄弱点识别准确率>=90%，推荐练习相关性>=85% |
| 7 | **学习进度追踪** | 整体学习进度、章节进度、知识点进度 | 进度追踪准确率100%，实时更新 |
| 8 | **真题考点分布分析** | 近5年真题考点频次、分值、题型分布 | 统计准确率100%，考点分布可视化 |
| 9 | **高频考点分析** | 基于真题频次统计高频考点、核心考点 | 高频考点识别准确率>=95%，与教研专家一致 |
| 10 | **学习报告生成** | 定期生成学习报告，总结进步和不足 | 报告内容完整、数据准确、建议可执行 |

**学习分析铁律**：
1. ❌ 禁止只收集数据不分析，数据必须深度挖掘价值
2. ❌ 禁止分析结果不准确，必须有验证机制
3. ❌ 禁止分析建议不可执行，必须有可操作的优化建议
4. ✅ 学习分析必须有量化指标，可验证、可优化
5. ✅ 学习分析结果必须可视化，用户可以直观理解
6. ✅ 学习分析必须有可执行的建议，不能只分析不行动
7. ✅ 学习分析必须有完善性验证报告，证明分析模型成熟可用

### 19.6 系统架构优化体系（可扩展性，8类必须全部建立完善）

**核心原则**：系统架构必须具备良好的可扩展性、可维护性、可演进性，支持持续迭代和功能扩展，持续优化架构质量。

**架构优化8类清单（必须全部建立完善）**：

| 序号 | 架构 | 用途 | 完善性标准 |
|------|------|------|-----------|
| 1 | **插件化架构** | 支持功能插件扩展，模块化解耦 | 插件化覆盖率>=80%，新增功能不影响核心 |
| 2 | **事件驱动架构** | 基于事件总线的模块通信，松耦合 | 事件驱动覆盖率>=70%，模块间无直接依赖 |
| 3 | **配置中心** | 统一配置管理，动态调整参数 | 配置管理覆盖率100%，参数可动态调整 |
| 4 | **API网关** | 统一API入口，限流、鉴权、日志 | API网关覆盖率100%，所有API通过网关 |
| 5 | **熔断降级** | 系统容错机制，故障隔离 | 熔断降级覆盖率>=90%，故障不扩散 |
| 6 | **微服务化** | 核心模块独立部署，横向扩展 | 核心模块微服务化率>=50%，可独立部署 |
| 7 | **模块化架构** | 前端/后端模块化，职责清晰 | 模块化覆盖率100%，模块职责清晰 |
| 8 | **统一状态管理** | 全局状态统一管理，禁止散乱 | 状态管理覆盖率>=90%，无业务级裸全局变量 |

**架构优化铁律**：
1. ❌ 禁止一次性重构，必须增量迁移、逐步优化
2. ❌ 禁止为了架构而架构，架构优化必须服务于业务需求
3. ❌ 禁止架构债务累积，必须定期清理优化
4. ✅ 架构优化必须有明确的目标和验收标准
5. ✅ 架构优化必须有回滚机制，优化失败可快速恢复
6. ✅ 架构优化必须有文档，新架构必须有规范文档
7. ✅ 架构优化必须有完善性验证报告，证明架构成熟可用

### 19.7 用户体验增强体系（易用性，10类必须全部建立完善）

**核心原则**：用户体验是系统成功的关键，必须持续优化，提供流畅、美观、易用的用户界面，持续收集用户反馈优化。

**用户体验增强10类清单（必须全部建立完善）**：

| 序号 | 功能 | 用途 | 完善性标准 |
|------|------|------|-----------|
| 1 | **离线完全可用** | 无网络环境下完整功能可用 | 离线功能覆盖率>=90%，核心功能100%可用 |
| 2 | **多端数据同步** | PC/平板/手机数据实时同步 | 同步延迟<5秒，数据一致性100% |
| 3 | **语音交互** | 语音输入、语音朗读、语音答疑 | 语音识别准确率>=90%，朗读自然流畅 |
| 4 | **手势操作** | 平板/手机手势支持，滑动切换 | 手势操作覆盖率>=80%，操作流畅 |
| 5 | **暗黑模式** | 护眼模式，夜间学习 | 暗黑模式覆盖率100%，视觉舒适 |
| 6 | **快捷键支持** | 提高操作效率，专业用户 | 快捷键覆盖率>=70%，操作效率提升>=30% |
| 7 | **个性化主题** | 自定义颜色、字体、布局 | 主题可定制项>=20个，用户满意度>=85% |
| 8 | **响应式适配** | PC/平板/手机多设备适配 | 适配设备覆盖率100%，布局无错乱 |
| 9 | **加载状态优化** | 加载动画、骨架屏、进度提示 | 加载状态覆盖率100%，用户无等待焦虑 |
| 10 | **错误提示优化** | 友好错误提示、解决方案建议 | 错误提示覆盖率100%，用户可自行解决>=80% |

**用户体验铁律**：
1. ❌ 禁止只追求功能不追求体验，用户体验与功能同等重要
2. ❌ 禁止界面混乱、布局不合理，必须有统一的设计规范
3. ❌ 禁止用户体验问题不解决，必须持续收集反馈优化
4. ✅ 用户体验必须有量化指标，可测量、可优化
5. ✅ 用户体验必须有用户测试，持续收集反馈优化
6. ✅ 用户体验必须有设计规范，所有界面遵循统一规范
7. ✅ 用户体验必须有完善性验证报告，证明体验成熟可用

### 19.8 安全体系完善（安全保障，10类必须全部建立完善）

**核心原则**：安全是系统的基础，必须有完善的安全体系，保障数据安全、系统安全、用户隐私，持续扫描审计优化。

**安全体系10类清单（必须全部建立完善）**：

| 序号 | 机制 | 用途 | 完善性标准 |
|------|------|------|-----------|
| 1 | **用户认证授权** | JWT + 角色权限，最小权限原则 | 认证授权覆盖率100%，无未授权访问 |
| 2 | **数据加密存储** | 敏感数据AES-256加密 | 敏感数据加密率100%，无明文存储 |
| 3 | **传输加密** | HTTPS强制加密 | 传输加密覆盖率100%，无明文传输 |
| 4 | **输入校验** | XSS/SQL注入防护，100%校验 | 输入校验覆盖率100%，无注入漏洞 |
| 5 | **CSRF防护** | 跨站请求伪造防护 | CSRF防护覆盖率100%，无跨站请求 |
| 6 | **限流防刷** | 接口QPS限流，防暴力攻击 | 限流覆盖率>=90%，无暴力攻击 |
| 7 | **审计日志** | 操作审计，完整可追溯 | 审计日志覆盖率100%，操作可追溯 |
| 8 | **文件上传安全** | 文件类型校验、内容校验、病毒扫描 | 文件上传安全覆盖率100%，无恶意文件 |
| 9 | **安全扫描** | 定期安全扫描，漏洞发现和修复 | 安全扫描频率>=每月1次，高危漏洞0个 |
| 10 | **数据备份安全** | 备份加密、异地备份、定期恢复测试 | 备份安全覆盖率100%，恢复成功率100% |

**安全铁律**：
1. ❌ 禁止安全漏洞，所有安全机制必须100%覆盖
2. ❌ 禁止敏感数据明文存储和传输
3. ❌ 禁止安全问题不修复，必须立即修复高危漏洞
4. ✅ 安全必须有量化指标，可测量、可验证
5. ✅ 安全必须有定期扫描和审计，持续优化
6. ✅ 安全必须有应急响应机制，安全事件可快速响应
7. ✅ 安全必须有完善性验证报告，证明安全体系成熟可用

### 19.9 本地部署智能化实施优先级（铁律）

**第一优先级（立即实施，核心基础）**：
1. ✅ 知识点知识库（已完成，需持续完善）
2. ✅ 题库/闪卡统计知识库（已完成，需持续完善）
3. ⏳ 学习行为知识库
4. ⏳ 本地全文搜索引擎（SQLite FTS5）
5. ⏳ 本地缓存系统（热点数据缓存）
6. ⏳ 数据质量监控
7. ⏳ 思维导图知识库
8. ⏳ 真题考点分布知识库

**第二优先级（短期实施，智能化核心）**：
1. ⏳ 本地向量数据库（RAG语义检索）
2. ⏳ 智能题目/闪卡/导图生成
3. ⏳ 智能答疑助手
4. ⏳ 智能去重判断
5. ⏳ 智能知识点关联
6. ⏳ 易错点知识库
7. ⏳ 公式知识库
8. ⏳ AI模型知识库

**第三优先级（中期实施，数据价值）**：
1. ⏳ 学习分析深化（掌握度、遗忘曲线、薄弱点）
2. ⏳ 智能学习路径推荐
3. ⏳ 智能错题分析
4. ⏳ 数据血缘追踪
5. ⏳ 法律法规知识库
6. ⏳ 口诀记忆知识库
7. ⏳ 学习资料库元数据知识库

**第四优先级（长期实施，系统进化）**：
1. ⏳ 本地知识图谱
2. ⏳ 插件化架构
3. ⏳ 事件驱动架构
4. ⏳ 多端同步完善
5. ⏳ 语音交互
6. ⏳ 微服务化

**实施铁律**：
1. ❌ 禁止跳过优先级，必须按优先级顺序实施
2. ❌ 禁止只实施不验证，每个功能实施后必须验证
3. ❌ 禁止功能实现就宣称完成，必须经过完善性验证
4. ✅ 每个优先级实施完成后，必须有验收报告和完善性验证报告
5. ✅ 高优先级功能未完成，不得启动低优先级功能
6. ✅ 实施过程中发现问题，必须立即记录并优化
7. ✅ 所有功能必须持续优化，追求极致质量

***

## 第二十章 62位专家主动履职机制（至尊铁律）

> **立法背景**：用户反复强调"62位专家要主动思考，不能每次提醒"、"这些都是你们应该充分考虑到的点"、"不能功能有就代表成熟完善，一定要发挥科学精神"。本章规定专家主动履职机制，确保专家主动思考、主动发现问题、主动优化，不需要用户每次提醒。

### 20.1 专家主动履职三原则

1. **主动思考原则**：专家必须主动思考系统的各个方面，发现潜在问题和优化机会，不需要用户提醒
2. **主动验证原则**：专家必须主动验证系统功能和数据质量，发现问题立即修复，不需要用户指出
3. **主动优化原则**：专家必须主动优化系统架构、性能、体验，持续提升系统质量，不需要用户要求

### 20.2 专家主动履职清单（必须主动执行）

| 序号 | 履职内容 | 执行频率 | 完善性标准 |
|------|----------|----------|-----------|
| 1 | 知识库完整性检查 | 每日 | 12类知识库100%完整，无缺失，数据准确 |
| 2 | 数据质量检查 | 每日 | 数据质量评分>=90分，无异常数据，数据一致 |
| 3 | 系统健康检查 | 每日 | 系统可用性>=99.9%，无故障，性能达标 |
| 4 | 性能监控优化 | 每周 | 性能指标达标，无慢查询，响应时间<500ms |
| 5 | 安全扫描审计 | 每月 | 高危漏洞0个，中危漏洞<3个，安全机制完善 |
| 6 | 用户体验检查 | 每周 | 用户体验评分>=85分，无严重体验问题，界面美观 |
| 7 | 学习分析深度挖掘 | 每周 | 10类分析维度完整，建议可执行，数据准确 |
| 8 | AI能力优化 | 每周 | AI能力准确率提升，用户满意度提升，模型优化 |
| 9 | 架构优化评估 | 每月 | 架构合规率>=95%，无架构债务，模块解耦 |
| 10 | 宪法和细则更新 | 每次发现问题 | 宪法和细则持续完善，无遗漏，规则清晰 |

### 20.3 专家主动履职铁律

1. ❌ 禁止等用户提醒才行动，专家必须主动思考、主动发现、主动优化
2. ❌ 禁止只做表面工作，必须深入分析、彻底解决、持续完善
3. ❌ 禁止说"可能"、"大概"、"应该"，必须有事实依据和验证结果
4. ❌ 禁止功能实现就宣称完成，必须经过完善性验证
5. ✅ 专家必须有全局视野，考虑系统的各个方面
6. ✅ 专家必须有前瞻性，预见潜在问题和风险
7. ✅ 专家必须有闭环思维，发现问题→分析原因→制定方案→实施验证→持续优化
8. ✅ 专家必须发挥科学精神，实证、质疑、迭代、全面、严谨

***

> **本章及第十九章为本地部署智能化的顶层设计，所有开发、修改、优化必须严格遵守。知识库建设是智能化的基础，12类知识库必须全部建立完善，禁止有功能就代表完善。必须发挥科学精神，持续验证、持续优化、持续完善，追求极致质量。**

***

## 第二十一章 数据去杂与质量治理铁律（至尊准则，优先执行）

> **立法背景**：用户反复强调"去杂处理要优先"、"存储是散的、加工过的，容易把细节漏掉"、"闪卡怎么可能有5000张，相同知识点要判断"、"不能功能有就代表完善"。本章规定数据去杂、质量治理、原始内容保护、完成标准等核心规则，是所有数据处理的最高准则，必须优先执行。
> **责任专家**：数据治理与质量专家、数据库架构专家、造价培训专家、AI专家、题库识别算法专家、闪卡SM-2算法专家联合制定。

### 21.1 去杂处理优先原则（铁律，最高优先级）

**核心原则**：任何数据进入系统前，必须先经过去杂处理；任何功能开发前，必须先确保基础数据干净。去杂处理优先于功能开发，优先于性能优化，优先于界面美化。

**去杂处理五层体系**：

| 层级 | 去杂内容 | 处理方式 | 执行时机 |
|------|----------|----------|----------|
| L1 输入层去杂 | 文件上传时的重复文件、损坏文件、格式错误 | 文件哈希去重、格式校验、完整性检查 | 文件上传时 |
| L2 识别层去杂 | OCR识别中的水印、页眉页脚、乱码、重复内容 | 自动识别并标记，低质量内容待人工校对 | 识别处理时 |
| L3 结构化层去杂 | 提取题目/闪卡/知识点时的重复、错误、不完整 | 三层去重机制、完整性校验、AI质量评估 | 数据提取时 |
| L4 关联层去杂 | 知识点关联错误、标签错误、分类错误 | 关联置信度评估、人工审核、定期复核 | 数据关联时 |
| L5 应用层去杂 | 展示时的重复内容、无效数据、过期数据 | 前端过滤、缓存清理、定期数据审计 | 数据展示时 |

**去杂处理铁律**：
1. ❌ 禁止未经去杂处理的数据直接进入业务库
2. ❌ 禁止跳过去杂步骤直接开发功能
3. ❌ 禁止去杂不彻底就宣称完成
4. ✅ 每次数据导入必须先去杂，再入库
5. ✅ 去杂结果必须可追溯、可恢复、可审计
6. ✅ 去杂标准必须量化、可验证、持续优化

### 21.2 原始内容完整保护原则（铁律，禁止丢失细节）

**核心原则**：原始识别结果必须100%完整保留，所有加工都从原始内容重新生成，禁止只存加工后的结构化数据而丢弃原始内容。

**五层存储架构（必须全部实现）**：

| 存储层级 | 内容 | 用途 | 保留策略 |
|----------|------|------|----------|
| **L0 原始层** | OCR引擎原始输出JSON（完整未加工） | 追溯、重新加工、细节恢复、引擎对比 | **永久保留，禁止删除** |
| **L1 文本层** | 纯文本内容（按页分隔，不做任何加工） | 全文搜索、基础分析、内容校验 | 永久保留 |
| **L2 结构层** | 结构化JSON（页面、块、公式、表格、图片） | 高级分析、功能应用、内容展示 | 永久保留 |
| **L3 索引层** | FTS5全文索引、向量索引、知识点索引 | 快速检索、语义搜索、关联查询 | 可重建，定期优化 |
| **L4 应用层** | 提取的知识点、题目、闪卡、导图 | 业务功能、学习应用 | 可重新生成，定期优化 |

**原始内容保护铁律**：
1. ❌ 禁止只存加工后的结构化数据，必须同时保存原始识别结果
2. ❌ 禁止删除L0原始层数据，即使认为"无用"也必须保留
3. ❌ 禁止覆盖原始内容，加工结果必须另存
4. ✅ 升级识别引擎后，原始结果保留，新旧结果可对比
5. ✅ 结构化数据丢失或错误时，必须能从原始内容重新生成
6. ✅ 支持多种识别引擎的原始结果并存，便于对比和融合

### 21.3 题库去重标准（修正版，研判清楚后物理删除）

**去重判定标准（铁律，四要素全部一致才算重复）**：
- 题干 + 选项 + 答案 + 解析全部一致，才算重复
- 仅题干相似但选项/答案/解析有差异的，不视为重复，全部保留
- 不同来源间重复：保留真题，其他来源的重复题物理删除

**三层去重机制**：
1. **第一层：精确MD5去重**：题干+选项+答案+解析全部预处理（去除空格、换行、标点、全半角统一）后计算MD5，MD5相同则为精确重复
2. **第二层：四要素比对去重**：题干前40字相同 + 选项A-E全部相同 + 答案相同 + 解析前50字相同 = 确认重复
3. **第三层：考点去重**：同一考点 + 同一题型 + 同一难度下题目数量超过阈值（单选≥5道、多选≥3道），标记为同考点重复，AI自动评估保留价值（不自动删除）

**去重后处理（研判清楚后物理删除，铁律）**：
- **前提条件（必须全部满足才能删除）**：
  1. 全面分析重复情况，输出重复报告
  2. AI三层去重机制判断为精确重复或高度重复
  3. 造价专家审核确认（批量去重必须人工审核，单条精确重复可自动）
  4. 删除前备份重复题目数据（记录到duplicate_log表）
- **精确重复**：MD5完全相同，研判确认后物理删除（DELETE），记录duplicate_of指向保留题ID
- **高度重复**：四要素全部相同，研判确认后物理删除（DELETE），记录duplicate_of指向保留题ID
- **同考点重复**：不自动删除，标记待人工评估，确认无保留价值后再删除

**去重铁律**：
1. ❌ 禁止未经研判就物理删除，必须全面分析、确认重复、该删才删
2. ❌ 禁止草率标记重复，必须四要素全部一致
3. ❌ 禁止删除真题，真题与其他来源重复时保留真题
4. ❌ 禁止删除前不备份，删除前必须记录到duplicate_log表
5. ✅ 去重前必须全面分析，输出重复报告
6. ✅ 批量去重必须由造价专家审核确认
7. ✅ 去重结果必须定期复核，发现误判立即恢复
8. ✅ 去重操作必须记录日志，可追溯、可恢复

### 21.4 闪卡去重与内容定义（铁律，闪卡不是题目）

**闪卡内容定义（铁律）**：
- 闪卡是**知识点、公式、考点、口诀**的记忆卡片
- ❌ 闪卡**不包含完整题目**（题干+选项+答案+解析），完整题目属于题库
- 闪卡正面：问题/知识点名称/公式名称
- 闪卡背面：答案/知识点解释/公式内容/口诀

**闪卡记忆机制（核心原理）**：
- 闪卡的**问题版（正面）+答案版（背面）**是强化记忆的核心手段——先看问题主动回忆答案，再翻卡验证，通过"主动回忆+间隔重复"强化记忆
- 正面必须是问题形式（如"工程造价的含义是什么？"），触发主动思考
- 背面必须是答案/知识点内容，验证回忆结果
- 禁止正面直接给答案（失去主动回忆价值），禁止背面只有"答案:X"（不是知识点答案）

**闪卡知识点核心原则（万变不离其宗）**：
- 闪卡的唯一核心是**知识点**，所有内容必须围绕知识点组织，禁止把题目直接当闪卡
- 题目只是知识点的载体和验证手段，闪卡必须从题目/解析中**提炼总结**出知识点，而非简单复制题目+答案
- 闪卡生成必须经过"题目→解析→AI总结提炼→知识点"的转化过程，AI总结分析功能必须用上
- 每个知识点应生成多种类型闪卡：定义类（是什么）、公式类（怎么算）、考点类（考什么）、对比类（易混淆）、口诀类（怎么记）
- 闪卡正面必须是知识点问题（如"工程造价的含义是什么？"），背面必须是知识点答案（定义/公式/考点），禁止出现"答案:X"这种题目形式
- 典型反例：把"根据《政府采购法》，下列说法正确的是（）+答案:B"当闪卡——这是题目不是闪卡；正确做法是提炼为"政府采购的方式有哪些？→公开招标、邀请招标、竞争性谈判、单一来源、询价、竞争性磋商"
- 知识点体系是骨架，闪卡是血肉，题库是验证——三者必须围绕知识点统一协同

**闪卡去重标准（铁律，相同知识点必须合并，研判清楚后物理删除）**：
- 相同知识点的闪卡必须合并，不能因为"这次空三个、下次空两个"就视为不同闪卡
- 去重判定：知识点相同 + 核心内容相似度>=90% = 重复
- **前提条件（必须全部满足才能删除）**：
  1. 全面分析重复情况，输出重复报告
  2. AI判断为相同知识点、内容相似度>=90%
  3. 造价专家审核确认（批量去重必须人工审核）
  4. 删除前备份重复闪卡数据（记录到duplicate_log表）
- 重复闪卡：保留内容最全、质量最高的版本，其他研判确认后物理删除
- 同一知识点的闪卡数量控制：每个知识点最多3张闪卡（概念卡、公式卡、口诀卡），超过的研判确认后删除

**闪卡数量控制（铁律）**：
- ❌ 禁止无限制生成闪卡，一个科目闪卡总数应控制在500-1000张
- ❌ 禁止把完整题目拆成闪卡，题目属于题库
- ✅ 闪卡必须是高频考点、核心公式、易混知识点
- ✅ 闪卡生成必须经过AI质量评估，低质量闪卡自动过滤
- ✅ 定期由造价专家审核闪卡质量，合并重复、删除低质量

#### 21.4.1 闪卡质量管控机制（铁律，多来源数据必须统一管控）

**立法背景**：闪卡来源渠道多样（手动新增、批量导入、PDF识别生成、AI生成、名师口诀库），各来源质量参差不齐，必须建立统一质量管控机制，避免低质量数据入库、避免重复浪费资源。

**质量评估六维标准**：
| 维度 | 标准 | 扣分 |
|------|------|------|
| 正面内容 | 非空、5-200字、不含纯选项/纯序号/URL/纯标点 | 不达标扣10-30分 |
| 背面内容 | 非空、有实质内容 | 不达标扣20分 |
| 知识点名称 | 必须有关联知识点名称 | 缺失扣15分 |
| 章节信息 | 必须有章节信息 | 缺失扣10分 |
| 记忆口诀 | 建议有口诀辅助记忆 | 缺失扣5分 |
| 内容纯净度 | 不含题目选项、解析、广告等非知识点内容 | 不达标扣20分 |

**质量等级**：
- 优秀（≥90分）：直接入库
- 良好（75-89分）：入库，标记待优化
- 一般（60-74分）：入库，标记需人工审核
- 较差（<60分）：自动过滤，不入库

**去重机制（双层去重）**：
1. **内容哈希去重**：front+back的MD5哈希相同 = 精确重复
2. **语义相似度去重**：正面内容相似度>80% = 疑似重复
3. 重复处理：保留内容最全、质量最高的版本，其他标记重复后物理删除

#### 21.4.2 口诀归集机制（铁律，多来源口诀统一归集）

**立法背景**：口诀来源包括视频智能笔记、名师口诀库、AI生成、手动添加，必须建立统一归集机制，按置信度排序，优先使用高质量口诀。

**口诀来源优先级（从高到低）**：
| 优先级 | 来源 | 置信度 | 说明 |
|--------|------|--------|------|
| 1 | 名师口诀库 | 95% | 环球网校、建工网校等知名机构名师口诀 |
| 2 | 视频智能笔记 | 90% | 从视频讲义的智能笔记中提取的口诀 |
| 3 | 手动添加 | 85% | 用户/专家手动添加的口诀 |
| 4 | AI生成 | 60% | AI从知识点内容中提取的首字口诀等 |

**视频智能笔记口诀提取规则**：
- 模式1："口诀：XXX"或"记忆口诀：XXX" → 直接提取
- 模式2："XXX记为XXX"或"XXX记作XXX" → 提取知识点和口诀
- 模式3：首字口诀需AI判断，不自动提取

#### 21.4.3 名师口诀库动态更新机制

**当前状态**：本地静态版本（一造管理60+、一建管理15、一建经济12、一建法规18、水利案例50+）

**动态更新预留接口**：
- 支持运行时动态添加新口诀
- 支持定期从网络搜集最新口诀（预留，未来实现）
- 更新日志记录所有新增/修改操作

### 21.5 资料库重复标记（只标记，人工确认）

**去重原则（与题库/闪卡不同）**：
- 资料库文件**只标记不删除**，等待人工确认，严禁自动删除文件
- 题库和闪卡是研判确认后物理删除，资料库文件必须人工确认

**重复判定标准**：
- 文件哈希相同 = 精确重复（100%相同）
- 文件名相同 + 文件大小相同 + 内容相似度>=95% = 高度重复
- 内容相似度>=80% = 疑似重复

**重复标记处理**：
- 前端学习资料库显示重复标记（黄色警告图标），但不影响文件正常使用
- 用户可选择"查看重复文件"、"标记为不重复"、"删除重复"
- 选择"删除重复"：软删除（is_deleted=1），不物理删除，保留30天可恢复

### 21.6 "完成"标准定义（铁律，禁止降低标准）

**功能完成的五级标准（必须全部满足才算"完成"）**：

| 级别 | 标准 | 必须满足 | 验证方式 |
|------|------|----------|----------|
| L1 基础完成 | 表结构建立、代码编写完成 | 数据库表完整、代码无语法错误 | node --check、数据库表检查 |
| L2 接口完成 | API接口开发完成 | 所有功能有对应RESTful API，接口文档完整 | API测试、接口文档审查 |
| L3 前端完成 | 前端界面集成完成 | 前端可调用API，界面可操作、可展示 | 浏览器实际操作测试 |
| L4 验证完成 | 实际数据验证通过 | 用真实数据测试，结果准确、性能达标 | 真实数据测试、性能测试 |
| L5 文档完成 | 文档和监控完善 | 有使用文档、有监控告警、有异常处理 | 文档审查、监控测试 |

**完成标准铁律**：
1. ❌ 禁止只建表就叫"完成"，必须L1-L5全部满足
2. ❌ 禁止只写策划就叫"完成"，必须实际落地并验证
3. ❌ 禁止功能有就代表完善，必须持续优化、持续验证
4. ✅ 每个功能必须有明确的完成标准和验收清单
5. ✅ 完成后必须输出验证报告，包含测试数据、测试结果、性能指标
6. ✅ 完成后必须持续监控，发现问题立即修复

### 21.7 功能合并与架构精简原则

**功能合并原则（避免重复功能）**：

| 模块 | 合并方案 | 说明 |
|------|----------|------|
| 记忆闪卡 + 记忆训练 | 记忆闪卡放入记忆训练，作为记忆训练的一个子功能 | 记忆训练包含多种训练方法，闪卡只是强化记忆的一部分 |
| 视频讲义 | 只负责播放，不负责资料管理 | 资料管理在学习资料库，视频讲义只做播放和同步滚动 |
| 章节教材 | 只负责拆分和教材管理，不负责文件管理 | 文件管理在学习资料库，章节教材只做拆分和拆分结果管理 |
| 知识库 + 学习笔记 | 知识库是后台储备知识，学习笔记是用户个人笔记 | 不重复，知识库是系统级，学习笔记是用户级 |
| 题库新增/识别 | 全部移到学习资料库 | 题库管理只负责展示和练习，新增和识别在资料库 |
| 闪卡新增/生成 | 全部移到学习资料库 | 闪卡管理只负责复习，新增和生成在资料库 |

**功能合并铁律**：
1. ❌ 禁止同一功能在多个模块重复实现
2. ❌ 禁止模块职责不清，每个模块必须有明确的职责边界
3. ✅ 新增功能必须先评估是否与现有功能重复
4. ✅ 定期审计功能清单，合并重复功能
5. ✅ 模块职责必须写入宪法，不得随意变更

### 21.8 标签系统规范（铁律）

**预设标签（精简版，只保留有用的）**：

| 标签 | 优先级 | 说明 |
|------|--------|------|
| 真题 | P0（最高） | 历年真题，优先级最高 |
| 模拟题 | P1 | 模拟考试题 |
| 精题 | P2 | 精选题目，必练 |
| 练习题 | P3（最低） | 普通练习题，讲义中的题目 |
| 题库 | - | 可用于题库识别 |
| 闪卡 | - | 可用于闪卡生成 |
| 思维导图 | - | 可用于导图生成 |
| 知识点分布 | - | 用于知识点分布分析 |

**标签优先级规则（铁律）**：
- 真题 > 模拟题 > 精题 > 练习题（依次优先）
- 讲义中的题目：先判断是否是真题，再判断是否是模拟题，再判断是否是精题，都不是的才归为练习题
- 同一文件可打多个标签，支持多选
- 批量标签修改后，文件夹内的所有单条记录必须同步修改

**标签操作铁律**：
1. ❌ 禁止标签只能单选，必须支持多选
2. ❌ 禁止批量修改标签后单条记录不同步
3. ✅ 标签选择后必须立即保存，不能只显示不保存
4. ✅ 支持整个文件夹批量打标签
5. ✅ 自动打标签后支持人工修改

### 21.9 学习资料库架构规范（铁律）

**学习资料库三层架构**：

| 层级 | 功能 | 说明 |
|------|------|------|
| **全部文件** | 源数据层，所有文件的唯一入口 | 负责文件上传、管理、打标签、识别、生成 |
| **大纲/教材** | 引用层，从全部文件引用 | 只负责预览，无删除、无重命名 |
| **视频讲义** | 引用层，从全部文件引用 | 只负责播放和同步滚动，无删除、无重命名 |

**架构规范铁律**：
1. ❌ 禁止大纲/教材、视频讲义独立管理文件，必须从全部文件引用
2. ❌ 禁止大纲/教材、视频讲义有删除、重命名功能
3. ✅ 全部文件是唯一数据源，其他tab都是引用
4. ✅ 全部文件以记录形式展示（表格），不是缩略图
5. ✅ 全部文件按照文件夹层次显示，保留原始文件夹结构
6. ✅ 视频讲义的视频和讲义同步对应滚动

### 21.10 上传去重与文件夹层次保留

**上传去重机制**：
- 文件上传时根据科目筛选上传对象，避免上传错误科目
- 文件哈希去重：相同哈希的文件不重复上传
- 文件名去重：同科目下同文件名的文件标记重复
- 上传进度条：根据文件总量设置进度，真实显示上传进度

**文件夹层次保留（铁律）**：
- 文件夹导入时必须保留原始文件夹层次，不得改变
- 分类逻辑是底层文件夹名字（最后一层文件夹名称）
- 文件夹内部要排序，外部也要排序，同类的排在一起
- 文件夹默认关闭状态
- 视频和讲义同步关联，包括文件夹结构同步

### 21.11 AI大脑自我进化与对话记录

**AI大脑对话记录机制**：
- AI智能大脑必须记录与用户的对话内容，用于丰富和完善思考链路
- 对话记录存储在本地数据库，支持检索和分析
- 从对话中提取用户偏好、系统问题、优化建议，自动更新宪法和细则
- 定期分析对话记录，发现系统薄弱环节，主动优化

**AI大脑进化铁律**：
1. ❌ 禁止AI大脑不记录对话，每次对话都必须记录
2. ❌ 禁止AI大脑不主动思考，必须从对话中学习和进化
3. ✅ 对话记录必须结构化存储，支持检索和分析
4. ✅ 从对话中提取的优化建议必须自动加入待办清单
5. ✅ AI大脑必须定期输出进化报告，说明学习成果和优化方向

### 21.12 识别储存体系与全面扫描（L0-L4五层架构，全面扫描是第一前提）

**全面扫描至尊地位（铁律）**：
- 全面扫描是所有后续功能的**第一前提**，没有扫描就没有内容，没有内容配对、识别、生成都是空谈
- 学习资料库中所有PDF必须100%全面扫描，禁止只扫描部分、禁止跳过文件
- 扫描结果必须完整存储（L0-L4五层），禁止只存加工后的数据
- 全面扫描优先于所有其他功能，扫描未完成前，其他功能只能用已有数据，不能影响扫描进度

**全面扫描范围（铁律）**：
- 学习资料库中所有PDF文件（100%覆盖，无例外）
- 包括：知识点精讲、真题、模拟题、讲义、教材、大纲、视频讲义等所有类型
- 已扫描文件如文件内容变更（重新上传），必须重新扫描
- 扫描范围动态扩展：新增文件自动触发扫描

**全面扫描优先级顺序（铁律，按重要性排序）**：
1. **第一梯队：历年真题**（最高优先级，考点分析的基础）
2. **第二梯队：知识点精讲**（高优先级，知识体系的来源）
3. **第三梯队：教材/大纲**（中优先级，知识体系骨架）
4. **第四梯队：讲义/练习题**（普通优先级，题库和闪卡来源）
5. **第五梯队：其他资料**（低优先级，最后扫描）

**全面扫描流程（铁律）**：
1. **单文件验证**：先用1-2个文件验证识别引擎和流程，确保识别准确
2. **小批量测试**：10-20个文件小批量扫描，验证批量流程和质量
3. **分梯队全量扫描**：按优先级梯队依次扫描，每梯队完成后验证质量
4. **断点续扫**：支持中断后从断点继续，不重复扫描已完成文件
5. **扫描后立即建索引**：每完成一批文件，立即建立FTS5全文索引

**全面扫描质量控制（铁律）**：
- 每扫描完一个梯队，立即进行质量抽检（至少5%文件）
- 文字识别准确率>=95%，公式>=85%，表格>=80%
- 低质量文件标记为待重新扫描，调整参数后重扫
- 扫描失败文件自动重试（最多3次），重试失败标记待人工处理
- 扫描完成后输出完整扫描报告（总数、成功、失败、准确率、耗时）

**全面扫描进度监控（铁律）**：
- 实时展示扫描进度（当前文件、完成数量、总数量、百分比）
- 展示每个文件的扫描状态（待扫描/扫描中/已完成/失败）
- 展示各梯队的完成情况
- 扫描完成后通知用户（提示音+界面提示）
- 支持暂停、继续、重新扫描

**识别储存五层架构（详见《识别储存与内容知识库分册V2.0》）**：
- L0原始层：OCR引擎原始输出JSON，永久保留
- L1文本层：纯文本内容，按页分隔
- L2结构层：结构化JSON（页面、块、公式、表格、图片）
- L3索引层：FTS5全文索引、向量索引、知识点索引
- L4应用层：提取的知识点、题目、闪卡、导图

**识别储存铁律**：
1. ❌ 禁止只存L4应用层数据，必须L0-L4全部存储
2. ❌ 禁止每次识别文件，必须一次识别永久使用
3. ❌ 禁止跳过全面扫描直接做配对/识别/生成
4. ✅ 全面扫描是第一前提，必须100%覆盖所有PDF
5. ✅ 新增文件自动触发识别，无需手动操作
6. ✅ 识别结果必须经过质量检查，低质量内容待人工校对
7. ✅ 识别引擎可升级，原始结果保留，新旧可对比
8. ✅ 扫描进度可监控，失败可重试、可断点续扫

### 21.13 资料预处理机制（铁律，预处理核心是配对，为识别服务）

**核心定位（铁律）**：资料预处理不是独立功能，而是为题库识别、闪卡生成、思维导图生成服务的**配对过程**。预处理的核心目的是：在识别阶段就完成PDF内容与知识体系的配对（知识点配对、题目配对、公式配对、考点配对），后续生成题库、闪卡、思维导图时直接使用配对结果，不需要重复分析。预处理只做一次，配对结果全局共享。

**配对是预处理的灵魂**：
- 识别PDF中的知识点 → 配对到知识体系（knowledge_framework）中的L3知识点
- 识别PDF中的题目 → 配对到题库（questions），自动关联知识点
- 识别PDF中的公式/考点/口诀 → 配对到闪卡（flash_cards），自动关联知识点
- 识别PDF中的章节结构 → 配对到思维导图（mind_maps），自动关联节/知识点
- 配对结果存储到预处理表，后续功能直接调用，不重复计算

**预处理五层体系（P1-P2是基础，P3-P4是桥梁，P5是核心配对）**：

| 层级 | 预处理内容 | 处理方式 | 配对目标 |
|------|----------|----------|----------|
| P1 文件预处理 | 格式转换、完整性校验、页数统计 | 自动处理 | 标准化文件，为后续处理打基础 |
| P2 图像预处理 | 去水印、倾斜校正、对比度增强、超分辨率 | 自动处理，参数可配置 | 高质量图片，提升识别准确率 |
| P3 版面预处理 | 版面分析、区域划分、阅读顺序、页眉页脚识别 | 自动处理，AI辅助 | 区分标题/正文/公式/表格/图片，为内容配对做准备 |
| P4 结构预处理 | 目录提取、章节识别、结构树构建、大纲生成 | 自动处理，人工可修正 | **配对章节**：PDF章节 ↔ 知识体系L1章/L2节 |
| P5 内容预处理（核心） | 文字/公式/表格识别 + **知识点配对 + 题目配对 + 考点配对** | OCR+AI+知识图谱匹配 | **配对核心**：内容 ↔ 知识点/题目/闪卡/导图 |

**P5内容预处理的配对机制（核心中的核心）**：

1. **知识点配对**：
   - 从PDF内容中识别知识点名称、定义、解释
   - 与知识体系（knowledge_framework）中的104个L3知识点进行匹配
   - 匹配方式：精确匹配（名称相同）→ 关键词匹配（扩展关键词）→ 语义匹配（向量相似度）
   - 配对结果：每个知识点记录来源文件、页码、上下文、匹配置信度
   - 未匹配到的知识点：标记为"待新增知识点"，待造价专家审核后加入知识体系

2. **题目配对**：
   - 从PDF内容中识别题目结构（题干、选项、答案、解析）
   - 与现有题库进行去重配对（MD5精确去重 + 四要素比对）
   - 自动配对知识点（题目内容 ↔ L3知识点）
   - 自动判断题型（单选/多选/判断/案例）、难度、来源（真题/模拟题/练习题）
   - 配对结果：题目暂存到预处理表，待审核后入库

3. **闪卡配对**：
   - 从PDF内容中识别知识点、公式、考点、口诀
   - 与现有闪卡库进行去重配对（相同知识点 + 内容相似度>=90%）
   - 自动配对知识点
   - 自动判断闪卡类型（概念卡/公式卡/口诀卡）
   - 配对结果：闪卡暂存到预处理表，待审核后入库

4. **思维导图配对**：
   - 从PDF目录和章节结构中提取层级关系
   - 与知识体系L1章/L2节/L3知识点进行配对
   - 自动生成思维导图节点结构
   - 配对结果：导图结构暂存到预处理表，待审核后生成

**预处理结果存储（配对结果必须完整存储）**：
- P1-P4结果：存储到file_content、file_page_content、file_structure表
- P5配对结果：存储到preprocess_pairing表（配对结果专用表）
- 配对结果包括：配对类型（知识点/题目/闪卡/导图）、配对对象ID、来源文件、页码、上下文、置信度、状态（待审核/已确认/已拒绝）
- 配对结果支持人工审核、修改、确认

**预处理配置管理（铁律）**：
- 系统必须提供预处理配置管理页面，支持配置各项预处理参数
- 预处理参数包括：去水印强度、倾斜校正阈值、对比度增强级别、OCR引擎选择、识别置信度阈值、配对置信度阈值等
- 支持按科目、按文件类型配置不同的预处理参数
- 支持保存预处理配置模板，一键应用
- 预处理配置变更必须记录日志，可追溯

**预处理触发机制（铁律）**：
- 文件上传完成后自动触发P1-P5全流程预处理，无需手动操作
- 预处理失败自动重试（最多3次），重试失败标记为待人工处理
- 支持批量预处理，支持断点续处理
- 支持手动重新预处理（预处理参数变更后）
- 预处理进度实时展示，用户可查看处理状态和配对结果

**预处理质量控制（铁律）**：
- 每一层预处理都必须有质量检查
- P5配对质量检查：知识点配对准确率>=90%，题目配对准确率>=90%，闪卡配对准确率>=85%
- 低置信度配对（<0.7）必须标记为待人工审核
- 造价专家定期审核配对结果，优化配对算法
- 配对准确率持续提升

**预处理铁律**：
1. ❌ 禁止预处理与识别分离，预处理就是为识别配对服务的
2. ❌ 禁止各功能重复配对，预处理配对结果必须全局共享
3. ❌ 禁止跳过配对直接生成题库/闪卡/导图，必须先配对再生成
4. ❌ 禁止配对结果不存储，必须完整保存配对过程和结果
5. ✅ 预处理核心是配对，配对准确率是预处理质量的核心指标
6. ✅ 配对结果支持人工审核、修改、确认，AI配对+人工审核=可靠
7. ✅ 预处理只做一次，所有功能复用配对结果
8. ✅ 配对算法持续优化，准确率持续提升

### 21.14 数据质量监控与自动检查

**数据质量监控指标（必须每日自动检查）**：

| 检查项 | 标准 | 检查频率 |
|--------|------|----------|
| 题库题干非空 | 100% | 每日 |
| 题库答案非空 | 100% | 每日 |
| 题库知识点关联率 | >=95% | 每日 |
| 闪卡正面非空 | 100% | 每日 |
| 闪卡背面非空 | 100% | 每日 |
| 闪卡知识点关联率 | >=90% | 每日 |
| 闪卡数量控制 | 每科目500-1000张 | 每日 |
| 资料库文件名非空 | 100% | 每日 |
| 识别覆盖率 | 100% | 每日 |
| 全文索引覆盖率 | 100% | 每日 |

**数据质量铁律**：
1. ❌ 禁止数据质量不达标就宣称完成
2. ❌ 禁止数据质量问题不处理，必须立即修复
3. ✅ 每日自动检查数据质量，生成质量报告
4. ✅ 质量异常自动告警，通知相关专家处理
5. ✅ 数据质量评分实时展示，透明可查

### 21.15 字段设计与功能设计规范（62位专家联合审查结论，铁律）

> **立法背景**：各专业专家从数据库架构、OCR识别、AI算法、造价业务、题库系统、闪卡算法、思维导图、API设计、前端架构、数据治理10个专业角度，全面审查字段设计和功能设计，形成本规范。所有表结构设计、功能开发必须严格遵守本规范，禁止随意设计字段、禁止功能缺失、禁止过度设计。

#### 21.15.1 字段设计总原则（铁律）

1. **完整性原则**：关键字段不得缺失，业务需要的字段必须存在
2. **合理性原则**：字段类型、大小、约束必须合理，符合业务需求
3. **性能原则**：查询频繁的字段必须建索引，冗余字段提升查询性能
4. **可扩展原则**：预留扩展字段，支持未来业务发展，避免频繁改表
5. **一致性原则**：同类字段命名、类型、约束必须统一，符合系统规范
6. **可追溯原则**：数据来源、处理过程必须可追溯，增加source和血缘字段
7. **软删除原则**：所有业务表必须有is_deleted字段，统一软删除规范

#### 21.15.2 识别储存相关表字段规范（必须遵守）

**file_content表（识别内容主表）必须包含以下字段**：
- `file_hash VARCHAR(64)`：文件哈希，用于判断文件是否变更需要重扫
- `pdf_type VARCHAR(16)`：PDF类型（text文字版/scanned扫描版/mixed混合版）
- `preprocess_status VARCHAR(16)`：预处理状态（scanned已识别/paired已配对/imported已入库）
- `total_pages`、`total_chars`、`total_formulas`、`total_tables`、`total_images`
- `content_text MEDIUMTEXT`、`content_json MEDIUMTEXT`
- `ocr_engine`、`ocr_engines_used`、`avg_accuracy`
- `status`、`scan_start_time`、`scan_end_time`、`scan_duration`
- `is_indexed`、`is_vectorized`、`is_analyzed`
- `is_deleted INTEGER DEFAULT 0`

**file_page_content表（页面内容表）必须包含以下字段**：
- `chapter VARCHAR(128)`：页面所属章（冗余字段，提升查询性能）
- `section VARCHAR(128)`：页面所属节（冗余字段，提升查询性能）
- `content_text`、`content_json`、`char_count`
- `formula_count`、`table_count`、`image_count`
- `has_title`、`title_text`、`page_accuracy`、`image_path`
- `is_deleted INTEGER DEFAULT 0`

**file_content_block表（内容块表）必须包含以下字段**：
- `parent_block_id INTEGER`：父块ID，支持层级结构（标题→正文）
- `block_type VARCHAR(32)`：块类型，枚举值必须包含：title/text/formula/table/image/list/caption/footnote/header/footer
- `content_text`、`content_json`、`level`（标题层级1-6）
- `bbox`（bounding box坐标）、`confidence`
- `is_deleted INTEGER DEFAULT 0`

**file_formula表（公式表）必须包含以下字段**：
- `formula_latex TEXT`：公式LaTeX表达式
- `formula_image_path VARCHAR(256)`：公式原始图片路径（LaTeX识别失败时用图片代替）
- `formula_text`、`context_text`、`confidence`
- `is_deleted INTEGER DEFAULT 0`

**preprocess_pairing表（配对结果表）必须包含以下字段**：
- `batch_id VARCHAR(64)`：批次ID，支持批量管理和回滚
- `source_text_hash VARCHAR(64)`：源内容哈希，配对去重用
- `pairing_type`（knowledge_point/question/flashcard/mindmap）
- `source_content`、`target_id`、`target_type`
- `match_method`（exact/keyword/semantic）、`match_confidence`
- `context_text`、`status`（pending/confirmed/rejected）
- `review_note`、`reviewer_id`、`review_time`
- `is_deleted INTEGER DEFAULT 0`

**file_image表（图片表）必须包含以下字段**：
- `image_type VARCHAR(32)`：图片类型（figure示意图/chart图表/diagram流程图/photo照片/table_screenshot表格截图）
- `image_path`、`width`、`height`、`file_size`
- `caption VARCHAR(256)`：图片标题（图注）
- `image_text TEXT`：图片中的文字（OCR识别，支持图片内容搜索）
- `knowledge_point_id INTEGER`：关联的知识点ID
- `is_deleted INTEGER DEFAULT 0`

**file_table表（表格表）必须包含以下字段**：
- `table_html TEXT`：表格HTML（用于渲染）
- `table_json TEXT`：表格结构化JSON（行列数据，支持查询）
- `table_text TEXT`：表格纯文本（用于全文搜索）
- `rows`、`cols`、`caption`（表注）
- `knowledge_point_id INTEGER`：关联的知识点ID
- `is_deleted INTEGER DEFAULT 0`

**图片和表格处理规范（铁律，必须充分考虑）**：
1. **图片内容必须OCR**：图片中的文字必须识别出来（image_text字段），支持图片内容全文搜索，禁止只存图片不识别文字
2. **表格数据必须结构化**：表格必须转换为结构化JSON（table_json），支持表格数据查询、分析、对比，禁止只存HTML不结构化
3. **图片表格必须配对知识点**：图片和表格必须与知识点配对（knowledge_point_id），点击知识点可查看相关图片和表格
4. **图片表格必须建全文索引**：图片文字（image_text）和表格文本（table_text）必须加入FTS5全文索引，支持跨内容搜索
5. **图片表格必须有管理功能**：系统必须提供图片库和表格库的浏览、搜索、查看功能，支持按知识点筛选
6. **图表标题必须提取**：图片的图注（caption）和表格的表注必须提取，用于理解图表含义和配对知识点
7. **复杂图表AI理解**：复杂的流程图、结构图、对比表，用AI辅助理解内容，生成摘要和知识点关联
8. **图片表格去重**：相同图片（感知哈希）和相同表格（内容相似度>=95%）必须去重，避免重复存储

#### 21.15.3 题库表字段规范（必须遵守）

**questions表必须增加/包含以下字段**：
- `question_no VARCHAR(32)`：原题号（如"一、单项选择题1."），对应原试卷题号
- `options_json TEXT`：结构化选项（A/B/C/D/E），同时保留原文本
- `source_file_id INTEGER`：来源文件ID，题目可追溯到原始PDF
- `source_page INTEGER`：来源页码
- `parent_question_id INTEGER`：父题目ID，支持案例题→小问的层级结构
- `year INTEGER`：真题年份
- `question_type VARCHAR(32)`：题型（single/multiple/judge/case/case_sub）
- `source VARCHAR(64)`：来源（真题/模拟题/精题/练习题）
- `difficulty FLOAT`：难度（0-1）
- `has_image INTEGER`：题目是否包含图片（0/1）
- `has_table INTEGER`：题目是否包含表格（0/1）
- `question_images TEXT`：题目中的图片ID列表（JSON数组，关联file_image表）
- `question_tables TEXT`：题目中的表格ID列表（JSON数组，关联file_table表）
- `is_deleted INTEGER DEFAULT 0`

**题库识别中的图片和表格处理规范（铁律）**：
1. **题目中的图片必须提取并关联**：题目中的示意图、工程图、电路图、图表等必须提取，保存到file_image表，并通过question_images字段关联到题目，禁止只识别文字忽略图片
2. **题目中的表格必须提取并关联**：题目中的数据表、参数表、对比表等必须提取，保存到file_table表，并通过question_tables字段关联到题目，禁止只识别文字忽略表格
3. **题目展示必须包含图片和表格**：题目展示时，图片和表格必须在对应位置显示，不能只显示文字，图片支持点击放大，表格支持完整渲染
4. **题目去重必须考虑图片和表格**：题目去重时，除了题干+选项+答案+解析，还要考虑图片内容（图片感知哈希）和表格内容（表格数据相似度），图文都一致才算重复
5. **图片中的文字必须识别**：题目图片中的文字（如图中标注、参数）必须OCR识别，加入题目内容，支持搜索
6. **表格数据必须结构化**：题目表格必须转换为结构化JSON，支持表格数据查询和分析
7. **案例题图片表格继承**：案例题的小问（case_sub）继承父案例题（case）的图片和表格，不需要重复存储
8. **图片表格质量检查**：题目中的图片和表格必须检查清晰度和完整性，模糊或不完整的标记待人工处理

#### 21.15.4 闪卡表字段规范（必须遵守）

**flash_cards表必须增加/包含以下字段**：
- `card_type VARCHAR(32)`：闪卡类型（concept概念卡/formula公式卡/mnemonic口诀卡/comparison对比卡/error易错点卡/process计算流程卡）
- `difficulty FLOAT`：难度（0-1），SM-2算法中考虑难度因子
- `related_question_ids TEXT`：相关题目ID列表，闪卡复习时可查看相关题目
- `front_format VARCHAR(16)`：正面格式（text/latex/html），支持公式渲染
- `back_format VARCHAR(16)`：背面格式（text/latex/html）
- `is_deleted INTEGER DEFAULT 0`

#### 21.15.5 思维导图相关表字段规范（必须遵守）

**mind_maps表必须增加/包含以下字段**：
- `node_count INTEGER`：节点总数（冗余字段，避免每次渲染统计）
- `max_depth INTEGER`：最大深度（冗余字段）
- `is_deleted INTEGER DEFAULT 0`

**mind_map_nodes表必须增加/包含以下字段**：
- `knowledge_point_id INTEGER`：关联的知识点ID，点击节点可查看相关题目/闪卡
- `is_deleted INTEGER DEFAULT 0`

#### 21.15.6 功能设计规范（必须遵守）

**识别功能必须包含**：
1. **PDF文本层检测**：先用pdfplumber/PyMuPDF提取文本层，文字版PDF直接提取文本跳过OCR（速度快10倍），扫描版才用OCR
2. **识别置信度分级处理**：>=0.9自动通过，0.7-0.9标记待审核，<0.7标记需重扫
3. **公式双保存**：公式区域同时保存LaTeX和原始图片，LaTeX识别失败时用图片代替
4. **断点续扫**：支持中断后从断点继续，不重复扫描已完成文件
5. **扫描进度实时推送**：WebSocket或SSE推送，减少前端轮询

**配对功能必须包含**：
1. **三层匹配机制**：精确匹配→扩展关键词匹配→语义向量匹配
2. **每个知识点扩展10-20个专业关键词**：同义词、缩写、英文术语
3. **AI辅助题目识别**：正则粗提取+AI判断是否完整题目，提升召回率
4. **闪卡判定规则**：正面<=50字、不含选项A-E、是知识点/公式/口诀，不符合的移到题库
5. **标题层级自动识别**：基于字体大小、加粗、编号自动识别标题层级

**审核功能必须包含**：
1. **左右对比视图**：左边原始内容，右边配对结果，提升审核效率
2. **快捷键审核**：支持键盘快捷键（确认/拒绝/下一条）
3. **批量确认**：高置信度（>=0.9）可一键批量确认
4. **配对批次管理**：支持按批次查看、回滚

**用户体验功能必须包含**：
1. **扫描进度可视化**：进度条、当前文件名、已完成/总数、预计剩余时间、速度统计
2. **完成提示音**：批量操作完成后播放提示音（可配置开关），支持浏览器通知
3. **选中状态反馈**：选中计数、批量操作栏、全选/反选
4. **操作结果即时反馈**：成功/失败提示，失败显示原因和重试按钮

**数据治理功能必须包含**：
1. **数据血缘追踪**：记录每个数据的来源文件、处理过程、变更历史
2. **质量趋势分析**：记录每日质量评分，支持趋势分析和异常检测
3. **知识点去重**：名称相同+章节相同=重复
4. **导图去重**：结构相似度>=90%=重复
5. **L4细分考点**：知识点体系增加第四层级（L1章→L2节→L3知识点→L4细分考点）

#### 21.15.7 字段设计与功能设计铁律

1. ❌ 禁止随意新增字段，必须经过专业专家审查，符合本规范
2. ❌ 禁止关键字段缺失，本规范列出的必须字段必须全部包含
3. ❌ 禁止功能缺失，本规范列出的必须功能必须全部实现
4. ❌ 禁止过度设计，只实现业务需要的功能，不做无用功能
5. ✅ 字段设计必须考虑性能、可扩展、可追溯
6. ✅ 功能设计必须考虑用户体验、效率、准确性
7. ✅ 新增字段和功能必须更新本规范，保持文档与代码一致
8. ✅ 每季度由各专业专家复审字段和功能设计，持续优化

***

> **本章为数据去杂与质量治理的最高准则，所有数据处理必须优先执行去杂，所有功能必须达到L5完成标准，所有原始内容必须完整保留。数据质量是系统的生命线，必须像对待生命一样对待数据质量。去杂优先、原始保护、物理去重、严格标准、持续监控。字段设计和功能设计必须严格遵守21.15规范，各专业专家审查结论必须执行。**

### 21.16 扫描完整性与零遗漏铁律（2026-09-06新增，血的教训）

#### 21.16.1 扫描范围铁律
- **禁止**在扫描查询中使用 `file_type != '其他'` 等条件过滤文件，这是导致67个文件漏扫的根因
- 扫描范围必须是：`WHERE is_deleted=0 AND filename LIKE '%.pdf'`，覆盖所有PDF
- Excel、视频等非PDF文件由其他专用处理流程负责，不纳入PDF扫描范围
- 任何新增的过滤条件必须经过62位专家评审，并写入本节

#### 21.16.2 扫描完整性校验机制（强制执行）
- 扫描完成后必须执行完整性校验：
  ```sql
  -- 校验1：总PDF数 vs 已扫描数
  SELECT COUNT(*) FROM fl_file_library WHERE is_deleted=0 AND filename LIKE '%.pdf';
  SELECT COUNT(DISTINCT file_id) FROM file_content;
  -- 两者必须相等，不等则判定扫描失败
  ```
- 校验不通过时，必须输出未扫描文件清单，自动触发补扫
- 禁止在未通过完整性校验的情况下宣称"扫描完成"

#### 21.16.3 科目判断逻辑铁律
- **禁止**使用宽泛关键词（如单独的"计价"、"管理"、"经济"）作为科目判断依据
- 关键词必须按**长度降序**匹配，更长更具体的关键词优先
- 文件夹路径匹配优先级**高于**文件名匹配
- 必须设置排除规则：如包含"水利"且包含"计量与计价应用"时归为一造水利案例，而非一造计价
- 科目判断代码必须集中管理，禁止分散在多个文件中各写一套
- 每次修改科目判断逻辑后，必须用全量文件回归测试

#### 21.16.4 扫描版PDF处理铁律
- 扫描版PDF**禁止**简单跳过或返回失败
- 必须在file_content表中记录 `status='pending_ocr'`，确保文件不丢失
- OCR完成后更新为 `status='completed'`
- 待OCR文件清单必须可查询、可追踪

#### 21.16.5 事后修正不等于修复（核心认知）
- 发现数据错误后，**必须**先修复产生错误的逻辑代码，再修正数据
- 禁止只UPDATE数据而不修复根因逻辑（如只把"一造计价"改成"一造水利案例"而不修复判断逻辑）
- 修复逻辑后必须用全量数据回归验证，确保不再产生同类错误
- 每次修复必须记录：问题根因、修复位置、验证结果

#### 21.16.6 扫描进度真实性铁律
- 进度条必须基于实际处理文件数，禁止"上传150个成功0个"式的虚假进度
- 跳过的文件必须明确标注跳过原因（重复/扫描版/文件损坏）
- 禁止把跳过计入成功数

### 21.17 根本解决问题铁律（至尊核心原则，2026-09-06新增）

#### 21.17.1 核心认知（必须内化）
- **发现问题 ≠ 解决问题**：只看到现象不叫发现问题，必须找到根因才算发现问题
- **治标不治本 = 制造新问题**：只修表面数据、不修产生问题的逻辑，等于埋下定时炸弹
- **事后补数据 = 掩盖问题**：只UPDATE错误数据而不修复根因逻辑，是严重违规
- **反复出现的问题 = 根本没解决**：同一问题出现第二次，说明第一次修复是失败的

#### 21.17.2 问题处理五步法（强制执行，缺一不可）
1. **根因定位**：用5Why分析法，至少追问3层"为什么"，直到找到代码逻辑/架构设计层面的根因
2. **逻辑修复**：修改产生问题的代码逻辑，而不是修改问题产生的数据
3. **机制建立**：建立防止同类问题再发生的机制（校验、监控、断言、约束）
4. **全量回归**：用全量数据验证修复效果，确保不再产生同类错误
5. **入宪记录**：把根因和修复方案写入宪法，作为后续开发的约束

#### 21.17.3 反常必有妖原则（最高警觉原则）
- 任何不符合预期的现象（数据异常、逻辑矛盾、性能反常、数量偏差）都必须深挖根因，禁止用"可能""大概""应该"敷衍
- 反常现象往往是深层bug的信号：题目数骤增/骤减、识别率突变、重复率异常、分类为空比例过高、选项长度异常
- 必须用5Why分析法连续追问至少5层"为什么"，直到找到代码逻辑或数据结构层面的根因
- 典型反常信号清单：
  1. 一套真题识别出1000+题（正常约80题）→ 重复识别或拆分错误
  2. 90%数据分类为空 → 分类逻辑未执行或字段映射错误
  3. 选项D长度是A/B/C的3倍 → 解析内容混入选项
  4. 答案包含"解析"二字 → 答案提取逻辑错误
  5. 相同内容哈希不同 → 去重逻辑有缺陷
  6. OCR跳过pending_ocr文件 → 跳过条件判断错误
  7. 上传150个只成功1个 → 科目筛选逻辑误杀
  8. OCR识别成功但保存0字 → 数据库约束冲突或连接管理错误
  9. 模型下载失败但脚本继续运行 → 异常捕获不完整
- 发现反常信号必须立即暂停当前任务，优先排查根因，禁止带着反常现象继续推进

#### 21.17.4 数据精简审慎原则（高精简率=高风险信号）
- **精简率超过50%本身就是反常信号**：删除超过一半数据时，必须暂停并验证是否误删有价值内容
- 数据清理必须遵循"先备份→再筛选→人工复核→后删除"四步流程，禁止直接批量删除
- 删除前必须验证三项覆盖度：
  1. 知识点覆盖度：每个知识点是否都有对应数据
  2. 高频考点覆盖度：5年考频>50次的考点是否都有数据
  3. 分类完整性：每个分类是否都有合理数量的数据
- 删除后必须验证：无重要内容丢失、无知识点断档、无高频考点空缺
- **精简不是目的，保留有价值内容才是目的**：宁可保留少量低质量数据待后续优化，不可误删高质量数据
- 典型反例：闪卡从4954张精简到474张（删除90.4%），导致35.7%知识点无闪卡、7个高频考点无闪卡——这是精简过度
- 安全精简率：单次精简不超过30%，超过30%必须分批次执行并逐批验证

#### 21.17.5 绝对禁止清单（违反直接判定任务失败）
- ❌ 禁止只修数据不修逻辑（如只把"一造计价"改成"一造水利案例"而不修复判断逻辑）
- ❌ 禁止用"跳过"、"忽略"、"降级"等方式回避问题
- ❌ 禁止用临时补丁（var绕过语法错误、硬编码特殊值）代替根本修复
- ❌ 禁止在未找到根因的情况下宣称"已修复"
- ❌ 禁止同一问题反复出现而不升级处理

#### 21.17.4 根因分析模板（每个问题必须输出）
```
问题现象：xxx
第一层为什么：xxx
第二层为什么：xxx
第三层为什么：xxx
根因：xxx（代码/架构/设计层面）
修复方案：修改xxx文件的xxx逻辑
防复发机制：xxx
验证方式：xxx
```

#### 21.17.5 问题分级响应机制
- **P0 阻断性问题**：15分钟内必须定位根因，1小时内必须修复逻辑并验证
- **P1 高风险问题**：1小时内定位根因，4小时内修复
- **P2 一般问题**：4小时内定位根因，24小时内修复
- 超过时限未定位根因的，必须升级到62位专家联合会诊

#### 21.17.6 "完成"的定义（重新定义）
- 代码修改完成 ≠ 任务完成
- 数据修正完成 ≠ 任务完成
- **只有同时满足以下条件才算完成**：
  1. 根因已找到并记录
  2. 产生问题的逻辑已修复
  3. 防复发机制已建立
  4. 全量回归验证通过
  5. 已写入宪法/细则


### 21.18 统一识别流程铁律（题库识别算法专家+多模态识别专家联合制定）

> **核心认知**：所有PDF（真题、模拟题、讲义、知识点精讲、教材等）都必须经过完全相同的识别流程，区别仅在于识别关键词和策略参数不同。AI的核心价值在于自动判断PDF类型并适配最优识别参数，而非替代规则识别。

#### 21.18.1 统一识别四阶段（所有PDF必须执行，不可跳过）

**阶段一：预处理（去杂+去页眉页脚+合并拼接）**
- 所有PDF必须执行，无例外
- 步骤：
  1. **坐标级遮挡法去页眉页脚**：基于字符坐标检测页眉页脚区域（顶部8%-12%、底部8%-12%），直接遮挡不提取，而非事后文本过滤
  2. **去杂**：清除水印、广告、版权声明、页码（文本级清理，作为遮挡法的补充）
  3. **合并拼接**：跨页题目合并、断句重连（PDF换行打断的句子重新拼接为完整逻辑行）
  4. **压缩空白**：统一格式
- 验收：预处理后文本无水印、无页眉页脚、无断句、跨页题目完整

**阶段二：类型识别（AI辅助，自动适配关键词）**
- AI根据文件名、内容特征、目录结构判断PDF类型
- 类型包括：真题、模拟题、精题、练习题、知识点精讲、讲义、教材、大纲等
- 根据类型自动选择：
  - 题号匹配正则（真题用`^\d+\.`，讲义可能用【习题N】等）
  - 选项标记（A.B.C.D. 或 A、B、C、D）
  - 答案标签（【答案】、答案：、参考答案等）
  - 解析标签（【解析】、【详解】、解析：等）
  - 知识点标签（【知识点】、【考点】等）
- 禁止：硬编码单一关键词适用于所有PDF类型

**阶段三：规则识别拆分（主体，优先使用）**
- 题目分割：按题号分割题目块（支持跨页）
- 选项提取：A/B/C/D/E，遇到答案/解析标签立即停止追加
- 答案提取：格式校验，只保留A-E组合
- 解析提取：到下一题/章标题结束
- 知识点关联：基于知识点标签和教材目录匹配

**阶段四：OCR/AI兜底（最后手段，仅在规则识别失败时）**
- 触发条件：扫描版PDF、规则识别率<50%、选项/答案失败率>20%
- 禁止：文字版PDF使用OCR、规则识别正常时调用AI
- AI用途：复杂题型识别、模糊选项判断、知识点关联优化

#### 21.18.2 遮挡法铁律（去页眉页脚的根本方法）
- 必须使用坐标级遮挡法，不能仅靠文本重复检测
- 原理：页眉页脚在页面固定位置（顶部/底部8%-12%区域），直接遮挡该区域的字符坐标
- 优势：
  1. 彻底清除，不会残留
  2. 不会误删跨页题目内容（题目内容在中间区域）
  3. 效率高，不需要逐行匹配
- 文本级去杂作为补充，清除遮挡法遗漏的行内水印

#### 21.18.3 跨页合并铁律
- 题目大多跨页显示，必须支持跨页合并
- 方法：基于坐标的区域裁剪（_crop_text_multi_page），从题目起始坐标到结束坐标，跨越多页提取
- 禁止：按页提取文本后简单拼接（会在题目中间插入页码和页眉页脚）
- 验收：跨页题目内容完整，无截断、无页码插入

#### 21.18.4 OCR双定位原则（必须区分，不可混淆）

OCR在系统中有两个完全不同的定位，必须严格区分：

**定位一：识别兜底（最后手段，仅扫描版PDF使用）**
- 用途：扫描版PDF无法提取文字时，用OCR提取文本内容
- 触发条件：仅当PyMuPDF提取文本为空或字符数<10/页时
- 禁止：文字版PDF使用OCR提取题目内容

**定位二：文档结构分析（提取策略决策，预处理阶段使用）**
- 核心目的：**找到合适的提取办法、确定关键词、清楚定位**
- 三大输出：
  1. **提取方法选择**：根据文档结构判断用坐标法、纯文本法还是混合法；判断题号格式、选项标记风格、答案标签类型
  2. **关键词适配**：根据文档类型自动匹配识别关键词（题号正则、选项标记、答案标签、解析标签、知识点标签）
  3. **精准定位**：定位标题、题目、选项、答案、解析、图表的坐标位置和层级关系
- 使用场景：
  1. 真题：定位题号区域、选项列、答案解析区，选择坐标法提取
  2. 讲义：定位知识点段落、例题区域，选择纯文本法+段落合并
  3. 教材/大纲：定位章节结构，建立目录树
  4. 模拟题：判断题号格式（可能是【习题N】而非N.），适配关键词
- 工作流程：先分析结构→再选方法→最后提取，禁止盲目用单一方法处理所有PDF
- 注意：此定位的OCR/AI不直接提取题目内容，仅输出结构元数据和提取策略

**关键区别**：
- 识别兜底OCR：输出文本，用于题目识别
- 结构分析OCR：输出结构元数据（坐标、层级、区域类型），用于AI理解文档

#### 21.18.5 AI适配原则（AI的正确定位）
- AI不是识别主体，是**策略适配者**和**质量校验者**
- AI的职责：
  1. 判断PDF类型，自动选择识别关键词和参数
  2. 校验规则识别结果的质量（答案是否合理、选项是否完整）
  3. 对规则识别失败的题目进行补救
  4. 持续学习不同类型PDF的识别模式，优化关键词库
- AI的禁区：
  1. 不得替代规则识别作为主要手段
  2. 不得在规则识别正常时介入（浪费资源且引入误差）
  3. 不得凭空生成题目内容（必须基于原文）

#### 21.18.6 识别质量验收标准（造价专家必须参与复核）
- ✅ 预处理：水印残留0处，跨页题目完整率100%
- ✅ 识别率：题目识别率>90%（与预期对比）
- ✅ 选项质量：选项过长（>80字）<2%，无解析混入
- ✅ 答案质量：答案格式异常<1%，抽样准确率>95%
- ✅ 类型适配：不同类型PDF使用对应关键词，无硬编码
- ✅ AI兜底：仅在规则失败时触发，有明确触发记录

---

### 21.19 思维导图集成铁律（万变不离其宗，结构为核心）

**核心认知（最高原则）**：**思维导图本质就是知识点体系的可视化投影**——有什么样的知识点体系，就自动生成什么样的思维导图。导图不是独立创建、独立存储的"图片"或"文档"，而是knowledge_points表的另一种展现形式。知识点体系更新，导图自动同步更新，无需手动维护。

**八大集成原则**：
1. **知识点体系为唯一骨架**：导图结构=科目→章→节→知识点，与knowledge_points表100%一致，节点ID=point_id
2. **数据唯一来源**：考频/题目数/闪卡数等统计数据实时查询，不冗余存储，确保一致性
3. **双向关联**：导图节点↔题目↔闪卡↔讲义，点击可跳转，mindmap_node_links表必须启用
4. **颜色编码标准化**：高频红、中频橙、低频绿、已掌握蓝、未掌握灰、新增紫，全局统一
5. **节点信息标准化**：每节点显示3行——知识点名、考频+正确率、题目数+闪卡数
6. **三视图同步**：思维导图视图↔大纲视图↔列表视图，共享数据，操作同步
7. **交互标准化**：单击展开/折叠、双击详情面板、右键操作菜单、搜索高亮定位
8. **自动生成**：从知识点体系自动生成导图，禁止手动创建空结构，支持按科目/章节/考频筛选
9. **创建入口统一在学习资料库**：思维导图的创建/生成入口必须在学习资料库，与题库识别、闪卡生成并列；导图页面只负责展示查看，不提供"新建导图"按钮
10. **双版本模式（问题版/答案版）**：思维导图与闪卡一样，必须支持两种视图模式——
    - **问题版（记忆模式）**：只显示节点名称（章/节/知识点名），隐藏考频、题目数、闪卡数等详细信息，触发用户主动回忆
    - **答案版（学习模式）**：显示完整节点信息（知识点名+考频+题目数+闪卡数+颜色编码），验证回忆结果
    - 一键切换两种模式，问题版用于自测记忆，答案版用于学习核对
    - 两种模式共享同一份知识点数据，只是显示粒度不同

**思维导图识别生成思路（从结构特点出发）**：
- 核心结构特征：**从左往右逐级文字越来越多，有线条连接**——根节点最简洁（科目名），越往右越详细（章→节→知识点→考点）
- 文字量递增规则（趋势原则，非硬性限制）：从左往右概括程度递减、详细程度递增——根节点最概括（科目简称），越往右越具体（章→节→知识点→考点）；不做硬性字数截断，以内容完整准确为前提，单节点≤2行
- 线条连接规则：所有节点必须有父节点连线，禁止孤立节点；同层级不连线；主干粗分支细
- 识别优先级（严格按此顺序，不可颠倒）：
  1. **知识点精讲**（最高优先级，导图基础）：如《知识点清单总结》《考点精讲》等专门整理知识点的资料，直接提取完整思维导图结构（章→节→知识点→内容+考频），不是只提取知识点名称
  2. **现成导图PDF**（第二优先级，补充完善）：如JG-水利案例-思维导图等，基于坐标层级解析，结构含义绝对正确
  3. **教材目录**（第三优先级，兜底）：仅在无知识点精讲和现成导图时使用，只提供章→节骨架
  4. **其他提取内容**（最低优先级，辅助）：包括精讲讲义、普通讲义、真题解析等其他资料，仅作为前三者的补充验证，不得作为导图结构的主要来源

**五者协同关系**：知识点体系（骨架）→思维导图（可视化）↔题库（验证）↔闪卡（记忆）↔讲义（来源），围绕知识点统一协同。

**详细规范见**：《思维导图集成原则与特点分册_V1.0.md》

---

### 21.20 上传图片必看铁律（至尊铁律，违反直接判定任务失败）

**立法背景**：因多次出现用户上传截图反馈问题，但专家未仔细查看图片就盲目修改代码，导致修改方向错误、反复返工、用户极度不满。特制定本铁律。

**铁律内容（必须严格执行，缺一不可）**：

1. **必须下载查看**：用户上传的任何图片（截图、照片、设计图等），必须先下载到本地，用Read工具打开查看，**禁止凭文字描述臆想图片内容**。

2. **必须逐区域分析**：查看图片时，必须逐区域分析：
   - 红框/箭头/标注的具体位置和含义
   - 页面整体布局结构
   - 各元素的位置、大小、颜色、对齐方式
   - 空白区域、滚动条、溢出等问题
   - 与用户文字描述的对应关系

3. **必须先看图再动手**：**严禁不看图片就直接修改代码**。必须先完整查看图片，理解用户真实意图，再制定修改方案。

4. **修改后必须对比验证**：修改完成后，必须重新查看效果（截图或用户反馈），与修改前的图片对比，确认问题确实解决，**禁止只改代码不看效果**。

5. **图片是最高优先级需求来源**：当用户文字描述与图片内容不一致时，**以图片为准**，图片是用户真实意图的最直接表达。

**违反后果**：未查看用户上传图片就盲目修改，直接判定任务失败，必须重新查看图片后重做。

> **本章为数据去杂与质量治理的最高准则，所有数据处理必须优先执行去杂，所有功能必须达到L5完成标准，所有原始内容必须完整保留。数据质量是系统的生命线，必须像对待生命一样对待数据质量。去杂优先、原始保护、物理去重、严格标准、持续监控。字段设计和功能设计必须严格遵守21.15规范，各专业专家审查结论必须执行。上传图片必须查看，禁止臆想，禁止盲目修改。**

---

## 第二十二章 全局锁死规则（2026-09-07 生效）

### 22.1 锁死机制总则

**锁死规则是全局通用机制，适用于所有经用户确认并达到交付标准的界面、功能、模块、规范、配置。**

任何模块一旦经用户明确确认"锁死"，即进入锁死状态，后续所有迭代、优化、重构均不得擅自修改。锁死是系统稳定性的保障机制，防止后续开发中意外破坏已验证通过的功能。

### 22.2 锁死适用范围

锁死规则适用于以下所有对象（不限于）：

1. **界面布局**：登录页、科目选择页、学习看板、题库管理、闪卡管理、思维导图管理等所有页面
2. **功能逻辑**：登录流程、科目选择流程、数据同步流程、缓存机制等核心功能
3. **数据结构**：数据库表结构、API接口格式、配置文件格式
4. **规范标准**：布局规范、命名规范、代码规范、数据质量标准
5. **配置参数**：主题配色、字体大小、间距尺寸等设计Token
6. **第三方集成**：OCR引擎、AI模型、音频播放器等外部依赖

### 22.3 锁死确认流程

一个对象进入锁死状态必须满足以下全部条件：

1. **用户明确声明**：用户明确说出"锁死"、"不再修改"、"确定了"等锁死意图
2. **功能完整可用**：该对象的所有功能已实现并可正常使用
3. **布局符合效果图**：界面布局与确认的效果图完全一致
4. **验证通过**：经过至少一次完整流程验证，无bug、无报错
5. **记录在案**：锁死状态、规格、验证结果记录在对应分册中

**满足以上5条后，该对象自动进入锁死状态，无需额外确认。**

### 22.4 锁死后的修改禁令

**锁死状态下，严禁以下行为**：

1. **擅自修改布局**：未经用户明确授权，修改任何颜色、尺寸、位置、文字、图标
2. **擅自修改功能**：未经用户明确授权，修改任何功能逻辑、流程、交互方式
3. **擅自修改数据**：未经用户明确授权，修改任何数据结构、配置参数、接口格式
4. **顺带修改**：在其他模块的修改中，顺带修改已锁死对象的相关代码
5. **以优化为名修改**：以"优化"、"美化"、"统一"、"重构"等理由擅自修改已锁死对象
6. **批量替换误伤**：使用全局替换、批量修改等操作时，误伤已锁死对象的代码

### 22.5 例外情况（可修改情形）

仅以下情况可以修改已锁死对象：

1. **用户明确提出修改要求**：用户主动要求修改某个已锁死对象
2. **严重bug修复**：出现导致功能完全不可用的严重bug，需先报告用户，经确认后修复
3. **安全漏洞修复**：发现安全漏洞，需先报告用户，经确认后修复
4. **用户要求解锁**：用户明确要求"解锁"某个对象，该对象退出锁死状态

**即使在例外情况下，修改后也必须重新验证，并更新分册记录。**

### 22.6 锁死状态标识

已锁死对象必须在代码和文档中明确标识：

1. **代码注释**：在对应函数/组件开头添加 `// [已锁死] 2026-09-07 经用户确认，请勿擅自修改`
2. **分册记录**：在对应分册中记录锁死日期、规格、验证结果
3. **宪法清单**：在本章22.7节"已锁死清单"中登记

### 22.7 已锁死清单

| 序号 | 锁死对象 | 锁死日期 | 分册 | 状态 |
|------|----------|----------|------|------|
| 1 | 登录界面（登录页+科目选择页） | 2026-09-07 | 登录界面整改分册_V1.0.md | ✅ 已锁死 |
| 2 | 唯一布局标准V2.0 | 2026-09-07 | 布局规范/唯一布局标准V2.0_全品类效果图.html | ✅ 已锁死 |

> **本清单为动态清单，后续新增锁死对象必须在此登记。**

### 22.8 违反后果

**未经授权修改已锁死对象，直接判定任务失败**，必须：
1. 立即回滚所有修改
2. 向用户道歉并说明原因
3. 重新验证锁死对象的功能完整性
4. 在宪法中记录违规事件

> **锁死规则是全局最高优先级规则之一，适用于所有模块、所有专家、所有迭代。任何已确认的功能都应及时锁死，防止后续开发中意外破坏。锁死不是僵化，而是对已验证成果的保护。系统的稳定性建立在每一个锁死模块的基础之上。**



---

## 第二十三章 有规范必执行铁律（2026-09-07 生效）

### 23.1 铁律声明

**有规范必执行，有标准必达标。严禁出现"规范写了但代码不执行"的情况。**

任何已写入宪法、细则、布局规范、设计标准的规则，必须在代码中100%落实。发现规范与代码不一致时，以规范为准，立即修改代码。

### 23.2 违规行为定义

以下行为均属于"有规范不执行"违规：

1. **布局规范不执行**：V2.0规范明确要求筛选栏一行显示，代码却用flex-wrap:wrap导致换行
2. **尺寸规范不执行**：规范要求圆角6px，代码却用2px
3. **命名规范不执行**：规范要求"一造水利案例"，代码却生成"一造案例（水利）"
4. **流程规范不执行**：规范要求先出效果图再改代码，却直接改代码
5. **验证规范不执行**：规范要求修改后必须验证实际效果，却只改代码不看页面
6. **锁死规范不执行**：已锁死的模块擅自修改
7. **任何"写了但没做"的情况**

### 23.3 根本原因

| 原因 | 说明 |
|------|------|
| 规范与代码脱节 | 规范写在文档里，代码是历史遗留，修改时没对照规范 |
| 只改功能不查布局 | 修改时关注功能逻辑，忽略布局规范是否符合 |
| 无自动检查机制 | 全靠人工记忆，改完不验证 |
| 修改后不看效果 | 只改代码不刷新浏览器验证实际呈现 |

### 23.4 规避机制（强制执行）

#### 机制一：修改前必查规范
- **任何页面修改前，必须先查阅对应布局规范**（V2.0效果图 + 宪法 + 细则）
- 确认该页面属于哪一类（A类列表页/B类详情页/C类表单页/D类答题页/E类看板页/F类播放器页）
- 严格按照该类别的规范执行，不得自行发挥

#### 机制二：修改后必对照检查清单
每次修改布局后，必须逐项检查：
- [ ] 边框圆角是否为6px（内容区）
- [ ] 筛选栏是否一行显示（flex-wrap:nowrap）
- [ ] 表头是否sticky固定
- [ ] 表格是否取消竖向线
- [ ] 列宽是否符合规范
- [ ] 命名是否符合规范（简称、专业课带方向）
- [ ] 功能区颜色区分是否正确
- [ ] 底部状态栏位置是否正确

#### 机制三：修改后必验证实际效果
- **修改代码后必须刷新浏览器（Ctrl+F5）查看实际效果**
- 必须截图或用浏览器自动化验证
- 禁止"只改代码不看页面"
- 发现与规范不符，立即修改，不得拖延

#### 机制四：布局规范参数全局化
- 关键布局参数（圆角6px、边框色#c5cae9、筛选栏高度40px等）必须统一
- 禁止在代码中出现与规范不符的硬编码值
- 新增页面必须复用已有规范样式，不得重新发明

#### 机制五：违规立即纠正
- 发现"有规范不执行"的情况，**立即从根本上修改代码**，不得打补丁
- 修改后必须重新验证全流程
- 记录违规原因，防止再次发生

### 23.5 布局规范检查清单（每次修改必过）

**A类标准列表页检查项**：
- [ ] 筛选栏40px高，所有元素一行显示（flex-wrap:nowrap）
- [ ] 表格表头sticky固定（position:sticky;top:0;z-index:10）
- [ ] 表格取消竖向线（只有border-bottom）
- [ ] 列宽符合规范（序号40/题干auto/题型50/章节90/答案45/年份45/类型55/操作80）
- [ ] 一行显示，题干超长省略（white-space:nowrap;text-overflow:ellipsis）
- [ ] 分页栏40px高
- [ ] 内容区边框2px solid #c5cae9，圆角6px

**E类学习看板页检查项**：
- [ ] 浅橙背景#fff8e1 + 橙色边框2px solid #ffcc80
- [ ] 统计卡片5列等宽
- [ ] 快捷入口彩色图标背景（36px圆形）
- [ ] 今日目标左右分栏+中间分割线
- [ ] 学习日历7列网格+进度条从下往上
- [ ] 第三行等宽1:1:1

**F类播放器页检查项**：
- [ ] 播放器与笔记比例6:4
- [ ] 视频列表与讲义列表并排
- [ ] 统一边框圆角6px


#### 机制六：CSS类样式覆盖检查（2026-09-07 新增，血的教训）

**问题根源**：只改内联样式，但CSS类默认样式（如`.tab-bar`的`align-items:center`、`border-bottom:1px`）优先级更高，导致内联样式被覆盖，修改不生效，产生空白条、布局错乱等问题。

**强制执行规则**：
1. **修改任何页面布局前，必须先检查该元素使用的CSS类默认样式**（查看style.css/style.min.css中对应类的定义）
2. **内联样式必须用`!important`确保覆盖CSS类默认样式**，特别是：
   - `align-items`、`justify-content`等flex属性
   - `padding`、`margin`、`border`等盒模型属性
   - `height`、`min-height`、`border-radius`等尺寸属性
   - `display`、`flex-wrap`等布局属性
3. **常见CSS类陷阱清单**（修改时必须检查）：
   - `.tab-bar`：默认`align-items:center`+`border-bottom:1px`+`border-radius:4px`
   - `.tab-bar .tab`：默认`padding:8px 16px`+`margin-bottom:-1px`
   - `.content-header`：默认`min-height:36px`+`padding:6px 12px`+`border-bottom:1px`
   - `.content-body`：默认`padding:12px 14px`
   - `.filter-bar`：默认`flex-wrap:wrap`+`padding:8px 12px`+`border-radius:4px`
4. **修改后必须验证**：刷新浏览器查看实际效果，不能只改代码不看页面
5. **发现空白条/布局错乱**，第一反应检查CSS类默认样式是否覆盖了内联样式，而不是继续加内联样式

> **教训**：2026-09-07，题库刷题页面空白条问题，反复修改3次才发现是CSS类`.tab-bar`的`align-items:center`覆盖了内联`align-items:stretch`。此后所有布局修改必须先查CSS类，内联样式加`!important`。


### 23.6 违反后果

**出现"有规范不执行"的情况**：
1. 立即从根本上修改代码，不得打补丁
2. 重新验证全流程
3. 在宪法中记录违规事件
4. 同类问题再次出现，从重处理

> **规范的生命力在于执行。写了不执行等于没写。所有专家必须牢记：先查规范再动手，改完对照检查清单，最后必须验证实际效果。任何"写了但没做"的情况都是违规，必须立即纠正。**



---

## 二十四、知识点排序规则（2026-09-07新增）

### 24.1 排序原则

**所有知识类列表必须按章节知识点排序**，便于用户按教材顺序学习和判断内容取舍。

**排序层级**（从粗到细）：
1. **章**（第1章、第2章...）
2. **节**（1.1、1.2...）
3. **目**（1.1.1、1.1.2...）
4. **知识点名称**（同章节内按知识点名称排序）

### 24.2 适用模块

**所有跟学习挂钩的资料模块都必须遵循章节目排序**，除非有物理限制（如文件夹结构）。

| 模块 | 排序字段 | 排序方式 | 备注 |
|------|----------|----------|------|
| **闪卡库** | chapter + knowledge_point | 章节编号→知识点名称 | 两级排序 |
| **题库管理** | chapter | 章节编号 | |
| **思维导图** | chapter | 章节编号 | |
| **视频管理** | chapter | 章节编号 | 文件夹内也按章节排序 |
| **讲义管理** | chapter | 章节编号 | 文件夹内也按章节排序 |
| **错题本** | chapter | 章节编号 | |
| **学习笔记** | chapter | 章节编号 | |
| **数据分析** | chapter | 章节编号 | |

**文件夹排序规则**：有文件夹结构的模块（视频/讲义），文件夹按名称排序，**文件夹内的文件按章节目排序**。

### 24.3 排序键函数

**统一使用`_chapter_sort_key()`函数**（位于`backend/crud/crud.py`）：
- 支持数字编号：`1.2.3` → `(1, 2, 3)`
- 支持中文编号：`第一章` → `(1,)`
- 支持最多4级编号（章→节→目→点）
- 无章节编号的排最后：`(9999,)`

### 24.4 两级排序规则

**闪卡库采用两级排序**：
```python
all_items.sort(key=lambda x: (_chapter_sort_key(x.chapter), x.knowledge_point or ''))
```
- 第一级：章节编号（章→节→目→点）
- 第二级：知识点名称（同章节内按名称排序）

### 24.5 强制执行规则

1. **新增知识类列表时，必须应用章节排序**，不得按ID或创建时间排序
2. **排序函数必须统一使用`_chapter_sort_key()`**，不得各自实现排序逻辑
3. **闪卡库必须返回`knowledge_point`字段**，前端显示知识点名称
4. **章节编号格式必须统一**：数字编号优先（1.1.1），中文编号兼容（第一章）
5. **修改排序逻辑前，必须检查所有使用该排序的模块**，避免影响其他功能
6. **有文件夹结构的模块**（视频/讲义），文件夹内文件必须按章节目排序，不得按文件名或上传时间排序
7. **新增任何学习资料模块**，必须默认应用章节目排序，不得按ID或创建时间排序

> **教训**：2026-09-07，用户要求闪卡按章节知识点排序以便判断取舍。此前闪卡仅按ID排序，同章节知识点分散，无法系统学习。此后所有知识类列表必须按章节知识点排序。


## 第二十四章 专家纠偏机制（防止集体走偏）

### 24.1 铁律声明
70名专家必须防止"集体走偏"——所有专家都犯同一个错误、都朝错误方向走、连续多次修改同一问题不解决。一旦出现走偏迹象，必须立即停止、换思路、从根本原因重新分析。

### 24.2 走偏预警规则
- **连续2次修改同一问题未解决**：黄色预警，必须检查是否在重复同样的错误
- **连续3次修改同一问题未解决**：红色预警，必须停止当前方法，从根本原因重新分析
- **修改后用户反馈"没有改变"**：立即验证是否修改了正确的文件、是否同步、是否被CSS类覆盖

### 24.3 五大纠偏机制
1. **独立验证机制**：每个专家的结论必须由另一个独立专家验证，不能自己说对就对。证据必须是：代码截图、浏览器截图、数据库查询、日志输出、测试通过，禁止"我觉得""应该是""大概"
2. **反向论证机制**：重要方案必须专门从反面找漏洞，回答5个问题：可能在什么情况下失败？有没有更简单的替代方案？会不会影响其他功能？失败了怎么回滚？有没有类似的失败案例？
3. **结果导向验证**：不能只看代码改了，必须看实际效果（浏览器截图/数据验证），"改了代码"不等于"解决了问题"
4. **多方案对比**：重要问题至少提出2个方案，对比后选择，不能一条路走到黑
5. **根本原因优先**：遇到问题先找根本原因，再修表面。治标不治本的修改一律拒绝

### 24.4 走偏案例库
所有走偏案例必须记录到`规划细则分册/专家走偏记录.json`，包括：问题、失败次数、错误方向、根本原因、正确方案、教训。后续遇到类似问题必须先查案例库。

### 24.5 已记录走偏案例
- **案例1：题库刷题空白条**（2026-09-07）
  - 失败3次，一直改Tab栏高度/align-items/border-bottom
  - 根本原因：父容器.content-area默认padding:16px，从未检查父容器
  - 正确方案：给chapterConfigPanel添加padding:0 !important
  - 教训：修改子元素前必须先检查父容器的CSS类默认样式

### 24.6 违反后果
- 连续3次走偏未纠正：相关专家暂停决策权，由其他专家接管
- 治标不治本的修改：必须返工，从根本原因重新解决
- 无证据的结论：一律无效，必须提供实际证据


## 第二十五章 系统性问题预防机制（九大机制）

### 25.1 修改生效验证机制
**问题**：改了代码但没生效（文件没同步、浏览器缓存、CSS类覆盖），用户反馈"没有改变"。

**规则**：
1. 修改app.js后必须立即同步到app_v3_897262.js，禁止只改一个
2. 修改后必须验证：文件大小变化、关键字符串存在、app_v3与app.js一致
3. 涉及样式修改必须检查CSS类默认样式，内联样式必须加!important
4. 用户反馈"没有改变"时，按顺序排查：①是否改对文件 ②是否同步 ③是否被CSS类覆盖 ④是否浏览器缓存 ⑤是否改对了元素
5. 验证工具：`tools/execution_guard.py verify`

### 25.2 已有资产复用机制
**问题**：重复造轮子，已有的文件/功能/工具又新建一遍。

**规则**：
1. 新建任何文件/功能/工具前，必须先搜索是否已存在
2. 搜索范围：frontend/css/、frontend/js/、tools/、backend/、规划细则分册/
3. 已存在的必须复用，不得新建重复文件。如确需扩展，在已有文件上修改
4. 发现重复资产必须立即合并删除
5. 反面案例：已有tokens.css（完善），又新建design-tokens.css（重复），已删除

### 25.3 用户反馈闭环机制
**问题**：用户提了问题，专家说"修好了"，但实际没修好，用户反复反馈。

**规则**：
1. 用户反馈的每个问题必须记录：问题描述、截图、修改方案、修改文件、验证结果
2. 修改后必须提供实际证据（浏览器截图/数据验证），不能只说"已修改"
3. 用户再次反馈同一问题 = 上一次修改失败，必须从根本原因重新分析，不能继续打补丁
4. 连续2次用户反馈同一问题 = 触发走偏预警（宪法24.2）
5. 问题解决后必须记录到案例库，避免重犯

### 25.4 需求理解确认机制
**问题**：用户说A，专家理解成B，做出来不符合预期，反复返工。

**规则**：
1. 复杂需求必须先复述确认："您的意思是XXX，对吗？"
2. 涉及布局/界面修改，必须先出效果图，用户确认后再改代码
3. 涉及功能变更，必须先说明影响范围，用户确认后再执行
4. 用户上传的图片必须查看（铁律），不能凭文字猜测
5. 歧义表述必须追问，不能自行假设。如"适当压缩"必须量化为具体数值

### 25.5 工具资产统一管理机制
**问题**：创建了20+脚本，没有统一管理，不知道哪个有用、哪个过时。

**规则**：
1. 所有工具脚本必须放在tools/目录，统一命名：`功能_版本.py`
2. 每个工具必须有：用途说明、用法、创建时间、状态（在用/过时/废弃）
3. 建立工具清单：`tools/README.md`，登记所有工具
4. 过时工具必须标记废弃，不得删除（保留历史）
5. 新增工具前必须检查是否已有类似工具，避免重复

### 25.6 机制执行检查清单
每次修改前必须确认：
- [ ] 是否搜索了已有资产？（25.2）
- [ ] 是否复述确认了需求？（25.4）
- [ ] 修改后是否同步+验证？（25.1）
- [ ] 是否提供了实际证据？（25.3）
- [ ] 工具是否登记到清单？（25.5）
- [ ] 连续失败是否触发走偏预警？（24.2）
- [ ] 是否按联动清单完成所有同步修改？（25.7）
- [ ] 迁移是否完成神经末梢级验证？（25.8）
- [ ] 是否生成迁移完整性报告？（25.8）
- [ ] 需求登记系统是否已更新？（25.8）

### 25.7 同步修改铁律（联动修改总纲，2026-09-11入宪）

**立法背景**：系统已完成模块化架构重构（frontend/core/ 核心框架 + frontend/modules/ 20个功能模块），原 app.js 单体文件及 app_v3_897262.js 已废弃不再被引用。但修改一个文件时经常遗漏关联文件的同步修改，导致功能异常、数据不一致、样式失效、用户反馈"没有改变"。本铁律明确所有必须联动修改的文件对，确保一次修改全链路同步。

**核心原则**：
1. 修改任何文件前，必须先评估影响范围，列出所有需要同步修改的关联文件
2. 禁止只改一个文件而忽略关联文件，必须一次性完成所有联动修改
3. 修改完成后必须验证所有关联文件的一致性，禁止"应该同步了"的纸面推测

**联动修改清单（当前模块化架构）**：

| 修改对象 | 必须同步修改 | 原因 |
|---------|------------|------|
| `frontend/core/*.js`（核心框架7文件） | 所有依赖该核心的 `modules/*/*.js` | 核心API/存储/事件总线变更影响所有模块 |
| `frontend/modules/X/*.js`（单个模块） | 依赖该模块的其他模块 + `index.html` 引用清单 | 模块间依赖和入口引用必须同步 |
| `frontend/css/tokens.css`（设计变量） | 所有引用变量的CSS文件 + 组件样式 + V2布局规则 | 变量变更影响全局样式体系 |
| `frontend/css/style.css` | `style.min.css`（压缩版必须同步重新生成） | 两者必须保持一致，禁止只改一个 |
| `frontend/css/components.css`（组件库） | 所有使用该组件的页面/模块 | 组件API/样式变更影响所有使用方 |
| `frontend/index.html`（资源引用/版本号） | 确保引用的所有文件存在 + 静态文件版本号参数 `?v=xxx` 更新 | 引用失效导致404/白屏，版本号不更新导致缓存 |
| `backend/main.py`（API接口） | 所有调用该API的前端模块（用 fast_search 搜索接口路径） | 接口参数/返回值变更影响前端调用 |
| 数据库表结构（ALTER TABLE/CREATE TABLE） | 后端数据模型 + 前端数据展示 + 离线缓存结构 + exam_config.json | 数据结构变更必须全链路同步 |
| `backend/data/exam_config.json`（考试配置） | 依赖该配置的题库/模考/错题/闪卡模块 | 配置变更影响功能逻辑和数据展示 |
| 批量标签修改（资料库） | 文件夹内所有单条记录的标签字段 | 数据一致性，禁止批量改后单条不同步 |
| `tailwind.config.js`（如存在） | CSS变量定义 + 所有使用Tailwind类的组件 | 配置必须与CSS变量同步 |

**同步验证流程（必须严格执行）**：
1. **修改前**：运行 `tools/impact_analyzer.py` 评估影响范围，列出联动清单
2. **修改中**：按联动清单逐一修改，每改完一个在清单上标记，不得遗漏
3. **修改后验证三步**：
   - 第一步：运行 `python tools/fast_search.py search <关键词>` 验证所有引用点已更新（毫秒级检索）
   - 第二步：运行 `python tools/execution_guard.py verify` 验证功能正常
   - 第三步：浏览器强制刷新（Ctrl+Shift+R）实际查看效果，提供截图证据
4. **静态文件修改**必须更新 `index.html` 中对应引用的版本号参数（`?v=xxx`），禁止省略
5. **CSS修改**必须同时检查 `style.css` 和 `style.min.css` 一致性，禁止只改源文件不改压缩版

**高效检索工具（强制使用）**：
- 工具：`tools/fast_search.py`
- 功能：对宪法、规划细则等大文件建立结构化索引，实现毫秒级关键词搜索和章节定位
- 用法：
  - `python tools/fast_search.py search <关键词>` — 关键词搜索
  - `python tools/fast_search.py chapter <章节名>` — 按章节定位
  - `python tools/fast_search.py list` — 列出所有章节
  - `python tools/fast_search.py build <文件>` — 重建索引
- 索引存放：`data/search_index/`
- 禁止：对300KB以上大文件使用逐行扫描（PowerShell Select-String/Grep），必须使用本工具

**违规处罚**：
- 遗漏关联文件修改 = 记1次严重违规
- 因不同步导致用户反馈"没有改变"或功能异常 = 记2次严重违规
- 未使用 fast_search 进行引用点验证 = 记1次警告
- 3次严重违规 = 专家团重组，重新制定工作流程

**与25.1的关系说明**：
- 25.1中"修改app.js后必须立即同步到app_v3_897262.js"为**历史规则**（原单体架构时期），当前模块化架构下 app.js 和 app_v3 均已不再被 index.html 引用，该规则实际已失效
- 本铁律（25.7）为当前架构下的同步修改总纲，**优先级高于**25.1中的历史规则
- 如未来架构再次重大变更，必须同步更新本铁律的联动清单，禁止清单与实际架构脱节

### 25.8 代码迁移与数据迁移质量保证体系（各负其责铁律，2026-09-11入宪，宪法最高执行标准）

**立法背景**：系统从单体架构（app.js 34849行、1029函数）迁移到模块化架构（frontend/modules/ 24个模块、132函数）过程中，出现严重功能阉割问题：旧代码30个方法的file_library模块迁移后仅剩26个方法，缺失文件预览、单文件识别、单文件导图等核心功能；collect/memory/sprint三个模块的bindEvents方法完全为空，所有可点击元素全部失效。根本原因是迁移过程中没有明确的方法论、质量标准、范围界定、检查机制和替代方案审批流程，"搬过来就好"变成了"搬一半就好"。本体系是宪法级最高执行标准，所有迁移必须严格遵守。

**宪法级定位**：本条款是系统迁移的最高执行标准，优先级高于任何临时决策、个人判断、效率考量。任何迁移工作必须先读本条款，再动手；任何违反本条款的迁移结果一律视为无效，必须返工。

---

**一、迁移方法论（怎么迁）**

**1.1 迁移五步法（强制执行，禁止跳步）**

| 步骤 | 名称 | 动作 | 输出物 | 责任人 |
|------|------|------|--------|--------|
| 第1步 | 旧代码深度研读 | 完整读取旧代码，逐方法、逐函数、逐事件理解功能意图，禁止只读方法名猜测功能 | 《旧代码功能清单》 | 迁移责任人 |
| 第2步 | 神经末梢拆解 | 拆解到每一个按钮、每一个输入框、每一个API调用、每一个state字段、每一个CSS类 | 《神经末梢清单》 | 迁移责任人 |
| 第3步 | 对照迁移 | 按神经末梢清单逐一迁移，每迁完一项在清单上标记，禁止"批量迁移"的模糊操作 | 已标记的《神经末梢清单》 | 迁移责任人 |
| 第4步 | 完整性自检 | 按神经末梢清单逐项自检，确认无遗漏、无阉割、无静默替换 | 《迁移完整性自检报告》 | 迁移责任人 |
| 第5步 | 独立验收 | 由非迁移责任人的专家进行独立验收，模拟用户操作验证每个交互 | 《迁移验收报告》 | 验收专家 |

**1.2 旧代码研读标准**
- 必须完整读取旧代码文件，禁止只读方法列表或前100行
- 必须理解每个方法的输入、输出、副作用、调用关系
- 必须理解每个事件绑定的触发条件和处理逻辑
- 必须理解每个API调用的URL、方法、参数、返回值处理
- 必须理解每个state字段的数据来源和更新时机
- 研读完成后必须能用自己的话复述该模块的完整功能，复述不清=没读懂，必须重读

**1.3 迁移操作标准**
- 禁止"重新实现"：必须以旧代码为基准迁移，禁止凭印象或个人偏好重新设计
- 禁止"优化阉割"：迁移过程中不得以"优化"为名删除旧功能，优化必须在迁移完成后单独提出
- 禁止"静默替换"：任何功能不直接迁移而采用替代方案的，必须走替代方案审批流程（见第五条）
- 禁止"半成品交付"：迁移必须100%完成才能交付，禁止"核心功能迁了，边缘功能以后再说"

---

**二、迁移质量标准（迁到什么程度算合格）**

**2.1 功能完整性标准（100%为合格线，99%=不合格）**

| 维度 | 标准 | 验证方法 |
|------|------|---------|
| 方法完整性 | 旧代码所有public方法必须在新代码中有对应实现或明确的替代方案 | 方法清单逐一对照 |
| 事件完整性 | 所有可交互元素（button/input/select/cursor:pointer）必须有事件绑定 | 神经末梢清单逐项验证 |
| API完整性 | 所有API调用必须与旧代码URL/方法/参数一致，变更必须说明 | API清单逐一对照 |
| 数据完整性 | 所有state字段必须有数据来源和初始化逻辑 | state清单逐一验证 |
| 样式完整性 | 所有CSS类必须有定义，视觉效果与旧代码一致 | 截图对比 |
| 路由完整性 | 所有页面跳转必须目标存在且可访问 | 路由清单逐一验证 |

**2.2 交互可用性标准**
- 每个按钮点击后必须有可见反馈（页面变化/弹窗/提示/加载状态）
- 每个输入框必须有输入处理逻辑（onchange/onkeydown/onsubmit）
- 每个列表项必须有点击处理（除非明确是纯展示）
- 每个异步操作必须有加载状态和错误处理
- 禁止"死按钮"：点击后无任何反应的按钮=严重缺陷

**2.3 数据一致性标准**
- 迁移前后数据结构必须一致，字段名/类型/格式不得静默变更
- 默认值必须与旧代码一致，变更必须说明原因
- 标签体系必须完整迁移，标签名称/分组/颜色映射不得遗漏
- 用户配置必须完整迁移，科目选择/学习偏好不得丢失

**2.4 质量验收红线（触碰任何一条=迁移不合格）**
1. ❌ bindEvents方法为空或只有注释
2. ❌ 存在点击无反应的死按钮
3. ❌ 核心功能缺失且无替代方案
4. ❌ API调用路径错误导致功能失效
5. ❌ 数据字段丢失导致展示异常
6. ❌ 未生成迁移完整性报告
7. ❌ 未经过独立验收

---

**三、迁移范围界定（迁什么、不迁什么）**

**3.1 必须迁移的范围（红线，禁止遗漏）**

| 范围类别 | 具体内容 | 说明 |
|---------|---------|------|
| 核心功能 | 旧代码中所有用户可感知的功能 | 包括但不限于：按钮点击、表单提交、列表展示、数据加载、页面跳转 |
| 边缘功能 | 旧代码中所有辅助功能 | 包括但不限于：搜索、筛选、排序、导出、批量操作、右键菜单 |
| 事件绑定 | 所有addEventListener/onclick/onchange/onkeydown | 包括动态生成元素的事件委托 |
| API调用 | 所有fetch/axios/window.api调用 | 包括URL、方法、参数、错误处理 |
| 状态管理 | 所有state字段及其更新逻辑 | 包括初始化、更新、持久化 |
| 样式定义 | 所有CSS类及其样式规则 | 包括动态样式、条件样式 |
| 数据结构 | 所有数据模型、字段映射、默认值 | 包括标签体系、配置项 |
| 错误处理 | 所有try/catch、错误提示、降级方案 | 包括网络错误、数据为空、权限不足 |

**3.2 可以不迁移的范围（必须登记并说明原因）**

| 范围类别 | 条件 | 登记要求 |
|---------|------|---------|
| 已废弃功能 | 旧代码中已被注释掉或明确标记为deprecated的功能 | 在迁移报告中说明"旧代码已废弃" |
| 重复功能 | 与其他模块功能完全重复且已有更优实现的功能 | 在迁移报告中说明"被XX模块替代" |
| 技术债功能 | 旧代码中明显的临时方案、硬编码、调试代码 | 在迁移报告中说明"技术债，已用XX方案替代" |
| 纯展示模块 | 明确只有展示功能、无任何交互的模块 | 在迁移报告中说明"纯展示，无需事件绑定" |

**3.3 范围变更审批**
- 任何"不迁移"的决定必须经过至少2位专家同意
- 必须在需求登记系统中记录：功能名称、不迁移原因、替代方案、审批人
- 禁止单人决定不迁移某个功能
- 禁止"先迁核心，边缘以后再说"的分期迁移，必须一次性完成

---

**四、检查机制（谁来查、怎么查）**

**4.1 三级检查制度**

| 检查级别 | 检查人 | 检查时机 | 检查内容 | 输出物 |
|---------|--------|---------|---------|--------|
| 一级自检 | 迁移责任人 | 迁移完成后立即 | 按神经末梢清单逐项自检 | 《迁移完整性自检报告》 |
| 二级互检 | 同领域另一位专家 | 自检通过后 | 抽查30%的神经末梢，重点检查事件绑定和API调用 | 《迁移互检报告》 |
| 三级验收 | 非本领域的独立专家 | 互检通过后 | 模拟用户操作，从入口到出口完整走一遍所有功能 | 《迁移验收报告》 |

**4.2 检查工具（强制执行）**

| 工具 | 用途 | 用法 |
|------|------|------|
| `tools/fast_search.py` | 毫秒级检索旧代码中的方法/API/事件 | `python tools/fast_search.py search <关键词>` |
| `tools/static_check.py` | 静态代码检查，检测空方法、未绑定事件、API路径错误 | `python tools/static_check.py <模块路径>` |
| 浏览器自动化 | 模拟用户点击，验证每个按钮有反应 | computer_use_tool + bu.js |
| 神经末梢清单 | 人工逐项核对 | 按清单逐一标记✅/❌ |

**4.3 检查不合格处理**
- 一级自检不合格：迁移责任人立即修复，修复后重新自检
- 二级互检不合格：返回迁移责任人修复，修复后重新互检
- 三级验收不合格：整个模块返工，重新走五步法
- 连续2次验收不合格：更换迁移责任人，原责任人记1次严重违规

**4.4 检查记录留存**
- 所有检查报告必须存档到 `docs/迁移报告/` 目录
- 报告必须包含：检查人、检查时间、检查项、检查结果、问题清单、整改情况
- 报告必须有检查人签字（专家角色名）
- 禁止"检查通过"的空泛结论，必须有具体检查项和结果

---

**五、替代方案审批制度（什么情况下可以不直接迁）**

**5.1 替代方案适用场景**

| 场景 | 说明 | 示例 |
|------|------|------|
| 技术升级 | 旧技术方案已过时，新技术方案更优且功能等价 | 原生input替代上传模态框 |
| 架构优化 | 模块化架构下旧方案不适用，新方案更合理 | 标签面板替代下拉标签选择 |
| 性能优化 | 旧方案性能差，新方案性能更好且功能等价 | page_size=1000替代分页 |
| 用户体验优化 | 旧方案体验差，新方案体验更好且功能等价 | 上下布局替代左右布局 |

**5.2 替代方案审批流程（四步）**

1. **提出**：迁移责任人提出替代方案，说明：旧功能是什么、为什么不直接迁、替代方案是什么、功能是否等价
2. **评估**：至少2位专家评估替代方案的功能等价性、用户体验影响、维护成本
3. **批准**：产品专家+技术专家双签字批准，禁止单人批准
4. **登记**：在需求登记系统中记录：旧功能、替代方案、批准人、批准时间

**5.3 替代方案质量标准**
- **功能等价**：替代方案必须覆盖旧功能的所有使用场景，禁止"核心等价，边缘缺失"
- **体验不降**：替代方案的用户体验不得低于旧方案，禁止"更简单但更难用"
- **可回退**：替代方案必须可回退到旧方案，禁止"迁了就改不回来"
- **有文档**：替代方案必须有文档说明，禁止"只有代码没有说明"

**5.4 禁止以替代方案为名阉割功能**
- ❌ 禁止："这个功能用户很少用，不迁了"（必须有数据支撑）
- ❌ 禁止："这个功能实现复杂，以后再说"（必须一次性完成）
- ❌ 禁止："这个功能我觉得没用，删掉"（个人判断不能替代用户需求）
- ❌ 禁止："替代方案只做80%，剩下20%以后补"（必须100%功能等价）

---

**六、专家全面分析机制**

**6.1 迁移前专家会诊**
- 每个模块迁移前，必须召开专家会诊（至少3位相关领域专家）
- 会诊内容：旧代码功能解读、迁移难点识别、风险点预判、替代方案讨论
- 会诊输出：《迁移方案》，包含功能清单、难点、风险、替代方案、时间估算
- 禁止无会诊直接迁移

**6.2 迁移中专家支持**
- 迁移责任人遇到疑问必须立即请教相关专家，禁止"猜着做"
- 专家必须在2小时内响应迁移疑问（工作时间内）
- 重大技术决策必须经过至少2位专家同意

**6.3 迁移后专家复盘**
- 每个模块迁移完成后，必须召开专家复盘会
- 复盘内容：迁移过程中的问题、遗漏的功能、替代方案的效果、经验教训
- 复盘输出：《迁移复盘报告》，更新到问题知识库
- 复盘发现的问题必须立即整改，禁止"记下来以后改"

**6.4 代码分析师（迁移质量守门人，拥有一票否决权）**

**角色定位**：代码分析师是迁移质量的最高守门人，独立于迁移责任人，拥有对迁移结果的一票否决权。任何模块迁移完成后，必须经过代码分析师的全面分析才能进入验收环节。

**核心职责**：
1. **旧代码深度拆解**：迁移前必须完整读取旧代码，输出《旧代码神经末梢清单》，包含：
   - 所有方法清单（方法名+行数+输入输出+功能描述+调用关系）
   - 所有事件绑定清单（元素+事件类型+处理函数+触发条件）
   - 所有API调用清单（URL+方法+参数+返回值处理+错误处理）
   - 所有state字段清单（字段名+数据类型+数据来源+更新时机+默认值）
   - 所有CSS类清单（类名+样式规则+使用位置+动态变化逻辑）
   - 所有可交互元素清单（按钮/输入框/下拉框/可点击div）
2. **新旧代码对比分析**：迁移后必须输出《新旧代码对比报告》，包含：
   - 方法级对比：旧方法→新方法，标记✅已迁移/❌缺失/⚠️替代
   - 事件级对比：旧事件→新事件，标记✅已绑定/❌未绑定
   - API级对比：旧API→新API，标记✅一致/❌路径错误/⚠️参数变更
   - 数据级对比：旧字段→新字段，标记✅一致/❌缺失/⚠️类型变更
3. **神经末梢验证**：按7类神经末梢清单逐项验证，输出《神经末梢验证报告》
4. **缺失功能预警**：发现任何缺失功能必须立即发出预警，禁止"先交付以后补"
5. **替代方案审查**：审查所有替代方案的功能等价性，有权否决功能不等价的替代方案

**工作流程**：
- 迁移前：输出《旧代码神经末梢清单》→ 交给迁移责任人作为迁移基准
- 迁移中：随时接受迁移责任人的代码咨询，提供旧代码功能解读
- 迁移后：执行新旧代码对比分析→输出对比报告→神经末梢验证→给出通过/不通过结论
- 不通过：列出问题清单→返回迁移责任人整改→整改后重新分析

**权力**：
- 一票否决权：代码分析师不通过的迁移结果，不得进入验收环节
- 叫停权：发现迁移过程中存在严重阉割风险时，有权叫停迁移工作
- 调阅权：有权调阅任何旧代码、新代码、设计文档、需求记录

**禁止行为**：
- ❌ 禁止"大概迁移了"的模糊判断，必须逐项验证
- ❌ 禁止只看方法名不看实现，必须深入理解功能意图
- ❌ 禁止与迁移责任人串通放水，必须独立客观
- ❌ 禁止跳过神经末梢验证，必须逐项核对

**6.5 需求整理迭代更新师（需求完整性守门人，拥有需求追溯权）**

**角色定位**：需求整理迭代更新师是需求完整性的最高守门人，负责所有功能需求的登记、跟踪、迭代、追溯，确保"用户提过的每一个需求都有记录、有状态、有结果"。

**核心职责**：
1. **需求全量登记**：用户提出的每一个功能需求、修改要求、设计决策，必须在2小时内登记到需求登记系统，包含：
   - 需求编号（唯一标识，如 REQ-2026-0911-001）
   - 需求描述（用户原话+整理后的清晰描述）
   - 提出时间、提出人
   - 关联模块、关联功能点
   - 优先级（P0/P1/P2）
   - 状态（待评估/进行中/已完成/已废弃/已替代）
   - 替代方案（如有）
   - 验收标准
2. **需求状态跟踪**：每个需求必须有明确的状态流转，禁止"提了就没人管"：
   - 待评估→评估中→已排期→进行中→待验收→已完成
   - 每个状态变更必须记录时间、责任人、变更原因
   - 超过3天无进展的需求必须发出预警
3. **迭代更新管理**：需求不是一成不变的，必须跟踪迭代：
   - 用户修改需求时，必须记录变更前后的对比
   - 需求拆分时，必须记录子需求与父需求的关系
   - 需求合并时，必须记录合并原因和关联需求
   - 需求废弃时，必须记录废弃原因和替代方案
4. **需求追溯审计**：定期（每周）进行需求追溯审计：
   - 检查是否有用户提过但未登记的需求
   - 检查是否有登记了但无人负责的需求
   - 检查是否有完成了但未更新状态的需求
   - 检查是否有"已完成"但实际未实现的需求（虚假完成）
5. **设计决策记录**：所有重要的设计决策必须记录，包含：
   - 决策内容、决策时间、决策人
   - 决策背景（为什么做这个决策）
   - 备选方案（考虑过哪些其他方案）
   - 决策理由（为什么选这个方案）
   - 影响范围（这个决策影响哪些模块/功能）

**工作工具**：
- 主工具：`docs/代码迁移分析师_需求登记.md`
- 辅助工具：`docs/神经末梢级深度分析报告.md`、`docs/全面代码对比报告.md`
- 更新频率：每次需求变更/状态变更必须立即更新，禁止事后补录
- 报告输出：每周输出《需求状态周报》，包含：新增需求、完成需求、延期需求、风险预警

**权力**：
- 需求追溯权：有权追溯任何需求的来龙去脉，要求相关人员提供信息
- 状态纠正权：发现虚假完成的需求，有权将状态改回"进行中"并要求整改
- 优先级调整建议权：有权根据用户反馈和业务价值，提出优先级调整建议
- 预警权：发现需求遗漏、延期、虚假完成时，有权发出正式预警

**禁止行为**：
- ❌ 禁止需求登记不完整，必须包含所有必填字段
- ❌ 禁止状态更新不及时，必须在状态变更后立即更新
- ❌ 禁止虚假完成，"已完成"必须有实际功能实现和验收证据
- ❌ 禁止需求遗漏，用户提过的每一个需求都必须有记录

**6.6 两师协同机制（代码分析师+需求整理迭代更新师）**

两个角色必须紧密协同，形成"需求-代码-验证"的完整闭环：

| 阶段 | 需求整理迭代更新师 | 代码分析师 | 协同输出 |
|------|-------------------|-----------|---------|
| 需求提出 | 登记需求，明确验收标准 | 分析旧代码，输出神经末梢清单 | 《需求登记》+《旧代码功能清单》 |
| 迁移实施 | 跟踪需求状态，记录变更 | 提供旧代码咨询，监控迁移质量 | 状态更新记录+代码咨询记录 |
| 迁移完成 | 核对需求是否全部实现 | 执行新旧代码对比+神经末梢验证 | 《需求核对报告》+《代码对比报告》 |
| 验收交付 | 确认需求验收标准达成 | 确认代码质量达标 | 双签字的《迁移验收报告》 |
| 迭代优化 | 收集用户反馈，更新需求 | 分析新问题，更新功能清单 | 《迭代需求清单》+《问题分析报告》 |

**两师联席会议**：每周召开一次两师联席会议，内容包括：
1. 需求状态回顾（新增/完成/延期/风险）
2. 代码质量回顾（缺失功能/死按钮/API错误）
3. 协同问题讨论（需求不清/代码不明/验收标准模糊）
4. 下周工作计划（优先级排序+资源分配）
5. 输出《两师联席会议纪要》，存档备查

---

**七、责任矩阵（谁干什么）**

**7.1 代码迁移责任矩阵**

| 模块 | 迁移责任人 | 互检专家 | 验收专家 | 旧代码基准 |
|------|-----------|---------|---------|-----------|
| file-library | 前端架构师+文件处理专家 | 题库专家 | 产品专家 | file_library.js（1313行，30方法） |
| video | 前端架构师+视频处理专家 | 文件处理专家 | 产品专家 | video.js |
| flashcard | 学习算法专家+前端架构师 | 题库专家 | 产品专家 | flashcard.js |
| question-practice | 题库专家+前端架构师 | 考试专家 | 产品专家 | question.js |
| mock-exam | 考试专家+前端架构师 | 题库专家 | 产品专家 | exam.js |
| wrong-book | 题库专家 | 考试专家 | 产品专家 | wrong.js |
| mindmap | AI专家+前端架构师 | 学习算法专家 | 产品专家 | mindmap.js |
| note | 产品专家 | 前端架构师 | 用户体验专家 | note.js |
| collect | 产品专家 | 前端架构师 | 用户体验专家 | collect.js（**bindEvents不能为空**） |
| memory | 学习算法专家 | 产品专家 | 用户体验专家 | memory.js（**bindEvents不能为空**） |
| sprint | 产品专家+学习算法专家 | 考试专家 | 用户体验专家 | sprint.js（**bindEvents不能为空**） |
| dashboard | 数据分析师 | 前端架构师 | 产品专家 | dashboard.js |
| analytics | 数据分析师 | 学习算法专家 | 产品专家 | analytics.js |
| knowledge | 知识库专家 | 题库专家 | 产品专家 | knowledge.js |
| material | 文件处理专家 | 前端架构师 | 产品专家 | material.js |
| photo-solve | AI专家 | 前端架构师 | 用户体验专家 | photo.js |
| settings | 运维专家 | 前端架构师 | 产品专家 | settings.js |
| system-admin | 运维专家 | 前端架构师 | 产品专家 | admin.js（可纯展示） |
| question-manager | 题库专家 | 运维专家 | 产品专家 | manager.js |
| layout | 前端架构师 | 运维专家 | 用户体验专家 | layout.js |

**7.2 数据迁移责任矩阵**

| 数据类型 | 迁移责任人 | 互检专家 | 验收专家 | 旧数据基准 |
|---------|-----------|---------|---------|-----------|
| 文件库数据 | 文件处理专家+DBA | 前端架构师 | 产品专家 | fl_file_library表（506条，含tags） |
| 视频数据 | 视频处理专家+DBA | 文件处理专家 | 产品专家 | video表（64条） |
| 题库数据 | 题库专家+DBA | 考试专家 | 产品专家 | questions表 |
| 闪卡数据 | 学习算法专家+DBA | 题库专家 | 产品专家 | flashcards表 |
| 错题数据 | 题库专家+DBA | 学习算法专家 | 产品专家 | wrong_questions表 |
| 标签体系 | 产品专家+AI专家 | 题库专家 | 用户体验专家 | 旧代码预设标签（18个） |
| 用户配置 | 运维专家 | 前端架构师 | 产品专家 | localStorage/exam_config.json |
| 学习进度 | 学习算法专家 | 数据分析师 | 产品专家 | study_progress表 |

---

**八、神经末梢级验证清单（强制执行）**

每个模块迁移完成后，必须逐项验证以下7类神经末梢，禁止跳过：

1. **按钮级验证**：列出HTML中所有`<button>`元素，逐一确认onclick/addEventListener已绑定，点击有反应
2. **输入级验证**：列出所有`<input>`/`<select>`/`<textarea>`，逐一确认onchange/onkeydown已绑定，输入有处理
3. **点击级验证**：列出所有带`cursor:pointer`样式的元素，逐一确认点击事件已绑定，点击有反应
4. **API级验证**：列出所有fetch/axios/window.api调用，逐一确认URL/方法/参数与旧代码一致，调用有结果
5. **数据级验证**：列出所有state字段，逐一确认数据来源和初始化逻辑与旧代码一致，数据有值
6. **样式级验证**：列出所有CSS类，逐一确认样式定义存在且生效，视觉与旧代码一致
7. **路由级验证**：列出所有页面跳转，逐一确认目标路由存在且可访问，跳转有结果

验证结果必须记录到《迁移完整性报告》，每项标记✅/❌，❌项必须立即整改。

---

**九、迁移完整性报告制度**

每个模块迁移完成后，责任人必须生成《迁移完整性报告》，包含以下9个部分：

1. **旧代码功能清单**：方法名+行数+功能描述+事件绑定+API调用
2. **新代码功能清单**：方法名+行数+功能描述+事件绑定+API调用
3. **已迁移对照表**：旧方法→新方法，一一对应，标记迁移状态
4. **缺失功能清单**：未迁移的功能，必须说明原因（替代方案/已废弃/待迁移）
5. **替代方案说明**：不直接迁移的功能，必须说明替代实现、功能等价性、审批人
6. **神经末梢验证结果**：7类神经末梢逐项验证结果，附截图证据
7. **API调用对照表**：旧API→新API，URL/方法/参数逐一对照
8. **数据结构对照表**：旧字段→新字段，类型/默认值/格式逐一对照
9. **浏览器测试证据**：至少5张截图（初始状态/加载中/交互后/错误处理/数据完整）

报告存放位置：`docs/迁移报告/<模块名>_迁移完整性报告.md`
报告必须有迁移责任人、互检专家、验收专家三方签字。

---

**十、违规处罚（宪法级强制执行）**

| 违规行为 | 处罚等级 | 说明 |
|---------|---------|------|
| 迁移后bindEvents方法为空 | 2次严重违规 | 等于功能完全阉割，用户看到的全是死按钮 |
| 存在点击无反应的死按钮 | 2次严重违规 | 神经末梢验证遗漏，用户直接感知 |
| 缺失核心功能未说明替代方案 | 1次严重违规 | 功能阉割且无交代 |
| 未走五步法直接迁移 | 1次严重违规 | 方法论违规，必然导致遗漏 |
| 未生成迁移完整性报告 | 1次严重违规 | 无文档=没做验证 |
| 未经过独立验收 | 1次严重违规 | 自说自话，质量无保障 |
| 替代方案未审批直接实施 | 1次严重违规 | 静默替换，功能可能阉割 |
| 数据迁移遗漏字段 | 1次严重违规 | 数据丢失，用户感知 |
| 未更新需求登记系统 | 1次警告 | 流程不规范 |
| 神经末梢验证不完整 | 1次警告 | 验证流于形式 |
| 3次严重违规 | 责任人更换 | 该模块重新迁移，原责任人不得再参与此模块 |
| 5次严重违规 | 专家团重组 | 重新制定工作流程，所有已迁移模块重新验收 |

---

**十一、与25.7的关系**

- 25.7（同步修改铁律）管的是**修改时的联动**，确保改一个地方全链路同步
- 25.8（迁移质量保证体系）管的是**迁移时的完整性**，确保从旧架构到新架构零遗漏
- 两者互补：迁移时用25.8验证完整性，迁移后修改用25.7保证同步
- 优先级：两者同等重要，都是宪法级最高标准，违反任何一条都按违规处罚
- 执行顺序：先25.8（迁移完成+验收通过），再25.7（后续修改保持同步）

---

**十二、当前迁移状态快照（2026-09-11）**

| 状态 | 模块数量 | 模块列表 | 整改要求 |
|------|---------|---------|---------|
| ✅ 功能完整 | 16 | file-library, video, flashcard, question-practice, mock-exam, wrong-book, mindmap, note, dashboard, analytics, knowledge, material, photo-solve, settings, question-manager, layout | 持续维护，后续修改遵守25.7 |
| ❌ bindEvents为空 | 3 | collect, memory, sprint | **立即整改**，走五步法补全事件绑定，完成后三级验收 |
| ⚪ 纯展示 | 2 | system-admin, statusbar | 确认无交互需求，登记为纯展示模块 |
| ⚠️ 缺失边缘功能 | 1 | file-library（缺预览/单文件识别/单文件导图等8项） | 按P0/P1/P2优先级逐步补全，每项走替代方案审批 |

**整改时间表**：
- collect/memory/sprint三个模块：必须在下次迭代前完成bindEvents补全+三级验收
- file-library缺失的8项边缘功能：P0项（7项）立即修复，P1/P2项按计划推进
- 所有已迁移模块：必须补生成《迁移完整性报告》，缺失的限期补齐




### 25.9 数据质量保障算法体系（源头治理铁律，2026-09-11入宪）

**立法背景**：用户一次性反馈29个题库质量问题（缺选项、缺解析、答案不匹配、广告杂质、年份错误、题目重复、格式混乱等），暴露出数据治理的根本问题：没有从源头上建立质量保障算法，而是等用户发现问题后一个个手动修复。本体系确立"算法优先、源头治理、自动检测、自动修复"的核心原则，用算法代替人工，从数据导入、识别、存储全流程防止质量问题。

**核心原则**：
1. **算法优先于人工**：能用算法自动检测和修复的，绝不靠人工一个个处理
2. **源头治理优于事后清理**：在数据导入和识别阶段就拦截问题，而不是等进了数据库再清理
3. **全流程覆盖**：导入→识别→存储→展示，每个环节都有质量检测点
4. **自动修复为主**：检测到问题后优先自动修复，无法自动修复的才标记人工处理
5. **持续监控**：建立定期质量巡检机制，防止新问题累积

**一、七大质量检测算法**

| 算法名称 | 检测内容 | 自动修复能力 | 工具位置 |
|---------|---------|-------------|---------|
| 选项完整性检测 | 缺选项、选项数错误、答案超出选项范围 | ✅ 自动同步options字段 | tools/data_quality_guard.py |
| 解析质量检测 | 缺解析、解析过短、解析含广告 | ✅ 自动清理广告杂质 | tools/data_quality_guard.py |
| 答案一致性检测 | 缺答案、答案格式错误、单选/多选答案长度错误 | ⚠️ 标记待人工 | tools/data_quality_guard.py |
| 重复题目检测 | 标题精确匹配、内容哈希匹配 | ⚠️ 标记待人工去重 | tools/data_quality_guard.py |
| 年份标签检测 | 缺年份、年份格式错误 | ✅ 从标题自动提取年份 | tools/data_quality_guard.py |
| 图片引用检测 | 题目引用图片但无图片 | ⚠️ 标记待补图 | tools/data_quality_guard.py |
| 格式标准化 | 多余空格、多余换行、特殊字符 | ✅ 自动标准化 | tools/data_quality_guard.py |

**二、数据导入阶段质量门禁**

所有数据导入（文件识别、批量导入、API同步）必须经过以下质量门禁，不通过不得入库：

1. **选项门禁**：每个题目必须有至少2个选项，单选题必须4个选项
2. **答案门禁**：每个题目必须有答案，答案必须在选项范围内
3. **解析门禁**：每个题目必须有解析，解析不得少于10个字
4. **广告门禁**：解析中不得包含广告关键词（VIP课程、精准押题、学员专用等）
5. **格式门禁**：标题和解析必须经过格式标准化处理
6. **去重门禁**：导入前必须检查重复，重复题目不得重复入库

**三、数据识别阶段质量增强**

AI识别题目时必须执行以下质量增强算法：

1. **选项分割算法**：智能识别A/B/C/D/E选项边界，防止选项混在一行
2. **答案提取算法**：从解析中智能提取正确答案，防止答案与解析不匹配
3. **广告过滤算法**：实时过滤识别结果中的广告、水印、页眉页脚
4. **年份识别算法**：从题目上下文智能识别年份标签
5. **题型判断算法**：根据选项数量和答案长度智能判断题型（单选/多选/案例）
6. **图片关联算法**：识别题目中的图片引用，自动关联图片资源

**四、全场景文件识别质量门禁（源头治理核心，2026-09-11落地）**

**所有文件识别和数据导入入口必须接入质量门禁**，不只是题目。通用质量门禁框架（`backend/utils/quality_gate_framework.py`）支持6大数据类型，每种类型有专门的质量管道：

| 数据类型 | 质量管道 | 接入入口 | 接入状态 |
|---------|---------|---------|---------|
| 题目 | DataQualityPipeline | Excel/CSV导入、AI识别导入 | ✅ 已接入 |
| 闪卡 | FlashcardQualityPipeline | 批量导入、文本解析导入 | ✅ 已接入 |
| 思维导图 | MindmapQualityPipeline | PDF生成、AI生成、上传生成 | ⚠️ 框架就绪，保存逻辑接入中 |
| 知识点 | KnowledgePointQualityPipeline | AI提取、批量导入 | ⚠️ 框架就绪 |
| 资料 | MaterialQualityPipeline | 资料上传、批量上传 | ⚠️ 框架就绪 |
| 讲义 | MaterialQualityPipeline | 讲义上传、导入题目 | ⚠️ 框架就绪 |

**通用质量管道五步流程**（所有数据类型统一执行）：
1. **清洗**：去除广告、杂质、无用文本（12种广告正则，全类型通用）
2. **校验**：检查各类型必填字段完整性、内容质量
3. **标准化**：统一格式、标签、命名规范
4. **自动修复**：尽可能自动修复可修复的问题
5. **质量门禁**：CRITICAL问题 → 拒绝入库

**各类型质量门禁标准**：

| 类型 | CRITICAL（拒绝入库） | WARNING（警告但可入库） |
|------|---------------------|------------------------|
| 题目 | 无选项、无答案、答案超范围 | 缺解析、缺年份、选项数错误 |
| 闪卡 | 正面为空 | 背面为空、标签缺失 |
| 思维导图 | 标题为空 | 内容为空 |
| 知识点 | 名称为空 | 内容为空 |
| 资料/讲义 | -（不强制拒绝） | 标题为空、文件路径为空 |

**核心原则**：
1. **全场景覆盖**：所有文件识别入口都要有质量门禁，不只是题目
2. **宁可拒绝入库，不可让脏数据进入数据库**
3. **事后清理是治标，源头门禁才是治本**
4. **持续迭代**：广告关键词库、校验规则、修复算法持续优化

**五、定期质量巡检机制**

- **每日巡检**：凌晨自动运行data_quality_guard.py，生成质量报告
- **每周汇总**：每周生成数据质量趋势报告，跟踪问题变化
- **每月审计**：每月进行一次全面数据质量审计，输出审计报告
- **预警阈值**：CRITICAL问题>10个或WARNING问题>100个时自动预警

**六、质量问题分级处理**

| 级别 | 定义 | 处理方式 | 处理时限 |
|------|------|---------|---------|
| CRITICAL | 缺选项、缺答案、答案超出范围 | 自动修复+人工复核 | 24小时内 |
| WARNING | 缺解析、年份错误、题目重复 | 自动修复或标记人工 | 7天内 |
| INFO | 解析过短、格式不规范 | 自动标准化 | 30天内 |

**六、首次运行成果（2026-09-11）**

- 检测题目：1902题
- 发现问题：2415个
- 自动修复：2199个（修复率91%）
- 具体修复：
  - 选项字段同步：1779题
  - 广告杂质清理：1779题
  - 年份自动提取：420题
  - 格式标准化：848题
- 剩余待人工处理：
  - 缺解析：548题
  - 缺年份：917题
  - 标题重复：204组
  - 缺选项：101题
  - 答案格式错误：52题

**八、与25.8的关系**

- 25.8（迁移质量保证体系）管的是**代码迁移**的完整性
- 25.9（数据质量保障体系）管的是**数据质量**的源头治理
- 两者互补：代码迁移保证功能完整，数据质量保证内容正确
- 都是宪法级最高标准，违反任何一条都按违规处罚

### 25.10 设计决策记录机制（防反复修改铁律，2026-09-11入宪）

**问题**：需求在模块化时已设计好，但因没有完整记录，导致反复修改同一功能，浪费时间，用户体验差。

**规则**：

1. **所有设计决策必须登记**：任何布局、功能、交互、样式的确定，必须立即记录到 `docs/设计决策记录.md`
2. **修改前必须查记录**：任何模块修改前，必须先查看设计决策记录，确认该设计是否已锁定
3. **已锁定设计禁止擅自修改**：用户确认过的布局/功能，标记为"已锁定"，禁止反复修改
4. **修改已锁定设计必须先征求同意**：如确需修改已锁定设计，必须先向用户说明原因并取得同意
5. **修改后立即更新记录**：任何设计变更后，必须立即更新设计决策记录，保持记录与实际一致
6. **记录文件具有宪法级约束力**：`docs/设计决策记录.md` 是本宪法的补充文件，具有同等约束力

**设计决策记录内容包括**：
- 模块布局结构（Tab、分栏、比例）
- 功能保留/移除决策及原因
- 标签体系定义
- 交互方式确定
- 修改历史追溯

**违反处罚**：
- 未查记录就修改已锁定设计：记一次违规
- 修改后未更新记录：记一次违规
- 反复修改同一功能3次以上：严重违规，必须复盘

### 25.10.5 以模块化为基础的核心工作原则（最高指导原则，2026-09-11入宪）

**核心思想**：所有修改、完善、优化工作都必须以模块化时的设计为基础，禁止重新设计或重新发明轮子。

**一、工作流程铁律**

1. **先读模块化代码**：任何模块修改前，必须先读取模块化时的原始代码（backup_modular目录），理解设计意图
2. **先对比再修改**：对比当前代码与模块化代码的差异，确定哪些是已实现的功能，哪些是缺失的
3. **先迁移再优化**：优先把模块化时已实现的功能迁移过来，再在这个基础上优化
4. **禁止重新设计**：布局、功能、交互方式都遵循模块化时的设计，禁止凭感觉重新设计
5. **禁止阉割功能**：优化时不能删除模块化时已有的功能，只能增强或完善

**二、模块化设计的权威性**

- 模块化时的设计是经过用户确认的，具有最高权威性
- 任何与模块化设计冲突的修改，必须先取得用户同意
- 模块化时的布局、Tab结构、功能清单是"锁死"的，禁止擅自修改
- 新功能必须在模块化设计的框架内添加，不能破坏原有结构

**三、功能迁移清单**

每个模块必须建立功能迁移清单：
- ✅ 已迁移：模块化时已有，当前代码已实现
- ⚠️ 部分迁移：模块化时已有，当前代码只实现了部分
- ❌ 未迁移：模块化时已有，当前代码完全缺失
- ➕ 新增：模块化时没有，当前代码新增的功能

修改前必须检查功能迁移清单，确保不遗漏任何功能。

**四、代码借鉴铁则（2026-09-11补充，最高优先级）**

1. **必须直接借鉴旧版代码**：功能迁移时，必须直接读取旧版（app_v3或模块化备份）的对应函数实现，理解其完整逻辑后再迁移，禁止凭印象或简化逻辑重新实现
2. **禁止重新造车轮**：旧版已实现并验证过的功能（如播放器控制栏、进度条拖拽、音量滑块等），必须完整迁移，不能只实现部分功能或用简化版本替代
3. **先复制再适配**：迁移流程是"先完整复制旧版实现 → 再适配模块化架构（去掉callTracker/commonModule等旧版特有逻辑）→ 最后测试验证"，禁止跳过复制步骤直接重写
4. **功能完整性检查**：迁移后必须逐项对比旧版功能清单，确保所有子功能（如进度条的鼠标拖拽+触摸支持、音量的滑块+静音按钮等）都已迁移
5. **违规后果**：因重新造车轮导致功能缺失或简化的，视为严重违规，必须回退并按旧版完整实现重新迁移

**四、违反处罚**

- 未读模块化代码就修改：记一次违规
- 重新设计模块化已有的布局/功能：严重违规，必须恢复
- 阉割模块化已有的功能：严重违规，必须恢复
- 未建立功能迁移清单：记一次违规

---

### 25.11 布局保护与功能保留机制（防误改铁律，2026-09-11入宪）

**问题**：改功能时误改布局，锁死的布局被大范围替换，导致反复修改。

**核心原则**：
- **布局与功能分离**：布局（HTML结构/CSS样式）与功能（JS逻辑/事件绑定）必须分离
- **改功能不改布局**：修改功能时，只改JS逻辑，不动HTML结构和CSS样式
- **改布局必须审批**：修改已锁定布局，必须先对比分析并取得用户同意

**一、修改前对比分析流程（必须执行）**

任何模块修改前，必须执行以下步骤：

1. **读取原始文件**：读取当前模块的完整代码
2. **识别布局部分**：标记HTML结构（render方法中的模板字符串）和CSS样式（_getCSS方法）
3. **识别功能部分**：标记JS逻辑（事件绑定、数据处理、API调用）
4. **对比设计决策记录**：确认哪些布局已锁定，哪些功能可修改
5. **确定修改范围**：只标记需要修改的功能部分，布局部分标记为"保护"
6. **输出修改计划**：明确列出将修改哪些函数、哪些行，不修改哪些部分

**二、布局保护机制**

**布局修改汇报制度（2026-09-11补充，最高优先级）**：
- 布局全局锁死，所有功能修改只改逻辑，不动布局
- 如确实需要修改布局（包括比例、位置、结构、样式），必须先向用户汇报，说明修改原因、影响范围和预期效果
- 取得用户明确同意后，才能进行布局修改
- 未经同意擅自修改布局的，视为严重违规，必须立即回退
- 布局修改后必须重新验证所有相关功能，确保无破坏

1. **布局锁标记**：在代码中用注释标记锁死的布局部分：
   ```javascript
   // === LAYOUT_LOCK_START: 视频播放页布局（已锁定，禁止修改）===
   // 上部分：左右平分（视频+智慧笔记）
   // 下部分：拉通播放列表
   // === LAYOUT_LOCK_END ===
   ```

2. **修改时跳过保护区域**：使用精确的小范围替换，只替换功能部分，不触碰布局部分

3. **禁止大范围替换**：禁止使用整个render方法或整个_getCSS方法的替换，必须精确到具体的行或函数

**三、功能保留机制**

1. **功能清单登记**：每个模块必须登记功能清单，包括：
   - 必须保留的功能（如：视频播放、笔记保存、列表点击）
   - 可修改的功能（如：数据加载方式、API调用）
   - 已移除的功能及原因

2. **修改后功能验证**：修改完成后，必须验证功能清单中的所有功能是否正常：
   - 检查事件绑定是否完整
   - 检查API调用是否正确
   - 检查UI交互是否正常

**四、修改后布局验证流程（必须执行）**

修改完成后，必须执行以下验证：

1. **代码对比**：对比修改前后的HTML结构和CSS样式，确认布局未被改变
2. **浏览器验证**：在浏览器中打开页面，截图对比布局
3. **功能测试**：测试所有功能是否正常
4. **记录更新**：如果布局确实需要改变，必须更新设计决策记录

**五、违反处罚**

- 未执行修改前对比分析：记一次违规
- 修改功能时误改布局：严重违规，必须立即恢复
- 未执行修改后布局验证：记一次违规
- 大范围替换导致布局丢失：严重违规，必须复盘

**六、工具支持**

- `tools/layout_guard.py`：布局保护检查工具，自动检测布局是否被改变
- `tools/feature_checklist.py`：功能清单验证工具，自动检查功能是否完整
- `tools/css_conflict_detector.py`：CSS冲突检测工具，自动检测重复CSS定义和属性覆盖
- `tools/css_merger.py`：CSS合并替代工具，对比重复定义后用新样式替代旧样式，保持唯一性
- 修改前必须运行布局保护和功能清单工具，确认修改范围
- 修改后必须运行CSS冲突检测工具，确认无重复定义或覆盖
- 发现重复CSS定义时，必须用css_merger.py合并替代，而不是简单删除或添加

**七、CSS修改铁律**

1. **禁止只增不删**：修改CSS时，必须找到旧定义的位置，用新样式替代，而不是添加新样式
2. **禁止新旧共存**：同一个CSS类只能有一个定义，禁止新旧样式共存
3. **后定义覆盖前定义**：CSS中后面的定义会覆盖前面的，必须确保只有一个定义
4. **修改后必检**：修改CSS后必须运行css_conflict_detector.py确认无重复
5. **重复必合并**：发现重复定义时，用css_merger.py合并，保留最新的定义

---



## 第二十六章 关键缺失机制（五大补充）

### 26.1 数据自动备份+软删除机制
**问题**：误删题库/闪卡/导图后无法恢复，复习数据永久丢失。

**规则**：
1. 所有删除操作必须是软删除（is_deleted=1），禁止物理删除
2. 软删除数据保留30天，30天后自动清理
3. 必须提供"回收站"功能，可查看和恢复已删除数据
4. 数据库每天自动备份一次，保留最近7天备份
5. 批量删除前必须二次确认，显示将删除的数量
6. 核心数据表（questions/flash_cards/mind_maps/knowledge_points）修改前自动备份到backup_records表

### 26.2 AI失败降级机制
**问题**：Ollama没启动或API超时，AI功能全挂，影响正常复习。

**规则**：
1. AI调用必须有超时控制（默认10秒），超时自动降级
2. AI不可用时显示"AI服务暂不可用，使用本地数据"，不能白屏或报错
3. 核心功能（刷题/闪卡/导图）不依赖AI，AI只是增强
4. AI识别失败时，必须保留原始数据，允许手动编辑
5. 定期检查AI服务状态，在设置页显示"AI服务：正常/离线"
6. 离线模式下，所有AI功能自动切换为本地缓存数据

### 26.3 操作撤销机制
**问题**：误删/误改无法回退，用户操作有心理负担。

**规则**：
1. 删除操作后显示Toast提示"已删除，点击撤销"，5秒内可撤销
2. 批量操作（批量删除/批量导入）必须支持撤销
3. 重要修改（题库编辑/闪卡编辑）支持Ctrl+Z撤销
4. 撤销操作必须恢复到修改前的精确状态，不能有数据丢失
5. 撤销历史保留最近10次操作

### 26.4 加载/空/错误三态统一机制
**问题**：每个页面loading样式不一样，空状态空白，错误状态只显示"错误"，体验差。

**规则**：
1. 所有列表页必须实现三态：
   - **加载态**：统一骨架屏（灰色占位块），禁止只显示"加载中..."
   - **空态**：显示图标+说明文字+引导操作按钮，禁止空白
   - **错误态**：显示错误原因+重试按钮，禁止只显示"错误"
2. 三态样式全局统一，使用统一组件，禁止每个页面自己发明
3. 加载超过3秒显示"加载较慢，请稍候..."
4. 加载超过10秒显示超时提示+重试按钮

### 26.5 日志轮转机制
**问题**：日志文件无限增长，最终占满磁盘，系统崩溃。

**规则**：
1. 所有日志文件必须有大小限制（单个文件最大10MB）
2. 超过大小自动轮转，保留最近5个日志文件
3. 超过30天的日志自动删除
4. 日志分级：DEBUG/INFO/WARN/ERROR，生产环境只记录WARN及以上
5. 数据库操作日志（operation_logs表）超过10000条自动清理最早的记录
6. 每月1号自动清理过期日志和临时文件

### 26.6 机制执行优先级
以上机制按以下优先级执行：
1. 🔴 P0：数据自动备份+软删除（防止数据丢失）
2. 🔴 P0：AI失败降级（保证核心功能可用）
3. 🟡 P1：操作撤销（用户体验）
4. 🟡 P1：三态统一（用户体验）
5. 🟢 P2：日志轮转（运维优化）


## 第二十七章 深层机制（学习科学+数据治理+AI质量）

### 27.1 知识点掌握度可信度评估机制
**问题**：做对一次就算"已掌握"，实际过几天就忘，导致"假掌握"。

**规则**：
1. 知识点掌握度必须综合计算：答题正确率×答题次数×时间衰减×题目难度
2. 掌握度分级：
   - 0-20%：未学习
   - 20-50%：学习中
   - 50-80%：初步掌握
   - 80-95%：基本掌握
   - 95%+：完全掌握
3. 必须满足以下条件才算"完全掌握"：
   - 连续答对3次以上
   - 间隔7天后再次答对
   - 不同题型（单选/多选/案例）都答对
   - 题目难度覆盖易/中/难
4. 掌握度每天自动衰减（艾宾浩斯遗忘曲线），需要定期复习维持
5. 学习看板显示的是"可信掌握度"，不是"做对率"

### 27.2 数据变更审计机制
**问题**：题库/闪卡/知识点被修改后，不知道谁改的、改了什么、为什么改，改错了无法追溯。

**规则**：
1. 所有核心数据（questions/flash_cards/knowledge_points/mind_maps）的修改必须记录审计日志
2. 审计日志包含：操作类型（新增/修改/删除）、操作人、操作时间、修改前内容、修改后内容、修改原因
3. 审计日志保留至少90天，不得删除
4. 提供审计日志查询界面，可按时间/操作人/数据类型筛选
5. 批量修改必须记录批次号，可整批回滚
6. 物理删除（非软删除）必须有超级管理员权限，且记录双重审计

### 27.3 AI知识冲突检测机制
**问题**：AI生成的内容与教材/考纲矛盾，用户学到错误知识，考试失分。

**规则**：
1. AI生成的所有知识点/解析/答案，必须与本地知识库（教材/考纲/真题）进行相似度比对
2. 相似度低于60%的AI输出，标记为"待核实"，不得直接入库
3. AI输出与教材内容矛盾时，自动告警，显示"AI内容与教材不一致，请人工核实"
4. 必须以教材/考纲/官方真题为最高权威，AI只是辅助，AI内容不得覆盖官方内容
5. 建立"AI纠错记录"，用户发现AI错误后反馈，用于优化AI提示词
6. 造价专业内容（定额/规范/政策）必须标注来源和生效日期，AI不得自行编造

### 27.4 学习疲劳检测+休息提醒机制
**问题**：用户连续刷题几小时不休息，学习效率下降，影响记忆效果。

**规则**：
1. 连续学习45分钟自动提醒休息5分钟（番茄钟）
2. 连续学习2小时强制休息15分钟，显示"休息一下，效率更高"
3. 夜间23:00-6:00学习时，提醒"注意休息，明天效率更高"
4. 答题正确率连续下降（连续5题正确率<50%）时，提醒"状态不佳，建议休息或换科目"
5. 休息提醒不可关闭（可延迟5分钟，但不可永久关闭）
6. 学习数据统计时区分"有效学习时间"和"疲劳学习时间"

### 27.5 首屏性能预算机制
**问题**：打开系统等3秒才显示，用户体验差，可能放弃使用。

**规则**：
1. 首屏加载时间必须≤2秒（从输入URL到内容可交互）
2. 首屏加载超过2秒时，显示骨架屏，禁止白屏
3. 首屏加载超过5秒时，显示"加载较慢，正在优化..."
4. 性能预算：
   - HTML/CSS：≤100KB
   - 首屏JS：≤500KB（懒加载其他模块）
   - 首屏API请求：≤3个
   - 图片：首屏图片必须压缩，单张≤200KB
5. 每次发版前必须测试首屏加载时间，超过预算必须优化
6. 大文件（PDF/视频）必须懒加载，不阻塞首屏

### 27.6 机制执行优先级
1. 🔴 P0：AI知识冲突检测（防止学错知识，直接影响考试）
2. 🔴 P0：知识点掌握度可信度（防止假掌握，影响复习效果）
3. 🟡 P1：数据变更审计（数据安全）
4. 🟡 P1：学习疲劳检测（学习效率）
5. 🟡 P1：首屏性能预算（用户体验）


## 第二十八章 造价培训专业机制（五大专项）

### 28.1 造价案例题步骤分机制
**问题**：造价案例分析是按步骤给分，步骤对但最终答案错也能得大部分分。当前系统只判最终答案对错，不符合真实考试评分标准。

**规则**：
1. 案例题必须拆分为多个步骤，每个步骤独立评分
2. 步骤类型：
   - 列式分：公式列对即得分（约30%）
   - 计算过程分：代入数据正确即得分（约40%）
   - 最终答案分：结果正确才得分（约30%）
3. 用户作答时必须分步输入，系统分步评分
4. 评分后显示每步得分情况，以及"步骤对但答案错"的题目
5. 案例题必须支持"部分得分"，不能只有0分或满分
6. 计算题必须展示标准解题过程，包括公式、代入、结果
7. 造价专家必须审核所有案例题的步骤拆分和分值分配

### 28.2 真题命题规律分析机制
**问题**：用户只做真题但不分析命题规律，不知道哪些是高频考点、哪些是必考点、命题趋势是什么。

**规则**：
1. 系统自动分析近5年真题，生成命题规律报告：
   - 高频考点（每年都考）：标记为"必考点"，必须100%掌握
   - 中频考点（2-3年考一次）：标记为"重点"，优先掌握
   - 低频考点（5年考1次）：标记为"了解"，时间充裕再看
   - 新增考点（当年新增）：标记为"热点"，很可能考
2. 每章统计：分值占比、题型分布、考察频率、趋势（上升/下降/稳定）
3. 命题趋势分析：对比近3年，哪些考点分值在上升，哪些在下降
4. 考点预测：基于历史规律，预测今年可能考的考点
5. 学习看板显示"考点掌握热力图"，红色=高频未掌握，绿色=已掌握
6. 造价专家必须每年教材改版后更新命题规律分析

### 28.3 薄弱点精准归因机制
**问题**：错题本只记录错题，不分析错误原因，用户反复犯同样的错误。

**规则**：
1. 每道错题必须归因到具体原因：
   - 知识点未掌握（占比>60%）：回到知识点精讲学习
   - 记忆模糊（占比20%）：加入闪卡强化记忆
   - 粗心大意（占比10%）：标记为"警示题"，做题时提醒
   - 理解偏差（占比10%）：AI解析+教材原文对照
2. 归因方式：用户选择+AI分析结合，AI根据答题历史自动判断
3. 同一知识点连续错3次，自动触发"薄弱点专项训练"
4. 薄弱点排序：按"考试分值×错误次数"加权，优先攻克高分值高频错的知识点
5. 每周生成"薄弱点报告"：本周新增薄弱点、已攻克薄弱点、待攻克薄弱点
6. 薄弱点攻克标准：连续答对3次+间隔7天再次答对（与27.1掌握度标准一致）

### 28.4 学习路径自适应规划机制
**问题**：学习计划一刀切，每个人基础不同、薄弱点不同，应该根据个人情况自适应调整。

**规则**：
1. 首次使用时进行"基础测评"（20题），评估当前水平
2. 根据测评结果生成个性化学习路径：
   - 基础薄弱：从教材精讲开始，按章节顺序学习
   - 有一定基础：从高频考点开始，重点突破
   - 冲刺阶段：从真题+模拟考试开始，查漏补缺
3. 学习路径动态调整：
   - 某知识点掌握度达到80%，自动减少该知识点练习
   - 某知识点连续出错，自动增加该知识点练习和复习频率
   - 模拟考试某章得分低，自动增加该章学习时间
4. 每日学习计划：根据剩余天数+知识点掌握度，自动分配每日学习任务
5. 学习计划必须可调整：用户可手动增加/减少/跳过，但系统记录偏离原因
6. 考前30天自动切换为"冲刺模式"：以真题+模拟考试+薄弱点复习为主

### 28.5 模拟考试真实评分+通过率预测机制
**问题**：模拟考试只显示分数，不知道在真实考试中能不能通过，通过率多少。

**规则**：
1. 模拟考试评分必须与真实考试一致：
   - 单选题：每题1分，多选/案例每题2分
   - 多选题：少选得0.5分，错选不得分
   - 案例题：按步骤给分（与28.1一致）
2. 评分后生成"考试分析报告"：
   - 总分及各章得分
   - 与历年通过分数线对比（一造管理合格线60%）
   - 薄弱章节排名
   - 做题时间分配分析（是否某章用时过长）
3. 通过率预测：
   - 基于近5次模拟考试分数趋势
   - 基于知识点掌握度
   - 基于历年真题正确率
   - 输出："当前水平通过率约XX%"
4. 模拟考试必须有时间限制，到点自动交卷，模拟真实考试压力
5. 考试后提供"错题重做"功能，只做错题，直到全部掌握
6. 造价专家必须审核模拟考试的难度系数，确保与真实考试难度匹配

### 28.6 机制执行优先级
1. 🔴 P0：薄弱点精准归因（直接影响复习效率）
2. 🔴 P0：真题命题规律分析（知道考什么比多做题更重要）
3. 🟡 P1：案例题步骤分（案例是造价考试核心）
4. 🟡 P1：学习路径自适应规划（提高学习效率）
5. 🟡 P1：模拟考试真实评分+预测（考前必备）


## 第二十九章 系统长期健康机制（五大根本）

### 29.1 技术债务管理机制
**问题**：为了快速上线，经常写"临时方案""先这样以后再改"，技术债务越积越多，最终代码无法维护，改一个坏一片。

**规则**：
1. 所有"临时方案""TODO""以后再优化"必须记录到技术债务清单，包含：位置、原因、建议方案、优先级
2. 技术债务分级：
   - 🔴 高危：可能导致数据丢失/系统崩溃，必须1周内偿还
   - 🟡 中危：影响维护效率，必须1个月内偿还
   - 🟢 低危：代码不优雅，可在重构时统一处理
3. 每完成一个功能，必须偿还至少1个技术债务，不能只借不还
4. 技术债务超过20条时，暂停新功能开发，集中偿还
5. 每月生成技术债务报告：新增多少、偿还多少、剩余多少、趋势
6. 禁止以"以后再改"为借口写低质量代码，必须在注释中标注TODO和预计偿还时间

### 29.2 专家经验沉淀机制
**问题**：每次解决问题后不记录，下次遇到类似问题重复踩坑，专家经验随对话流失。

**规则**：
1. 每次解决一个非平凡问题（超过30分钟/修改超过3个文件/用户反馈3次以上），必须沉淀为经验文档
2. 经验文档包含：问题描述、根本原因、解决过程、最终方案、教训、类似问题预防
3. 经验文档统一存放在`规划细则分册/专家经验库/`，按领域分类（前端/后端/数据/AI/布局）
4. 遇到类似问题时，必须先查经验库，不能从零开始分析
5. 每周整理一次经验库，去重、分类、更新
6. 走偏案例库（24.4）是经验库的子集，专门记录集体走偏的教训

### 29.3 版本发布门禁机制
**问题**：改完代码就上线，没有检查清单，用户当小白鼠，带bug上线影响复习。

**规则**：
1. 任何代码修改上线前必须通过"发布门禁"检查：
   - ✅ 核心功能冒烟测试通过（登录/刷题/闪卡/导图）
   - ✅ 数据质量巡检无严重问题
   - ✅ 执行保障验证通过（括号匹配/文件大小/核心函数存在）
   - ✅ app.js与app_v3同步一致
   - ✅ 浏览器实际验证通过（截图为证）
   - ✅ 无console.error（除已知的第三方错误）
2. 门禁不通过不得上线，必须修复后重新检查
3. 重大修改（涉及核心数据/全局布局）必须用户确认后才能上线
4. 上线后30分钟内必须监控：错误率、API失败率、页面加载时间
5. 上线后发现严重bug，立即回滚到上一个稳定版本，不得在线热修
6. 每次发布必须记录版本号、修改内容、验证结果、发布时间

### 29.4 多端数据同步冲突解决机制
**问题**：用户同时在手机和电脑上使用，数据互相覆盖，学习记录丢失。

**规则**：
1. 所有数据同步必须基于"最后修改时间"（LWW），后修改的覆盖先修改的
2. 同一记录两端同时修改时，自动合并：
   - 数值型（学习次数、掌握度）：取最大值
   - 文本型（笔记、解析）：保留两端，标记为"冲突待合并"
   - 状态型（已完成/未完成）：取"已完成"
3. 冲突数据必须显示给用户，由用户决定保留哪个，不能静默覆盖
4. 离线模式下的修改，联网后自动同步，同步前必须检查是否有冲突
5. 同步失败时必须重试3次，仍失败则显示"同步失败，请检查网络"，本地数据保留
6. 每台设备有唯一device_id，同步记录来源设备，可追溯

### 29.5 决策记录机制
**问题**：为什么做这个决策？当时考虑了什么？以后重复讨论，方向摇摆，浪费时间。

**规则**：
1. 所有重大决策（架构变更/功能取舍/技术选型/规范制定）必须记录决策日志
2. 决策日志包含：决策内容、背景、可选方案、选择理由、反对意见、决策时间、决策人
3. 决策日志存放在`规划细则分册/决策记录.md`，按时间倒序
4. 已决策的事项不得随意推翻，如需变更必须说明理由并重新决策
5. 宪法修改属于重大决策，必须记录修改原因和修改内容
6. 每季度回顾一次决策记录，评估决策效果，错误决策要标注并说明原因

### 29.6 宪法体系说明
本宪法共29章，覆盖系统设计全维度：
- 第1-21章：基础架构与功能规范
- 第22章：全局锁死规则
- 第23章：有规范必执行铁律
- 第24章：专家纠偏机制（防集体走偏）
- 第25章：系统性问题预防（5大机制）
- 第26章：关键缺失补充（5大机制）
- 第27章：深层机制（学习科学+数据治理+AI质量）
- 第28章：造价培训专业机制（5大专项）
- 第29章：系统长期健康机制（5大根本）

**宪法体系已完整，后续新增机制必须先评估是否与现有机制重复，避免机制膨胀。**


## 第三十章 执行保障机制（确保宪法不变成废纸）

### 30.1 修改前检查清单强制机制
**问题**：宪法写了40+机制，但专家修改代码时想不起来用，宪法变废纸。

**规则**：
1. 任何代码修改前，必须过以下检查清单（全部✅才能开始修改）：
   - [ ] 是否搜索了已有资产？（25.2）
   - [ ] 是否复述确认了需求？（25.4）
   - [ ] 是否分析了修改影响范围？（M7工具）
   - [ ] 是否备份了当前版本？（execution_guard.py）
   - [ ] 是否检查了CSS类默认样式？（23.7）
   - [ ] 是否提出了至少2个方案？（24.3）
   - [ ] 是否从反面论证了方案风险？（24.3）
2. 检查清单必须在修改前输出到对话中，用户可见
3. 任何一项未通过，不得开始修改
4. 简单修改（改个文字/颜色）可简化为3项：已有资产搜索+备份+CSS类检查
5. 复杂修改（涉及核心数据/全局布局）必须完整执行7项

### 30.2 机制执行审计机制
**问题**：不知道哪些机制被执行了，哪些没有，机制形同虚设。

**规则**：
1. 每周生成"机制执行审计报告"，包含：
   - 本周执行了哪些机制
   - 哪些机制应该执行但没执行
   - 未执行的原因
   - 机制执行率（目标≥80%）
2. 审计报告存放在`规划细则分册/机制执行审计/`目录
3. 连续2周执行率<60%的机制，必须分析原因：是机制不合理还是专家不执行
   - 机制不合理：优化或淘汰
   - 专家不执行：加强问责（30.5）
4. 高优先级机制（P0）执行率必须100%，不得有例外
5. 审计结果作为专家绩效考核依据

### 30.3 机制效果评估+淘汰机制
**问题**：执行了但没效果的机制一直保留，浪费时间，机制越来越臃肿。

**规则**：
1. 每个机制执行后必须评估效果，用数据说话：
   - 布局规范机制：布局问题数量是否下降？
   - 数据质量巡检：数据问题是否减少？
   - 冒烟测试：核心功能bug是否减少？
   - 走偏预警：集体走偏次数是否减少？
2. 每月评估一次，效果分为：
   - ✅ 有效：问题明显减少，继续执行
   - ⚠️ 部分有效：需要优化
   - ❌ 无效：问题没有改善，淘汰或重构
3. 连续2个月评估为"无效"的机制，必须淘汰或重构
4. 淘汰机制必须记录原因，避免以后重复建立无效机制
5. 机制总数控制在50个以内，新增必须淘汰旧的（有进有出）

### 30.4 机制优先级动态调整机制
**问题**：40+机制，不知道当前阶段先执行哪个，眉毛胡子一把抓。

**规则**：
1. 机制优先级不是固定的，根据当前阶段动态调整：
   - **考试前1个月**：核心功能稳定>数据质量>学习效率>其他
   - **考试后**：架构优化>新功能>性能>其他
   - **系统不稳定时**：bug修复>稳定性>其他一切
   - **新功能开发时**：需求确认>架构设计>编码>测试
2. 每阶段开始时，明确本阶段Top5优先执行的机制
3. 非优先机制可以暂缓，但不得违反（如锁死规则任何时候都不能违反）
4. 优先级调整必须记录原因（29.5决策记录）
5. 当前阶段（考前冲刺）Top5机制：
   - ① 修改前检查清单（30.1）
   - ② 版本发布门禁（29.3）
   - ③ 数据自动备份（26.1）
   - ④ AI失败降级（26.2）
   - ⑤ 薄弱点精准归因（28.3）

### 30.5 机制执行问责机制
**问题**：违反机制没后果，专家不把机制当回事，随意违反。

**规则**：
1. 违反机制的后果分级：
   - **轻度违反**（忘记检查清单/未备份）：口头提醒，记录在案
   - **中度违反**（未验证就上线/治标不治本）：必须返工，本次修改无效
   - **重度违反**（修改锁死模块/导致数据丢失/集体走偏3次以上）：暂停决策权，由其他专家接管
2. 违反记录存入`规划细则分册/机制违反记录.json`
3. 同一专家连续3次违反同一机制，必须重新学习该机制并通过测试
4. 违反机制导致用户数据丢失或系统崩溃的，必须立即回滚并公开道歉
5. 机制不是用来约束用户的，是用来约束专家的，专家必须以身作则

### 30.6 执行保障总结
宪法30章，机制40+，但核心只有一句话：
**"写了就要执行，执行了就要有效，无效就要淘汰，违反就要问责。"**

所有机制的最终目的只有一个：**保障系统稳定、数据准确、用户复习高效。**


## 第三十一章 需求收集校核机制

### 31.1 铁律声明
所有用户需求必须经过"收集→校核→分解→执行→验证"五步闭环，禁止"用户提一个专家加一个"、禁止理解偏差、禁止做了但没满足原始需求。

### 31.2 需求五步闭环
1. **收集**：用户每次提的需求必须记录到需求管理清单，包含原始描述、优先级、截图、上下文
2. **校核**：专家必须复述理解，用户确认正确后才能执行，禁止凭印象执行
3. **分解**：大需求分解为可执行的子任务，每个子任务有明确的完成标准
4. **执行**：按优先级执行，P0优先，执行过程中必须遵守修改前检查清单（30.1）
5. **验证**：完成后必须对照原始需求验证，提供实际证据，不能只说"已完成"

### 31.3 需求状态流转
```
待校核 → 待确认 → 待处理 → 进行中 → 已完成 → 已验证
  ↓         ↓         ↓         ↓         ↓
理解错   确认错   取消    阻塞    验证不通过→重新进行
```
- 待校核：需求已记录，等待专家复述理解
- 待确认：专家已复述，等待用户确认理解正确
- 待处理：理解已确认，等待执行
- 进行中：正在执行
- 已完成：代码修改完成，等待验证
- 已验证：对照原始需求验证通过，需求闭环

### 31.4 需求优先级
- **P0**：核心功能、影响复习、数据安全、系统崩溃，必须立即处理
- **P1**：重要功能、体验优化、效率提升，优先处理
- **P2**：锦上添花、长期优化，有空再做
- 优先级由专家评估后提出，用户确认，不得自行降级

### 31.5 需求验证标准
需求完成必须满足以下全部条件才能标记为"已验证"：
1. 代码修改完成且已同步（app.js=app_v3）
2. 执行保障验证通过（括号匹配/文件大小/核心函数）
3. 冒烟测试通过（核心功能无回归）
4. 浏览器实际验证通过（截图为证）
5. 对照原始需求，确认每个细节都满足
6. 用户确认满意

### 31.6 需求管理工具
- 工具：`tools/requirement.py`
- 数据：`规划细则分册/需求管理清单.json`
- 命令：
  - `python requirement.py add <描述> [优先级]` - 添加需求
  - `python requirement.py list` - 列出所有需求
  - `python requirement.py understand <id> <理解>` - 专家复述理解
  - `python requirement.py confirm <id>` - 用户确认理解
  - `python requirement.py update <id> <状态>` - 更新状态
  - `python requirement.py verify <id> <证据>` - 完成验证

### 31.7 需求回顾
- 每周回顾一次需求清单：已完成多少、进行中多少、待处理多少
- 已验证的需求定期回顾，确认用户持续满意
- 长期未处理的需求（超过2周）必须评估：是取消、降级、还是立即处理
- 禁止需求无限堆积，待处理需求不得超过20条


## 第三十二章 代码质量与混入检测机制

### 32.1 代码混入零容忍原则
- 修改代码时必须确保新代码完全替换旧代码，禁止新旧逻辑混在一起
- 旧代码作为fallback保留时，必须明确标注 `// fallback: 旧逻辑，新逻辑失败时使用`
- 禁止在同一函数中存在两套功能相同的实现逻辑
- 每次修改后必须运行重复函数检测和重复代码块检测

### 32.2 代码修改前检查清单
1. 搜索目标函数/变量，确认只有一处定义
2. 检查是否有其他地方调用了将要修改的函数
3. 确认修改范围，只改需要改的部分
4. 备份原文件（execution_guard自动完成）

### 32.3 代码修改后验证清单
1. 括号匹配验证（execution_guard自动完成）
2. 重复函数检测：`python tools\code_quality_check.py --duplicate-functions`
3. 重复代码块检测：搜索新增关键词出现次数，确认定义1次+调用N次
4. 核心函数存在性验证
5. app_v3同步验证
6. 浏览器实际效果验证（宪法23.4）

### 32.4 增量修改原则
- 禁止推翻重写整个文件或大段代码
- 每次修改只针对具体需求，不扩展范围
- 修改必须精确到行级，用Python脚本精确替换
- 禁止用PowerShell -replace修改JS文件（中文乱码）
- 新增功能必须独立成函数，不混入现有函数体

### 32.5 代码质量定期检查
- 每周运行一次代码质量检查工具
- 检查项：重复函数、重复代码块、未使用变量、硬编码、console.log残留
- 检查报告存入 `规划细则分册/代码质量报告/`
- 发现问题必须立即修复，不能累积

### 32.6 app.js体积控制
- 当前app.js 1480KB，加载时间3秒，需要优化
- 长期目标：拆分模块，按需加载
- 短期措施：删除未使用代码、压缩注释、合并重复逻辑
- 新增功能优先考虑是否可以复用现有代码，避免重复造轮子

### 32.7 代码审查机制
- 每次修改后，用change_diff.py对比修改前后
- 确认修改范围与需求一致，没有超范围修改
- 确认没有引入新的重复代码
- 确认没有破坏现有功能（冒烟测试验证）


## 第三十三章 专家协同执行机制

### 33.1 机制联动原则
- 所有工具和机制不是孤立的，必须形成协同闭环
- 总控脚本 orchestrator.py 统一调度，避免各自为战
- 每个专家领域的工具必须能被总控调用，输出标准化结果

### 33.2 四阶段协同执行流程

**阶段一：修改前（pre）**
1. impact_analyzer.py 分析影响范围
2. execution_guard.py 自动备份
3. 确认修改范围，不超范围

**阶段二：修改中**
1. 精确替换，防止代码混入（第三十二章）
2. 新增功能独立成函数
3. 不扩展修改范围

**阶段三：修改后（post）**
1. execution_guard.py 括号匹配+核心函数验证
2. code_quality_check.py 代码质量检查（重复函数/重复代码块/硬编码）
3. security_check.py 安全检查
4. smoke_test.py 核心流程冒烟测试
5. full_inspector_v2.py 全面巡查（8大维度）
6. change_diff.py 修改前后对比

**阶段四：发布前（release）**
1. code_quality_check.py 代码质量
2. security_check.py 安全检查
3. performance_monitor.py 性能监控
4. smoke_test.py 冒烟测试
5. backup_restore_test.py 备份恢复演练
6. release_check.py 版本发布检查（26项，0失败才允许发布）

### 33.3 每日巡检（daily）
- full_inspector_v2.py 全面巡查
- data_quality_inspector.py 数据质量巡检
- code_quality_check.py 代码质量
- constitution_audit.py 宪法执行审计

### 33.4 专家分工与协同
- **架构专家**：负责整体架构、模块划分、技术选型
- **造价专家**：负责造价专业内容准确性、题目/闪卡/导图质量复核
- **UI/UX专家**：负责布局规范、视觉一致性、用户体验
- **前端专家**：负责代码质量、性能优化、防混入
- **后端专家**：负责API设计、数据库、安全
- **测试专家**：负责冒烟测试、巡查、发布检查
- **数据专家**：负责数据质量、去重、血缘追踪
- **AI专家**：负责AI功能、OCR识别、智能分析
- **安全专家**：负责安全检查、漏洞修复
- **运维专家**：负责备份、部署、监控

### 33.5 协同执行命令
```bash
# 修改后检查（最常用）
python tools\orchestrator.py post

# 发布前全面检查
python tools\orchestrator.py release

# 每日巡检
python tools\orchestrator.py daily

# 修改前检查
python tools\orchestrator.py pre
```

### 33.6 阻塞机制
- 阻塞性检查（括号匹配、代码质量、冒烟测试、发布检查）失败时，立即停止后续流程
- 非阻塞性检查（安全、性能、巡查）失败时，警告但继续，记录到报告
- 所有检查结果存入 `规划细则分册/协同执行报告/`


## 第三十四章 备份验证与保留标准

### 34.1 备份验证铁律
- 备份必须定期验证，不能只创建不验证
- 验证标准：备份文件可读取、括号匹配、数据库可打开、恢复演练通过
- 验证工具：`python tools\backup_restore_test.py`
- 验证不通过的备份必须立即重新创建

### 34.2 验证频率
- **每次修改后**：execution_guard自动验证备份文件完整性（括号匹配+文件大小）
- **每周一次**：运行完整备份恢复演练，验证所有备份可恢复
- **每次发布前**：release_check.py包含备份检查，必须通过
- **黄金备份创建后**：立即验证，确认包含代码+数据库

### 34.3 备份分级标准
| 级别 | 内容 | 保留期 | 验证频率 |
|------|------|--------|----------|
| 自动备份 | app.js + app_v3 | 30天 | 每次创建时自动验证 |
| 黄金备份 | app.js + app_v3 + index.html + 数据库 | 永久 | 创建后立即验证，每月复检 |
| 部署备份 | 部署前全量备份 | 90天 | 部署时验证 |

### 34.4 备份完整性检查项
1. ✅ 备份文件存在且非空（>1MB）
2. ✅ app.js括号匹配（{=}）
3. ✅ app.js可正常读取（无编码错误）
4. ✅ 数据库文件可正常打开（SQLite）
5. ✅ 数据库表结构完整（核心表存在）
6. ✅ 备份与当前版本差异可追溯

### 34.5 恢复演练标准
- 每月至少一次完整恢复演练（模拟，不实际覆盖）
- 演练内容：从最新备份恢复到临时目录，验证可正常启动
- 演练报告存入 `规划细则分册/备份恢复演练报告/`
- 演练失败必须立即排查原因，重新创建备份

### 34.6 备份清理机制
- 自动备份超过30天自动清理（保留最近10个）
- 黄金备份永久保留，不自动清理
- 清理前必须确认备份已验证通过
- 清理操作必须记录日志

### 34.7 备份位置
- 主备份目录：`backups/execution_guard/`
- 黄金备份目录：`backups/GOLDEN_golden_backup/`
- 部署备份目录：`backups/deploy/`
- 禁止将备份放在系统目录或C盘，必须放在项目目录下

### 34.8 备份触发条件（明确什么情况下必须备份）

**必须备份的操作（触发execution_guard自动备份）：**
1. 修改 `frontend/js/app.js` —— 核心业务代码
2. 修改 `frontend/js/app_v3_*.js` —— 实际运行的JS
3. 修改 `frontend/index.html` —— 页面结构
4. 修改 `frontend/css/style.css` 或 `style.min.css` —— 全局样式
5. 修改数据库表结构（ALTER TABLE、CREATE TABLE）
6. 修改 `backend/main.py` —— 后端核心逻辑
7. 修改 `backend/data/exam_config.json` —— 考试配置
8. 大规模数据操作（批量删除、批量更新题库/闪卡）
9. 任何涉及P0级功能的修改

**不需要备份的操作：**
1. 新增 `tools/` 目录下的工具脚本
2. 修改 `系统设计宪法.md`、`规划细则分册/` 文档
3. 修改 `布局规范/` 下的效果图HTML
4. 新增报告文件（检查报告、分析报告）
5. 纯数据查询操作（不修改数据）
6. 运行检查工具（只读操作）

**黄金备份触发条件（手动创建，含数据库）：**
1. **重大版本发布前**——判定标准（满足任一）：
   - 版本号大版本升级（如V4.x→V5.0）
   - 同时修改≥5个核心模块（题库/闪卡/导图/资料库/看板）
   - 新增≥3个独立功能
   - 用户明确说"发布新版本"
2. **大规模重构前**——判定标准（满足任一）：
   - 单次修改代码≥1000行
   - 涉及≥3个核心模块的架构调整
   - P0-06阶段4-5（全局变量收敛+函数迁移）
   - 用户明确说"重构"
3. **考前稳定版本确认后**——判定标准（全部满足）：
   - 距离考试≤7天
   - 所有P0需求已完成并验证
   - 协同执行总控release阶段全部通过
   - 用户明确确认"这个版本稳定，锁死"
4. **用户明确要求"锁死"某个版本时**——立即执行

### 34.9 备份命名规范
- 格式：`YYYYMMDD_HHMMSS_功能描述`
- 示例：`20260907_204007_键盘快捷键刷题`
- 功能描述用中文，简洁明了，不超过20字
- 禁止用"修改1"、"测试"、"备份"等无意义名称

### 34.10 备份内容标准
- **自动备份**：app.js + app_v3_897262.js（必须）
- **黄金备份**：app.js + app_v3 + index.html + style.css + 数据库（必须）
- 备份后立即验证：文件存在、非空、括号匹配
- 验证失败的备份必须删除并重新创建

### 34.11 备份数量控制
- 自动备份保留最近20个，超过自动清理最旧的
- 黄金备份不超过5个，超过时合并最旧的2个
- 每周一运行备份清理，保持目录整洁
- 清理前必须确认备份已验证通过



## 第三十五章 多端样式严格隔离铁律

### 35.1 铁律声明
手机、平板、电脑三端CSS必须严格隔离，严禁一端样式干扰其他端布局。违反此条视为P0级事故。

### 35.2 隔离原则
1. **媒体查询必须精确限定范围**：
   - 手机端：仅在 width≤768px 生效
   - 平板端：仅在 769px≤width≤1024px 生效
   - 电脑端：仅在 width≥1025px 生效
2. **禁止使用无差别的全局选择器**：如 \* { max-width: 100% !important }\ 会压缩表格布局，必须排除 table/thead/tbody/tr/th/td
3. **三端CSS文件独立**：mobile.css、tablet.css 不得包含影响电脑端的全局样式
4. **修改一端必须验证其他端**：改手机样式后必须在电脑和平板上验证无干扰

### 35.3 表格布局保护
- 表格元素（table/thead/tbody/tr/th/td）不受响应式全局 max-width 限制
- 表格必须使用 table-layout:fixed 保证列宽生效
- 题库管理等数据表格的列宽由内联样式或V2规则精确控制，响应式CSS不得覆盖

### 35.4 验证要求
- 每次CSS修改后，必须在三种宽度（375px手机、810px平板、1920px电脑）下验证
- 发现一端布局错乱，立即回滚相关CSS，不得带病上线
- 布局规范V2.0是电脑端唯一标准，手机/平板样式只能在自身媒体查询范围内调整

### 35.5 违规处理
- 因全局选择器导致多端布局混乱：记P0事故，立即修复
- 未验证三端就上线：记P1事故，补充验证


---

## 第三十九章 代码与数据治理保障机制（铁律）

> **立法背景**：系统规模庞大（3689个内联style、1181条CSS规则、5390张闪卡、1969道题），治理必须有完备保障机制，确保彻底、不遗漏、不回退。

### N.1 进度追踪机制

**治理看板（必须建立）：**
- 实时显示各页面内联style清理进度（已清理/总数）
- 实时显示数据去重进度（闪卡/题库/知识点）
- 自动扫描未治理的函数和页面，生成未完成清单
- 每日更新，专家组成员可见

**完成度量化指标：**
- 内联style清理率 = 已清理数 / 3689
- CSS规则精简率 = (1181 - 当前规则数) / 1181
- 闪卡去重率 = 已合并重复数 / 5390
- 页面布局达标率 = 已对齐效果图页面数 / 总页面数

### N.2 质量验证机制（不可跳过）

**每页治理必须三重验证：**
1. **截图对比**：治理前vs治理后截图，布局必须完全一致
2. **效果图比对**：与V2.0效果图像素级对比，偏差>5px不通过
3. **功能回归**：核心功能（刷题/闪卡/导图/视频）治理后必须跑通

**数据治理必须双重验证：**
1. **造价专家复核**：对照PDF原文，准确率<95%不通过
2. **交叉验证**：数据组完成后，另一组专家独立验证

### N.3 防回退机制（铁律）

**代码混入检查（每次提交前自动运行）：**
- 新增内联style > 5个 → 警告，需说明理由
- 新增硬编码颜色 → 警告，必须改用Token
- 新增硬编码尺寸 → 警告，必须改用Token
- 修改style.css → 警告，应修改V2 CSS
- 不符合规范的代码阻止提交

**布局巡检机器人（每日自动运行）：**
- 自动访问所有页面，截图对比V2.0标准
- 发现布局偏差立即报告，生成修复清单
- 每周生成布局合规报告

**数据质量监控（每周自动运行）：**
- 检查闪卡重复率，超过5%告警
- 检查题库完整性，缺章缺节告警
- 检查知识点覆盖率，低于80%告警

### N.4 专家协同机制

**三组并行，责任到人：**
- 布局重构组：首席UI专家，负责页面布局对齐
- 数据治理组：首席造价专家，负责数据准确性
- 代码治理组：首席架构师，负责代码质量

**交叉验证流程：**
1. 布局组完成页面治理 → 提交测试组验证
2. 数据组完成数据治理 → 提交造价专家复核
3. 代码组完成代码清理 → 提交布局组验证功能不受影响

**每日同步三要素：**
- 进度：今天完成了什么
- 阻塞：遇到什么问题
- 风险：可能影响什么

### N.5 验收标准机制（量化，不达标不进入下一阶段）

**阶段1（核心页面布局）验收标准：**
- 看板/题库/闪卡/思维导图布局与效果图偏差<5px
- 核心页面内联style减少50%以上
- 所有核心功能正常运行

**阶段2（数据治理）验收标准：**
- 闪卡重复率<5%
- 题库年份准确率100%（只有6年）
- 知识点体系覆盖教材全部章节

**阶段3（全面治理）验收标准：**
- 所有页面布局达标率100%
- 内联style总数<100个（仅保留动态计算）
- style.css < 70KB
- 20遍全面测试无问题

### N.6 功能迁移验收标准（2026-09-14新增）

**P0 必须满足（缺一不可）：**
1. 后端API测试通过 — node tools/test_xxx.js 运行无报错
2. 前端语法检查通过 — node -c xxx.js 无语法错误
3. 代码逻辑完整 — 事件绑定、状态更新、渲染都闭环
4. 无"开发中"占位 — 不能有 alert('开发中') 或 showToast('开发中')

**测试机制（自己测试，不让用户测试）：**
- 后端API测试：tools/test_xxx.js
- 前端逻辑测试：tools/test_frontend_xxx.js
- 前端语法检查：node -c xxx.js

**判断题清单：**
| 检查项 | 怎么查 | 不通过的表现 |
|---|---|---|
| 后端API存在 | grep backend/api/v1/xxx.py | 404 |
| 后端API返回正确数据 | node tools/test_xxx.js | 数据为空 |
| 前端有事件绑定 | grep modules/xxx.js onclick | 点了没反应 |
| 前端事件逻辑完整 | 读代码 | 只弹"开发中"toast |
| 前端语法正确 | node -c | 语法错误 |
| 前后端联通 | 测试脚本 | 405/500错误 |

**深度测试铁律（2026-09-14新增，必须遵守）：**
❌ 禁止只看页面能不能打开就标记"通过"
✅ 必须点每个按钮、填每个表单、验证结果变化
✅ 必须深入到最下层功能（比如错题本：点标记掌握→看掌握数有没有变）
✅ 必须验证"操作前vs操作后"数据有没有变化
❌ 禁止"代码里有"就标记"功能完整"
❌ 禁止"页面打开了"就标记"模块通过"

**深度测试标准流程：**
1. 进入模块页面 → 截图
2. 记录当前数据状态（比如：已掌握0道）
3. 点击第一个功能按钮 → 截图
4. 记录操作后数据状态（比如：已掌握1道）
5. 对比操作前后变化 → 有变化=通过，没变化=有bug
6. 重复测试每个功能按钮

**工作流程：**
1. 先写测试脚本 → 2. 运行测试发现问题 → 3. 修问题 → 4. 再测试直到通过 → 5. 打勾断点记录

**融合铁律（2026-09-14新增）：**
1. **旧代码是可用的** — 直接搬旧代码的实现，不重新写
2. **bug先看旧代码** — 旧代码里这个功能怎么实现的，直接搬
3. **功能缺失先对比** — 旧代码有什么功能，新版缺什么，列清单
4. **模块化要深刻** — 不是拆文件就叫模块化，要思考：
   - 哪些是通用组件（按钮、弹窗、卡片）
   - 哪些是业务模块（题库、错题本、闪卡）
   - 哪些是插件（TTS、PDF解析、AI）
   - 模块间怎么通信（事件总线？依赖注入？）
5. **禁止自己猜bug** — 先看旧代码怎么写的，再修

**对比方法：**
- 旧代码app_v3_897262.js（34848行）
- 新版frontend/modules/（14565行）
- 对比：旧代码有什么函数 → 新版有没有对应实现
- 对比：旧代码这个功能怎么写的 → 新版有没有抄过来
旧代码是可用的，新代码是没融合进去。融合前必须预判会出现什么情况：

| 常见坑 | 现象 | 修复方式 | 案例 |
|---|---|---|---|
| state初始化缺字段 | Cannot read properties of undefined (reading 'add') | state初始化补上字段 | answeredQuestions undefined |
| this指向不对 | s.showResult undefined | 改成 this.state.showResult | 单选题提交不显示结果 |
| 字段名不对 | 选项为空 | 兼容新老字段名 | option_a vs options JSON |
| 类没实例化 | EventBus.emit is not a function | 静态方法兼容 | EventBus是class不是实例 |

**融合前必须检查：**
1. state初始化有没有缺字段
2. this指向对不对（箭头函数vs普通函数）
3. 字段名对不对（新老字段兼容）
4. 类有没有实例化（class vs instance）
5. 旧代码里这个功能是怎么实现的（直接搬，不重新写）

### N.7 备份回滚机制（已在17.7节规定）

- L3快照：每次修改前自动备份
- L2增量：每阶段完成后备份
- 一键回滚：出问题30秒内恢复
- 备份验证：MD5校验，确保可恢复

---

> **治理铁律：没有验证的治理不算完成，没有达标的阶段不算通过，没有备份的修改不允许执行。70名专家各负其责，协同作战，确保系统彻底治理、不遗漏、不回退。**

### N.8 功能融合断点记录（2026-09-14融合自功能融合断点记录.md）

**当前进度总览：**
- 总覆盖率：**42%**（新版14565行 / 旧版34848行）
- 已完成：核心框架+布局模块+题库刷题+模拟考试（基本闭环）
- 进行中：题库刷题多选题提交验证

**P0 本周必成：**
- [x] 1. 闪卡SM-2间隔重复算法（后端API完整，前端已改调后端）
- [x] 2. 闪卡TTS朗读专练（正面/背面/全部/随机4种模式）
- [x] 3. 题库管理CRUD（后端POST/PUT/DELETE已补）
- [x] 4. 错题本导出CSV（筛选/导出/掌握/删除/艾宾浩斯复习）
- [x] 5. 多选题提交验证（已修复2个bug，单选题已测试通过，待找多选题验证）
- [x] 6. 模拟考试交卷（已修复EventBus.emit、选项字段名，全流程通过）
- [x] 7. 错题本标记掌握（已修复StorageService.wrongQuestions.update方法缺失）

**P1 下周：**
- [x] 资料库批量标签+文件夹操作
- [x] 视频智能笔记+播放控制
- [x] 收藏/笔记导出+章节筛选
- [x] 学习分析图表可视化

**P2 第三周：**
- [x] 知识库CRUD+知识图谱
- [x] 思维导图AI生成+节点编辑
- [x] 记忆训练9大记忆法
- [x] 系统设置项全量

**下一个对话框怎么接：**
1. 读本文件N.8节（断点记录）
2. 读总控第6.0节（布局基准）
3. 按P0顺序做，做完一项打勾
4. 做完更新覆盖率统计

### N.9 功能融合方案（2026-09-14融合自功能融合方案_V2.0_基于实际索引.md）

**现状诊断：**
| 版本 | 大小 | 行数 | 说明 |
|---|---|---|---|
| 旧版单体 app_v3_897262.js | 1630 KB | 34848 行 | 所有业务逻辑 |
| 新版模块化 frontend/modules/ | 614 KB | 14565 行 | 已搭框架+部分功能 |
| **覆盖率** | **38%** | **42%** | 还有约20000行没搬 |

**融合原则（锁死）：**
1. 布局不动：只往现有模块加方法，不改HTML结构
2. API不变：前端请求路径不变，旧API兜底
3. 零数据迁移：新旧共用同一批数据库表
4. 模块化：每个功能独立方法，通过event-bus通信
5. 改前备份：每次改前备份到_archived/

**分阶段路线：**
- P0：闪卡SM-2 + TTS朗读 + 题库CRUD + 错题导出
- P1：资料库批量操作 + 视频智能笔记 + 收藏导出 + 分析图表
- P2：知识图谱 + 思维导图 + 记忆训练 + 系统设置
- P3：AI拍照解题 + 模拟考试 + 系统管理

### N.7 内联样式清理详细约束规则（铁律）

**立法背景**：系统有3689个内联style，是布局混乱的根源。清理必须有明确规则，禁止盲目删除导致功能异常。

#### N.7.1 可清理的内联样式（必须清理）

以下内联样式必须提取为CSS类名，写入V2 CSS：
1. **静态布局样式**：display、flex、grid、padding、margin、width、height、gap
2. **静态视觉样式**：border、border-radius、background（静态色）、color（静态色）
3. **静态字体样式**：font-size、font-weight、line-height、text-align
4. **重复出现的样式**：同一模式出现3次以上，必须提取为通用类名
5. **筛选栏/表格/分页栏样式**：统一提取为组件类名

#### N.7.2 必须保留的内联样式（禁止清理）

以下内联样式必须保留，禁止提取为CSS类名：
1. **动态计算样式**：通过JS计算的width、height、top、left（如进度条宽度、定位坐标）
2. **条件样式**：根据数据动态变化的background、color（如真题/模拟题标签颜色、奇偶行背景）
3. **事件绑定样式**：onmouseover/onmouseout中动态修改的style
4. **唯一一次性样式**：只出现1次且无复用价值的特殊样式
5. **动画过渡样式**：transition、transform等动态效果

#### N.7.3 清理方法（标准流程）

1. **分析**：统计函数内所有内联style，分类为"可清理"和"必须保留"
2. **提取**：将可清理样式合并为CSS类名，命名规范：`页面-模块-元素`（如`qm-header`、`qm-filter-select`）
3. **写入V2 CSS**：新类名必须写入`V2布局规则_统一版.css`，禁止写入style.css
4. **替换JS**：将JS中的`style="..."`替换为`class="类名"`，保留必须保留的内联样式
5. **验证**：真实浏览器截图对比，布局必须与清理前完全一致
6. **备份**：清理前自动创建L3快照，清理后创建L2增量备份

#### N.7.4 清理验证标准（缺一不可）

1. **布局一致性**：清理前后截图对比，像素偏差<3px
2. **功能完整性**：页面所有交互功能正常（筛选、搜索、分页、编辑、删除）
3. **响应式**：窗口缩放时布局正常，无溢出、无错位
4. **控制台无报错**：F12控制台无红色Error
5. **内联style减少**：该函数内联style数量减少>80%（仅保留动态计算）



#### N.7.6 【新增铁律】全面分析统一修改原则（2026-09-08入宪）

**铁律背景**：逐项修改导致功能错乱（删mgYear未查JS引用、跳过登录未设OFFLINE_MODE），专家团深刻反思后制定。

**铁律内容**：

1. **修改前全面分析**：任何HTML/CSS/JS修改前，必须由相关领域专家（前端架构师、DOM渲染专家、业务专家）联合完成：
   - 全局搜索所有相关代码（HTML结构、CSS类名、JS getElementById/querySelector引用、onclick事件、API调用、数据依赖）
   - 分析修改影响范围（直接影响+间接影响+跨模块影响）
   - 识别所有依赖关系（谁引用了这个元素、谁依赖这个样式、谁调用这个函数）
   - 输出《修改影响分析报告》，列出所有受影响的文件、函数、元素

2. **统一给出修改清单**：分析完成后，必须输出完整的《修改清单》，包括：
   - 待删除的元素/样式/代码（附理由和影响评估）
   - 待修改的元素/样式/代码（附修改前后对比）
   - 待新增的元素/样式/代码（附位置和用途）
   - 风险点和回滚方案
   - 验证清单（修改后必须验证的功能点）

3. **一次性执行**：修改清单经用户确认后，必须一次性执行所有修改，禁止：
   - ❌ 逐项修改（改一处验证一处）
   - ❌ 边分析边修改
   - ❌ 打补丁式修复
   - ❌ 发现问题临时加代码
   - ✅ 统一修改→统一验证→统一交付

4. **专家协同要求**：
   - 前端架构师：负责CSS/JS架构影响分析
   - DOM渲染专家：负责HTML结构和JS引用分析
   - 业务专家：负责功能逻辑和数据依赖分析
   - 测试专家：负责验证清单制定
   - 四方专家签字确认后才能执行

5. **违规处罚**：
   - 未做全面分析直接修改：记一次严重违规
   - 逐项修改导致功能错乱：记两次严重违规
   - 三次严重违规：专家团重组

**本铁律适用于所有代码修改，包括但不限于：布局调整、内联样式清理、功能新增、bug修复、重构。**

#### N.7.5 清理顺序（优先级）

1. **P0核心页面**：学习看板→题库管理→闪卡管理→思维导图
2. **P1重要页面**：视频播放→智能笔记→学习分析→登录界面
3. **P2一般页面**：系统设置→错题本→模拟考试→其他页面
4. **P3边缘页面**：弹窗、提示框、次要功能页

#### N.7.6 禁止事项（红线）

- ❌ 禁止批量删除内联style，必须逐个分析分类
- ❌ 禁止将动态计算样式提取为CSS类名（会导致功能失效）
- ❌ 禁止清理后不验证就继续下一个页面
- ❌ 禁止将新类名写入style.css，必须写入V2 CSS
- ❌ 禁止一次清理多个页面，必须逐页清理逐页验证
- ❌ 禁止清理后不备份，必须先备份再清理

#### N.7.7 清理进度追踪

每个页面清理完成后，必须记录：
- 页面名称、函数名
- 清理前内联style数量
- 清理后内联style数量
- 保留的动态样式数量
- 验证结果（截图对比、功能测试）
- 新增CSS类名列表

记录位置：`代码治理清理日志.md`

### N.8 内联编码约束规则（防止未来新增，铁律）

**立法背景**：只清理不约束，未来新增代码又会产生新的内联样式，治理永远做不完。必须从编码源头禁止。

#### N.8.1 禁止事项（红线，违反即打回）

新增代码中，**禁止**以下内联样式：
1. ❌ 禁止静态布局内联：`style="display:flex"`、`style="padding:10px"`、`style="width:100px"`
2. ❌ 禁止静态视觉内联：`style="border:1px solid #ccc"`、`style="background:#fff"`、`style="color:#333"`
3. ❌ 禁止静态字体内联：`style="font-size:12px"`、`style="font-weight:600"`、`style="text-align:center"`
4. ❌ 禁止硬编码颜色：`style="color:#1976d2"`，必须用CSS变量`var(--v2-primary)`
5. ❌ 禁止硬编码尺寸：`style="height:48px"`，必须用CSS变量`var(--v2-nav-height)`
6. ❌ 禁止重复样式内联：同一模式出现2次以上，必须提取为CSS类名

#### N.8.2 允许的内联样式（唯一例外）

仅以下情况允许使用内联样式，且必须加注释说明：
1. ✅ 动态计算样式：`style="width:${progress}%"`（JS计算值）
2. ✅ 条件样式：`style="background:${isActive?'#dbeafe':'#fff'}"`（根据数据变化）
3. ✅ 事件临时样式：`onmouseover="this.style.background='#eee'"`（交互临时效果）
4. ✅ 唯一一次性样式：只出现1次且无复用价值，需加注释`/* 一次性样式 */`

#### N.8.3 编码规范（必须遵守）

1. **所有静态样式必须写在V2 CSS中**，使用类名引用
2. **类名命名规范**：`页面-模块-元素`，如`qm-header`、`dash-stat-card`
3. **颜色必须用CSS变量**：`var(--v2-primary)`、`var(--v2-bg)`，禁止硬编码
4. **尺寸必须用CSS变量**：`var(--v2-nav-height)`、`var(--v2-gap-md)`，禁止硬编码
5. **新增页面必须先在V2 CSS中定义样式**，再写JS渲染代码
6. **修改样式必须修改V2 CSS**，禁止在JS中加内联style覆盖

#### N.8.4 代码审查机制（每次提交前）

新增或修改代码必须通过以下检查：
1. **自动检查**：运行`tools/check_inline_style.py`，新增内联style>5个告警
2. **人工审查**：UI专家审查样式是否符合V2.0规范
3. **硬编码检查**：搜索`#`颜色值和`px`硬编码，必须改用变量
4. **类名检查**：新类名是否符合命名规范，是否已存在可复用类名

#### N.8.5 违规处理（铁律）

1. **新增违规内联样式**：立即打回，要求改为CSS类名
2. **硬编码颜色/尺寸**：立即打回，要求改用CSS变量
3. **屡犯不改**：暂停代码提交权限，重新学习宪法
4. **因违规导致布局问题**：回滚代码，责任人记录违规日志

#### N.8.6 新页面开发流程（标准）

1. 先在V2 CSS中定义页面所需的所有样式类名
2. 再写JS渲染代码，只引用类名，不写内联style
3. 动态计算样式才允许内联，且必须加注释
4. 完成后运行自动检查，确保无违规内联样式
5. UI专家审查通过后，方可合并

### N.9 系统演进与未来扩展规则（前瞻性，铁律）

**立法背景**：规则不能只解决当前问题，必须结合系统特点和未来发展，确保系统可扩展、可演进、不返工。

#### N.9.1 系统特点约束（必须遵守）

本系统为**造价考试学习系统**，核心特点：
1. **数据驱动**：题库、闪卡、思维导图都围绕知识点，所有功能必须以知识点为核心
2. **多科目多专业**：当前支持一造/二造、水利/交通等，新增科目必须遵循现有架构
3. **多端适配**：电脑/手机/平板三端，新功能必须三端同时设计
4. **离线优先**：支持离线模式和APK，新功能必须考虑离线场景
5. **AI增强**：AI学习计划、智能语音等，AI输出必须有验证机制
6. **备考导向**：用户要考试，所有功能必须服务于备考效率

#### N.9.2 新科目/新专业扩展规则

未来新增科目（如二造、监理、咨询）或专业方向（如水利、交通、土建）：
1. **必须遵循现有数据结构**：科目表、章节表、知识点表、题库表结构不变
2. **必须遵循知识点体系**：知识点精讲→教材→大纲→真题四级打通
3. **必须遵循登录选择流程**：大专业→专业方向→学习科目，三级联动
4. **必须遵循布局V2.0**：所有页面必须符合唯一布局标准
5. **必须遵循命名规范**：科目简称、章节格式（如"4 工程经济"）全局统一
6. **禁止为新科目新建独立表结构**，必须复用现有架构

#### N.9.3 新功能模块扩展规则

未来新增功能模块：
1. **必须先入宪**：新功能必须先制定规则写入宪法，才能开发
2. **必须遵循模块架构**：前端渲染函数+后端API+数据库表，三层分离
3. **必须遵循布局V2.0**：新页面必须符合6类布局规范
4. **必须遵循编码约束**：禁止内联样式，必须用V2 CSS类名
5. **必须三端适配**：电脑/手机/平板同时设计，禁止只做一端
6. **必须离线可用**：核心功能必须支持离线缓存
7. **必须有数据来源**：新增数据必须明确来源（教材/大纲/真题/AI生成），禁止无依据造数据

#### N.9.4 AI功能规则

未来新增AI功能：
1. **AI输出必须可验证**：AI生成的知识点、题目、闪卡必须有原文依据
2. **AI输出必须可纠错**：用户可以纠正AI错误，纠错后数据更新
3. **AI不是数据源**：AI只能辅助整理，知识点必须以教材/大纲/真题为准
4. **AI功能必须有开关**：用户可以选择是否使用AI功能
5. **AI生成内容必须标注**：明确标注"AI生成，仅供参考"

#### N.9.5 数据演进规则

未来数据结构变更：
1. **必须向后兼容**：新数据结构必须兼容旧数据，禁止破坏性变更
2. **必须有迁移脚本**：数据结构变更必须提供自动迁移脚本
3. **必须备份后迁移**：迁移前必须创建L1黄金备份
4. **必须验证迁移结果**：迁移后数据完整性必须100%验证
5. **知识点ID不可变**：知识点一旦建立，ID全局唯一不可修改，确保闪卡/题库/导图关联不失效

#### N.9.6 版本演进规则

系统版本迭代：
1. **大版本（Vx.0）**：架构变更、数据结构变更，必须全量备份+全面测试
2. **中版本（Vx.y）**：新功能模块、布局调整，必须L2备份+核心测试
3. **小版本（Vx.y.z）**：Bug修复、样式微调，必须L3备份+验证
4. **考前稳定版**：考前30天冻结功能，只修Bug，不加新功能
5. **版本发布前必须20遍全面测试**，无问题方可发布

#### N.9.7 禁止事项（前瞻性红线）

- ❌ 禁止为赶进度跳过规则，"先做了再说"
- ❌ 禁止为新功能新建独立架构，必须复用现有
- ❌ 禁止只做电脑端不做手机/平板
- ❌ 禁止AI生成无依据数据
- ❌ 禁止破坏性数据结构变更
- ❌ 禁止考前30天加新功能

### N.10 功能融合断点记录（2026-09-14融合自功能融合断点记录.md）

**当前进度总览：**
- 总覆盖率：**42%**（新版14565行 / 旧版34848行）
- 已完成：核心框架+布局模块+题库刷题+模拟考试（基本闭环）
- 进行中：无（P0/P1/P2全部核实通过）

**三级标记体系（必须分开）：**
- 🔧 代码里有：grep到了方法名/事件绑定/API调用
- ⚙️ 功能完整：代码逻辑闭环（绑定→state更新→渲染→判分）
- ✅ 运行验证：实际浏览器测试通过

**P0 本周必成：**
- 1. 闪卡SM-2间隔重复算法：🔧代码有 ⚙️功能完整 ✅运行验证（后端API测试通过）
- 2. 闪卡TTS朗读专练：🔧代码有 ⚙️功能完整 ❌未运行验证
- 3. 题库管理CRUD：🔧代码有 ⚙️功能完整 ❌未运行验证
- 4. 错题本导出CSV：🔧代码有 ⚙️功能完整 ❌未运行验证
- 5. 多选题提交：🔧代码有 ⚙️功能完整（已加try-catch+render()） ❌未运行验证

**P1 下周：**
- 资料库批量标签+文件夹操作：🔧代码有（batchTag()） ❌功能完整性待核实 ❌未运行验证
- 视频智能笔记+播放控制：🔧代码有（generateAINote()） ❌功能完整性待核实 ❌未运行验证
- 收藏/笔记导出+章节筛选：🔧代码有（_exportFavorites()） ❌功能完整性待核实 ❌未运行验证
- 学习分析图表可视化：🔧代码有（div条形图） ❌功能完整性待核实 ❌未运行验证

**P2 第三周：**
- 知识库CRUD+知识图谱：🔧代码有（添加/编辑/删除） ❌功能完整性待核实 ❌未运行验证
- 思维导图AI生成+节点编辑：🔧代码有（aiGenerateMindmap()） ❌功能完整性待核实 ❌未运行验证
- 记忆训练9大记忆法：🔧代码有（9个卡片） ❌功能完整性待核实 ❌未运行验证
- 系统设置项全量：🔧代码有（主题/语音/通知/备份） ❌功能完整性待核实 ❌未运行验证

**下一个对话框怎么接：**
1. 读本文件N.10节（断点记录）
2. 读总控第6.0节（布局基准）
3. 按P0顺序做，做完一项打勾

### N.11 backend py文件分析与合并建议（2026-09-14）

**按功能分组：**
1. **题库模块（qb）**：routes + service + IRT算法 + 质量管理
2. **思维导图模块（mm）**：routes + service + parser，结构清晰
3. **记忆训练模块（mt）**：routes + service + BKT/FSRS算法 + 学习路径
4. **AI模块**：routes + service + ai_brain + ai_solve
5. **PDF处理**：pdf_parser + pdf_splitter + pdf_base_processor

**重复/冗余清单：**
| 重复组 | 文件1 | 文件2 | 建议 |
|---|---|---|---|
| 题库路由 | api/v1/question.py (68KB) | modules/qb/routes.py (47KB) | 统一到qb/routes.py |
| AI大脑 | utils/ai_brain.py (44KB) | utils/ai_brain_hub.py (40KB) | 合并成ai_brain.py |
| 闪卡/记忆 | api/v1/flashcard.py (15KB) | modules/mt/ | 闪卡并入mt模块 |
| 思维导图识别 | mindmap_recognizer.py (24KB) | mindmap_recognizer_v2.py (12KB) | v2保留，v1归档 |

**下一步建议：**
1. P0：合并重复的题库路由
2. P0：合并AI大脑
3. P1：闪卡并入mt模块
4. P1：拆分common/routes.py（52KB）成小文件

### N.12 前端modules/优化建议（2026-09-14）

**大文件需拆分（>50KB）：**
| 文件 | 大小 | 建议拆分 |
|---|---|---|
| file-library.js | 74KB | 拆成：文件列表+上传+标签+文件夹 |
| question-practice.js | 63KB | 拆成：刷题主逻辑+选项渲染+结果解析 |
| flashcard.js | 59KB | 拆成：闪卡练习+SM-2算法+口诀磨耳朵 |
| video.js | 58KB | 拆成：播放器+智能笔记+收藏 |

**应删除/归档：**
- hello-demo.js（4KB）— 演示文件，应删除

**可合并的layout小文件：**
- topbar.js + sidebar.js + module-nav.js + statusbar.js → 合并成 layout.js

### N.13 临时脚本清理建议（2026-09-14）

**tools/临时脚本：**
- 274个 _*.py 临时脚本 → 全部移到 tools/archive/
- 110个 archive/ 归档脚本 → 保留

**根目录散落py文件（42个）：**
- ai_code_analyzer.py / ai_code_analyzer_v2.py → 移到 tools/
- system_brain.py / system_brain_analyzer.py / v2.py → 移到 tools/
- ocr_easyocr.py / ocr_rapidocr.py / ocr_scanner.py / pdf_scanner.py → 移到 tools/
- 修改登录布局.py / 恢复看板布局.py / 添加服务器函数.py → 归档
- _*.py 临时文件 → 归档

**清理原则：**
1. 一次性脚本 → tools/archive/
2. 工具脚本 → tools/
3. 根目录只保留：架构总控文件.md + start.bat + 必要配置文件

### N.10 核心模块内联代码专项规则（铁律）

**立法背景**：6大核心模块（题库、闪卡、思维导图、视频、笔记、分析）是内联样式重灾区，必须有针对性的专项规则。

#### N.10.1 题库管理模块专项规则

**页面结构**：筛选栏 + 表格 + 分页栏 + 弹窗

**必须提取为CSS类名的内联样式：**
1. 筛选栏容器：`.qm-toolbar`（border、background、padding、flex布局）
2. 筛选下拉框：`.qm-filter-select`（height:26px、font-size、width）
3. 筛选输入框：`.qm-search-input`（height:26px、flex:1）
4. 操作按钮：`.qm-btn`（含 `.qm-btn-primary`/`-success`/`-danger`，padding:2px 8px、height:26px）
5. 表格滚动容器：`.qm-list`（overflow:auto、background:#fff、padding:0）
6. 表格：`.qm-table`（width:100%、border-collapse、table-layout:fixed）
7. 表头：`.qm-table th`（padding、border-bottom、background，遵守 6.20 不用 sticky）
8. 表格行：`.qm-table tr`（border-bottom、cursor、hover效果）
9. 表格单元格：`.qm-table td`（padding、font-size、white-space、ellipsis）
10. 列宽：用nth-child精确控制（序号40px、题型50px、章节90px、答案45px、年份45px、类型55px、操作80px）
11. 标签：`.qm-tag`（inline-block、padding、border-radius、font-size）
12. 分页栏：`.qm-pagination`（height:36px、flex布局）
13. 分页按钮：`.qm-page-btn`（height:28px、min-width、padding）

**必须保留的内联样式：**
- 奇偶行背景色（动态计算`i%2===0`）
- 题型/类型标签颜色（根据数据动态变化）
- 行hover效果（onmouseover/onmouseout）

#### N.10.2 闪卡管理模块专项规则

**页面结构**：统计栏 + 卡片列表 + 复习界面 + 弹窗

**必须提取为CSS类名的内联样式：**
1. 统计卡片：`.fc-stat-card`（padding、min-height、text-align）
2. 卡片网格：`.fc-grid`（display:grid、grid-template-columns、gap）
3. 闪卡卡片：`.fc-card`（border、border-radius、padding、background）
4. 卡片正面：`.fc-card-front`（padding、font-size）
5. 卡片背面：`.fc-card-back`（padding、font-size、background）
6. 复习界面：`.fc-review`（flex布局、align-items、justify-content）
7. 进度条：`.fc-progress`（height、background、border-radius）
8. 操作按钮：`.fc-btn`（padding、font-size、min-width）

**必须保留的内联样式：**
- 进度条宽度（动态计算`progress%`）
- 卡片翻转效果（transform、transition）
- 卡片背景色（根据掌握程度动态变化）

#### N.10.3 思维导图模块专项规则

**页面结构**：编辑器 + 预览 + 节点树 + 弹窗

**必须提取为CSS类名的内联样式：**
1. 编辑器容器：`.mm-editor`（flex布局、height、overflow）
2. 预览容器：`.mm-preview`（flex:1、overflow、background）
3. 节点树：`.mm-tree`（width、border-right、overflow-y）
4. 节点：`.mm-node`（padding、margin-left、border-left）
5. 节点内容：`.mm-node-content`（padding、font-size、border-radius）
6. 工具栏：`.mm-toolbar`（height、flex布局、border-bottom）
7. 连接线：`.mm-link`（stroke、stroke-width）

**必须保留的内联样式：**
- 节点坐标（x、y动态计算）
- 节点颜色（根据层级动态变化）
- 连接线路径（SVG动态生成）
- 缩放/平移（transform动态计算）

#### N.10.4 视频播放模块专项规则

**页面结构**：播放器 + 视频列表 + 讲义列表 + 控制栏

**必须提取为CSS类名的内联样式：**
1. 播放器容器：`.vp-player`（flex:1、background、position:relative）
2. 视频元素：`.vp-video`（width:100%、height:100%）
3. 侧边栏：`.vp-sidebar`（width、border-left、overflow-y）
4. 列表项：`.vp-list-item`（padding、border-bottom、cursor、hover）
5. 控制栏：`.vp-controls`（height、flex布局、background）
6. 进度条：`.vp-progress`（height、cursor、background）
7. 讲义区域：`.vp-notes`（padding、font-size、line-height）

**必须保留的内联样式：**
- 视频进度（currentTime动态计算）
- 播放进度条宽度（动态计算）
- 音量控制（动态值）

#### N.10.5 智能笔记模块专项规则

**页面结构**：笔记列表 + 编辑器 + 标签栏 + 弹窗

**必须提取为CSS类名的内联样式：**
1. 笔记列表：`.note-list`（width、border-right、overflow-y）
2. 笔记项：`.note-item`（padding、border-bottom、cursor、hover）
3. 编辑器：`.note-editor`（flex:1、display:flex、flex-direction:column）
4. 工具栏：`.note-toolbar`（height、flex布局、border-bottom）
5. 编辑区：`.note-content`（flex:1、padding、font-size、line-height）
6. 标签：`.note-tag`（inline-block、padding、border-radius、font-size）

**必须保留的内联样式：**
- 光标位置（动态计算）
- 选中文本样式（动态range）

#### N.10.6 学习分析模块专项规则

**页面结构**：统计卡片 + 图表区 + 趋势图 + 明细表

**必须提取为CSS类名的内联样式：**
1. 统计卡片：`.ana-stat-card`（padding、text-align、border、border-radius）
2. 图表容器：`.ana-chart`（height、padding、background）
3. 图表标题：`.ana-chart-title`（font-size、font-weight、margin-bottom）
4. 趋势图：`.ana-trend`（height、position:relative）
5. 明细表：`.ana-table`（width:100%、border-collapse）
6. 进度条：`.ana-progress`（height、background、border-radius）

**必须保留的内联样式：**
- 图表尺寸（根据数据动态计算）
- 进度条宽度（动态计算百分比）
- 数据点坐标（SVG动态生成）

#### N.10.7 通用组件专项规则

所有模块共用的组件：
1. **弹窗**：`.modal-overlay`、`.modal`、`.modal-header`、`.modal-body`、`.modal-footer`
2. **按钮**：`.btn`、`.btn-sm`、`.btn-primary`、`.btn-success`、`.btn-danger`、`.btn-outline`
3. **输入框**：`.input`、`.input-sm`
4. **下拉框**：`.select`、`.select-sm`
5. **表格**：`.data-table`、`.data-table th`、`.data-table td`
6. **标签**：`.tag`、`.tag-blue`、`.tag-green`、`.tag-yellow`、`.tag-red`
7. **空状态**：`.empty-state`、`.empty-state .icon`、`.empty-state p`

**通用组件必须全局统一定义在V2 CSS中，禁止各模块重复定义。**

---

## 第四十章 问题判定与预防体系（2026-09-08入宪）

> **立法背景**：70名专家团队在工作中出现"测试便利性问题误判为P0"、"修改前未做影响分析导致功能错乱"、"类似问题反复发生"等情况。经专家团深刻反思，建立本章体系，明确问题判定标准、流程、预防机制和专家职责。

### 37.1 问题分级标准（4级分类）

| 级别 | 定义 | 示例 | 处理时效 | 审批要求 |
|------|------|------|---------|---------|
| **P0 生产阻断** | 正式环境用户无法使用核心功能，数据丢失或系统不可用 | 登录失败、白屏、数据丢失、核心功能完全不可用 | 立即修复，1小时内 | 首席架构师+产品负责人双签 |
| **P1 功能异常** | 正式环境某功能不正常但有替代方案，不影响核心流程 | 筛选失效、导出失败、某按钮无响应 | 24小时内修复 | 前端架构师+业务专家确认 |
| **P2 体验优化** | 功能正常但体验不好，用户可正常使用 | 布局不协调、操作繁琐、加载慢 | 排期优化，版本迭代 | 产品专家评估优先级 |
| **P3 测试便利** | 仅影响开发测试，不影响正式用户使用 | 跳过登录无数据、调试信息不足、测试环境配置 | 可选改进，不强制 | 测试专家记录，不强制修复 |

**铁律：禁止将P3问题升级为P0/P1，禁止将测试环境问题等同于生产环境问题。**

### 37.2 问题判定流程（5步专家协同）

#### 第一步：问题发现与记录
- 发现人：测试专家、用户、任意专家
- 记录内容：问题描述、复现步骤、截图/日志、发生环境（生产/测试/开发）

#### 第二步：初步分级
- 责任人：前端架构师
- 依据：37.1分级标准
- 输出：初步级别、影响范围预估

#### 第三步：影响评估
- 责任人：业务专家+产品专家
- 评估维度：
  - 影响用户群（正式用户/测试用户/开发人员）
  - 影响功能范围（核心功能/辅助功能/测试功能）
  - 严重程度（完全不可用/部分异常/体验不佳）
  - 发生频率（必现/偶现/特定条件）

#### 第四步：交叉验证
- 要求：至少2名不同领域专家确认分级无误
- 争议处理：分级有争议时，按"就低不就高"原则（先按较低级别处理，避免过度反应）

#### 第五步：输出问题报告
- 必含内容：
  - 问题描述
  - 级别（P0-P3）
  - 影响范围
  - 根因分析
  - 修复方案
  - 风险评估
  - 验证清单
  - 预防措施（如何避免再次发生）

### 37.3 代码修改前影响分析机制（铁律）

**任何代码修改前，必须完成以下检查，缺一不可：**

#### 37.3.1 HTML修改检查清单
- [ ] 全局搜索`getElementById`：确认删除/修改的元素ID没有被JS引用
- [ ] 全局搜索`querySelector`：确认没有CSS选择器依赖
- [ ] 全局搜索`onclick`/`onchange`：确认事件绑定完整
- [ ] 检查父元素/子元素依赖关系
- [ ] 输出：《HTML修改影响分析表》

#### 37.3.2 CSS修改检查清单
- [ ] 检查类名是否被其他页面复用
- [ ] 检查选择器优先级是否会覆盖其他样式
- [ ] 检查响应式断点影响
- [ ] 检查动画/过渡效果依赖
- [ ] 输出：《CSS修改影响分析表》

#### 37.3.3 JS修改检查清单
- [ ] 检查函数调用链（谁调用了这个函数）
- [ ] 检查全局变量依赖
- [ ] 检查API接口变更影响
- [ ] 检查异步流程/回调函数
- [ ] 输出：《JS修改影响分析表》

#### 37.3.4 测试模式/跳过登录特殊检查
- [ ] 必须模拟正式环境的完整初始化流程
- [ ] 必须设置：OFFLINE_MODE、token、user、currentSubject
- [ ] 必须验证：数据加载、路由跳转、状态管理
- [ ] 禁止：测试模式与正式环境行为不一致

### 37.4 预防机制（避免类似问题反复发生）

#### 37.4.1 静态检查脚本（自动化）
- 每日自动运行：检测"删除了HTML元素但JS还在引用"的情况
- 检测"CSS类名已删除但HTML还在使用"的情况
- 检测"函数已删除但还在调用"的情况
- 输出：《每日代码健康检查报告》

#### 37.4.2 问题知识库
- 每个问题修复后，必须写入《问题知识库》
- 记录内容：问题描述、根因、修复方案、预防措施
- 定期复盘：每月回顾高频问题，优化流程

#### 37.4.3 代码审查机制
- 所有代码修改必须经过至少1名专家审查
- 审查重点：是否遵循37.3检查清单、是否有潜在风险
- 审查不通过：打回修改，不得合并

#### 37.4.4 统一修改原则（N.7.6联动）
- 禁止逐项修改、边分析边修改、打补丁式修复
- 必须：全面分析→统一清单→一次性执行→统一验证

### 37.5 70名专家在问题判定中的职责

| 专家组 | 人数 | 职责 |
|--------|------|------|
| 前端架构师 | 2 | 问题分级、CSS/JS架构影响分析、代码审查 |
| DOM渲染专家 | 2 | HTML结构分析、JS引用检查、渲染性能评估 |
| 测试专家 | 3 | 问题发现、复现验证、测试用例制定、自动化测试 |
| 业务专家（造价） | 5 | 功能逻辑影响评估、业务数据准确性验证 |
| 产品专家 | 2 | 用户体验影响评估、优先级排序 |
| 后端架构师 | 2 | API接口影响分析、数据一致性检查 |
| 数据专家 | 2 | 数据质量检查、数据迁移影响评估 |
| 安全专家 | 1 | 安全风险评估、权限影响分析 |
| 其他专家 | 51 | 各领域专业问题判定 |

**协同要求：任何P0/P1问题，必须至少3个不同领域专家参与判定和修复。**

### 37.6 违规处罚

| 违规行为 | 处罚 |
|---------|------|
| 未做影响分析直接修改 | 记1次严重违规 |
| P3误判为P0导致过度反应 | 记1次严重违规 |
| 逐项修改导致功能错乱 | 记2次严重违规 |
| 类似问题重复发生3次以上 | 专家团重组，流程重审 |
| 代码未审查直接合并 | 记1次严重违规 |

**3次严重违规 = 专家团重组，重新制定工作流程。**

---

**本章与N.7.6（全面分析统一修改原则）联动执行，构成完整的代码修改质量保障体系。**

### 37.7 静态资源路径规范（2026-09-08入宪）

> **立法背景**：后端缺少`/data`挂载导致离线数据404，根因是前端用相对路径`data/offline/`隐式依赖后端配置，换环境即失效。建立本规范，统一静态资源路径管理。

#### 37.7.1 路径使用铁律

1. **绝对路径强制**：所有前端代码引用静态资源（JS/CSS/JSON/图片/视频/字体），必须使用以`/static/`开头的绝对路径
   - ✅ 正确：`/static/data/offline/questions.json`
   - ✅ 正确：`/static/js/app.js`
   - ✅ 正确：`/static/css/style.css`
   - ❌ 错误：`data/offline/questions.json`（相对路径）
   - ❌ 错误：`./data/offline/questions.json`（相对路径）
   - ❌ 错误：`../data/offline/questions.json`（相对路径）

2. **后端挂载唯一入口**：后端只挂载`/static`一个静态目录，指向`frontend/`，禁止为子目录单独挂载
   - ✅ 正确：`app.mount("/static", StaticFiles(directory=frontend_dir))`
   - ❌ 错误：`app.mount("/data", StaticFiles(directory=frontend/data))`（临时补丁，后续移除）

3. **目录结构规范**：
   ```
   frontend/
   ├── js/          → /static/js/
   ├── css/         → /static/css/
   ├── data/        → /static/data/
   │   └── offline/ → /static/data/offline/
   ├── images/      → /static/images/
   ├── videos/      → /static/videos/
   └── index.html   → / （根路径，由后端路由返回）
   ```

#### 37.7.2 迁移计划

**当前状态**：✅ **已完成（2026-09-11）**

**迁移完成情况**：
1. ✅ 全局搜索所有相对路径静态资源引用（共62处，涉及index.html、core/config.js、core/data-service.js）
2. ✅ 统一替换为`/static/`前缀绝对路径（共替换36处）
3. ✅ 移除后端`/data`临时挂载（backend/main.py L527-531已注释）
4. ✅ 验证所有页面资源加载正常（Python语法通过、离线数据目录6文件完整、无残留/data引用）
5. ⏳ APK/离线模式同步验证（待用户在实际设备验证）

**涉及文件**：
- `frontend/index.html`：34处 `static/` → `/static/`
- `frontend/core/config.js`：1处 basePath 更新
- `frontend/core/data-service.js`：1处 basePath 更新
- `backend/main.py`：注释掉 `/data` 独立挂载

**说明**：原 `app.js`/`app_v3` 单体文件已废弃不再被引用，其中的相对路径无需迁移。

#### 37.7.3 新功能开发规范

新增静态资源时：
1. 必须放入`frontend/`对应子目录
2. 前端引用必须用`/static/xxx/yyy`绝对路径
3. 代码审查时必须检查路径规范
4. 静态检查脚本自动检测相对路径引用，发现即报错

#### 37.7.4 检查机制

- **静态检查脚本**：每日扫描前端代码，检测相对路径静态资源引用
- **代码审查清单**：新增/修改代码必须检查路径规范
- **违规处罚**：新增相对路径引用记1次违规，累计3次专家团重组

#### 37.7.5 多环境适配

| 环境 | 静态资源根路径 | 说明 |
|------|--------------|------|
| 开发环境（localhost） | `/static/` | 后端FastAPI提供 |
| 生产环境（Nginx） | `/static/` | Nginx配置alias |
| APK离线模式 | `file:///android_asset/public/static/` | WebView本地路径 |
| PWA离线缓存 | `/static/` | Service Worker缓存 |

**所有环境统一用`/static/`前缀，通过构建工具或运行时配置适配不同根路径。**

### 37.8 待办追踪铁律（2026-09-08入宪）

> **立法背景**：对话过长导致专家忘记后续迁移计划，问题反复发生。建立本铁律，确保所有待办事项不遗漏。

#### 37.8.1 会话启动检查（强制）

**每次会话开始时，专家团必须执行以下步骤，缺一不可：**

1. 读取《待执行迁移计划.md》文件
2. 确认当前待办事项清单
3. 确认上次会话的完成状态
4. 确认本次会话的工作范围
5. 在回复中向用户确认待办状态

**禁止**：不读取待办清单直接开始工作。

#### 37.8.2 待办清单维护规则

1. **新增待办**：任何需要后续执行的任务，必须立即写入《待执行迁移计划.md》，不得只在对话中提及
2. **完成标记**：任务完成后，必须在清单中标记`[x]`，并记录完成日期和执行人
3. **状态更新**：每次会话结束前，必须更新待办清单状态
4. **优先级标注**：每个待办事项必须标注优先级（P0/P1/P2/P3）
5. **触发条件**：每个待办事项必须明确触发条件（如"布局清理完成后"）

#### 37.8.3 防遗忘机制

1. **文件位置**：《待执行迁移计划.md》放在项目根目录，易于发现
2. **宪法联动**：本铁律与N.7.6（全面分析统一修改）、第三十七章（问题判定）联动
3. **定期复盘**：每周回顾待办清单，清理已完成项，调整优先级
4. **违规处罚**：会话开始未检查待办清单，记1次严重违规

#### 37.8.4 当前待办概览（详见《待执行迁移计划.md》）

| 优先级 | 任务 | 触发条件 |
|--------|------|---------|
| P1 | 静态资源路径规范化 | 布局清理完成后 |
| P2 | 缺失离线数据文件补全 | 布局清理完成后 |
| P1 | 闪卡/思维导图/视频/笔记/分析内联样式清理 | 进行中 |
| P1 | 数据治理（闪卡去重/题库矫正/知识点体系） | 布局完成后 |
| P2 | 代码治理（style.css清理/Token体系/多端隔离） | 布局完成后 |


## 第四十一章 代码治理与设计系统铁律（2026-09-08新增）

### 38.1 新代码铁律（违反即拦截）
1. **禁止新增内联样式**：所有新代码必须使用CSS类，禁止写`style="..."`
2. **必须使用组件库**：按钮、卡片、表格、表单、标签页等必须使用`components.css`中的组件类
3. **必须使用Design Token**：颜色、间距、字号、圆角、阴影必须使用`tokens.css`中的变量，禁止硬编码
4. **多端样式严格隔离**：电脑端样式只写在`style.css`，手机/平板样式只写在`mobile.css`/`tablet.css`，禁止混入
5. **组件复用优先**：优先使用已有组件，不重复造轮子

### 38.2 代码健康检查机制
1. 每次代码修改后必须运行`code_health_check.py`
2. 健康评分低于60分必须立即治理
3. 内联样式数量必须持续下降，禁止反弹
4. 组件复用率必须持续增长
5. 检查历史数据保存在`code_health_history.json`，用于趋势分析

### 38.3 Strangler Fig渐进式重构策略
1. **不推翻重写**：旧代码保持运行，不主动修改
2. **新代码用新标准**：所有新功能必须使用组件库+Token+CSS类
3. **按模块迁移**：旧代码按优先级逐步迁移到新标准
4. **迁移一个验证一个**：每个模块迁移后必须通过自动化验证
5. **最终目标**：核心模块全部组件化，内联样式<500个

### 38.4 Design System组件库规范
1. 组件库文件：`frontend/css/components.css`
2. 包含10类组件：按钮、卡片、表格、表单、标签页、徽章、分页、弹窗、布局工具类、动画
3. 所有组件基于Design Token，支持深色主题
4. 新组件必须经过专家评审后才能加入组件库
5. 组件使用情况纳入健康检查统计

### 38.5 违规处罚机制
1. 新增内联样式：代码审查拒绝合并
2. 硬编码颜色/尺寸：要求修改为Token
3. 多端样式混入：要求隔离到对应文件
4. 重复造轮子：要求使用已有组件
5. 连续违规：专家团队介入，重新培训设计系统规范



======================================================================
# 附录4 【来源：实施细则总集.md】
======================================================================

# 📚 实施细则总集（现行唯一权威合集）
> 版本 V1.0 ｜ 2026-09-13 ｜ 由5份散落分册合并而成，原分册已归档。
> 本文件是各子系统实施细则的唯一入口；总控文件第11章指向此处。

## 📑 目录
1. 数据去杂与质量治理实施细则
2. 识别储存与内容知识库细则（V2.0）
3. 规划细则（V3.0完整细化版）
4. 思维导图集成原则
5. PDF公共预处理底座实施细则

---





============================================================
# § 数据去杂与质量治理实施细则分册_V1.0.md
============================================================

# 水利智学系统 数据去杂与质量治理实施细则分册（V1.0）

> **版本**：V1.0
> **生效日期**：2026-09-06
> **地位**：本文件为《系统设计宪法》第二十一章的配套实施细则，详细规定数据去杂、质量治理、原始内容保护、去重、完成标准等的具体执行步骤、验收标准、责任专家。所有执行必须严格遵守本细则。
> **制定委员会**：61位全球顶级专家联合制定，数据治理与质量专家牵头，数据库架构专家、造价培训专家、AI专家、题库识别算法专家、闪卡SM-2算法专家联合制定。
> **核心原则**：去杂优先、原始保护、物理去重、严格标准、持续监控。

---

## 一、去杂处理实施细则

### 1.1 去杂处理执行流程

```
步骤1：输入层去杂（文件上传时）
├─ 1.1 文件格式校验（仅支持PDF/Excel/Word/图片）
├─ 1.2 文件完整性校验（文件大小>0，可正常打开）
├─ 1.3 文件哈希计算（MD5/SHA256）
├─ 1.4 重复文件检查（哈希对比，同科目同哈希不重复上传）
├─ 1.5 科目筛选（根据文件夹名称/文件名判断科目，错误科目跳过）
└─ 1.6 输出：去杂报告（通过/跳过/失败及原因）

步骤2：识别层去杂（OCR识别时）
├─ 2.1 水印识别和去除（自动检测常见水印）
├─ 2.2 页眉页脚识别和标记（不删除，标记为非正文）
├─ 2.3 乱码检测（异常字符比例>30%标记为低质量）
├─ 2.4 空白页检测（字符数<10标记为空白页）
├─ 2.5 重复内容检测（页面相似度>95%标记为重复页）
└─ 2.6 输出：识别质量报告（每页置信度、质量标记）

步骤3：结构化层去杂（数据提取时）
├─ 3.1 题目完整性校验（题干、选项、答案、解析非空）
├─ 3.2 题目去重（三层去重机制，详见1.3）
├─ 3.3 闪卡质量评估（AI评估闪卡质量，低质量过滤）
├─ 3.4 闪卡去重（相同知识点合并，详见1.4）
├─ 3.5 知识点完整性校验（名称、章节、来源非空）
└─ 3.6 输出：提取质量报告（提取数量、去重数量、过滤数量）

步骤4：关联层去杂（数据关联时）
├─ 4.1 知识点关联置信度评估（精确/关键词/语义）
├─ 4.2 低置信度关联标记（置信度<0.7标记待人工审核）
├─ 4.3 标签准确性校验（自动标签与内容匹配度评估）
├─ 4.4 分类准确性校验（文件分类与内容匹配度评估）
└─ 4.5 输出：关联质量报告（关联率、置信度分布、待审核数量）

步骤5：应用层去杂（数据展示时）
├─ 5.1 重复内容过滤（前端展示时去重）
├─ 5.2 无效数据过滤（空内容、已删除数据不展示）
├─ 5.3 过期数据标记（超过有效期的数据标记）
├─ 5.4 数据缓存清理（定期清理过期缓存）
└─ 5.5 输出：展示质量报告（展示数量、过滤数量）
```

### 1.2 去杂处理验收标准

| 检查项 | 标准 | 验证方法 |
|--------|------|----------|
| 文件上传去重率 | 100%（相同哈希文件不重复上传） | 上传相同文件测试 |
| 文件格式校验 | 100%（不支持格式拒绝上传） | 上传非支持格式测试 |
| 科目筛选准确率 | >=95%（根据文件夹/文件名判断科目） | 抽样核对 |
| OCR识别准确率 | 文字>=95%，公式>=85% | 抽样人工核对 |
| 题目提取完整率 | >=95%（题干选项答案解析完整） | 抽样核对 |
| 闪卡质量合格率 | >=80%（AI评估质量>=80分） | AI评估+人工核对 |
| 知识点关联准确率 | >=90%（关联正确） | 抽样人工核对 |
| 去重准确率 | >=95%（误判率<5%） | 抽样核对 |

### 1.3 题库去重实施步骤

```
步骤1：数据预处理
├─ 对每道题的题干、选项、答案、解析进行预处理
├─ 去除空格、换行、标点、全半角统一
├─ 去除HTML标签、特殊字符
└─ 生成预处理后的文本

步骤2：第一层精确MD5去重
├─ 计算"题干+选项+答案+解析"的MD5哈希
├─ MD5相同的题目标记为精确重复
├─ 保留质量最高的版本（真题优先、解析最全优先）
└─ 其他精确重复题物理删除

步骤3：第二层四要素比对去重
├─ 题干前40字相同
├─ 选项A-E全部相同
├─ 答案相同
├─ 解析前50字相同
├─ 以上全部满足标记为高度重复
└─ 保留最优版本，其他物理删除

步骤4：第三层考点去重（不自动删除）
├─ 同一考点 + 同一题型 + 同一难度
├─ 题目数量超过阈值（单选≥5道、多选≥3道）
├─ 标记为同考点重复
└─ AI评估保留价值，不自动删除，待人工审核

步骤5：不同来源重复处理
├─ 真题与其他来源重复：保留真题，其他研判确认后物理删除
├─ 模拟题与练习题重复：保留模拟题，练习题研判确认后删除
└─ 相同来源重复：保留质量最高版本，其他研判确认后删除

步骤6：造价专家审核（批量去重必须人工审核）
├─ 输出重复报告（重复题目列表、重复原因、保留建议）
├─ 造价专家逐批审核确认
├─ 单条精确重复（MD5完全相同）可自动删除，批量必须人工审核
└─ 审核通过后执行物理删除

步骤7：删除前备份
├─ 待删除题目数据备份到duplicate_log表
├─ 记录题目ID、题干摘要、重复原因、保留题ID
├─ 记录操作人、操作时间
└─ 备份完成后执行物理删除

步骤8：去重结果验证
├─ 统计去重前后题目数量
├─ 抽样核对去重结果准确性
├─ 造价专家复核
└─ 生成去重报告
```

### 1.4 闪卡去重实施步骤

```
步骤1：闪卡内容定义校验
├─ 检查闪卡是否包含完整题目（题干+选项+答案）
├─ 包含完整题目的闪卡标记为"题目型闪卡"
├─ 题目型闪卡：移到题库，不保留在闪卡库
└─ 纯知识点/公式/口诀闪卡保留

步骤2：相同知识点合并
├─ 按知识点分组
├─ 同一知识点下的闪卡进行内容相似度计算
├─ 核心内容相似度>=90%标记为重复
├─ 保留内容最全、质量最高的版本
└─ 其他重复闪卡物理删除

步骤3：闪卡数量控制
├─ 每个知识点最多3张闪卡（概念卡、公式卡、口诀卡）
├─ 超过3张的，AI评估保留价值
├─ 保留最高频、最核心的3张
└─ 其他物理删除

步骤4：闪卡质量评估
├─ AI评估每张闪卡的质量（0-100分）
├─ 评估维度：知识点准确性、内容完整性、记忆有效性
├─ 质量<60分的闪卡标记为低质量
└─ 低质量闪卡物理删除或待人工优化

步骤5：造价专家审核（批量去重必须人工审核）
├─ 输出重复报告（重复闪卡列表、重复原因、保留建议）
├─ 造价专家逐批审核确认
├─ 单条精确重复可自动删除，批量必须人工审核
└─ 审核通过后执行物理删除

步骤6：删除前备份
├─ 待删除闪卡数据备份到duplicate_log表
├─ 记录闪卡ID、正面摘要、重复原因、保留卡ID
├─ 记录操作人、操作时间
└─ 备份完成后执行物理删除

步骤7：闪卡总数控制
├─ 每个科目闪卡总数控制在500-1000张
├─ 超过1000张的，按重要性排序
├─ 保留最重要的1000张
└─ 其他研判确认后物理删除或合并

步骤8：去重结果验证
├─ 统计去重前后闪卡数量
├─ 检查每个知识点的闪卡数量
├─ 抽样核对去重结果准确性
├─ 造价专家复核
└─ 生成去重报告
```

### 1.5 闪卡质量标准（2026-09-07 新增，曾多次踩坑）

#### 低质量闪卡类型（必须删除或优化）

| 类型 | 特征 | 处理方式 |
|------|------|----------|
| **题目自动生成型** | 正面"XX的核心考点是什么？"，背面是题目解析含"正确选项"，口诀是首字拼凑以"正"结尾 | 物理删除，题目保留在题库 |
| **宽泛问题型** | 正面是"XX是什么？"无具体指向，背面内容空洞 | 优化为具体知识点问题，或删除 |
| **名词堆砌口诀型** | 口诀只是英文缩写罗列（如"BOT PFI PPP ABS TOT REITs"），无记忆逻辑 | 重新生成有记忆逻辑的口诀 |
| **张冠李戴口诀型** | 口诀与知识点不匹配（如"大公外国"是招标范围，却用在投标保证金上） | 清理错误口诀，重新匹配 |
| **无意义首字型** | 口诀是无意义的首字拼凑（如"关关关的关但"、"投投招依以"） | 清理，用名师口诀库替换 |
| **内容过短型** | 背面内容<20字，只有结论无解释 | 补充具体知识点内容 |

#### 有效口诀质量标准

1. **有记忆逻辑**：谐音、联想、场景、首字成句，不能是无意义堆砌
2. **与知识点匹配**：口诀内容必须与闪卡知识点直接相关，禁止张冠李戴
3. **可朗读**：口诀必须通顺可读，不能是纯英文缩写罗列
4. **有解释**：复杂口诀需附带括号说明（如"大公外国（大型基础设施、公用事业、国有资金、国家融资、国际组织外国政府贷款）"）

#### 朗读记忆逻辑（铁律）

**播报顺序：知识点名称 → 具体内容全称（前200字） → 口诀**

- 禁止只读口诀不读知识点内容
- 禁止只读正面问题不读具体内容
- 显示区必须显示`knowledge_point`字段，而非`front`字段
- 无口诀的闪卡：读知识点名称+内容全称，提示"暂无口诀"

#### 名师口诀库（已建设）

- 通用口诀库：`backend/utils/famous_teacher_mnemonics.py`（一造管理60+、一建管理15、一建经济12、一建法规18）
- 水利案例专项：`backend/utils/water_case_mnemonics.py`（50+条，含关键词匹配映射）
- 应用规则：优先使用名师口诀，无匹配时自动生成，生成后AI评估质量

---

## 二、原始内容完整保护实施细则

### 2.1 五层存储实施步骤

```
步骤1：建立L0原始层存储
├─ 建立file_raw_result表（已完成）
├─ 每个文件识别后，保存OCR引擎原始输出JSON
├─ 记录引擎名称、版本、配置、扫描时间
└─ 原始结果永久保留，禁止删除

步骤2：建立L1文本层存储
├─ 从原始结果中提取纯文本
├─ 按页分隔，用\n\n===PAGE_BREAK===\n\n分隔
├─ 不做任何加工，保留原始文本
└─ 存储到file_content.content_text字段

步骤3：建立L2结构层存储
├─ 从原始结果中解析结构化内容
├─ 按页面、块、公式、表格、图片组织
├─ 存储到file_content.content_json字段
└─ 同时存储到file_page_content、file_content_block等表

步骤4：建立L3索引层
├─ FTS5全文索引（unicode61分词器，支持中文）
├─ 向量索引（bge-small-zh，512维）
├─ 知识点索引（知识点→文件→页面映射）
└─ 标签索引（标签→文件映射）

步骤5：建立L4应用层
├─ 从结构化内容中提取知识点
├─ 从结构化内容中识别题目
├─ 从结构化内容中生成闪卡
└─ 从结构化内容中生成思维导图
```

### 2.2 原始内容保护验收标准

| 检查项 | 标准 | 验证方法 |
|--------|------|----------|
| L0原始层覆盖率 | 100%（每个识别文件都有原始结果） | 数据库查询 |
| L1文本层完整性 | 100%（每页都有文本内容） | 抽样核对 |
| L2结构层完整性 | >=95%（公式、表格、图片正确识别） | 抽样核对 |
| L3索引层覆盖率 | 全文100%，向量>=90% | 索引查询 |
| L4应用层准确率 | 知识点>=90%，题目>=90%，闪卡>=80% | 抽样核对 |
| 原始结果可恢复性 | 100%（可从原始结果重新生成结构化数据） | 恢复测试 |

---

## 三、资料预处理实施细则（核心是配对，为题库/闪卡/导图识别服务）

### 3.1 预处理核心定位：配对过程

**预处理不是独立功能，是配对过程**：
- 预处理的唯一目的：为题库识别、闪卡生成、思维导图生成做准备
- 预处理的核心动作：把PDF内容与知识体系进行配对
- 预处理的输出：配对结果（知识点配对、题目配对、闪卡配对、导图配对）
- 后续功能直接使用配对结果，不重复分析

**四类配对（预处理的核心产出）**：

| 配对类型 | 配对内容 | 配对目标 | 后续用途 |
|----------|----------|----------|----------|
| 知识点配对 | PDF中的知识点名称、定义、解释 | 知识体系L3知识点（104个） | 知识点关联、掌握度分析 |
| 题目配对 | PDF中的题目（题干、选项、答案、解析） | 题库questions表 | 题库识别、自动入库 |
| 闪卡配对 | PDF中的公式、考点、口诀 | 闪卡flash_cards表 | 闪卡生成、自动入库 |
| 导图配对 | PDF中的章节结构、层级关系 | 思维导图mind_maps表 | 导图生成、自动关联 |

### 3.2 预处理五层执行流程（P1-P2基础，P3-P4桥梁，P5核心配对）

```
步骤1：P1 文件预处理（基础）
├─ 1.1 文件格式校验（PDF/Word/Excel/图片）
├─ 1.2 文件完整性校验（文件大小>0，可正常打开）
├─ 1.3 加密PDF破解（尝试自动破解，失败标记待人工处理）
├─ 1.4 Word/Excel转PDF（统一转换为PDF格式）
├─ 1.5 页数统计、文件元数据提取（标题、作者、创建时间）
├─ 1.6 文件哈希计算（MD5/SHA256，用于去重）
└─ 1.7 输出：标准化PDF文件 + 文件元数据JSON

步骤2：P2 图像预处理（基础）
├─ 2.1 PDF页面转图片（DPI=300，保证清晰度）
├─ 2.2 去水印处理（自动检测常见水印，参数可配置）
├─ 2.3 倾斜校正（检测倾斜角度，自动校正，阈值可配置）
├─ 2.4 对比度增强（自适应直方图均衡化，级别可配置）
├─ 2.5 超分辨率（低质量图片放大增强，可选）
├─ 2.6 二值化（文字区域二值化，提高OCR准确率，可选）
├─ 2.7 图片质量评估（清晰度、对比度、倾斜度）
└─ 2.8 输出：高质量页面图片（WebP格式，质量80%）

步骤3：P3 版面预处理（桥梁）
├─ 3.1 版面区域划分（标题、正文、公式、表格、图片、列表、页眉页脚）
├─ 3.2 区域bounding box坐标记录
├─ 3.3 阅读顺序排序（按从上到下、从左到右）
├─ 3.4 页眉页脚识别和标记（不删除，标记为非正文）
├─ 3.5 多栏排版识别（单栏/双栏/三栏）
├─ 3.6 版面质量评估（区域划分准确率、阅读顺序正确性）
└─ 3.7 输出：版面结构JSON + 区域坐标（为内容配对做准备）

步骤4：P4 结构预处理（桥梁，配对章节）
├─ 4.1 目录页识别和提取（自动定位目录页）
├─ 4.2 目录条目解析（章节标题、页码、层级）
├─ 4.3 章节结构树构建（章→节→知识点→考点）
├─ 4.4 大纲生成（基于目录和标题层级）
├─ 4.5 页码映射（目录页码与实际页面对应）
├─ 4.6 章节边界识别（每章起始页和结束页）
├─ 4.7 **章节配对**：PDF章节 ↔ 知识体系L1章/L2节
├─ 4.8 结构质量评估（目录提取准确率、章节完整性）
└─ 4.9 输出：结构树JSON + 章节大纲 + 页码映射 + 章节配对结果

步骤5：P5 内容预处理（核心，四类配对）
├─ 5.1 文字识别（PaddleOCR，中文+英文+数字）
├─ 5.2 公式识别（PaddleLaTeX，输出LaTeX）
├─ 5.3 表格识别（TableMaster，输出HTML/JSON）
├─ 5.4 图片提取和保存（WebP格式）
├─ 5.5 【配对1】知识点配对：
│   ├─ 从内容中识别知识点名称、定义、解释
│   ├─ 与知识体系104个L3知识点匹配
│   ├─ 匹配方式：精确匹配→关键词匹配→语义匹配
│   ├─ 记录来源文件、页码、上下文、置信度
│   └─ 未匹配的标记为"待新增知识点"
├─ 5.6 【配对2】题目配对：
│   ├─ 从内容中识别题目结构（题干、选项、答案、解析）
│   ├─ 与现有题库去重配对（MD5+四要素比对）
│   ├─ 自动配对知识点（题目↔L3知识点）
│   ├─ 自动判断题型、难度、来源（真题/模拟题/练习题）
│   └─ 暂存到预处理表，待审核后入库
├─ 5.7 【配对3】闪卡配对：
│   ├─ 从内容中识别知识点、公式、考点、口诀
│   ├─ 与现有闪卡库去重配对（相同知识点+相似度>=90%）
│   ├─ 自动配对知识点
│   ├─ 自动判断闪卡类型（概念卡/公式卡/口诀卡）
│   └─ 暂存到预处理表，待审核后入库
├─ 5.8 【配对4】导图配对：
│   ├─ 从目录和章节结构提取层级关系
│   ├─ 与知识体系L1/L2/L3配对
│   ├─ 自动生成导图节点结构
│   └─ 暂存到预处理表，待审核后生成
├─ 5.9 内容质量评估（识别准确率、配对准确率、置信度）
└─ 5.10 输出：结构化内容 + 四类配对结果（待审核）
```

### 3.3 配对结果存储（核心表设计）

```sql
-- 预处理配对结果表（核心表，存储所有配对结果）
CREATE TABLE IF NOT EXISTS preprocess_pairing (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_id INTEGER NOT NULL,              -- 来源文件ID
    page_num INTEGER,                      -- 来源页码
    pairing_type VARCHAR(32) NOT NULL,     -- 配对类型：knowledge_point/question/flashcard/mindmap
    source_content TEXT,                   -- 原始内容（知识点名称/题目/公式）
    target_id INTEGER,                     -- 配对目标ID（知识点ID/题目ID/闪卡ID/导图ID）
    target_type VARCHAR(32),               -- 配对目标类型
    match_method VARCHAR(32),              -- 匹配方式：exact/keyword/semantic
    match_confidence FLOAT,                -- 匹配置信度（0-1）
    context_text TEXT,                     -- 上下文（前后各100字）
    status VARCHAR(16) DEFAULT 'pending',  -- 状态：pending待审核/confirmed已确认/rejected已拒绝
    review_note TEXT,                      -- 审核备注
    reviewer_id INTEGER,                   -- 审核人ID
    review_time DATETIME,                  -- 审核时间
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_pp_file_id ON preprocess_pairing(file_id);
CREATE INDEX idx_pp_pairing_type ON preprocess_pairing(pairing_type);
CREATE INDEX idx_pp_status ON preprocess_pairing(status);
CREATE INDEX idx_pp_target ON preprocess_pairing(target_type, target_id);

-- 文件结构表（P4结构预处理结果）
CREATE TABLE IF NOT EXISTS file_structure (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_id INTEGER NOT NULL,
    structure_type VARCHAR(32) NOT NULL,  -- catalog/outline/chapter
    structure_json MEDIUMTEXT NOT NULL,   -- 结构树JSON
    page_mapping TEXT,                    -- 页码映射JSON
    quality_score FLOAT DEFAULT 0,        -- 结构质量评分
    is_manual_modified INTEGER DEFAULT 0, -- 是否人工修改过
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(file_id, structure_type)
);

-- 预处理任务表（预处理进度和状态）
CREATE TABLE IF NOT EXISTS preprocess_task (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_id INTEGER NOT NULL,
    task_type VARCHAR(32) NOT NULL,  -- P1/P2/P3/P4/P5
    status VARCHAR(16) DEFAULT 'pending',  -- pending/running/completed/failed
    progress INTEGER DEFAULT 0,      -- 进度0-100
    pairing_count INTEGER DEFAULT 0, -- 配对数量
    start_time DATETIME,
    end_time DATETIME,
    duration INTEGER DEFAULT 0,
    error_message TEXT,
    retry_count INTEGER DEFAULT 0,
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(file_id, task_type)
);
```

### 3.4 配对审核流程

```
步骤1：配对结果展示
├─ 按文件展示配对结果（知识点配对/题目配对/闪卡配对/导图配对）
├─ 展示配对内容、配对目标、置信度、来源页码
├─ 高置信度（>=0.9）默认勾选确认
├─ 中置信度（0.7-0.9）标记建议确认
└─ 低置信度（<0.7）标记待人工审核

步骤2：人工审核
├─ 造价专家逐批审核配对结果
├─ 支持批量确认（高置信度可一键确认）
├─ 支持修改配对目标（配对错误时重新选择）
├─ 支持拒绝配对（配对错误时标记拒绝）
└─ 支持新增知识点（未匹配到的知识点可新增）

步骤3：确认入库
├─ 知识点配对确认：更新知识点来源、关联文件
├─ 题目配对确认：题目入库，自动关联知识点，自动去重
├─ 闪卡配对确认：闪卡入库，自动关联知识点，自动去重
├─ 导图配对确认：生成思维导图，自动关联章节/知识点
└─ 所有入库操作记录日志，可追溯

步骤4：配对算法优化
├─ 统计人工审核结果（确认率、修改率、拒绝率）
├─ 分析配对错误原因
├─ 优化关键词库、匹配算法、语义模型
└─ 持续提升配对准确率
```

### 3.5 预处理配置管理

**配置参数清单**：

| 参数类别 | 参数名 | 默认值 | 可选值 | 说明 |
|----------|--------|--------|--------|------|
| 图像预处理 | 去水印强度 | 中 | 关/低/中/高 | 水印去除强度 |
| 图像预处理 | 倾斜校正阈值 | 5度 | 0-15度 | 超过此角度才校正 |
| 图像预处理 | 对比度增强级别 | 中 | 关/低/中/高 | 对比度增强级别 |
| OCR识别 | OCR引擎 | PaddleOCR | PaddleOCR/Tesseract/MinerU | 主识别引擎 |
| OCR识别 | 识别置信度阈值 | 0.5 | 0.3-0.9 | 低于此值标记低质量 |
| 配对配置 | 知识点配对置信度阈值 | 0.7 | 0.5-0.95 | 低于此值待人工审核 |
| 配对配置 | 题目配对置信度阈值 | 0.7 | 0.5-0.95 | 低于此值待人工审核 |
| 配对配置 | 闪卡配对置信度阈值 | 0.7 | 0.5-0.95 | 低于此值待人工审核 |
| 配对配置 | 自动确认置信度阈值 | 0.9 | 0.8-1.0 | 高于此值自动确认 |

### 3.6 预处理验收标准

| 检查项 | 标准 | 验证方法 |
|--------|------|----------|
| P1文件预处理成功率 | >=98% | 统计成功/总数 |
| P2图像预处理质量 | 清晰度>=80分，无倾斜 | 图像质量评估 |
| P3版面预处理准确率 | >=90% | 抽样人工核对 |
| P4目录提取准确率 | >=95% | 抽样人工核对 |
| P5文字识别准确率 | >=95% | 抽样人工核对 |
| P5公式识别准确率 | >=85% | 抽样人工核对 |
| **知识点配对准确率** | **>=90%** | **抽样人工核对（核心指标）** |
| **题目配对准确率** | **>=90%** | **抽样人工核对（核心指标）** |
| **闪卡配对准确率** | **>=85%** | **抽样人工核对（核心指标）** |
| 配对结果存储完整率 | 100%（四类配对全部存储） | 数据库查询 |
| 配对审核流程可用 | 100%（展示、审核、确认、入库） | 功能测试 |
| 预处理进度可监控 | 100%（实时进度展示） | 功能测试 |

---

## 四、"完成"标准实施细则

### 4.1 五级完成标准验收清单

#### L1 基础完成验收
- [ ] 数据库表结构完整，字段、索引、约束正确
- [ ] 代码编写完成，无语法错误（node --check / py_compile通过）
- [ ] 代码注释完整，关键逻辑有说明
- [ ] 代码符合编码规范（命名、格式、结构）

#### L2 接口完成验收
- [ ] 所有功能有对应RESTful API接口
- [ ] 接口参数、返回值、错误码定义清晰
- [ ] 接口文档完整（请求示例、响应示例、错误说明）
- [ ] 接口单元测试通过（正常、异常、边界情况）

#### L3 前端完成验收
- [ ] 前端界面可正常访问，无白屏、无报错
- [ ] 前端可调用API，数据可正常展示
- [ ] 界面操作流畅，无卡顿、无死锁
- [ ] 界面美观，符合设计规范（布局、配色、字体）
- [ ] 响应式适配正常（PC、平板、手机）

#### L4 验证完成验收
- [ ] 用真实数据测试，结果准确无误
- [ ] 性能达标（响应时间、并发量、资源占用）
- [ ] 异常处理完善（网络错误、数据错误、系统错误）
- [ ] 安全测试通过（XSS、CSRF、注入、权限）
- [ ] 边界情况测试通过（空数据、大数据、特殊字符）

#### L5 文档完成验收
- [ ] 使用文档完整（功能说明、操作步骤、注意事项）
- [ ] 监控告警完善（关键指标监控、异常告警）
- [ ] 日志记录完整（操作日志、错误日志、性能日志）
- [ ] 备份恢复机制完善（定期备份、可快速恢复）
- [ ] 验收报告完整（测试数据、测试结果、性能指标）

### 4.2 完成标准执行流程

```
步骤1：开发人员自验
├─ 按五级标准逐项检查
├─ 填写自验报告
└─ 自验不通过的立即修复

步骤2：测试专家验收
├─ 按五级标准逐项验证
├─ 用真实数据测试
├─ 性能测试、安全测试
├─ 填写验收报告
└─ 验收不通过的返回开发人员修复

步骤3：造价专家验收（业务相关功能）
├─ 业务逻辑正确性验证
├─ 专业内容准确性验证
├─ 学习效果评估
└─ 填写专业验收报告

步骤4：最终交付
├─ 所有验收通过
├─ 输出完整验收报告
├─ 文档归档
└─ 标记为"完成"
```

---

## 五、功能合并实施细则

### 5.1 功能合并执行步骤

```
步骤1：功能清单审计
├─ 列出所有功能模块
├─ 分析每个功能的职责边界
├─ 识别重复功能和职责不清的功能
└─ 输出功能审计报告

步骤2：合并方案制定
├─ 制定功能合并方案（哪些合并、哪些保留、哪些删除）
├─ 评估合并影响（数据迁移、接口变更、前端调整）
├─ 制定回滚方案
└─ 专家评审通过

步骤3：数据迁移
├─ 合并模块的数据迁移
├─ 数据一致性校验
├─ 旧数据兼容处理
└─ 数据迁移验证

步骤4：接口合并
├─ 合并重复的API接口
├─ 旧接口保留兼容期（30天）
├─ 接口文档更新
└─ 接口测试

步骤5：前端合并
├─ 合并重复的前端页面
├─ 菜单结构调整
├─ 跳转链接更新
└─ 前端测试

步骤6：验证上线
├─ 全流程测试
├─ 性能测试
├─ 用户体验测试
└─ 正式上线
```

### 5.2 当前待合并功能清单

| 序号 | 功能 | 合并方案 | 优先级 | 状态 |
|------|------|----------|--------|------|
| 1 | 记忆闪卡 + 记忆训练 | 记忆闪卡放入记忆训练，作为子功能 | P0 | 待执行 |
| 2 | 题库新增/识别 | 移到学习资料库 | P0 | 待执行 |
| 3 | 闪卡新增/生成 | 移到学习资料库 | P0 | 待执行 |
| 4 | 视频讲义资料管理 | 只保留播放，资料管理移到资料库 | P1 | 待执行 |
| 5 | 章节教材文件管理 | 只保留拆分管理，文件管理移到资料库 | P1 | 待执行 |

---

## 六、标签系统实施细则

### 6.1 标签系统实施步骤

```
步骤1：标签库建立
├─ 建立预设标签（真题、模拟题、精题、练习题、题库、闪卡、思维导图、知识点分布）
├─ 标签优先级定义（真题>模拟题>精题>练习题）
├─ 标签颜色和图标定义
└─ 标签库存储到数据库

步骤2：自动打标签
├─ 根据文件名自动打标签（含"真题"打真题标签）
├─ 根据文件夹名自动打标签（含"知识点精讲"打知识点分布标签）
├─ 根据文件内容自动打标签（AI分析内容）
└─ 自动打标签后支持人工修改

步骤3：手动打标签
├─ 单条记录打标签（下拉多选）
├─ 文件夹批量打标签（整个文件夹所有文件）
├─ 标签选择后立即保存
└─ 批量修改后文件夹内所有记录同步

步骤4：标签应用
├─ 按标签筛选文件
├─ 按标签触发功能（题库标签→识别题库，闪卡标签→生成闪卡）
├─ 标签统计分析
└─ 标签优化建议

步骤5：标签验证
├─ 标签准确性检查（自动标签与内容匹配度）
├─ 标签覆盖率统计
├─ 用户反馈收集
└─ 标签算法优化
```

### 6.2 标签优先级判定规则

```
对于讲义中的题目：
1. 先判断是否是真题（含年份、"真题"字样、题目格式符合真题）
   ├─ 是 → 打"真题"标签（最高优先级）
   └─ 否 → 继续判断
2. 再判断是否是模拟题（含"模拟"、"模考"字样）
   ├─ 是 → 打"模拟题"标签
   └─ 否 → 继续判断
3. 再判断是否是精题（含"精题"、"必练"、"经典"字样）
   ├─ 是 → 打"精题"标签
   └─ 否 → 继续判断
4. 都不是 → 打"练习题"标签（最低优先级）
```

---

## 七、学习资料库架构实施细则

### 7.1 三层架构实施步骤

```
步骤1：全部文件（源数据层）
├─ 所有文件的唯一入口
├─ 负责文件上传、管理、打标签、识别、生成
├─ 以记录形式展示（表格），不是缩略图
├─ 按照文件夹层次显示，保留原始文件夹结构
├─ 支持单条删除、批量删除
└─ 支持批量标签、识别题库、生成闪卡、生成导图

步骤2：大纲/教材（引用层）
├─ 从全部文件引用（文件类型为"教材"或"大纲"的文件）
├─ 只负责预览，无删除、无重命名
├─ 靠左布局，表格形式
└─ 点击文件跳转到预览

步骤3：视频讲义（引用层）
├─ 从全部文件引用（文件类型为"视频"或"讲义"的文件）
├─ 只负责播放和同步滚动，无删除、无重命名
├─ 视频和讲义分两列，同步对应滚动
├─ 视频和讲义文件夹结构同步
└─ 点击文件开始播放
```

### 7.2 学习资料库验收标准

| 检查项 | 标准 | 验证方法 |
|--------|------|----------|
| 全部文件展示 | 表格形式，记录展示，非缩略图 | 界面检查 |
| 文件夹层次 | 保留原始文件夹结构，底层文件夹名称显示 | 界面检查 |
| 标签功能 | 支持多选，批量修改后单条同步 | 功能测试 |
| 大纲/教材 | 只有预览，无删除重命名 | 功能测试 |
| 视频讲义 | 两列布局，同步滚动，无删除重命名 | 功能测试 |
| 数据源唯一性 | 全部文件是唯一数据源，其他tab引用 | 架构检查 |

---

## 八、数据质量监控实施细则

### 8.1 每日自动检查清单

| 序号 | 检查项 | 标准 | 检查方法 | 异常处理 |
|------|--------|------|----------|----------|
| 1 | 题库题干非空 | 100% | SQL查询 | 标记异常，待修复 |
| 2 | 题库答案非空 | 100% | SQL查询 | 标记异常，待修复 |
| 3 | 题库知识点关联率 | >=95% | SQL查询 | 优化关联算法 |
| 4 | 闪卡正面非空 | 100% | SQL查询 | 标记异常，待修复 |
| 5 | 闪卡背面非空 | 100% | SQL查询 | 标记异常，待修复 |
| 6 | 闪卡知识点关联率 | >=90% | SQL查询 | 优化关联算法 |
| 7 | 闪卡数量控制 | 每科目500-1000张 | SQL查询 | 触发去重流程 |
| 8 | 资料库文件名非空 | 100% | SQL查询 | 标记异常，待修复 |
| 9 | 识别覆盖率 | 100% | SQL查询 | 触发未识别文件扫描 |
| 10 | 全文索引覆盖率 | 100% | SQL查询 | 重建索引 |
| 11 | 向量索引覆盖率 | >=90% | SQL查询 | 触发向量化 |
| 12 | 重复题目数量 | <5% | SQL查询 | 触发去重流程 |
| 13 | 重复闪卡数量 | <5% | SQL查询 | 触发去重流程 |
| 14 | 数据库表完整性 | 所有表存在 | PRAGMA检查 | 自动创建缺失表 |
| 15 | 数据库索引完整性 | 所有索引存在 | PRAGMA检查 | 自动创建缺失索引 |

### 8.2 质量评分计算

```
总体质量评分 = 各项指标加权平均

权重分配：
- 数据完整性（非空、完整）：30%
- 数据准确性（关联正确、内容正确）：30%
- 去重效果（重复率低）：20%
- 索引完整性（全文、向量）：10%
- 识别覆盖率（OCR识别）：10%

评分等级：
- >=90分：优秀
- 80-89分：良好
- 70-79分：一般
- 60-69分：较差
- <60分：严重，必须立即修复
```

### 8.3 质量监控实施步骤

```
步骤1：建立质量监控表（已完成data_quality_report）
步骤2：编写自动检查脚本（每日执行）
步骤3：建立质量评分算法
步骤4：建立异常告警机制（质量<80分自动告警）
步骤5：建立质量报告生成机制（每日生成报告）
步骤6：建立质量问题跟踪机制（问题→修复→验证→关闭）
步骤7：建立质量趋势分析（每周、每月质量趋势）
```

---

## 九、字段设计与功能设计规范（61位专家联合审查结论，必须严格遵守）

### 9.1 识别储存相关表字段清单（必须全部包含）

#### 9.1.1 file_content表（识别内容主表）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | INTEGER | 是 | 主键 |
| file_id | INTEGER | 是 | 关联fl_file_library.id，UNIQUE |
| file_hash | VARCHAR(64) | 是 | 文件哈希，判断文件是否变更需要重扫 |
| pdf_type | VARCHAR(16) | 是 | PDF类型：text文字版/scanned扫描版/mixed混合版 |
| subject | VARCHAR(64) | 是 | 科目 |
| file_type | VARCHAR(32) | 是 | 文件类型 |
| preprocess_status | VARCHAR(16) | 是 | 预处理状态：scanned/paired/imported |
| total_pages | INTEGER | 是 | 总页数 |
| total_chars | INTEGER | 是 | 总字符数 |
| total_formulas | INTEGER | 是 | 公式总数 |
| total_tables | INTEGER | 是 | 表格总数 |
| total_images | INTEGER | 是 | 图片总数 |
| content_text | MEDIUMTEXT | 是 | 纯文本内容（按页分隔） |
| content_json | MEDIUMTEXT | 是 | 结构化内容JSON |
| ocr_engine | VARCHAR(32) | 是 | 主识别引擎 |
| ocr_engines_used | VARCHAR(128) | 是 | 使用的所有引擎 |
| avg_accuracy | FLOAT | 是 | 平均识别置信度 |
| status | VARCHAR(16) | 是 | 状态：pending/scanning/completed/failed |
| scan_start_time | DATETIME | 建议 | 扫描开始时间 |
| scan_end_time | DATETIME | 建议 | 扫描结束时间 |
| scan_duration | INTEGER | 是 | 扫描耗时（秒） |
| is_indexed | INTEGER | 是 | 是否已建立全文索引 |
| is_vectorized | INTEGER | 是 | 是否已建立向量索引 |
| is_analyzed | INTEGER | 是 | 是否已进行知识点分析 |
| error_message | TEXT | 建议 | 错误信息 |
| is_deleted | INTEGER | 是 | 软删除标记，默认0 |
| create_time | DATETIME | 是 | 创建时间 |
| update_time | DATETIME | 是 | 更新时间 |

**必须建立的索引**：idx_fc_file_id(UNIQUE)、idx_fc_file_hash、idx_fc_subject、idx_fc_status、idx_fc_preprocess_status、idx_fc_is_indexed

#### 9.1.2 file_page_content表（页面内容表）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | INTEGER | 是 | 主键 |
| file_id | INTEGER | 是 | 关联文件ID |
| page_num | INTEGER | 是 | 页码（从1开始） |
| chapter | VARCHAR(128) | 建议 | 页面所属章（冗余字段，提升查询性能） |
| section | VARCHAR(128) | 建议 | 页面所属节（冗余字段，提升查询性能） |
| content_text | TEXT | 是 | 该页纯文本 |
| content_json | TEXT | 是 | 该页结构化内容 |
| char_count | INTEGER | 是 | 该页字符数 |
| formula_count | INTEGER | 是 | 该页公式数 |
| table_count | INTEGER | 是 | 该页表格数 |
| image_count | INTEGER | 是 | 该页图片数 |
| has_title | INTEGER | 是 | 是否包含标题 |
| title_text | VARCHAR(256) | 建议 | 标题文本 |
| page_accuracy | FLOAT | 是 | 该页识别置信度 |
| image_path | VARCHAR(256) | 建议 | 页面图片路径 |
| is_deleted | INTEGER | 是 | 软删除标记 |
| create_time | DATETIME | 是 | 创建时间 |

**必须建立的索引**：idx_fpc_file_page(UNIQUE)、idx_fpc_file_id、idx_fpc_chapter、idx_fpc_section、idx_fpc_has_title

#### 9.1.3 file_content_block表（内容块表）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | INTEGER | 是 | 主键 |
| file_id | INTEGER | 是 | 关联文件ID |
| page_num | INTEGER | 是 | 页码 |
| block_id | INTEGER | 是 | 块ID（页内顺序） |
| parent_block_id | INTEGER | 建议 | 父块ID，支持层级结构（标题→正文） |
| block_type | VARCHAR(32) | 是 | 块类型：title/text/formula/table/image/list/caption/footnote/header/footer |
| content_text | TEXT | 是 | 块文本内容 |
| content_json | TEXT | 建议 | 块结构化内容 |
| level | INTEGER | 建议 | 标题层级（1-6，仅标题块） |
| bbox | VARCHAR(64) | 建议 | bounding box坐标 |
| confidence | FLOAT | 是 | 识别置信度 |
| is_deleted | INTEGER | 是 | 软删除标记 |
| create_time | DATETIME | 是 | 创建时间 |

**必须建立的索引**：idx_fcb_file_page、idx_fcb_block_type、idx_fcb_parent_id

#### 9.1.4 file_formula表（公式表）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | INTEGER | 是 | 主键 |
| file_id | INTEGER | 是 | 关联文件ID |
| page_num | INTEGER | 是 | 页码 |
| formula_latex | TEXT | 是 | 公式LaTeX表达式 |
| formula_image_path | VARCHAR(256) | 建议 | 公式原始图片路径（LaTeX识别失败时用图片代替） |
| formula_text | VARCHAR(256) | 建议 | 公式文本描述 |
| context_text | TEXT | 建议 | 公式上下文 |
| confidence | FLOAT | 是 | 识别置信度 |
| is_deleted | INTEGER | 是 | 软删除标记 |
| create_time | DATETIME | 是 | 创建时间 |

#### 9.1.5 preprocess_pairing表（配对结果表）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | INTEGER | 是 | 主键 |
| batch_id | VARCHAR(64) | 是 | 批次ID，支持批量管理和回滚 |
| file_id | INTEGER | 是 | 来源文件ID |
| page_num | INTEGER | 建议 | 来源页码 |
| pairing_type | VARCHAR(32) | 是 | 配对类型：knowledge_point/question/flashcard/mindmap |
| source_content | TEXT | 是 | 原始内容 |
| source_text_hash | VARCHAR(64) | 是 | 源内容哈希，配对去重用 |
| target_id | INTEGER | 建议 | 配对目标ID |
| target_type | VARCHAR(32) | 建议 | 配对目标类型 |
| match_method | VARCHAR(32) | 是 | 匹配方式：exact/keyword/semantic |
| match_confidence | FLOAT | 是 | 匹配置信度（0-1） |
| context_text | TEXT | 建议 | 上下文 |
| status | VARCHAR(16) | 是 | 状态：pending待审核/confirmed已确认/rejected已拒绝 |
| review_note | TEXT | 建议 | 审核备注 |
| reviewer_id | INTEGER | 建议 | 审核人ID |
| review_time | DATETIME | 建议 | 审核时间 |
| is_deleted | INTEGER | 是 | 软删除标记 |
| create_time | DATETIME | 是 | 创建时间 |
| update_time | DATETIME | 是 | 更新时间 |

**必须建立的索引**：idx_pp_file_id、idx_pp_pairing_type、idx_pp_status、idx_pp_batch_id、idx_pp_source_hash、idx_pp_target

### 9.2 题库表字段规范（必须增加的字段）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| question_no | VARCHAR(32) | 建议 | 原题号（如"一、单项选择题1."） |
| options_json | TEXT | 建议 | 结构化选项（A/B/C/D/E） |
| source_file_id | INTEGER | 建议 | 来源文件ID，题目可追溯到原始PDF |
| source_page | INTEGER | 建议 | 来源页码 |
| parent_question_id | INTEGER | 建议 | 父题目ID，支持案例题→小问层级结构 |
| year | INTEGER | 建议 | 真题年份 |
| question_type | VARCHAR(32) | 是 | 题型：single/multiple/judge/case/case_sub |
| source | VARCHAR(64) | 建议 | 来源：真题/模拟题/精题/练习题 |
| difficulty | FLOAT | 建议 | 难度（0-1） |
| has_image | INTEGER | 是 | 题目是否包含图片（0/1） |
| has_table | INTEGER | 是 | 题目是否包含表格（0/1） |
| question_images | TEXT | 建议 | 题目中的图片ID列表（JSON数组，关联file_image表） |
| question_tables | TEXT | 建议 | 题目中的表格ID列表（JSON数组，关联file_table表） |

**题库识别中图片和表格处理实施要点**：

```
题目识别流程（包含图片和表格）：
步骤1：题目区域检测
├─ 检测题干、选项、答案、解析区域
├─ 检测题目区域内的图片（示意图、工程图、图表）
├─ 检测题目区域内的表格（数据表、参数表、对比表）
└─ 记录图片和表格的位置坐标

步骤2：图片提取和处理
├─ 提取题目中的图片，保存到file_image表
├─ 对图片进行OCR识别，提取图片中的文字（标注、参数）
├─ 图片文字加入题目内容，支持搜索
├─ 计算图片感知哈希，用于去重
└─ 通过question_images字段关联到题目

步骤3：表格提取和处理
├─ 提取题目中的表格，保存到file_table表
├─ 表格转换为结构化JSON（行列数据）
├─ 表格转换为纯文本，加入全文索引
├─ 计算表格内容相似度，用于去重
└─ 通过question_tables字段关联到题目

步骤4：题目展示
├─ 题目文字按原顺序展示
├─ 图片在对应位置显示，支持点击放大
├─ 表格在对应位置完整渲染（HTML表格）
└─ 案例题小问继承父题的图片和表格

步骤5：题目去重（包含图片表格）
├─ 文字去重：题干+选项+答案+解析四要素比对
├─ 图片去重：图片感知哈希比对
├─ 表格去重：表格内容相似度比对（>=95%）
└─ 图文都一致才算重复，保留质量最高版本
```

### 9.3 闪卡表字段规范（必须增加的字段）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| card_type | VARCHAR(32) | 是 | 闪卡类型：concept/formula/mnemonic/comparison/error/process |
| difficulty | FLOAT | 建议 | 难度（0-1），SM-2算法考虑难度因子 |
| related_question_ids | TEXT | 建议 | 相关题目ID列表，闪卡复习时可查看相关题目 |
| front_format | VARCHAR(16) | 是 | 正面格式：text/latex/html |
| back_format | VARCHAR(16) | 是 | 背面格式：text/latex/html |

**闪卡类型说明**：
- concept：概念卡（知识点定义、含义）
- formula：公式卡（公式、计算方法）
- mnemonic：口诀卡（记忆口诀、顺口溜）
- comparison：对比卡（易混知识点对比）
- error：易错点卡（常见错误、陷阱）
- process：计算流程卡（计算步骤、流程）

### 9.4 思维导图相关表字段规范

**mind_maps表必须增加**：
- node_count INTEGER：节点总数（冗余字段）
- max_depth INTEGER：最大深度（冗余字段）

**mind_map_nodes表必须增加**：
- knowledge_point_id INTEGER：关联的知识点ID，点击节点可查看相关题目/闪卡

### 9.5 功能设计清单（必须全部实现）

#### 9.5.1 识别功能清单

| 序号 | 功能 | 说明 | 验收标准 |
|------|------|------|----------|
| 1 | PDF文本层检测 | 文字版PDF直接提取文本，跳过OCR | 文字版PDF识别速度提升10倍，准确率>=99% |
| 2 | 识别置信度分级处理 | >=0.9自动通过，0.7-0.9待审核，<0.7需重扫 | 低质量内容100%标记 |
| 3 | 公式双保存 | LaTeX+原始图片同时保存 | LaTeX识别失败时可用图片代替 |
| 4 | 断点续扫 | 中断后从断点继续 | 不重复扫描已完成文件 |
| 5 | 扫描进度实时推送 | WebSocket/SSE推送 | 进度实时更新，无延迟 |

#### 9.5.2 配对功能清单

| 序号 | 功能 | 说明 | 验收标准 |
|------|------|------|----------|
| 1 | 三层匹配机制 | 精确→关键词→语义 | 配对准确率>=90% |
| 2 | 知识点扩展关键词库 | 每个知识点10-20个专业关键词 | 关键词覆盖率>=95% |
| 3 | AI辅助题目识别 | 正则+AI判断 | 题目召回率>=95% |
| 4 | 闪卡判定规则 | 正面<=50字、不含选项、是知识点/公式/口诀 | 闪卡误判率<5% |
| 5 | 标题层级自动识别 | 字体大小、加粗、编号 | 层级识别准确率>=90% |

#### 9.5.3 审核功能清单

| 序号 | 功能 | 说明 | 验收标准 |
|------|------|------|----------|
| 1 | 左右对比视图 | 左边原始内容，右边配对结果 | 审核效率提升50% |
| 2 | 快捷键审核 | 确认/拒绝/下一条 | 支持键盘操作 |
| 3 | 批量确认 | 高置信度一键确认 | 批量操作可用 |
| 4 | 配对批次管理 | 按批次查看、回滚 | 批次管理可用 |

#### 9.5.4 用户体验功能清单

| 序号 | 功能 | 说明 | 验收标准 |
|------|------|------|----------|
| 1 | 扫描进度可视化 | 进度条、当前文件名、已完成/总数、预计剩余时间 | 进度展示清晰 |
| 2 | 完成提示音 | 批量操作完成后播放提示音（可配置） | 提示音可开关 |
| 3 | 选中状态反馈 | 选中计数、批量操作栏、全选/反选 | 选中状态清晰 |
| 4 | 操作结果即时反馈 | 成功/失败提示，失败显示原因和重试 | 反馈及时准确 |

#### 9.5.5 数据治理功能清单

| 序号 | 功能 | 说明 | 验收标准 |
|------|------|------|----------|
| 1 | 数据血缘追踪 | 记录来源文件、处理过程、变更历史 | 数据可追溯 |
| 2 | 质量趋势分析 | 每日质量评分记录，趋势分析 | 趋势图可用 |
| 3 | 知识点去重 | 名称相同+章节相同=重复 | 去重准确率>=95% |
| 4 | 导图去重 | 结构相似度>=90%=重复 | 去重准确率>=90% |
| 5 | L4细分考点 | 知识点体系增加第四层级 | L1→L2→L3→L4完整 |

---

## 十、实施优先级与时间规划

### 10.1 第一优先级（立即执行，1周内）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | 题库去重（三层去重，物理删除） | 2天 | 题库识别算法专家、造价专家 | 去重准确率>=95%，题目数量合理 |
| 2 | 闪卡去重（相同知识点合并，数量控制） | 2天 | 闪卡SM-2算法专家、造价专家 | 每科目500-1000张，无重复 |
| 3 | FTS5中文搜索修复（已完成） | 0.5天 | 数据库架构专家 | 中文搜索正常，结果准确 |
| 4 | 原始内容存储表建立（已完成） | 0.5天 | 数据库架构专家 | 7张表建立完成 |
| 5 | 数据质量每日自动检查 | 1天 | 数据治理专家 | 15项检查每日自动执行 |

### 9.2 第二优先级（2周内）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | 功能合并（闪卡入记忆训练等） | 3天 | 系统架构专家、前端专家 | 功能合并完成，无重复 |
| 2 | 标签系统完善（多选、批量同步） | 2天 | 前端专家、开发专家 | 标签多选可用，批量同步 |
| 3 | 学习资料库三层架构完善 | 3天 | 前端专家、开发专家 | 全部文件为源，其他tab引用 |
| 4 | 知识点关联率提升（题库>=95%，闪卡>=90%） | 3天 | AI专家、造价专家 | 关联率达标 |
| 5 | API接口完善（所有新功能有API） | 2天 | API接口设计专家 | API完整，文档齐全 |

### 9.3 第三优先级（1个月内）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | OCR全量扫描存储实施 | 1周 | OCR专家、AI专家 | 识别覆盖率100%，准确率>=95% |
| 2 | 向量索引建立（语义检索） | 3天 | AI专家、数据库专家 | 向量覆盖率>=90%，检索准确率>=85% |
| 3 | AI大脑对话记录机制 | 2天 | AI专家 | 对话记录完整，可检索分析 |
| 4 | 智能答疑功能 | 5天 | AI专家、开发专家 | 答疑准确率>=85% |
| 5 | 数据质量监控面板 | 2天 | 数据可视化专家 | 质量评分实时展示，异常告警 |

### 9.4 第四优先级（长期持续）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | 识别引擎优化升级 | 持续 | OCR专家、AI专家 | 准确率持续提升 |
| 2 | 去重算法优化 | 持续 | AI专家、造价专家 | 去重准确率持续提升 |
| 3 | 数据质量持续优化 | 持续 | 数据治理专家 | 质量评分持续提升 |
| 4 | 知识库持续完善 | 持续 | 所有专家 | 12类知识库全部完善 |
| 5 | 系统性能持续优化 | 持续 | 性能优化专家 | 性能指标持续提升 |

---

## 十、风险与应对

| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|----------|
| 去重误判导致有效数据丢失 | 数据丢失，影响学习 | 中 | 去重前备份，造价专家复核，误判可恢复 |
| 原始内容存储占用空间过大 | 存储空间不足 | 低 | 压缩优化，按需加载，定期清理缓存 |
| 功能合并导致功能异常 | 用户体验下降 | 中 | 增量合并，充分测试，保留回滚方案 |
| 自动标签准确率低 | 标签混乱，影响功能 | 中 | 人工审核机制，持续优化算法 |
| 数据质量检查误报 | 告警过多，忽略真实问题 | 低 | 优化检查规则，分级告警 |
| OCR识别准确率不达标 | 内容错误，影响后续功能 | 中 | 多引擎融合，人工校对，持续优化 |

---

## 十一、验收标准（必须全部满足）

### ✅ 语法层
- 所有代码无语法错误（node --check / py_compile通过）
- 数据库表结构完整，索引正确
- API接口定义清晰，文档完整

### ✅ 运行层
- 系统无白屏、无阻断性报错
- 所有功能可正常访问和操作
- 性能达标（响应时间<500ms，并发正常）
- 数据质量监控正常运行

### ✅ 业务层
- 题库去重完成，无重复题目，去重准确率>=95%
- 闪卡去重完成，每科目500-1000张，无重复闪卡
- 知识点关联率达标（题库>=95%，闪卡>=90%）
- 标签系统正常（多选、批量同步、自动打标签）
- 学习资料库三层架构正常（全部文件为源，其他tab引用）
- 原始内容完整存储（L0-L4五层架构）
- 全文搜索正常（中文搜索准确，响应<500ms）

### ✅ 质量层
- 数据质量评分>=90分
- 每日自动检查正常运行
- 异常问题有跟踪、有修复、有验证
- 所有功能达到L5完成标准

---

> **本细则为活文档，随着系统迭代和专家经验持续更新。数据去杂与质量治理是系统的生命线，必须优先执行、严格标准、持续监控、不断优化。去杂优先、原始保护、物理去重、严格标准、持续监控。**



============================================================
# § 识别储存与内容知识库分册_V2.0_详细版.md
============================================================

# 水利智学系统 识别储存与内容知识库分册（V2.0 详细版）

> **版本**：V2.0（详细版）
> **生效日期**：2026-09-06
> **地位**：本文件为《系统设计宪法》和《规划细则分册》的核心配套专项分册，专门规划学习资料的识别、储存、索引、查询、分析全流程。所有PDF/Word/Excel等学习资料必须进行全量识别并结构化存储，建立内容知识库，避免每次识别文件，为后续的知识点提取、题目识别、闪卡生成、智能答疑、考点分析提供数据基础。
> **制定委员会**：61位全球顶级专家联合制定，OCR识别专家、AI专家、数据库架构专家、NLP专家、造价专家、教研专家、数据分析师联合策划。
> **核心原则**：一次识别，永久使用；结构化存储，多维索引；质量可控，持续优化；全面分析，深度挖掘。

---

## 一、识别储存体系总体架构

### 1.1 体系定位

**核心定位**：对学习资料库中的所有文件进行全量识别，将识别结果结构化存储，建立统一的内容知识库，为整个系统的智能化提供数据基础。

**在系统中的位置**：
```
学习资料库（原始文件）
        ↓
   识别储存体系（本分册）
        ↓
   内容知识库（结构化数据 + 多维索引）
        ↓
   应用层（知识点提取、题目识别、闪卡生成、智能答疑、考点分析、全文搜索）
```

### 1.2 体系目标

| 目标 | 量化标准 | 验证方法 |
|------|----------|----------|
| 识别覆盖率 | 学习资料库文件100%识别 | 统计已识别文件数/总文件数 |
| 识别准确率 | 文字>=95%，公式>=85%，表格>=80% | 抽样人工核对（至少5%） |
| 存储完整性 | 文字、公式、表格、图片100%存储 | 内容检查 |
| 查询响应时间 | 全文搜索<500ms，语义检索<1秒 | 性能测试 |
| 数据一致性 | 识别内容与原始文件一致性>=95% | 抽样对比 |
| 可扩展性 | 支持新增文件自动识别，支持增量更新 | 功能测试 |

### 1.3 识别储存流水线

```
┌─────────────────────────────────────────────────────────────────┐
│                        识别储存流水线                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  输入层：学习资料库文件（PDF/Word/Excel/图片）                     │
│       ↓                                                         │
│  预处理层：文件解析 → 去水印 → 倾斜校正 → 分页 → 图像增强          │
│       ↓                                                         │
│  识别层：文字识别 → 公式识别 → 表格识别 → 版面分析 → 图片提取      │
│       ↓                                                         │
│  后处理层：错别字校正 → 格式规范化 → 语义校验 → 结构化解析        │
│       ↓                                                         │
│  存储层：原始文本存储 → 结构化JSON存储 → 图片缓存存储             │
│       ↓                                                         │
│  索引层：全文索引（FTS5）→ 向量索引 → 知识点索引 → 标签索引       │
│       ↓                                                         │
│  应用层：全文搜索 → 语义检索 → 知识点提取 → 题目识别 → 闪卡生成   │
│           → 智能答疑 → 考点分析 → 跨文件关联                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 二、识别引擎选型与配置

### 2.1 识别引擎选型矩阵

| 引擎 | 类型 | 中文识别 | 公式识别 | 表格识别 | 速度 | 资源占用 | 开源 | 推荐度 |
|------|------|----------|----------|----------|------|----------|------|--------|
| **PaddleOCR** | 深度学习OCR | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 中 | 中 | 是 | ⭐⭐⭐⭐⭐ 主力 |
| **PaddleLaTeX** | 公式识别 | - | ⭐⭐⭐⭐⭐ | - | 中 | 中 | 是 | ⭐⭐⭐⭐⭐ 公式专用 |
| **TableMaster** | 表格识别 | - | - | ⭐⭐⭐⭐⭐ | 中 | 中 | 是 | ⭐⭐⭐⭐ 表格专用 |
| **Tesseract** | 传统OCR | ⭐⭐⭐ | ⭐ | ⭐ | 快 | 低 | 是 | ⭐⭐⭐ 备选 |
| **Ollama VL** | 多模态大模型 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 慢 | 高 | 是 | ⭐⭐⭐⭐ 复杂版面辅助 |
| **MinerU** | 文档解析 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 中 | 中 | 是 | ⭐⭐⭐⭐⭐ PDF专用 |

**最终选型方案**：
- **主力引擎**：MinerU（PDF文档解析，支持文字、公式、表格、版面分析）
- **辅助引擎**：PaddleOCR（图片OCR，补充识别）
- **公式专用**：PaddleLaTeX（公式识别，LaTeX输出）
- **复杂版面**：Ollama VL（语义理解，复杂版面解析）
- **备选引擎**：Tesseract（轻量级，快速识别）

### 2.2 识别引擎配置参数

**MinerU配置**：
```python
config = {
    "model": "mineru-v2",
    "language": "ch",
    "device": "cpu",  # 或cuda
    "batch_size": 1,
    "text_threshold": 0.8,  # 文字识别置信度阈值
    "formula": True,  # 启用公式识别
    "table": True,  # 启用表格识别
    "layout": True,  # 启用版面分析
    "image": True,  # 启用图片提取
    "output_format": "json",  # 输出格式
}
```

**PaddleOCR配置**：
```python
config = {
    "lang": "ch",
    "use_angle_cls": True,
    "det_model_dir": "ch_PP-OCRv4_det",
    "rec_model_dir": "ch_PP-OCRv4_rec",
    "cls_model_dir": "ch_ppocr_mobile_v2.0_cls",
    "drop_score": 0.5,  # 识别置信度阈值
}
```

### 2.3 识别引擎降级策略

| 场景 | 主力引擎 | 降级引擎 | 触发条件 |
|------|----------|----------|----------|
| 普通PDF | MinerU | PaddleOCR | MinerU识别失败或置信度<0.5 |
| 扫描版PDF | PaddleOCR | Tesseract | PaddleOCR识别失败 |
| 复杂公式 | PaddleLaTeX | Ollama VL | 公式识别置信度<0.6 |
| 复杂表格 | TableMaster | Ollama VL | 表格识别失败 |
| 复杂版面 | Ollama VL | 人工标注 | 版面分析置信度<0.5 |
| 批量快速识别 | Tesseract | PaddleOCR | 用户选择快速模式 |

---

## 三、存储结构设计（核心）

### 3.1 数据库表结构

#### 3.1.1 文件内容主表（file_content）

| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | INTEGER | 是 | 主键，自增 | 1 |
| file_id | INTEGER | 是 | 关联fl_file_library.id | 72 |
| subject | VARCHAR(64) | 是 | 科目 | 一造管理 |
| file_type | VARCHAR(32) | 是 | 文件类型：pdf/word/excel | pdf |
| total_pages | INTEGER | 是 | 总页数 | 50 |
| total_chars | INTEGER | 是 | 总字符数 | 25000 |
| total_formulas | INTEGER | 是 | 公式总数 | 15 |
| total_tables | INTEGER | 是 | 表格总数 | 3 |
| total_images | INTEGER | 是 | 图片总数 | 8 |
| content_text | MEDIUMTEXT | 是 | 纯文本内容（按页分隔，用\n\n===PAGE_BREAK===\n\n分隔） | 第1页内容...\n\n===PAGE_BREAK===\n\n第2页内容... |
| content_json | MEDIUMTEXT | 是 | 结构化内容（JSON格式，包含每页的详细结构） | {"pages": [{"page_num": 1, "blocks": [...]}]} |
| ocr_engine | VARCHAR(32) | 是 | 主识别引擎 | MinerU |
| ocr_engines_used | VARCHAR(128) | 是 | 使用的所有引擎（逗号分隔） | MinerU,PaddleLaTeX |
| avg_accuracy | FLOAT | 是 | 平均识别置信度（0-1） | 0.92 |
| status | VARCHAR(16) | 是 | 状态：pending/scanning/completed/failed | completed |
| scan_start_time | DATETIME | 建议 | 扫描开始时间 | 2026-09-06 14:00:00 |
| scan_end_time | DATETIME | 建议 | 扫描结束时间 | 2026-09-06 14:02:00 |
| scan_duration | INTEGER | 是 | 扫描耗时（秒） | 120 |
| is_indexed | INTEGER | 是 | 是否已建立全文索引：0/1 | 1 |
| is_vectorized | INTEGER | 是 | 是否已建立向量索引：0/1 | 1 |
| is_analyzed | INTEGER | 是 | 是否已进行知识点分析：0/1 | 0 |
| error_message | TEXT | 建议 | 错误信息（扫描失败时） | - |
| create_time | DATETIME | 是 | 创建时间 | 2026-09-06 14:00:00 |
| update_time | DATETIME | 是 | 更新时间 | 2026-09-06 14:02:00 |

**索引**：
- `idx_fc_file_id` (file_id) - UNIQUE
- `idx_fc_subject` (subject)
- `idx_fc_status` (status)
- `idx_fc_is_indexed` (is_indexed)
- `idx_fc_is_vectorized` (is_vectorized)
- `idx_fc_is_analyzed` (is_analyzed)

#### 3.1.2 页面内容表（file_page_content）

| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | INTEGER | 是 | 主键，自增 | 1 |
| file_id | INTEGER | 是 | 关联文件ID | 72 |
| page_num | INTEGER | 是 | 页码（从1开始） | 1 |
| content_text | TEXT | 是 | 该页纯文本 | 工程造价含义... |
| content_json | TEXT | 是 | 该页结构化内容（JSON） | {"blocks": [...]} |
| char_count | INTEGER | 是 | 该页字符数 | 500 |
| formula_count | INTEGER | 是 | 该页公式数 | 1 |
| table_count | INTEGER | 是 | 该页表格数 | 0 |
| image_count | INTEGER | 是 | 该页图片数 | 1 |
| has_title | INTEGER | 是 | 是否包含标题：0/1 | 1 |
| title_text | VARCHAR(256) | 建议 | 标题文本 | 第一节 工程造价基本内容 |
| page_accuracy | FLOAT | 是 | 该页识别置信度 | 0.95 |
| image_path | VARCHAR(256) | 建议 | 页面图片路径（WebP格式） | ocr_images/72/page_1.webp |
| create_time | DATETIME | 是 | 创建时间 | 2026-09-06 14:00:00 |

**索引**：
- `idx_fpc_file_page` (file_id, page_num) - UNIQUE
- `idx_fpc_file_id` (file_id)
- `idx_fpc_has_title` (has_title)

#### 3.1.3 内容块表（file_content_block）

| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | INTEGER | 是 | 主键，自增 | 1 |
| file_id | INTEGER | 是 | 关联文件ID | 72 |
| page_num | INTEGER | 是 | 页码 | 1 |
| block_id | INTEGER | 是 | 块ID（页内顺序） | 1 |
| block_type | VARCHAR(32) | 是 | 块类型：title/text/formula/table/image/list | title |
| content_text | TEXT | 是 | 块文本内容 | 第一节 工程造价基本内容 |
| content_json | TEXT | 建议 | 块结构化内容（公式LaTeX、表格HTML等） | - |
| level | INTEGER | 建议 | 标题层级（1-6，仅标题块） | 1 |
| bbox | VARCHAR(64) | 建议 |  bounding box位置坐标 | x1,y1,x2,y2 |
| confidence | FLOAT | 是 | 识别置信度 | 0.98 |
| create_time | DATETIME | 是 | 创建时间 | 2026-09-06 14:00:00 |

**索引**：
- `idx_fcb_file_page` (file_id, page_num)
- `idx_fcb_block_type` (block_type)
- `idx_fcb_file_type` (file_id, block_type)

#### 3.1.4 公式表（file_formula）

| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | INTEGER | 是 | 主键，自增 | 1 |
| file_id | INTEGER | 是 | 关联文件ID | 72 |
| page_num | INTEGER | 是 | 页码 | 5 |
| formula_latex | TEXT | 是 | 公式LaTeX表达式 | E = mc^2 |
| formula_text | VARCHAR(256) | 建议 | 公式文本描述 | 能量等于质量乘以光速的平方 |
| context_text | TEXT | 建议 | 公式上下文（前后各100字） | - |
| confidence | FLOAT | 是 | 识别置信度 | 0.88 |
| create_time | DATETIME | 是 | 创建时间 | 2026-09-06 14:00:00 |

**索引**：
- `idx_ff_file_id` (file_id)
- `idx_ff_page_num` (page_num)

#### 3.1.5 表格表（file_table）

| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | INTEGER | 是 | 主键，自增 | 1 |
| file_id | INTEGER | 是 | 关联文件ID | 72 |
| page_num | INTEGER | 是 | 页码 | 10 |
| table_html | TEXT | 是 | 表格HTML | <table>...</table> |
| table_json | TEXT | 是 | 表格JSON结构 | {"rows": [...]} |
| rows | INTEGER | 是 | 行数 | 5 |
| cols | INTEGER | 是 | 列数 | 3 |
| caption | VARCHAR(256) | 建议 | 表格标题 | 表1-1 工程造价构成 |
| confidence | FLOAT | 是 | 识别置信度 | 0.85 |
| create_time | DATETIME | 是 | 创建时间 | 2026-09-06 14:00:00 |

**索引**：
- `idx_ft_file_id` (file_id)
- `idx_ft_page_num` (page_num)

#### 3.1.6 图片表（file_image）

| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | INTEGER | 是 | 主键，自增 | 1 |
| file_id | INTEGER | 是 | 关联文件ID | 72 |
| page_num | INTEGER | 是 | 页码 | 8 |
| image_path | VARCHAR(256) | 是 | 图片存储路径 | ocr_images/72/img_1.webp |
| image_type | VARCHAR(32) | 是 | 图片类型：figure/chart/diagram/photo | figure |
| caption | VARCHAR(256) | 建议 | 图片标题 | 图1-1 工程造价管理流程 |
| width | INTEGER | 建议 | 图片宽度（像素） | 800 |
| height | INTEGER | 建议 | 图片高度（像素） | 600 |
| file_size | INTEGER | 建议 | 文件大小（字节） | 50000 |
| create_time | DATETIME | 是 | 创建时间 | 2026-09-06 14:00:00 |

**索引**：
- `idx_fi_file_id` (file_id)
- `idx_fi_page_num` (page_num)
- `idx_fi_image_type` (image_type)

#### 3.1.7 全文搜索虚拟表（file_content_fts）

```sql
CREATE VIRTUAL TABLE file_content_fts USING fts5(
    content_text,
    subject,
    filename,
    tokenize = "unicode61 remove_diacritics 2",
    content='file_content',
    content_rowid='id'
);
```

**说明**：
- 使用`unicode61`分词器，支持中文
- `remove_diacritics 2`移除变音符号
- 内容关联file_content表，支持自动同步

#### 3.1.8 向量索引表（file_content_vector）

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | INTEGER | 是 | 主键 |
| file_id | INTEGER | 是 | 关联文件ID |
| page_num | INTEGER | 是 | 页码 |
| chunk_id | INTEGER | 是 | 文本块ID（每页分多个块，每块500字） |
| chunk_text | TEXT | 是 | 文本块内容 |
| vector | BLOB | 是 | 向量数据（FP16压缩，768维） |
| model_name | VARCHAR(64) | 是 | 向量模型名称 |
| create_time | DATETIME | 是 | 创建时间 |

**索引**：
- `idx_fcv_file_page` (file_id, page_num)
- `idx_fcv_chunk_id` (chunk_id)

### 3.2 文件存储结构

```
backend/data/
├── ocr_images/                    # OCR图片缓存
│   ├── {file_id}/                 # 按文件ID分目录
│   │   ├── page_1.webp           # 页面图片（WebP格式，质量80%）
│   │   ├── page_2.webp
│   │   ├── img_1.webp            # 提取的图片
│   │   └── img_2.webp
│   └── ...
├── ocr_cache/                     # OCR中间结果缓存
│   ├── {file_id}/
│   │   ├── raw_result.json       # 原始识别结果
│   │   └── processed_result.json # 处理后结果
│   └── ...
└── vector_cache/                  # 向量缓存
    ├── {file_id}/
    │   └── vectors.npy           # 向量数据（numpy格式）
    └── ...
```

**存储优化策略**：
1. 页面图片使用WebP格式，质量80%，比JPG小30-50%
2. 图片按文件ID分目录存储，避免单目录文件过多
3. OCR中间结果缓存保留7天，自动清理
4. 向量数据使用FP16压缩，比FP32小50%
5. 文本内容去重，相同内容只存一份
6. 定期清理临时文件和缓存

### 3.3 存储容量估算

| 存储内容 | 单文件平均 | 150个文件总计 | 500个文件总计 |
|----------|-----------|--------------|--------------|
| 原始文本 | 100KB | 15MB | 50MB |
| 结构化JSON | 200KB | 30MB | 100MB |
| 全文索引 | 150KB | 22.5MB | 75MB |
| 向量索引 | 500KB | 75MB | 250MB |
| 页面图片 | 5MB | 750MB | 2.5GB |
| 提取图片 | 2MB | 300MB | 1GB |
| 中间缓存 | 1MB | 150MB | 500MB |
| **总计** | **约9MB** | **约1.3GB** | **约4.5GB** |

**结论**：150个文件约需1.3GB存储空间，当前磁盘空间充足，完全可接受。

---

## 四、识别流程详细设计

### 4.1 单文件识别流程

```
步骤1：文件检查与预处理
├─ 1.1 检查文件是否已识别（查询file_content表）
├─ 1.2 检查文件类型（PDF/Word/Excel）
├─ 1.3 检查文件大小和页数
├─ 1.4 PDF文件：提取页面，转图片
├─ 1.5 Word/Excel文件：转PDF，再提取页面
└─ 1.6 图像预处理（去水印、倾斜校正、对比度增强、超分辨率）

步骤2：版面分析
├─ 2.1 使用MinerU进行版面分析
├─ 2.2 识别页面区域（标题、正文、公式、表格、图片、列表）
├─ 2.3 记录每个区域的bounding box
└─ 2.4 按阅读顺序排序区域

步骤3：内容识别
├─ 3.1 文字区域：PaddleOCR识别文字
├─ 3.2 公式区域：PaddleLaTeX识别公式（输出LaTeX）
├─ 3.3 表格区域：TableMaster识别表格（输出HTML/JSON）
├─ 3.4 图片区域：提取图片，保存为WebP
└─ 3.5 标题区域：识别标题，标记层级

步骤4：后处理
├─ 4.1 错别字校正（基于词典和上下文）
├─ 4.2 格式规范化（统一标点、空格、换行）
├─ 4.3 语义校验（检查内容连贯性）
├─ 4.4 低置信度标记（置信度<0.8标记待校对）
└─ 4.5 结构化解析（按页面、块、层级组织）

步骤5：存储
├─ 5.1 存储到file_content主表
├─ 5.2 存储到file_page_content页面表
├─ 5.3 存储到file_content_block块表
├─ 5.4 存储公式到file_formula表
├─ 5.5 存储表格到file_table表
├─ 5.6 存储图片到file_image表和文件系统
└─ 5.7 更新文件状态为已完成

步骤6：索引建立
├─ 6.1 建立全文索引（FTS5）
├─ 6.2 建立向量索引（异步处理）
└─ 6.3 更新is_indexed和is_vectorized标记

步骤7：质量检查
├─ 7.1 自动检查（空白页、乱码、重复内容）
├─ 7.2 计算平均置信度
├─ 7.3 生成识别质量报告
└─ 7.4 低质量文件标记待重新识别
```

### 4.2 批量识别流程

```
1. 创建批量识别任务
   ├─ 获取待识别文件列表（学习资料库中未识别的文件）
   ├─ 按优先级排序（真题 > 知识点精讲 > 讲义 > 其他）
   └─ 记录任务总数和当前进度

2. 并发控制
   ├─ 同时最多2个文件识别（避免资源占用过高）
   ├─ CPU占用不超过70%
   └─ 内存占用不超过500MB

3. 逐个文件识别
   ├─ 调用单文件识别流程
   ├─ 记录每个文件的识别结果
   ├─ 更新任务进度
   └─ 失败文件记录错误，加入重试队列

4. 断点续扫
   ├─ 记录已完成的文件
   ├─ 中断后从断点继续
   └─ 已完成文件不重复识别

5. 任务完成
   ├─ 生成批量识别报告（成功率、准确率、耗时统计）
   ├─ 失败文件列表（可手动重试）
   └─ 更新统计数据
```

### 4.3 增量识别流程（新增文件）

```
1. 文件上传完成事件
   └─ 自动触发增量识别任务

2. 异步后台处理
   ├─ 不阻塞用户操作
   ├─ 任务加入队列
   └─ 按优先级处理

3. 识别完成通知
   ├─ 更新文件状态
   ├─ 建立索引
   └─ 可选：通知前端（WebSocket/轮询）
```

### 4.4 重新识别流程

```
1. 用户手动触发重新识别
   └─ 选择文件，点击重新识别

2. 备份旧内容
   ├─ 备份旧的识别结果（保留历史版本）
   └─ 记录重新识别原因

3. 执行识别流程
   └─ 调用单文件识别流程

4. 对比新旧内容
   ├─ 对比识别准确率
   ├─ 对比内容差异
   └─ 标记变更部分

5. 更新索引
   ├─ 更新全文索引
   └─ 更新向量索引
```

---

## 五、索引机制设计

### 5.1 全文索引（FTS5）

**索引表设计**：
```sql
-- 文件内容全文索引
CREATE VIRTUAL TABLE file_content_fts USING fts5(
    content_text,
    subject,
    filename,
    tokenize = "unicode61 remove_diacritics 2",
    content='file_content',
    content_rowid='id'
);

-- 页面内容全文索引
CREATE VIRTUAL TABLE file_page_fts USING fts5(
    content_text,
    title_text,
    tokenize = "unicode61 remove_diacritics 2",
    content='file_page_content',
    content_rowid='id'
);
```

**搜索语法**：
| 搜索类型 | 语法 | 示例 |
|----------|------|------|
| 关键词搜索 | 关键词 | 工程造价 |
| 短语搜索 | "短语" | "工程造价含义" |
| 布尔搜索 | AND/OR/NOT | 工程造价 AND 净现值 |
| 字段限定 | 字段:关键词 | subject:一造管理 工程造价 |
| 前缀搜索 | 关键词* | 工程* |

**搜索结果展示**：
- 文件名、页码、匹配片段
- 高亮显示匹配关键词
- 点击跳转到对应页面
- 支持按文件、按科目、按文件类型筛选

### 5.2 向量索引

**向量模型选型**：
| 模型 | 维度 | 中文支持 | 速度 | 推荐度 |
|------|------|----------|------|--------|
| **bge-small-zh** | 512 | ⭐⭐⭐⭐⭐ | 快 | ⭐⭐⭐⭐⭐ 推荐 |
| **bge-base-zh** | 768 | ⭐⭐⭐⭐⭐ | 中 | ⭐⭐⭐⭐ 备选 |
| **m3e-base** | 768 | ⭐⭐⭐⭐ | 中 | ⭐⭐⭐⭐ 备选 |
| **text2vec-base** | 768 | ⭐⭐⭐⭐ | 中 | ⭐⭐⭐ 备选 |

**推荐方案**：bge-small-zh（512维，速度快，中文支持好，资源占用低）

**分块策略**：
- 每页分1-3个块，每块约500字
- 块之间有50字重叠，避免上下文丢失
- 标题块单独存储，权重更高

**向量检索流程**：
1. 用户输入问题
2. 问题向量化（使用相同模型）
3. 向量相似度计算（余弦相似度）
4. 返回Top 5最相关的文本块
5. 可选：重排序（使用交叉编码器提升准确率）

### 5.3 知识点索引

**索引方式**：
- 从识别内容中自动提取知识点
- 与知识体系（knowledge_framework）关联
- 建立知识点→文件→页面的映射关系

**索引表设计**：
```sql
CREATE TABLE file_knowledge_point_index (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_id INTEGER NOT NULL,
    page_num INTEGER,
    knowledge_point VARCHAR(256) NOT NULL,
    chapter VARCHAR(128),
    section VARCHAR(128),
    match_type VARCHAR(32),  -- exact/keyword/semantic
    match_confidence FLOAT,
    context_text TEXT,  -- 知识点上下文
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(file_id, page_num, knowledge_point)
);
```

### 5.4 标签索引

**索引方式**：
- 从文件名、路径、内容中自动提取标签
- 支持用户手动添加标签
- 建立标签→文件的映射关系

**索引表设计**：
```sql
CREATE TABLE file_tag_index (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_id INTEGER NOT NULL,
    tag VARCHAR(64) NOT NULL,
    tag_type VARCHAR(32),  -- auto/manual
    confidence FLOAT,
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(file_id, tag)
);
```

---

## 六、查询与分析接口设计

### 6.1 API接口清单

| 接口 | 方法 | 路径 | 功能 | 参数 |
|------|------|------|------|------|
| 全文搜索 | GET | /api/v1/content/search | 全文搜索文件内容 | q, subject, file_type, page, page_size |
| 语义搜索 | GET | /api/v1/content/semantic-search | 语义搜索 | q, top_k, subject |
| 获取文件内容 | GET | /api/v1/content/{file_id} | 获取文件识别内容 | file_id, page_num |
| 获取页面内容 | GET | /api/v1/content/{file_id}/page/{page_num} | 获取页面识别内容 | file_id, page_num |
| 获取公式列表 | GET | /api/v1/content/{file_id}/formulas | 获取文件公式列表 | file_id |
| 获取表格列表 | GET | /api/v1/content/{file_id}/tables | 获取文件表格列表 | file_id |
| 获取图片列表 | GET | /api/v1/content/{file_id}/images | 获取文件图片列表 | file_id |
| 触发识别 | POST | /api/v1/content/scan | 触发文件识别 | file_id, force |
| 批量识别 | POST | /api/v1/content/batch-scan | 批量识别文件 | file_ids, priority |
| 识别状态 | GET | /api/v1/content/scan-status | 查询识别状态 | file_id |
| 识别统计 | GET | /api/v1/content/stats | 获取识别统计 | subject |
| 知识点提取 | POST | /api/v1/content/extract-knowledge | 从文件提取知识点 | file_id, auto_tag |
| 题目提取 | POST | /api/v1/content/extract-questions | 从文件提取题目 | file_id, auto_tag |
| 闪卡生成 | POST | /api/v1/content/generate-flashcards | 从文件生成闪卡 | file_id, auto_tag |

### 6.2 统一响应格式

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    // 具体数据
  },
  "timestamp": 1234567890
}
```

### 6.3 错误码定义

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 404 | 文件不存在 |
| 409 | 文件正在识别中 |
| 500 | 识别失败 |
| 501 | 识别引擎不可用 |

---

## 七、质量控制与验证

### 7.1 识别质量指标

| 指标 | 标准 | 验证方法 | 检查频率 |
|------|------|----------|----------|
| 识别成功率 | >=95% | 成功文件数/总文件数 | 每次批量识别后 |
| 文字识别准确率 | >=95% | 抽样人工核对（至少5%） | 每月 |
| 公式识别准确率 | >=85% | 抽样人工核对 | 每月 |
| 表格识别准确率 | >=80% | 抽样人工核对 | 每月 |
| 版面分析准确率 | >=90% | 抽样人工核对 | 每月 |
| 平均识别置信度 | >=0.85 | 系统计算 | 每次识别后 |
| 全文搜索覆盖率 | 100% | 搜索测试 | 每周 |
| 向量检索准确率 | >=85% | 语义检索测试 | 每月 |
| 单文件扫描时间 | <5分钟（50页以内） | 耗时统计 | 每次识别后 |

### 7.2 自动质量检查

| 检查项 | 检查方法 | 处理方式 |
|--------|----------|----------|
| 空白页 | 检查页面字符数<10 | 标记空白页，记录原因 |
| 乱码 | 检查异常字符比例>30% | 标记乱码页，待重新识别 |
| 重复内容 | 检查页面相似度>95% | 标记重复页，记录原因 |
| 低置信度 | 检查页面平均置信度<0.7 | 标记待人工校对 |
| 内容缺失 | 对比PDF页数和识别页数 | 标记缺失页，待重新识别 |
| 索引完整 | 检查FTS5索引覆盖率 | 自动重建索引 |

### 7.3 人工校对机制

1. **校对范围**：
   - 低置信度内容（置信度<0.8）必须人工校对
   - 核心文件（知识点精讲、真题）必须人工校对
   - 每月抽样5%的文件进行质量审计

2. **校对流程**：
   - 系统标记待校对内容
   - 造价专家/教研专家人工校对
   - 校对结果反馈系统
   - 系统优化识别模型

3. **校对反馈**：
   - 记录校对修改内容
   - 统计识别错误类型
   - 优化识别引擎参数
   - 持续提升识别准确率

### 7.4 完善性验证报告

```
✅ 识别储存完善性验证报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 识别完整性：✅通过 / ❌不通过
   - 总文件数：X个
   - 已识别：X个
   - 识别成功率：X%
   - 未识别：X个（列出原因）

2. 识别准确性：✅通过 / ❌不通过
   - 文字识别准确率：X%
   - 公式识别准确率：X%
   - 表格识别准确率：X%
   - 平均置信度：X
   - 抽样数量：X个文件

3. 存储完整性：✅通过 / ❌不通过
   - 文本存储完整率：X%
   - 公式存储完整率：X%
   - 表格存储完整率：X%
   - 图片存储完整率：X%

4. 索引完整性：✅通过 / ❌不通过
   - 全文索引覆盖率：X%
   - 向量索引覆盖率：X%
   - 知识点索引覆盖率：X%
   - 搜索响应时间：Xms

5. 性能达标：✅通过 / ❌不通过
   - 平均单文件扫描时间：X秒
   - 全文搜索响应时间：Xms
   - 语义检索响应时间：Xms
   - CPU占用率：X%
   - 内存占用：X MB

6. 存储空间：✅通过 / ❌不通过
   - 总存储空间：X GB
   - 文本内容：X MB
   - 图片缓存：X MB
   - 向量索引：X MB

7. 应用验证：✅通过 / ❌不通过
   - 全文搜索功能：正常/异常
   - 语义检索功能：正常/异常
   - 知识点提取功能：正常/异常
   - 题目识别功能：正常/异常
   - 闪卡生成功能：正常/异常

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
综合评定：✅成熟可用 / ⏳需优化 / ❌不可用
验证人：[专家姓名]
验证日期：[日期]
```

---

## 八、应用场景与功能

### 8.1 全文搜索功能

**功能描述**：支持跨文件全文搜索，毫秒级定位内容，显示搜索结果所在文件、页码、上下文。

**搜索流程**：
1. 用户输入关键词
2. 系统预处理关键词（移除空格、标点）
3. FTS5全文索引搜索
4. 按相关度排序结果
5. 展示文件名、页码、匹配片段（高亮关键词）
6. 点击跳转到对应页面

**高级搜索**：
- 按科目筛选
- 按文件类型筛选
- 按文件标签筛选
- 按日期范围筛选
- 布尔搜索（AND/OR/NOT）

### 8.2 语义检索功能

**功能描述**：基于向量相似度的语义检索，支持自然语言提问，返回最相关的内容片段。

**检索流程**：
1. 用户输入自然语言问题
2. 问题向量化
3. 向量相似度计算（余弦相似度）
4. 返回Top 5最相关的文本块
5. 展示相关内容和来源（文件、页码）
6. 可选：AI基于检索内容生成答案

### 8.3 知识点提取功能

**功能描述**：从识别内容中自动提取知识点，建立和完善知识体系。

**提取流程**：
1. 分析文件内容，识别知识点标题和内容
2. 与现有知识体系对比
3. 新增知识点或补充现有知识点
4. 标记知识点来源（文件、页码）
5. 自动关联到章/节
6. 人工审核确认

### 8.4 题目识别功能

**功能描述**：直接从识别内容中提取题目，不需要重新扫描PDF。

**提取流程**：
1. 从识别内容中识别题目结构（题干、选项、答案、解析）
2. 判断题型（单选/多选/判断/案例）
3. 自动关联知识点
4. 去重判断（与现有题库对比）
5. 存入题库
6. 人工审核确认

### 8.5 闪卡生成功能

**功能描述**：直接从识别内容中提取知识点，生成闪卡。

**生成流程**：
1. 从识别内容中识别知识点、公式、考点
2. 生成闪卡正面（问题）和背面（答案）
3. 自动关联知识点
4. 去重判断（与现有闪卡对比）
5. 存入闪卡库
6. 人工审核确认

### 8.6 智能答疑功能

**功能描述**：基于识别内容建立向量库，用户提问时检索相关内容，AI生成答案。

**答疑流程**：
1. 用户输入问题
2. 向量检索相关内容（Top 5）
3. AI基于检索内容生成答案
4. 标注答案来源（文件、页码）
5. 支持追问和多轮对话
6. 用户反馈优化

### 8.7 考点分布分析功能

**功能描述**：基于识别内容分析真题考点分布，统计高频考点。

**分析流程**：
1. 识别真题文件中的题目和考点
2. 统计每个知识点的出现频次、分值
3. 按年份、章节、知识点维度统计
4. 生成考点分布图表
5. 标记高频考点、核心考点
6. 与知识体系关联

### 8.8 跨文件内容关联功能

**功能描述**：自动识别不同文件中相关的内容，建立跨文件关联。

**关联流程**：
1. 对所有文件内容进行向量化
2. 计算文件之间的相似度
3. 识别相同知识点在不同文件中的内容
4. 建立跨文件关联关系
5. 支持从一个文件跳转到相关文件
6. 支持内容对比和融合

---

## 九、实施计划

### 9.1 第一阶段：基础建设（1-2周）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | 建立数据库表结构（7张表） | 1天 | 数据库架构师 | 表结构完整，索引建立 |
| 2 | 建立文件存储目录结构 | 0.5天 | 运维专家 | 目录结构完整，权限正确 |
| 3 | 集成MinerU识别引擎 | 2天 | OCR专家、AI专家 | MinerU安装配置完成，识别正常 |
| 4 | 集成PaddleOCR辅助引擎 | 1天 | OCR专家 | PaddleOCR安装配置完成 |
| 5 | 实现单文件识别功能 | 3天 | 开发专家、OCR专家 | 单文件识别正常，内容存储正确 |
| 6 | 实现批量识别功能 | 2天 | 开发专家 | 批量识别正常，任务管理可用 |
| 7 | 建立全文索引（FTS5） | 1天 | 数据库架构师 | 全文搜索可用，中文搜索正常 |
| 8 | 扫描10个测试文件验证 | 1天 | 测试专家、造价专家 | 扫描成功率>=95%，准确率>=95% |

### 9.2 第二阶段：全量扫描（2-3周）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | 全量扫描学习资料库所有PDF | 5-7天 | OCR专家、开发专家 | 扫描成功率>=95%，覆盖率100% |
| 2 | 建立全文索引 | 1天 | 数据库架构师 | 全文索引覆盖率100% |
| 3 | 扫描质量检查和优化 | 2天 | 造价专家、测试专家 | 文字识别准确率>=95% |
| 4 | 低置信度内容人工校对 | 3天 | 造价专家、教研专家 | 核心文件100%校对 |
| 5 | 生成扫描报告 | 0.5天 | 数据分析师 | 报告完整，数据准确 |

### 9.3 第三阶段：向量索引与语义检索（2周）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | 集成bge-small-zh向量模型 | 2天 | AI专家 | 模型加载正常，向量化正常 |
| 2 | 实现文本分块和向量化 | 2天 | AI专家、开发专家 | 分块合理，向量化正常 |
| 3 | 建立向量索引表 | 1天 | 数据库架构师 | 向量索引建立完成 |
| 4 | 实现语义检索API | 2天 | 开发专家、AI专家 | 语义检索准确率>=85% |
| 5 | 全量内容向量化 | 2-3天 | AI专家 | 向量索引覆盖率>=90% |

### 9.4 第四阶段：应用功能开发（3-4周）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | 实现全文搜索前端功能 | 2天 | 前端专家、开发专家 | 搜索响应<500ms，结果准确 |
| 2 | 实现语义检索前端功能 | 2天 | 前端专家、AI专家 | 检索响应<1秒，结果相关 |
| 3 | 实现智能答疑功能 | 5天 | AI专家、开发专家 | 答疑准确率>=85%，响应<3秒 |
| 4 | 优化知识点提取功能 | 3天 | AI专家、造价专家 | 提取准确率>=90% |
| 5 | 优化题目识别功能 | 3天 | AI专家、造价专家 | 识别准确率>=90% |
| 6 | 优化闪卡生成功能 | 3天 | AI专家、造价专家 | 生成质量>=80分 |
| 7 | 实现考点分布分析功能 | 2天 | 数据分析师、造价专家 | 统计准确，可视化展示 |
| 8 | 实现跨文件内容关联功能 | 3天 | AI专家、开发专家 | 关联准确率>=85% |

### 9.5 第五阶段：持续优化（长期）

| 序号 | 任务 | 预计工时 | 责任专家 | 验收标准 |
|------|------|----------|----------|----------|
| 1 | OCR模型优化和迭代 | 持续 | AI专家、OCR专家 | 准确率持续提升 |
| 2 | 向量检索优化 | 持续 | AI专家 | 检索准确率持续提升 |
| 3 | 新增文件自动扫描 | 1天 | 开发专家 | 新增文件自动扫描，无需手动 |
| 4 | 扫描性能优化 | 持续 | 开发专家 | 扫描速度持续提升 |
| 5 | 存储空间优化 | 持续 | 数据库架构师 | 存储空间持续优化 |
| 6 | 识别质量持续监控 | 持续 | 质量专家 | 质量评分实时监控 |

---

## 十、风险与应对

| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|----------|
| OCR识别准确率不达标 | 内容错误，影响后续功能 | 中 | 多引擎融合，人工校对，持续优化模型 |
| 扫描时间过长 | 用户等待时间长 | 中 | 后台异步处理，断点续扫，并发控制，性能优化 |
| 存储空间不足 | 无法存储全部内容 | 低 | 压缩优化，按需加载，定期清理，扩展存储 |
| 扫描过程中系统崩溃 | 扫描中断，数据丢失 | 低 | 断点续扫，事务保障，定期备份，资源限制 |
| 向量检索准确率低 | 智能答疑效果差 | 中 | 优化向量模型，增加重排序，人工反馈优化 |
| 新增文件未自动扫描 | 内容不完整 | 低 | 文件上传后自动触发扫描，状态监控，告警 |
| 中文搜索效果差 | 全文搜索不可用 | 中 | 使用unicode61分词器，搜索预处理，优化索引 |
| 识别引擎依赖复杂 | 安装配置困难 | 中 | 提供一键安装脚本，Docker容器化，详细文档 |

---

## 十一、与其他体系的协同

### 11.1 与知识库体系的协同

| 知识库 | 协同方式 | 数据流向 |
|--------|----------|----------|
| 知识点知识库 | 从识别内容中提取知识点，完善知识体系 | 识别内容 → 知识点提取 → 知识点知识库 |
| 题库统计知识库 | 从识别内容中提取题目，统计题库数据 | 识别内容 → 题目识别 → 题库 → 题库统计 |
| 闪卡统计知识库 | 从识别内容中生成闪卡，统计闪卡数据 | 识别内容 → 闪卡生成 → 闪卡 → 闪卡统计 |
| 真题考点分布知识库 | 从真题识别内容中统计考点分布 | 真题识别内容 → 考点统计 → 真题考点知识库 |
| 易错点知识库 | 从错题识别内容中分析易错点 | 错题识别内容 → 易错点分析 → 易错点知识库 |
| 公式知识库 | 从识别内容中提取公式 | 识别内容 → 公式提取 → 公式知识库 |
| 法律法规知识库 | 从法规识别内容中提取法条 | 法规识别内容 → 法条提取 → 法律法规知识库 |

### 11.2 与AI能力体系的协同

| AI能力 | 协同方式 | 数据流向 |
|--------|----------|----------|
| 智能题目生成 | 基于识别内容生成题目 | 识别内容 → 题目生成 → 题库 |
| 智能闪卡生成 | 基于识别内容生成闪卡 | 识别内容 → 闪卡生成 → 闪卡库 |
| 智能思维导图生成 | 基于识别内容生成导图 | 识别内容 → 知识点提取 → 导图生成 |
| 智能学习路径推荐 | 基于识别内容和学习行为推荐 | 识别内容 + 学习行为 → 路径推荐 |
| 智能错题分析 | 基于识别内容分析错题 | 错题识别内容 → 错误原因分析 |
| 智能答疑助手 | 基于识别内容回答问题 | 识别内容 → 向量检索 → AI生成答案 |
| 智能内容审核 | 审核识别内容质量 | 识别内容 → 质量审核 → 优化建议 |
| 智能去重判断 | 基于识别内容去重 | 识别内容 → 语义相似度 → 去重判断 |
| 智能知识点关联 | 基于识别内容关联知识点 | 识别内容 → 关键词/语义匹配 → 知识点关联 |

### 11.3 与学习分析体系的协同

| 分析维度 | 协同方式 | 数据流向 |
|----------|----------|----------|
| 知识点掌握度分析 | 基于识别内容建立知识点体系，统计掌握度 | 识别内容 → 知识点体系 → 掌握度统计 |
| 遗忘曲线预测 | 基于识别内容生成闪卡，预测遗忘曲线 | 识别内容 → 闪卡生成 → 复习记录 → 遗忘曲线 |
| 考试准备度评估 | 基于真题识别内容评估准备度 | 真题识别内容 → 真题练习 → 准备度评估 |
| 薄弱点自动识别 | 基于识别内容和错题识别薄弱点 | 识别内容 + 错题 → 薄弱点识别 |
| 真题考点分布分析 | 基于真题识别内容统计考点分布 | 真题识别内容 → 考点统计 → 分布分析 |
| 高频考点分析 | 基于真题识别内容统计高频考点 | 真题识别内容 → 频次统计 → 高频考点 |

---

## 十二、完善性标准（科学精神）

### 12.1 功能完整性标准

| 序号 | 功能点 | 标准 | 验证方法 |
|------|--------|------|----------|
| 1 | 文件识别 | 支持PDF/Word/Excel，识别成功率>=95% | 实际扫描测试 |
| 2 | 内容存储 | 文字、公式、表格、图片100%存储 | 内容检查 |
| 3 | 全文搜索 | 跨文件全文搜索，响应<500ms | 搜索测试 |
| 4 | 语义检索 | 语义检索，准确率>=85% | 检索测试 |
| 5 | 智能答疑 | 基于内容答疑，准确率>=85% | 答疑测试 |
| 6 | 知识点提取 | 自动提取知识点，准确率>=90% | 提取测试 |
| 7 | 题目识别 | 自动识别题目，准确率>=90% | 识别测试 |
| 8 | 闪卡生成 | 自动生成闪卡，质量>=80分 | 生成测试 |
| 9 | 考点分析 | 考点分布统计，准确率100% | 统计测试 |
| 10 | 任务管理 | 识别任务可管理、可追踪 | 功能测试 |
| 11 | 质量监控 | 识别质量可监控、可优化 | 质量检查 |
| 12 | 跨文件关联 | 跨文件内容关联，准确率>=85% | 关联测试 |

### 12.2 数据准确性标准

| 序号 | 数据项 | 标准 | 验证方法 |
|------|--------|------|----------|
| 1 | 文字识别准确率 | >=95% | 抽样人工核对（至少5%） |
| 2 | 公式识别准确率 | >=85% | 抽样人工核对 |
| 3 | 表格识别准确率 | >=80% | 抽样人工核对 |
| 4 | 版面分析准确率 | >=90% | 抽样人工核对 |
| 5 | 内容完整性 | 100%页面有内容 | 内容检查 |
| 6 | 索引完整性 | 全文索引100%，向量索引>=90% | 索引检查 |
| 7 | 知识点提取准确率 | >=90% | 抽样人工核对 |
| 8 | 题目识别准确率 | >=90% | 抽样人工核对 |

### 12.3 性能标准

| 序号 | 性能项 | 标准 | 验证方法 |
|------|--------|------|----------|
| 1 | 单文件扫描时间 | <5分钟（50页以内） | 耗时统计 |
| 2 | 全文搜索响应时间 | <500ms | 性能测试 |
| 3 | 语义检索响应时间 | <1秒 | 性能测试 |
| 4 | 智能答疑响应时间 | <3秒 | 性能测试 |
| 5 | 并发扫描数 | 最多2个同时 | 资源监控 |
| 6 | CPU占用率 | <70% | 性能监控 |
| 7 | 内存占用 | <500MB | 性能监控 |
| 8 | 存储空间 | <10GB（500个文件） | 存储监控 |

### 12.4 持续优化机制

1. **用户反馈机制**：用户可以标记识别错误，反馈用于优化模型
2. **定期质量审计**：每月抽样检查5%的文件，统计准确率
3. **模型迭代机制**：定期更新OCR模型和向量模型，提升准确率
4. **性能监控机制**：实时监控扫描性能和搜索性能，持续优化
5. **存储空间监控**：监控存储空间使用情况，及时优化压缩
6. **识别引擎升级**：跟踪最新OCR技术，及时升级识别引擎
7. **知识库联动**：识别内容自动同步到各知识库，保持数据一致

---

> **本分册为活文档，随着OCR技术发展和系统迭代持续更新。识别储存体系是本地部署智能化的基础，必须优先实施，持续优化。功能存在不等于功能完善，必须发挥科学精神，持续验证、持续优化、持续完善，追求极致质量。一次识别，永久使用；结构化存储，多维索引；质量可控，持续优化；全面分析，深度挖掘。**



============================================================
# § 规划细则分册_V3.0_完整细化版.md
============================================================

# 水利智学系统 规划细则分册（V3.0 完整细化版）

> **版本**：V3.0（完整细化版）
> **生效日期**：2026-09-06
> **地位**：本文件为《系统设计宪法》的配套细则分册，宪法规定顶层原则，本细则规定具体实施标准、指标、验收要求、实施步骤、责任专家。所有体系、所有部件的详细规划、量化标准、验收指标均在本文件中。
> **制定委员会**：61位全球顶级专家联合制定，涵盖架构、AI、专业、设计、安全、质量、运维等全维度。
> **核心原则**：每个体系必须有明确的定位、具体的标准、可量化的指标、可验证的验收要求、详细的实施步骤、明确的责任专家。禁止只写标题不写内容。功能存在不等于功能完善，必须发挥科学精神持续验证、持续优化、持续完善。

---

## 第一部分：科学精神与完善性体系（最高原则）

### 1.1 科学精神五要素（必须严格遵守）

| 要素 | 内涵 | 具体要求 | 验证方法 | 责任专家 |
|------|------|----------|----------|----------|
| **实证精神** | 所有功能必须经过实际运行验证 | 禁止凭印象、凭记忆、凭推测判断功能正常；必须实际运行、实际测试、实际验证 | 实际运行测试报告、截图、数据库记录 | 测试质量专家 |
| **质疑精神** | 对所有已实现的功能保持质疑 | 主动寻找缺陷和不足；禁止自我满足；定期复盘已实现功能的质量 | 缺陷清单、优化建议、复盘报告 | 架构专家、质量专家 |
| **迭代精神** | 功能实现只是开始，必须持续迭代优化 | 追求更好的性能、更好的体验、更好的质量；每个功能必须有持续优化计划 | 版本迭代记录、性能对比、用户满意度 | 产品专家、开发专家 |
| **全面精神** | 必须全面考虑系统的各个方面 | 禁止只看局部、只看表面、只看功能；必须考虑架构、性能、安全、体验、可维护性、可扩展性 | 全面检查清单、多维度评估报告 | 系统架构师 |
| **严谨精神** | 所有数据、所有结论、所有方案必须有事实依据 | 禁止"可能"、"大概"、"应该"；必须有数据支撑、有验证结果、有来源追溯 | 数据来源记录、验证报告、引用来源 | 数据分析师、造价专家 |

### 1.2 完善性判定标准（功能成熟必须同时满足8项）

| 序号 | 维度 | 标准 | 验证方法 | 责任专家 | 不达标处理 |
|------|------|------|----------|----------|-----------|
| 1 | **功能完整性** | 100%功能点实现，无缺失 | 功能清单逐项验证，对照需求文档 | 产品专家 | 补充缺失功能 |
| 2 | **数据准确性** | 数据准确率>=95%，无错误数据 | 数据抽样人工核对，至少抽样10% | 数据分析师、造价专家 | 修正错误数据，优化识别算法 |
| 3 | **性能达标** | 响应时间<500ms，无慢查询 | 性能测试监控，压力测试 | 性能优化专家 | 优化数据库查询，增加缓存 |
| 4 | **稳定性** | 连续运行7天无崩溃，无内存泄漏 | 稳定性测试，长时间运行监控 | 运维专家 | 修复崩溃问题，优化内存管理 |
| 5 | **安全性** | 0高危漏洞，0中危漏洞 | 安全扫描审计，渗透测试 | 安全专家 | 立即修复漏洞，加强安全机制 |
| 6 | **易用性** | 用户体验评分>=85分，无严重体验问题 | 用户测试反馈，至少10人测试 | UX专家、产品专家 | 优化界面布局，改进交互逻辑 |
| 7 | **可维护性** | 代码规范，文档完整，测试覆盖>=70% | 代码审查，文档检查，测试覆盖率统计 | 架构专家、开发专家 | 重构代码，补充文档，增加测试 |
| 8 | **可扩展性** | 架构合理，模块解耦，支持功能扩展 | 架构评估，扩展测试，新增功能不影响核心 | 系统架构师 | 优化架构，模块解耦，增加插件机制 |

### 1.3 完善性验证报告模板（每个功能必须输出）

```
✅ 完善性验证报告：[功能名称]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 功能完整性：✅通过 / ❌不通过
   - 功能点总数：X个
   - 已实现：X个
   - 缺失：X个（列出缺失功能）

2. 数据准确性：✅通过 / ❌不通过
   - 抽样数量：X条
   - 准确数量：X条
   - 准确率：X%
   - 错误数据：（列出错误数据及修正方案）

3. 性能达标：✅通过 / ❌不通过
   - 平均响应时间：Xms
   - 最大响应时间：Xms
   - 慢查询数量：X个
   - 优化建议：（列出优化方案）

4. 稳定性：✅通过 / ❌不通过
   - 连续运行时间：X天
   - 崩溃次数：X次
   - 内存泄漏：有/无
   - 修复方案：（列出修复方案）

5. 安全性：✅通过 / ❌不通过
   - 高危漏洞：X个
   - 中危漏洞：X个
   - 低危漏洞：X个
   - 修复方案：（列出修复方案）

6. 易用性：✅通过 / ❌不通过
   - 用户体验评分：X分
   - 测试人数：X人
   - 严重体验问题：X个
   - 优化建议：（列出优化方案）

7. 可维护性：✅通过 / ❌不通过
   - 代码规范评分：X分
   - 文档完整性：X%
   - 测试覆盖率：X%
   - 优化建议：（列出优化方案）

8. 可扩展性：✅通过 / ❌不通过
   - 架构合规率：X%
   - 模块耦合度：低/中/高
   - 扩展测试结果：通过/不通过
   - 优化建议：（列出优化方案）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
综合评定：✅成熟可用 / ⏳需优化 / ❌不可用
持续优化计划：（列出后续优化计划）
验证人：[专家姓名]
验证日期：[日期]
```

---

## 第二部分：知识库体系（12类必须全部建立完善）

### 2.1 知识库体系总览

| 序号 | 知识库名称 | 优先级 | 状态 | 核心价值 |
|------|-----------|--------|------|----------|
| 1 | 知识点知识库 | P0 | ✅已建立，需完善 | 统一知识体系骨架，所有数据关联核心 |
| 2 | 题库统计知识库 | P0 | ✅已建立，需完善 | 题库按多维度统计，支持学习分析 |
| 3 | 闪卡统计知识库 | P0 | ✅已建立，需完善 | 闪卡按多维度统计，支持记忆分析 |
| 4 | 思维导图知识库 | P1 | ⏳待建立 | 导图节点结构，关联知识点 |
| 5 | 真题考点分布知识库 | P1 | ⏳待建立 | 近5年真题考点频次、分值 |
| 6 | 易错点知识库 | P2 | ⏳待建立 | 高频错题、错误原因分析 |
| 7 | 公式知识库 | P2 | ⏳待建立 | 计算公式、参数、适用场景 |
| 8 | 法律法规知识库 | P3 | ⏳待建立 | 现行有效法条、关联考点 |
| 9 | 口诀记忆知识库 | P3 | ⏳待建立 | 记忆口诀、对应知识点 |
| 10 | 学习资料库元数据知识库 | P1 | ⏳待建立 | 文件标签、分类、关联知识点 |
| 11 | 学习行为知识库 | P1 | ⏳待建立 | 用户学习时长、频次、习惯、进度 |
| 12 | AI模型知识库 | P2 | ⏳待建立 | AI生成内容、用户反馈、模型参数 |

### 2.2 知识点知识库（详细实施细则）

**定位**：统一知识体系骨架，所有数据的关联核心，智能化的基础。

**数据结构**：
| 字段 | 类型 | 必填 | 标准 | 示例 |
|------|------|------|------|------|
| id | INTEGER | 是 | 主键，自增 | 1 |
| subject | VARCHAR(64) | 是 | 科目，统一命名 | 一造管理 |
| chapter | VARCHAR(128) | 是 | 章，格式"第X章 章节名称" | 第一章 工程造价管理及其基本制度 |
| section | VARCHAR(128) | 节必填 | 节，格式"X.Y 节名称" | 1.1 工程造价基本内容 |
| point | VARCHAR(256) | 知识点必填 | 知识点，简洁明确，不超过20字 | 工程造价含义 |
| level | INTEGER | 是 | 层级：0=章,1=节,2=知识点 | 2 |
| parent_id | INTEGER | 是 | 父节点ID | 5 |
| sort_order | INTEGER | 是 | 排序序号 | 1 |
| importance | VARCHAR(16) | 知识点必填 | 重要性：掌握/熟悉/了解 | 掌握 |
| is_high_freq | INTEGER | 是 | 是否高频考点：0/1 | 1 |
| is_key_point | INTEGER | 是 | 是否核心考点：0/1 | 1 |
| question_count | INTEGER | 是 | 关联题目数量 | 243 |
| flashcard_count | INTEGER | 是 | 关联闪卡数量 | 81 |
| source | VARCHAR(64) | 是 | 来源：知识点精讲/教材/大纲 | 知识点精讲 |
| source_page | VARCHAR(32) | 建议 | 来源页码 | P5-8 |
| keywords | TEXT | 建议 | 关键词，用于匹配，逗号分隔 | 工程造价,建设费用,建设期 |
| description | TEXT | 建议 | 知识点描述 | 工程造价通常是指工程建设项目在建设期预计或实际支出的建设费用 |
| create_time | DATETIME | 是 | 创建时间 | 2026-09-06 10:00:00 |
| update_time | DATETIME | 是 | 更新时间 | 2026-09-06 15:00:00 |

**实施步骤**：
1. **资料收集**：收集知识点精讲PDF、官方教材目录、考试大纲
   - 验收：至少50个知识点精讲PDF、1本教材、1份大纲
   - 责任：教研专家、造价专家
2. **骨架建立**：建立L1章→L2节→L3知识点完整结构
   - 验收：章/节与教材目录100%一致，知识点100%来自知识点精讲
   - 责任：造价专家、教研专家
3. **重要性标记**：根据真题频次、知识点重要性标记掌握/熟悉/了解
   - 验收：每个知识点有重要性标记，高频考点有真题统计支撑
   - 责任：造价专家、数据分析师
4. **关联统计**：统计每个知识点关联的题目数量、闪卡数量
   - 验收：统计数据准确，实时更新
   - 责任：数据分析师、开发专家
5. **关键词扩展**：为每个知识点扩展5-15个专业关键词，用于匹配
   - 验收：每个知识点至少5个关键词，匹配准确率>=90%
   - 责任：造价专家、AI专家
6. **质量审核**：造价专家审核知识点名称准确性、章节结构完整性
   - 验收：造价专家签字确认，准确率100%
   - 责任：造价专家

**完善性标准**：
- 100%知识点有官方来源（知识点精讲PDF）
- 章/节与教材目录100%一致
- 知识点关联率：题库>=95%，闪卡>=90%，导图>=100%
- 重要性标记准确率>=95%
- 关键词匹配准确率>=90%
- 统计数据实时更新，准确率100%
- 造价专家审核通过率100%

### 2.3 题库统计知识库（详细实施细则）

**定位**：题库按多维度统计，支持学习分析、薄弱点识别、高频考点分析。

**数据结构**：
| 字段 | 类型 | 必填 | 标准 |
|------|------|------|------|
| id | INTEGER | 是 | 主键 |
| subject | VARCHAR(64) | 是 | 科目 |
| chapter | VARCHAR(128) | 是 | 章 |
| knowledge_point | VARCHAR(256) | 是 | 知识点 |
| q_type | VARCHAR(32) | 是 | 题型：单选/多选/判断/案例 |
| year | INTEGER | 真题必填 | 年份 |
| total_count | INTEGER | 是 | 题目总数 |
| correct_count | INTEGER | 是 | 正确次数 |
| wrong_count | INTEGER | 是 | 错误次数 |
| accuracy | FLOAT | 是 | 正确率 |
| avg_time | FLOAT | 建议 | 平均答题时间（秒） |
| last_update | DATETIME | 是 | 最后更新时间 |

**统计维度**：
1. 按章统计：每章题目数量、正确率、平均答题时间
2. 按知识点统计：每个知识点题目数量、正确率、错误次数
3. 按题型统计：每种题型题目数量、正确率
4. 按年份统计：每年真题题目数量、分值分布
5. 按难度统计：每个难度题目数量、正确率

**实施步骤**：
1. 建立统计表结构
2. 编写统计脚本，从questions表聚合数据
3. 建立定时任务，每日更新统计数据
4. 建立API接口，前端可以查询统计数据
5. 验证统计数据准确性，与原始数据对比

**完善性标准**：
- 统计维度完整（5个维度）
- 统计数据准确率100%
- 统计数据实时更新（每日更新）
- API接口响应时间<500ms
- 统计数据可视化展示

### 2.4 闪卡统计知识库（详细实施细则）

**定位**：闪卡按多维度统计，支持记忆分析、遗忘曲线预测、复习计划优化。

**数据结构**：
| 字段 | 类型 | 必填 | 标准 |
|------|------|------|------|
| id | INTEGER | 是 | 主键 |
| subject | VARCHAR(64) | 是 | 科目 |
| chapter | VARCHAR(128) | 是 | 章 |
| knowledge_point | VARCHAR(256) | 是 | 知识点 |
| mastery | VARCHAR(32) | 是 | 掌握状态：待学习/学习中/已掌握 |
| total_count | INTEGER | 是 | 闪卡总数 |
| review_count | INTEGER | 是 | 复习总次数 |
| correct_count | INTEGER | 是 | 记住次数 |
| forget_count | INTEGER | 是 | 遗忘次数 |
| memory_rate | FLOAT | 是 | 记忆率 |
| avg_interval | FLOAT | 建议 | 平均复习间隔（天） |
| last_update | DATETIME | 是 | 最后更新时间 |

**统计维度**：
1. 按章统计：每章闪卡数量、记忆率、平均复习间隔
2. 按知识点统计：每个知识点闪卡数量、记忆率、复习次数
3. 按掌握状态统计：每种状态闪卡数量、占比
4. 按复习频率统计：高频复习、中频复习、低频复习闪卡数量
5. 按遗忘曲线统计：每个知识点遗忘曲线预测

**实施步骤**：
1. 建立统计表结构
2. 编写统计脚本，从flash_cards表聚合数据
3. 建立定时任务，每日更新统计数据
4. 建立API接口，前端可以查询统计数据
5. 验证统计数据准确性，与原始数据对比

**完善性标准**：
- 统计维度完整（5个维度）
- 统计数据准确率100%
- 统计数据实时更新（每日更新）
- API接口响应时间<500ms
- 遗忘曲线预测准确率>=85%

### 2.5 其他9类知识库（实施要点摘要）

| 序号 | 知识库 | 核心字段 | 实施要点 | 完善性标准 |
|------|--------|----------|----------|-----------|
| 4 | 思维导图知识库 | map_id, node_id, node_text, level, knowledge_point, parent_id | 从mind_maps表提取节点结构，关联知识点，建立层级关系 | 100%导图关联到章/节/知识点，节点结构完整 |
| 5 | 真题考点分布知识库 | year, chapter, knowledge_point, question_count, score, q_type | 从真题中统计考点频次、分值，按年份/章节/知识点分布 | 近5年真题100%统计，分值准确率100% |
| 6 | 易错点知识库 | knowledge_point, error_count, error_type, error_reason, correct_method | 从错题中统计高频错误，分析错误原因，提供正确方法 | 高频错题100%收录，错误原因分析准确率>=80% |
| 7 | 公式知识库 | formula_name, formula_expression, parameters, applicable_scenario, example, knowledge_point | 从教材/讲义中提取公式，整理参数说明、适用场景、例题 | 核心公式100%收录，参数说明完整，例题准确 |
| 8 | 法律法规知识库 | law_name, article_no, article_content, knowledge_point, effective_date, amendment | 收集现行有效法条，关联考点，记录修订历史 | 现行有效法条100%收录，关联考点准确率>=90% |
| 9 | 口诀记忆知识库 | mnemonic_text, knowledge_point, applicable_scenario, memory_tips | 收集/生成记忆口诀，对应知识点，提供记忆技巧 | 难记知识点100%有口诀辅助，口诀顺口易记 |
| 10 | 学习资料库元数据知识库 | file_id, filename, file_type, tags, subject, chapter, knowledge_point, source | 为每个文件建立元数据，自动标签识别，关联知识点 | 100%文件有元数据，标签准确率>=80% |
| 11 | 学习行为知识库 | user_id, study_date, study_duration, study_count, study_time, chapter_progress, point_progress | 记录用户学习行为，建立行为画像，追踪学习进度 | 学习行为数据100%记录，行为画像完整 |
| 12 | AI模型知识库 | model_name, generate_type, generate_content, user_feedback, model_params, optimize_record | 记录AI生成内容，收集用户反馈，优化模型参数 | AI生成内容100%记录，用户反馈100%收集 |

---

## 第三部分：本地AI智能化组件体系（6类必须全部建立完善）

### 3.1 本地全文搜索引擎（第一优先级，立即实施）

**定位**：题库/闪卡/资料全文检索，提高查询效率，支持复杂搜索。

**技术方案**：SQLite FTS5（全文搜索虚拟表）

**实施步骤**：
1. 建立FTS5虚拟表，索引questions表的title、analysis字段
2. 建立FTS5虚拟表，索引flash_cards表的front、back字段
3. 建立FTS5虚拟表，索引学习资料库文件的文本内容
4. 编写搜索API，支持关键词搜索、短语搜索、布尔搜索
5. 建立索引更新机制，数据变更时自动更新索引
6. 性能测试，确保检索响应时间<500ms

**完善性标准**：
- 全文检索覆盖率100%（题库、闪卡、资料库）
- 检索响应时间<500ms
- 检索准确率>=95%
- 支持复杂搜索（关键词、短语、布尔）
- 索引实时更新，数据变更后索引自动更新

### 3.2 本地缓存系统（第一优先级，立即实施）

**定位**：热点数据缓存，减少数据库查询，提高系统性能。

**技术方案**：内存缓存（LRU策略） + SQLite缓存表（持久化）

**实施步骤**：
1. 建立全局数据缓存表（已建立global_data_cache表）
2. 实现内存缓存管理器，支持LRU淘汰策略
3. 预加载热点数据到缓存（知识点体系、题库统计、闪卡统计）
4. 建立缓存更新机制，数据变更时自动失效缓存
5. 建立缓存命中率监控，定期优化缓存策略
6. 性能测试，确保缓存命中率>=80%

**完善性标准**：
- 缓存命中率>=80%
- 数据库查询减少>=50%
- 缓存更新及时，数据变更后5秒内失效
- 缓存内存占用可控，无内存泄漏
- 支持缓存预热、缓存失效、缓存监控

### 3.3 本地向量数据库（第二优先级，短期实施）

**定位**：RAG语义检索，智能答疑，语义去重，智能知识点关联。

**技术方案**：SQLite-vec 或 Chroma本地版

**实施步骤**：
1. 安装向量数据库依赖
2. 建立向量表，存储知识点、题目、闪卡的向量表示
3. 实现向量化函数，将文本转换为向量（使用本地Embedding模型）
4. 实现语义检索API，支持相似度搜索
5. 应用到智能答疑、语义去重、智能知识点关联
6. 性能测试，确保语义检索响应时间<1秒

**完善性标准**：
- 语义检索准确率>=85%
- 检索响应时间<1秒
- 向量索引完整，覆盖率100%
- 支持批量向量化、增量更新
- 应用到至少3个业务场景（答疑、去重、关联）

### 3.4 本地知识图谱（第四优先级，长期实施）

**定位**：知识点关联推理，学习路径推荐，知识体系可视化。

**技术方案**：NetworkX + 图数据库（或SQLite模拟）

**实施步骤**：
1. 建立知识图谱数据结构（节点、边、属性）
2. 从知识点知识库提取节点，建立知识点之间的关联边
3. 实现图谱推理算法（关联度计算、路径推荐、聚类分析）
4. 实现图谱可视化API，支持图谱展示
5. 应用到学习路径推荐、知识点关联分析
6. 性能测试，确保推理响应时间<2秒

**完善性标准**：
- 知识点关联覆盖率>=90%
- 推理准确率>=80%
- 图谱可视化流畅，响应时间<2秒
- 支持图谱查询、推理、推荐
- 应用到至少2个业务场景

### 3.5 本地任务调度器（第二优先级，短期实施）

**定位**：后台批量识别，缓存更新，定时任务，异步处理。

**技术方案**：APScheduler

**实施步骤**：
1. 安装APScheduler依赖
2. 建立任务调度器，支持定时任务、间隔任务、一次性任务
3. 实现任务管理API（创建、查询、取消任务）
4. 实现任务状态追踪，记录任务执行进度、结果、错误
5. 应用到批量PDF识别、缓存更新、数据统计
6. 稳定性测试，确保任务执行成功率>=99%

**完善性标准**：
- 任务执行成功率>=99%
- 任务可追踪，状态实时更新
- 支持任务优先级、任务依赖、任务重试
- 任务失败自动告警，错误日志完整
- 应用到至少3个业务场景

### 3.6 本地监控告警（第一优先级，立即实施）

**定位**：系统健康监控，异常告警，性能监控，日志分析。

**技术方案**：健康检查 + 日志分析 + 告警机制

**实施步骤**：
1. 建立健康检查API，检查数据库、后端、前端状态
2. 建立性能监控，监控响应时间、数据库查询、内存占用
3. 建立日志分析，分析错误日志、异常日志、慢查询
4. 建立告警机制，异常时自动告警（控制台提示、日志记录）
5. 建立监控面板，可视化展示系统状态
6. 稳定性测试，确保监控覆盖率100%

**完善性标准**：
- 监控覆盖率100%（数据库、后端、前端、性能）
- 异常告警响应时间<1分钟
- 健康检查API响应时间<100ms
- 监控数据可视化，实时更新
- 告警准确，无误报、漏报

---

## 第四部分：AI能力增强体系（10类必须全部建立完善）

### 4.1 智能知识点关联（第二优先级，短期实施）

**定位**：自动关联题目/闪卡到知识点，提高关联率和准确率。

**实现方式**：关键词匹配 + 语义匹配 + 规则引擎

**实施步骤**：
1. 扩展知识点关键词库（每个知识点5-15个专业关键词）
2. 实现关键词匹配算法，支持模糊匹配、同义词匹配
3. 实现语义匹配算法（基于向量相似度）
4. 实现规则引擎，处理特殊情况（数字章节、错误知识点）
5. 建立关联置信度机制，低置信度标记待人工审核
6. 批量关联所有未关联的题目/闪卡
7. 验证关联准确率，持续优化算法

**完善性标准**：
- 题库关联率>=95%
- 闪卡关联率>=90%
- 关联准确率>=90%
- 支持批量关联、增量关联
- 低置信度内容标记待人工审核

### 4.2 智能题目生成（第二优先级，短期实施）

**定位**：基于知识点自动生成题目，补充题库，提高覆盖率。

**实现方式**：Ollama + 知识点知识库 + 题目模板

**实施步骤**：
1. 建立题目模板库（单选、多选、判断、案例）
2. 实现题目生成Prompt，基于知识点生成题目
3. 实现题目质量审核（规则引擎 + AI审核）
4. 建立题目生成任务调度，支持批量生成
5. 生成题目自动关联知识点
6. 人工审核生成题目，确保质量
7. 持续优化生成Prompt，提高题目质量

**完善性标准**：
- 生成题目质量评分>=80分
- 知识点关联准确率>=90%
- 题目格式规范，选项完整
- 支持批量生成、按知识点生成
- 生成题目经过质量审核，无错误

### 4.3 智能闪卡生成（第二优先级，短期实施）

**定位**：基于知识点自动生成闪卡，补充闪卡库，提高记忆效率。

**实现方式**：Ollama + 知识点知识库 + 闪卡模板

**实施步骤**：
1. 建立闪卡模板库（知识点卡、公式卡、考点卡、口诀卡）
2. 实现闪卡生成Prompt，基于知识点生成闪卡
3. 实现闪卡质量审核（禁止完整题目类闪卡）
4. 建立闪卡生成任务调度，支持批量生成
5. 生成闪卡自动关联知识点
6. 人工审核生成闪卡，确保质量
7. 持续优化生成Prompt，提高闪卡质量

**完善性标准**：
- 生成闪卡质量评分>=80分
- 无完整题目类闪卡（100%审核）
- 知识点关联准确率>=90%
- 闪卡正面问题明确，背面答案完整
- 支持批量生成、按知识点生成

### 4.4 智能去重判断（第二优先级，短期实施）

**定位**：语义相似度去重，提高数据质量，减少重复数据。

**实现方式**：向量相似度计算 + 规则引擎

**实施步骤**：
1. 实现向量化函数，将题目/闪卡转换为向量
2. 实现相似度计算算法，支持语义相似度
3. 建立去重规则（题干+选项+答案+解析完全一致、语义相似度>90%）
4. 实现批量去重功能，支持全库去重
5. 建立去重置信度机制，低置信度标记待人工确认
6. 验证去重准确率，持续优化算法
7. 应用到题库去重、闪卡去重

**完善性标准**：
- 去重准确率>=90%
- 误判率<5%
- 支持批量去重、增量去重
- 不同来源间重复：保留真题，删除其他
- 去重后重复率<5%

### 4.5 智能答疑助手（第二优先级，短期实施）

**定位**：基于RAG回答学习问题，提供智能答疑服务。

**实现方式**：向量检索 + Ollama生成

**实施步骤**：
1. 建立答疑知识库（知识点、教材、讲义、真题解析）
2. 实现向量检索，从知识库中检索相关内容
3. 实现答案生成Prompt，基于检索内容生成答案
4. 建立答案引用机制，标注答案来源
5. 实现多轮对话，支持追问
6. 建立用户反馈机制，收集答案质量反馈
7. 持续优化检索和生成效果

**完善性标准**：
- 回答准确率>=85%
- 响应时间<3秒
- 答案有来源引用，可追溯
- 支持多轮对话、追问
- 用户满意度>=80%

### 4.6 其他5类AI能力（实施要点摘要）

| 序号 | AI能力 | 实现方式 | 实施要点 | 完善性标准 |
|------|--------|----------|----------|-----------|
| 6 | 智能思维导图生成 | 知识点体系 + 模板渲染 | 基于知识点体系自动生成导图，支持章节导图、知识点导图 | 导图节点完整率>=90%，层级结构清晰 |
| 7 | 智能学习路径推荐 | 协同过滤 + 知识点掌握度 | 基于学习行为和知识点掌握度，推荐学习内容和优先级 | 推荐相关性>=80%，用户满意度>=85% |
| 8 | 智能错题分析 | 错题聚类 + 知识点关联 | 分析错题原因，识别薄弱知识点，推荐针对性练习 | 错题原因分析准确率>=80%，推荐练习相关性>=85% |
| 9 | 智能内容审核 | 规则引擎 + AI审核 | 自动审核题库/闪卡质量，识别低质量内容、错误内容 | 审核准确率>=90%，低质量内容识别率>=95% |
| 10 | 智能复习计划 | SM-2 + 艾宾浩斯遗忘曲线 | 基于SM-2算法和遗忘曲线，自动安排复习计划 | 复习计划科学合理，记忆保持率>=85% |

---

## 第五部分：数据治理体系（8类必须全部建立完善）

### 5.1 数据质量监控（第一优先级，立即实施）

**定位**：实时监控数据完整性、准确性、一致性，发现异常数据。

**监控维度**：
| 维度 | 监控项 | 标准 | 检查频率 |
|------|--------|------|----------|
| 完整性 | 非空字段检查 | 核心字段100%非空 | 每日 |
| 准确性 | 专业数据校验 | 数据准确率>=95% | 每周 |
| 一致性 | 跨模块数据一致 | 数据一致性100% | 每日 |
| 唯一性 | 重复数据检查 | 重复率<5% | 每周 |
| 及时性 | 数据更新时效 | 实时同步 | 实时 |
| 规范性 | 格式规范检查 | 格式规范率>=95% | 每日 |

**实施步骤**：
1. 建立数据质量监控表，记录监控结果
2. 编写数据质量检查脚本，检查各维度数据质量
3. 建立定时任务，每日自动检查数据质量
4. 建立异常告警机制，发现异常数据自动告警
5. 建立数据质量报告，可视化展示数据质量
6. 建立数据质量优化机制，持续优化数据质量

**完善性标准**：
- 数据质量评分>=90分
- 异常数据识别率>=95%
- 监控覆盖率100%
- 异常告警响应时间<1小时
- 数据质量持续优化，每月提升>=2分

### 5.2 其他7类数据治理机制（实施要点摘要）

| 序号 | 机制 | 核心功能 | 实施要点 | 完善性标准 |
|------|------|----------|----------|-----------|
| 2 | 数据血缘追踪 | 追踪数据来源、变更历史、影响范围 | 建立数据血缘表，记录数据来源和变更，支持影响分析 | 数据血缘覆盖率100%，变更可追溯 |
| 3 | 数据版本管理 | 管理数据版本，支持回滚 | 建立数据版本表，记录每次变更，支持版本对比和回滚 | 版本管理覆盖率100%，回滚成功率100% |
| 4 | 数据同步机制 | 多端数据同步、冲突解决 | 建立同步队列，实现增量同步，冲突自动解决 | 同步延迟<5秒，冲突解决率100%，数据一致性100% |
| 5 | 数据备份恢复 | 自动备份、快速恢复、黄金备份 | 每日自动备份，黄金备份机制，定期恢复测试 | 备份完整性100%，恢复成功率100%，RTO<10分钟 |
| 6 | 数据脱敏机制 | 敏感数据脱敏、隐私保护 | 敏感数据加密存储，传输加密，日志脱敏 | 敏感数据脱敏率100%，无隐私泄露 |
| 7 | 数据一致性规则 | 跨模块数据统一，禁止别名和不一致 | 建立统一枚举常量，数据格式规范，跨模块校验 | 数据一致性100%，无别名和不一致 |
| 8 | 数据审计日志 | 所有数据变更可审计、可追溯 | 建立审计日志表，记录所有数据变更，支持审计查询 | 审计日志覆盖率100%，变更可追溯 |

---

## 第六部分：学习分析深化体系（10类必须全部建立完善）

### 6.1 知识点掌握度分析（第三优先级，中期实施）

**定位**：基于题目正确率和闪卡复习进度，评估知识点掌握度。

**评估模型**：
- 掌握度 = 题目正确率 * 0.6 + 闪卡记忆率 * 0.4
- 题目正确率 = 正确次数 / 总答题次数
- 闪卡记忆率 = 记住次数 / 总复习次数

**掌握度分级**：
| 等级 | 掌握度范围 | 状态 | 建议 |
|------|-----------|------|------|
| 已掌握 | >=80% | 绿色 | 定期复习，保持记忆 |
| 学习中 | 50%-80% | 黄色 | 加强练习，重点复习 |
| 待学习 | <50% | 红色 | 优先学习，重点突破 |

**实施步骤**：
1. 建立知识点掌握度表，记录每个知识点的掌握度
2. 编写掌握度计算脚本，基于题目和闪卡数据计算
3. 建立定时任务，每日更新掌握度
4. 实现掌握度可视化，支持按章、按知识点展示
5. 建立薄弱点识别，自动识别掌握度低的知识点
6. 建立学习建议，基于掌握度推荐学习内容

**完善性标准**：
- 掌握度评估准确率>=90%
- 与实际表现一致度>=85%
- 掌握度实时更新（每日更新）
- 可视化展示流畅，响应时间<500ms
- 薄弱点识别准确率>=90%

### 6.2 其他9类学习分析维度（实施要点摘要）

| 序号 | 分析维度 | 核心功能 | 实施要点 | 完善性标准 |
|------|----------|----------|----------|-----------|
| 1 | 学习行为分析 | 学习时长、频次、时段、习惯分析 | 记录学习行为，建立行为画像，分析学习习惯 | 分析数据准确率100%，行为画像完整 |
| 2 | 遗忘曲线预测 | 基于艾宾浩斯预测记忆衰退，自动安排复习 | 建立遗忘曲线模型，预测记忆衰退，自动安排复习 | 预测准确率>=85%，复习计划科学合理 |
| 3 | 考试准备度评估 | 真题模拟分数、知识点掌握、薄弱点 | 综合评估考试准备度，预测考试分数，识别薄弱点 | 评估准确率>=85%，与实际考试成绩相关 |
| 4 | 学习效率分析 | 学习投入与产出比、效率优化建议 | 计算学习效率，分析效率影响因素，提供优化建议 | 效率分析准确率>=80%，优化建议可执行 |
| 5 | 薄弱点自动识别 | 基于错题和正确率自动识别薄弱知识点 | 建立薄弱点识别算法，自动识别薄弱点，推荐练习 | 薄弱点识别准确率>=90%，推荐练习相关性>=85% |
| 6 | 学习进度追踪 | 整体学习进度、章节进度、知识点进度 | 追踪学习进度，实时更新，可视化展示 | 进度追踪准确率100%，实时更新 |
| 7 | 真题考点分布分析 | 近5年真题考点频次、分值、题型分布 | 统计真题考点分布，可视化展示，识别高频考点 | 统计准确率100%，考点分布可视化 |
| 8 | 高频考点分析 | 基于真题频次统计高频考点、核心考点 | 统计考点频次，标记高频考点，与教研专家对比 | 高频考点识别准确率>=95%，与教研专家一致 |
| 9 | 学习报告生成 | 定期生成学习报告，总结进步和不足 | 每周/每月生成学习报告，总结进步，识别不足，提供建议 | 报告内容完整、数据准确、建议可执行 |

---

## 第七部分：系统架构优化体系（8类必须全部建立完善）

### 7.1 统一状态管理（第一优先级，立即实施）

**定位**：全局状态统一管理，禁止业务状态散乱，提高状态一致性。

**状态分类**：
| 类型 | 范围 | 存储位置 | 示例 |
|------|------|----------|------|
| 共享业务状态 | 跨模块共享 | window.store | 当前科目、用户信息、全局设置 |
| 模块内部状态 | 模块内部使用 | 模块_state | 筛选条件、分页、弹窗显隐 |
| 临时UI状态 | 单次交互使用 | 局部变量 | 加载状态、编辑状态 |

**实施步骤**：
1. 建立全局状态清单，明确每个状态的归属、读写权限
2. 跨模块共享状态全部迁移到window.store
3. 模块内部状态下沉到模块_state，添加注释区分
4. 建立状态变更监听机制，状态变更时自动通知相关模块
5. 建立状态持久化机制，重要状态保存到localStorage
6. 验证状态一致性，确保跨模块状态同步

**完善性标准**：
- 跨模块共享状态100%通过store读写
- 无业务级裸全局变量
- 状态变更实时同步，无不一致
- 状态持久化完整，刷新页面不丢失
- 状态管理文档完整，每个状态有明确说明

### 7.2 其他7类架构优化（实施要点摘要）

| 序号 | 架构 | 核心功能 | 实施要点 | 完善性标准 |
|------|------|----------|----------|-----------|
| 1 | 插件化架构 | 支持功能插件扩展，模块化解耦 | 建立插件接口，支持插件注册、加载、卸载，新增功能不影响核心 | 插件化覆盖率>=80%，新增功能不影响核心 |
| 2 | 事件驱动架构 | 基于事件总线的模块通信，松耦合 | 建立事件总线，支持事件发布、订阅、解绑，模块间无直接依赖 | 事件驱动覆盖率>=70%，模块间无直接依赖 |
| 3 | 配置中心 | 统一配置管理，动态调整参数 | 建立统一配置表，支持配置动态调整，配置变更实时生效 | 配置管理覆盖率100%，参数可动态调整 |
| 4 | API网关 | 统一API入口，限流、鉴权、日志 | 建立API网关，所有API通过网关，统一限流、鉴权、日志 | API网关覆盖率100%，所有API通过网关 |
| 5 | 熔断降级 | 系统容错机制，故障隔离 | 建立熔断降级机制，故障时自动降级，核心功能仍可用 | 熔断降级覆盖率>=90%，故障不扩散 |
| 6 | 微服务化 | 核心模块独立部署，横向扩展 | 核心模块拆分为独立服务，支持独立部署、横向扩展 | 核心模块微服务化率>=50%，可独立部署 |
| 7 | 模块化架构 | 前端/后端模块化，职责清晰 | 建立模块化规范，模块职责清晰，接口明确，文档完整 | 模块化覆盖率100%，模块职责清晰 |

---

## 第八部分：用户体验增强体系（10类必须全部建立完善）

### 8.1 响应式适配（第一优先级，立即实施）

**定位**：PC/平板/手机多设备适配，确保所有设备布局正常。

**适配断点**：
| 设备 | 宽度范围 | 布局方式 | 字体大小 |
|------|----------|----------|----------|
| PC | >=1280px | 左菜单+右内容，多列布局 | 14px-16px |
| 平板 | 768px-1279px | 左菜单可折叠，双列布局 | 13px-15px |
| 手机 | <768px | 顶部菜单，单列布局，底部导航 | 12px-14px |

**实施步骤**：
1. 建立响应式设计规范，明确断点、布局、字体、间距
2. 建立CSS变量，统一管理颜色、字体、间距、圆角
3. 实现媒体查询，针对不同设备调整布局
4. 建立响应式组件库，所有组件支持响应式
5. 多设备测试，确保PC/平板/手机布局正常
6. 性能优化，确保移动端加载速度<3秒

**完善性标准**：
- 适配设备覆盖率100%（PC/平板/手机）
- 布局无错乱，所有功能可用
- 字体大小合适，可读性好
- 触控操作流畅，按钮大小适合触控
- 移动端加载速度<3秒

### 8.2 其他9类用户体验增强（实施要点摘要）

| 序号 | 功能 | 核心功能 | 实施要点 | 完善性标准 |
|------|------|----------|----------|-----------|
| 1 | 离线完全可用 | 无网络环境下完整功能可用 | 建立Service Worker缓存，IndexedDB本地存储，离线操作队列 | 离线功能覆盖率>=90%，核心功能100%可用 |
| 2 | 多端数据同步 | PC/平板/手机数据实时同步 | 建立同步机制，增量同步，冲突解决，实时同步 | 同步延迟<5秒，数据一致性100% |
| 3 | 语音交互 | 语音输入、语音朗读、语音答疑 | 集成语音识别API，语音合成API，支持语音输入、朗读、答疑 | 语音识别准确率>=90%，朗读自然流畅 |
| 4 | 手势操作 | 平板/手机手势支持，滑动切换 | 实现手势识别，支持滑动切换、缩放、拖拽，操作流畅 | 手势操作覆盖率>=80%，操作流畅 |
| 5 | 暗黑模式 | 护眼模式，夜间学习 | 建立暗黑模式主题，支持一键切换，自动跟随系统 | 暗黑模式覆盖率100%，视觉舒适 |
| 6 | 快捷键支持 | 提高操作效率，专业用户 | 建立快捷键体系，支持常用操作快捷键，快捷键可配置 | 快捷键覆盖率>=70%，操作效率提升>=30% |
| 7 | 个性化主题 | 自定义颜色、字体、布局 | 建立主题定制功能，支持颜色、字体、布局自定义，主题可保存 | 主题可定制项>=20个，用户满意度>=85% |
| 8 | 加载状态优化 | 加载动画、骨架屏、进度提示 | 建立统一加载状态组件，支持加载动画、骨架屏、进度提示 | 加载状态覆盖率100%，用户无等待焦虑 |
| 9 | 错误提示优化 | 友好错误提示、解决方案建议 | 建立统一错误提示组件，友好提示错误，提供解决方案建议 | 错误提示覆盖率100%，用户可自行解决>=80% |

---

## 第九部分：安全体系完善（10类必须全部建立完善）

### 9.1 输入校验（第一优先级，立即实施）

**定位**：XSS/SQL注入防护，100%校验用户输入。

**校验规则**：
| 输入类型 | 校验规则 | 处理方式 |
|----------|----------|----------|
| 文件名 | 长度<=255，禁止特殊字符（../、<、>、|） | 重命名存储，不使用原始文件名 |
| 文件内容 | 校验文件头，禁止可执行文件 | 文件类型白名单，内容校验 |
| 文本内容 | 长度限制，禁止HTML标签（除非富文本） | HTML转义，XSS过滤 |
| 数字 | 范围校验，类型校验 | 参数化查询，类型转换 |
| 日期 | 格式校验，范围校验 | 格式转换，范围检查 |
| 邮箱 | 格式校验 | 正则匹配 |
| 手机号 | 格式校验 | 正则匹配 |

**实施步骤**：
1. 建立统一输入校验工具函数，支持多种类型校验
2. 所有用户输入必须经过校验，禁止未校验输入直接使用
3. 建立HTML转义函数，所有用户来源字符串插入DOM时必须转义
4. 建立参数化查询，所有数据库查询使用参数化，禁止字符串拼接
5. 建立文件上传安全机制，校验文件类型、内容、大小
6. 安全扫描，确保无注入漏洞、XSS漏洞

**完善性标准**：
- 输入校验覆盖率100%
- 无XSS漏洞、SQL注入漏洞
- 文件上传安全，无恶意文件
- 安全扫描通过率100%
- 渗透测试无高危漏洞

### 9.2 其他9类安全机制（实施要点摘要）

| 序号 | 机制 | 核心功能 | 实施要点 | 完善性标准 |
|------|------|----------|----------|-----------|
| 1 | 用户认证授权 | JWT + 角色权限，最小权限原则 | 建立JWT认证，角色权限控制，最小权限原则，Token刷新机制 | 认证授权覆盖率100%，无未授权访问 |
| 2 | 数据加密存储 | 敏感数据AES-256加密 | 敏感数据加密存储，密钥安全管理，加密性能优化 | 敏感数据加密率100%，无明文存储 |
| 3 | 传输加密 | HTTPS强制加密 | 强制HTTPS，证书管理，HSTS头 | 传输加密覆盖率100%，无明文传输 |
| 4 | CSRF防护 | 跨站请求伪造防护 | 建立CSRF-Token机制，所有POST请求校验Token | CSRF防护覆盖率100%，无跨站请求 |
| 5 | 限流防刷 | 接口QPS限流，防暴力攻击 | 建立接口限流机制，按IP/用户限流，超限返回429 | 限流覆盖率>=90%，无暴力攻击 |
| 6 | 审计日志 | 操作审计，完整可追溯 | 建立审计日志表，记录所有操作，支持审计查询 | 审计日志覆盖率100%，操作可追溯 |
| 7 | 文件上传安全 | 文件类型校验、内容校验、病毒扫描 | 文件类型白名单，内容校验，大小限制，病毒扫描（可选） | 文件上传安全覆盖率100%，无恶意文件 |
| 8 | 安全扫描 | 定期安全扫描，漏洞发现和修复 | 每月安全扫描，漏洞分级，高危漏洞立即修复 | 安全扫描频率>=每月1次，高危漏洞0个 |
| 9 | 数据备份安全 | 备份加密、异地备份、定期恢复测试 | 备份加密存储，异地备份，定期恢复测试，备份访问控制 | 备份安全覆盖率100%，恢复成功率100% |

---

## 第十部分：实施优先级与时间规划

### 10.1 第一优先级（立即实施，1-2周完成）

| 序号 | 任务 | 类型 | 预计工时 | 责任专家组 | 验收标准 |
|------|------|------|----------|-----------|----------|
| 1 | 知识点知识库完善 | 知识库 | 2天 | 造价专家、数据分析师 | 100%知识点有官方来源，关联率>=90% |
| 2 | 题库/闪卡统计知识库完善 | 知识库 | 1天 | 数据分析师、开发专家 | 统计数据准确，实时更新 |
| 3 | 学习行为知识库建立 | 知识库 | 2天 | 数据分析师、开发专家 | 学习行为100%记录，行为画像完整 |
| 4 | 本地全文搜索引擎 | AI组件 | 2天 | 开发专家、AI专家 | 检索覆盖率100%，响应时间<500ms |
| 5 | 本地缓存系统完善 | AI组件 | 1天 | 开发专家、架构专家 | 缓存命中率>=80%，数据库查询减少>=50% |
| 6 | 本地监控告警 | AI组件 | 2天 | 运维专家、开发专家 | 监控覆盖率100%，异常告警响应<1分钟 |
| 7 | 数据质量监控 | 数据治理 | 2天 | 数据分析师、质量专家 | 数据质量评分>=90分，异常识别率>=95% |
| 8 | 统一状态管理 | 架构优化 | 3天 | 架构专家、前端专家 | 共享状态100%通过store，无裸全局变量 |
| 9 | 响应式适配完善 | 用户体验 | 3天 | UX专家、前端专家 | PC/平板/手机布局正常，无错乱 |
| 10 | 输入校验完善 | 安全 | 2天 | 安全专家、开发专家 | 输入校验100%，无注入/XSS漏洞 |

### 10.2 第二优先级（短期实施，3-4周完成）

| 序号 | 任务 | 类型 | 预计工时 | 责任专家组 | 验收标准 |
|------|------|------|----------|-----------|----------|
| 1 | 思维导图知识库建立 | 知识库 | 2天 | 数据分析师、开发专家 | 100%导图关联知识点，节点结构完整 |
| 2 | 真题考点分布知识库建立 | 知识库 | 3天 | 造价专家、数据分析师 | 近5年真题100%统计，分值准确 |
| 3 | 学习资料库元数据知识库 | 知识库 | 2天 | 数据分析师、开发专家 | 100%文件有元数据，标签准确率>=80% |
| 4 | 本地向量数据库 | AI组件 | 5天 | AI专家、开发专家 | 语义检索准确率>=85%，响应时间<1秒 |
| 5 | 本地任务调度器 | AI组件 | 3天 | 开发专家、运维专家 | 任务执行成功率>=99%，任务可追踪 |
| 6 | 智能知识点关联 | AI能力 | 3天 | AI专家、造价专家 | 题库关联率>=95%，闪卡>=90%，准确率>=90% |
| 7 | 智能题目生成 | AI能力 | 5天 | AI专家、造价专家 | 生成题目质量>=80分，知识点关联准确 |
| 8 | 智能闪卡生成 | AI能力 | 5天 | AI专家、造价专家 | 生成闪卡质量>=80分，无完整题目类闪卡 |
| 9 | 智能去重判断 | AI能力 | 3天 | AI专家、数据分析师 | 去重准确率>=90%，误判率<5% |
| 10 | 智能答疑助手 | AI能力 | 5天 | AI专家、造价专家 | 回答准确率>=85%，响应时间<3秒 |
| 11 | 易错点知识库建立 | 知识库 | 2天 | 造价专家、数据分析师 | 高频错题100%收录，错误原因分析准确 |
| 12 | 公式知识库建立 | 知识库 | 3天 | 造价专家 | 核心公式100%收录，参数说明完整 |
| 13 | AI模型知识库建立 | 知识库 | 2天 | AI专家、数据分析师 | AI生成内容100%记录，用户反馈100%收集 |

### 10.3 第三优先级（中期实施，5-8周完成）

| 序号 | 任务 | 类型 | 预计工时 | 责任专家组 | 验收标准 |
|------|------|------|----------|-----------|----------|
| 1 | 知识点掌握度分析 | 学习分析 | 3天 | 数据分析师、AI专家 | 掌握度评估准确率>=90%，与实际一致 |
| 2 | 遗忘曲线预测 | 学习分析 | 3天 | AI专家、数据分析师 | 预测准确率>=85%，复习计划科学 |
| 3 | 考试准备度评估 | 学习分析 | 3天 | 数据分析师、造价专家 | 评估准确率>=85%，与实际成绩相关 |
| 4 | 薄弱点自动识别 | 学习分析 | 2天 | AI专家、数据分析师 | 薄弱点识别准确率>=90% |
| 5 | 学习报告生成 | 学习分析 | 3天 | 数据分析师、产品专家 | 报告内容完整、数据准确、建议可执行 |
| 6 | 智能学习路径推荐 | AI能力 | 5天 | AI专家、产品专家 | 推荐相关性>=80%，用户满意度>=85% |
| 7 | 智能错题分析 | AI能力 | 3天 | AI专家、造价专家 | 错题原因分析准确率>=80% |
| 8 | 智能思维导图生成 | AI能力 | 3天 | AI专家、开发专家 | 导图节点完整率>=90%，层级清晰 |
| 9 | 智能内容审核 | AI能力 | 3天 | AI专家、质量专家 | 审核准确率>=90%，低质量识别率>=95% |
| 10 | 智能复习计划 | AI能力 | 3天 | AI专家、记忆算法专家 | 复习计划科学，记忆保持率>=85% |
| 11 | 法律法规知识库建立 | 知识库 | 5天 | 法律专家、造价专家 | 现行有效法条100%收录，关联考点准确 |
| 12 | 口诀记忆知识库建立 | 知识库 | 3天 | 造价专家、记忆专家 | 难记知识点100%有口诀辅助 |

### 10.4 第四优先级（长期实施，9-16周完成）

| 序号 | 任务 | 类型 | 预计工时 | 责任专家组 | 验收标准 |
|------|------|------|----------|-----------|----------|
| 1 | 本地知识图谱 | AI组件 | 10天 | AI专家、架构专家 | 知识点关联覆盖率>=90%，推理准确 |
| 2 | 插件化架构 | 架构优化 | 10天 | 架构专家、开发专家 | 插件化覆盖率>=80%，新增功能不影响核心 |
| 3 | 事件驱动架构 | 架构优化 | 8天 | 架构专家、开发专家 | 事件驱动覆盖率>=70%，模块松耦合 |
| 4 | 多端同步完善 | 用户体验 | 10天 | 开发专家、架构专家 | 同步延迟<5秒，数据一致性100% |
| 5 | 语音交互 | 用户体验 | 10天 | AI专家、前端专家 | 语音识别准确率>=90%，朗读自然 |
| 6 | 微服务化 | 架构优化 | 15天 | 架构专家、运维专家 | 核心模块微服务化率>=50%，可独立部署 |
| 7 | 离线完全可用 | 用户体验 | 10天 | 前端专家、架构专家 | 离线功能覆盖率>=90%，核心功能100%可用 |
| 8 | 暗黑模式 | 用户体验 | 3天 | UX专家、前端专家 | 暗黑模式覆盖率100%，视觉舒适 |
| 9 | 个性化主题 | 用户体验 | 5天 | UX专家、前端专家 | 主题可定制项>=20个，用户满意度>=85% |
| 10 | 快捷键支持 | 用户体验 | 3天 | 前端专家、产品专家 | 快捷键覆盖率>=70%，操作效率提升>=30% |

---

## 第十一部分：验收标准与质量保障

### 11.1 语法层验收（必须全部满足）

| 序号 | 验收项 | 标准 | 验证方法 |
|------|--------|------|----------|
| 1 | JavaScript语法 | 所有JS文件node --check零语法错误 | node --check |
| 2 | Python语法 | 所有Python文件py_compile零语法错误 | python -m py_compile |
| 3 | SQL语法 | 所有SQL语句语法正确，无注入风险 | SQL审查、参数化检查 |
| 4 | HTML语法 | 所有HTML标签闭合，无语法错误 | HTML验证工具 |
| 5 | CSS语法 | 所有CSS语法正确，无无效属性 | CSS验证工具 |
| 6 | 无SyntaxError | 控制台无SyntaxError报错 | 浏览器控制台检查 |
| 7 | 无ReferenceError | 控制台无ReferenceError报错 | 浏览器控制台检查 |

### 11.2 运行层验收（必须全部满足）

| 序号 | 验收项 | 标准 | 验证方法 |
|------|--------|------|----------|
| 1 | 后端启动 | 后端正常启动，无报错 | 启动日志检查 |
| 2 | 前端加载 | 前端正常加载，无白屏 | 浏览器实际加载 |
| 3 | 控制台错误 | 控制台无阻断性红色错误 | 浏览器控制台检查 |
| 4 | 全局对象 | window.store/api/logger正常访问 | 控制台检查 |
| 5 | 模块健康 | 所有模块healthCheck()状态正常 | 模块健康检查 |
| 6 | API响应 | 所有API响应时间<500ms | 性能测试 |
| 7 | 数据库查询 | 无慢查询（>1秒） | 慢查询日志 |
| 8 | 内存占用 | 内存占用<500MB，无内存泄漏 | 性能监控 |
| 9 | Service Worker | 完全注销无残留 | Application检查 |
| 10 | 缓存命中率 | 缓存命中率>=80% | 缓存监控 |

### 11.3 业务层验收（必须全部满足）

| 序号 | 验收项 | 标准 | 验证方法 |
|------|--------|------|----------|
| 1 | 登录流程 | 登录、科目选择流程正常 | 实际操作测试 |
| 2 | 题库功能 | 题库浏览、练习、错题功能正常 | 实际操作测试 |
| 3 | 闪卡功能 | 闪卡浏览、复习、记忆功能正常 | 实际操作测试 |
| 4 | 思维导图 | 导图浏览、编辑、生成功能正常 | 实际操作测试 |
| 5 | 学习资料库 | 文件上传、浏览、标签功能正常 | 实际操作测试 |
| 6 | 知识点关联 | 题库关联率>=95%，闪卡>=90% | 数据统计 |
| 7 | 数据一致性 | UI与数据库一致，无虚假成功 | 断网测试、刷新验证 |
| 8 | 批量导入 | 批量导入异常可完整回滚 | 异常测试 |
| 9 | PDF识别 | PDF识别区分不同错误提示 | 错误测试 |
| 10 | 离线异常 | Ollama/离线异常，核心功能可用 | 离线测试 |
| 11 | 知识库完整 | 12类知识库全部建立完善 | 知识库检查 |
| 12 | AI能力可用 | 10类AI能力全部可用 | AI功能测试 |

### 11.4 完善性验收（必须全部满足，科学精神）

| 序号 | 验收项 | 标准 | 验证方法 |
|------|--------|------|----------|
| 1 | 功能完整性 | 100%功能点实现，无缺失 | 功能清单逐项验证 |
| 2 | 数据准确性 | 数据准确率>=95%，无错误数据 | 数据抽样人工核对 |
| 3 | 性能达标 | 响应时间<500ms，无慢查询 | 性能测试监控 |
| 4 | 稳定性 | 连续运行7天无崩溃，无内存泄漏 | 稳定性测试 |
| 5 | 安全性 | 0高危漏洞，0中危漏洞 | 安全扫描审计 |
| 6 | 易用性 | 用户体验评分>=85分，无严重体验问题 | 用户测试反馈 |
| 7 | 可维护性 | 代码规范，文档完整，测试覆盖>=70% | 代码审查文档检查 |
| 8 | 可扩展性 | 架构合理，模块解耦，支持功能扩展 | 架构评估扩展测试 |
| 9 | 完善性报告 | 每个功能有完善性验证报告 | 报告检查 |
| 10 | 持续优化 | 每个功能有持续优化计划 | 计划检查 |

---

## 第十二部分：责任专家与履职机制

### 12.1 责任专家组分工

| 体系 | 责任专家组 | 核心职责 |
|------|-----------|----------|
| 知识库体系 | 造价专家、教研专家、数据分析师 | 知识库内容准确性、完整性、官方来源验证 |
| 本地AI组件 | AI专家、开发专家、架构专家 | AI组件技术实现、性能优化、稳定性保障 |
| AI能力增强 | AI专家、造价专家、产品专家 | AI能力业务价值、质量审核、用户体验 |
| 数据治理 | 数据分析师、质量专家、安全专家 | 数据质量、一致性、安全性、可追溯性 |
| 学习分析 | 数据分析师、AI专家、教育专家 | 学习分析模型、预测准确率、建议可执行性 |
| 架构优化 | 系统架构师、前端专家、后端专家 | 架构合理性、可扩展性、可维护性 |
| 用户体验 | UX专家、产品专家、前端专家 | 界面美观、交互流畅、多设备适配 |
| 安全体系 | 安全专家、开发专家、运维专家 | 安全机制完善、漏洞修复、安全审计 |

### 12.2 专家主动履职机制

| 履职内容 | 执行频率 | 完善性标准 | 责任专家 |
|----------|----------|-----------|----------|
| 知识库完整性检查 | 每日 | 12类知识库100%完整，无缺失，数据准确 | 数据分析师、造价专家 |
| 数据质量检查 | 每日 | 数据质量评分>=90分，无异常数据，数据一致 | 数据分析师、质量专家 |
| 系统健康检查 | 每日 | 系统可用性>=99.9%，无故障，性能达标 | 运维专家、开发专家 |
| 性能监控优化 | 每周 | 性能指标达标，无慢查询，响应时间<500ms | 性能优化专家 |
| 安全扫描审计 | 每月 | 高危漏洞0个，中危漏洞<3个，安全机制完善 | 安全专家 |
| 用户体验检查 | 每周 | 用户体验评分>=85分，无严重体验问题，界面美观 | UX专家、产品专家 |
| 学习分析深度挖掘 | 每周 | 10类分析维度完整，建议可执行，数据准确 | 数据分析师、教育专家 |
| AI能力优化 | 每周 | AI能力准确率提升，用户满意度提升，模型优化 | AI专家 |
| 架构优化评估 | 每月 | 架构合规率>=95%，无架构债务，模块解耦 | 系统架构师 |
| 宪法和细则更新 | 每次发现问题 | 宪法和细则持续完善，无遗漏，规则清晰 | 系统架构师、全体专家 |

### 12.3 专家履职铁律

1. ❌ 禁止等用户提醒才行动，专家必须主动思考、主动发现、主动优化
2. ❌ 禁止只做表面工作，必须深入分析、彻底解决、持续完善
3. ❌ 禁止说"可能"、"大概"、"应该"，必须有事实依据和验证结果
4. ❌ 禁止功能实现就宣称完成，必须经过完善性验证
5. ✅ 专家必须有全局视野，考虑系统的各个方面
6. ✅ 专家必须有前瞻性，预见潜在问题和风险
7. ✅ 专家必须有闭环思维，发现问题→分析原因→制定方案→实施验证→持续优化
8. ✅ 专家必须发挥科学精神，实证、质疑、迭代、全面、严谨

---



---

## 附录C：三级备份体系实施细则

### C.1 备份目录结构

```
backups/
├── GOLDEN_golden_backup/          # L1 黄金备份（只读）
│   └── 稳定版_YYYYMMDD_HHMM/
│       ├── frontend/
│       ├── backend/
│       └── 备份说明.md
├── 功能增量_模块名_YYYYMMDD/      # L2 功能增量备份
│   ├── frontend/
│   └── 变更说明.md
├── pre_change_YYYYMMDD_HHMMSS/   # L3 变更前快照
│   ├── frontend/
│   └── 变更说明.md
├── 备份关联说明.md                # 所有备份的关联图谱
└── CHANGELOG.md                  # 变更日志
```

### C.2 自动备份脚本（tools/auto_backup.py）

**功能：**
1. 对比黄金备份，识别变更文件
2. 按级别创建备份（L1/L2/L3）
3. MD5校验验证完整性
4. 自动清理过期L3快照
5. 更新备份关联说明

**调用方式：**
```bash
# 修改前自动创建L3快照
python tools/auto_backup.py --level L3 --reason "修改看板布局"

# 功能验证通过创建L2增量
python tools/auto_backup.py --level L2 --module "看板布局" --reason "V2.0对齐效果图"

# 用户锁死创建L1黄金备份
python tools/auto_backup.py --level L1 --reason "用户确认布局锁死"
```

### C.3 备份验证标准

| 验证项 | 标准 | 方法 |
|--------|------|------|
| 文件完整性 | MD5与源文件一致 | 备份后自动校验 |
| 文件可读性 | 关键文件可正常打开 | 尝试读取前100行 |
| 可恢复性 | 恢复后系统可启动 | 每周自动测试 |
| 关联完整性 | 备份说明.md存在且完整 | 检查必填字段 |

### C.4 回滚实施步骤

**按功能模块回滚（L2）：**
1. 确认要回滚的模块名
2. 从`backups/功能增量_模块名_日期/`恢复对应文件
3. 验证系统正常运行
4. 记录回滚日志

**按时间点回滚（L3）：**
1. 找到修改前的快照目录
2. 恢复所有变更文件
3. 验证系统正常运行
4. 记录回滚日志

**全量回滚（L1）：**
1. 确认黄金备份版本
2. 恢复所有关键文件
3. 验证系统正常运行
4. 记录回滚日志

### C.5 备份清理策略

- L1黄金备份：永久保留，不清理
- L2功能增量：保留全部，按模块归档，每年整理一次
- L3变更前快照：保留最近10个，超过30天自动清理
- 清理前自动验证：确保要清理的备份不是唯一可用版本

### C.6 责任专家

- 备份架构师：负责备份体系设计和脚本维护
- 验证专家：负责备份完整性验证和恢复测试
- 变更管控专家：负责变更日志和关联说明维护


> **本规划细则分册为活文档，随着系统迭代持续更新。每个体系必须有明确的定位、具体的标准、可量化的指标、可验证的验收要求、详细的实施步骤、明确的责任专家。禁止只写标题不写内容。功能存在不等于功能完善，必须发挥科学精神持续验证、持续优化、持续完善，追求极致质量。**



============================================================
# § 思维导图集成原则与特点分册_V1.0.md
============================================================

# 思维导图集成原则与特点分册 V1.0

## 一、优秀思维导图核心特点（搜集整理）

### 1. 结构特点
- **层级清晰**：根节点→章→节→知识点→考点，层级不超过5层
- **从左往右逐级细化**：根节点最简洁（科目名），越往右文字越多、越详细（章→节→知识点→考点→具体内容），这是思维导图的核心识别特征
- **线条连接**：节点之间必须有线条连接，形成树状/放射状结构，不是孤立的文字块
- **节点信息密度适中**：每个节点1个核心概念，不堆砌长文本
- **平衡分布**：左右分支数量均衡，避免一侧过重
- **逻辑递进**：从宏观到微观，从总论到分论

### 2. 视觉特点
- **颜色编码**：不同层级/重要程度用不同颜色，不超过5种主色
- **图标标注**：高频考点⭐、重点🔥、易错⚠️、口诀📝
- **线条粗细**：主干粗、分支细，视觉层级分明
- **节点形状**：根节点圆角矩形、分支椭圆、叶子节点矩形

### 3. 交互特点
- **展开/折叠**：点击节点展开/折叠子分支
- **拖拽调整**：支持拖拽节点调整顺序
- **缩放平移**：支持鼠标滚轮缩放、拖拽平移
- **详情面板**：点击节点弹出详情，显示关联内容
- **搜索定位**：关键词搜索，高亮匹配节点并自动定位

### 4. 数据特点
- **数据驱动**：节点内容来自知识库，非手动输入
- **动态更新**：底层数据变化时导图自动更新
- **关联丰富**：每个节点关联题目、闪卡、讲义、笔记
- **统计可视化**：节点显示考频、题目数、掌握程度等统计数据

### 5. 多视图特点
- **思维导图视图**：放射状/树状布局
- **大纲视图**：缩进列表形式，适合快速浏览
- **列表视图**：表格形式，适合批量管理
- **三视图同步**：任一视图操作，其他视图同步更新

---

## 二、本系统思维导图集成原则（铁律）

### 核心认知（最高原则）
**思维导图本质就是知识点体系的可视化投影**——有什么样的知识点体系，就自动生成什么样的思维导图。导图不是独立创建、独立存储的"图片"或"文档"，而是knowledge_points表的另一种展现形式。知识点体系更新，导图自动同步更新，无需手动维护。

### 原则1：知识点体系为唯一骨架
- 思维导图结构必须与`knowledge_points`表完全一致：科目→章→节→知识点
- 禁止手动创建与知识点体系不一致的导图结构
- 导图节点ID必须与知识点point_id一一对应
- 知识点体系更新时，导图结构自动同步更新

### 原则2：数据唯一来源，不重复存储
- 导图节点显示的考频、题目数、闪卡数等数据，必须从题库/闪卡表**实时查询**，不冗余存储
- `mind_maps`表只存储导图结构（content_json），不存储统计数据
- 统计数据在前端渲染时动态计算，确保数据一致性

### 原则3：双向关联，点击跳转
- 每个知识点节点必须关联：
  - 该知识点的所有题目（点击跳转题库筛选）
  - 该知识点的所有闪卡（点击跳转闪卡筛选）
  - 该知识点的讲义/教材位置（点击跳转PDF定位）
- `mindmap_node_links`表必须启用，记录节点与题目/笔记的关联
- 从题库/闪卡点击知识点，也能跳转到导图对应节点

### 原则4：颜色编码标准化
- **高频考点**（5年考≥10次）：红色节点 🔴
- **中频考点**（5年考5-9次）：橙色节点 🟠
- **低频考点**（5年考<5次）：绿色节点 🟢
- **已掌握**（正确率≥80%）：蓝色边框 🔵
- **未掌握**（正确率<60%）：灰色边框 ⚪
- **新增考点**：紫色节点 🟣
- 颜色规则必须全局统一，禁止各页面自定义

### 原则5：节点信息标准化
每个知识点节点必须显示：
```
【知识点名称】
📊 5年考X次 | 正确率Y%
📝 X题 | 🃏 X卡
```
- 第一行：知识点名称
- 第二行：考频+正确率（统计数据）
- 第三行：题目数+闪卡数（关联数据）
- 节点信息不超过3行，保持简洁

### 原则6：三视图同步
- 思维导图视图：放射状布局，适合整体把握
- 大纲视图：缩进列表，适合快速浏览和复习
- 列表视图：表格形式，适合批量管理和筛选
- 三个视图共享同一份数据，任一视图操作同步更新

### 原则7：交互流程标准化
```
点击节点 → 展开/折叠子分支（单击）
双击节点 → 打开详情面板（显示关联题目/闪卡/讲义）
右键节点 → 操作菜单（跳转题库/闪卡/讲义、标记掌握程度）
搜索关键词 → 高亮匹配节点，自动展开路径并定位
```

### 原则8：生成机制
- 导图从知识点体系**自动生成**，禁止手动创建空结构
- 生成时自动关联该知识点的题目和闪卡
- 支持按科目、章节、考频筛选生成局部导图
- 支持导出为图片/Markdown/PDF

### 原则9：创建入口统一在学习资料库
- 思维导图的**创建/生成入口必须在学习资料库**，与题库识别、闪卡生成并列
- 思维导图页面只负责**展示、查看、交互**，不提供"新建导图"按钮
- 用户在学习资料库选择文件/文件夹后，可一键生成思维导图
- 生成的导图自动关联知识点体系，保存到mind_maps表
- 导图页面提供"导图列表"供查看已生成的导图，点击进入详情展示

### 原则10：双版本模式（问题版/答案版）
思维导图与闪卡一样，必须支持两种视图模式，作为记忆强化工具：

**问题版（记忆模式）**：
- 只显示节点名称（章/节/知识点名）
- 隐藏考频、题目数、闪卡数、颜色编码等详细信息
- 目的：触发用户主动回忆"这个知识点包含什么内容、考多少次"
- 节点简洁，只有文字，无统计数据

**答案版（学习模式）**：
- 显示完整节点信息（知识点名+考频+题目数+闪卡数+颜色编码）
- 目的：验证回忆结果，核对知识点的详细数据
- 节点信息丰富，3行显示

**切换机制**：
- 页面顶部提供"问题版/答案版"一键切换按钮
- 两种模式共享同一份知识点数据，只是显示粒度不同
- 默认进入答案版（学习模式），用户可切换到问题版自测记忆

---

## 三、思维导图识别生成思路（从结构特点出发）

### 核心识别特征
思维导图的本质结构是**"从左往右逐级文字越来越多，有线条连接"**：
```
[根节点：科目名] ←最简洁
    │
    ├─[章名] ←简洁
    │   │
    │   ├─[节名] ←稍详细
    │   │   │
    │   │   └─[知识点名] ←详细
    │   │       │
    │   │       └─[考点/具体内容] ←最详细
    │   │
    │   └─[节名]
    │
    └─[章名]
```

### 识别PDF生成导图的思路
1. **第一层（根节点）**：从文件名/科目提取，如"一造管理"——最简洁
2. **第二层（章）**：从PDF目录/标题提取"第X章 XXX"——简洁
3. **第三层（节）**：从PDF目录/标题提取"X.X XXX"——稍详细
4. **第四层（知识点）**：从讲义/知识点精讲中提取知识点名称——详细
5. **第五层（考点）**：从真题/解析中提取具体考点——最详细

### 文字量递增规则（趋势原则，非硬性字数限制）
- **核心原则**：从左往右，节点内容**概括程度递减、详细程度递增**——根节点最概括，越往右越具体
- 根节点：科目简称（如"一造管理"），高度概括
- 章节点：章名（如"工程造价管理及其基本制度"），概括本章主题
- 节节点：节名（如"工程造价的基本内容"），明确本节范围
- 知识点节点：知识点名称+考频统计（如"工程造价的含义 📊5年考37次"），具体到知识点
- 考点节点：具体考点内容（如"工程造价的含义：工程建设固定资产投资"），最详细
- **不做硬性字数截断**，以内容完整准确为前提，仅控制节点不堆砌长文本（单个节点≤2行）

### 线条连接规则
- 所有节点必须有父节点连线，禁止孤立节点
- 同层级节点之间不连线（避免网状结构）
- 线条从父节点右侧连到子节点左侧
- 主干线条粗、分支线条细

### 识别优先级
1. **教材目录**：最权威的章→节结构来源
2. **知识点精讲PDF**：知识点名称的权威来源
3. **考纲**：验证知识点完整性
4. **真题解析**：提取考点和考频
5. **普通讲义**：辅助补充

---

## 三、思维导图与其他模块协同关系

```
知识点体系（骨架）
    ↓ 自动生成
思维导图（可视化）
    ↕ 双向关联
题库（验证） ←→ 闪卡（记忆） ←→ 讲义（来源）
```

- **知识点体系**是骨架，定义"有什么"
- **思维导图**是可视化，展示"结构关系"
- **题库**是验证，检验"掌握没有"
- **闪卡**是记忆，强化"记住没有"
- **讲义/教材**是来源，提供"权威依据"

五者必须围绕知识点统一协同，数据互通，不能各自为政。

---

## 四、验收标准

### 语法层
- 导图结构与knowledge_points表100%一致
- 节点ID与point_id一一对应
- 无孤立节点、无重复节点

### 运行层
- 点击节点正常展开/折叠
- 双击节点弹出详情面板，显示关联题目/闪卡
- 三视图切换正常，数据同步
- 搜索功能正常，高亮定位准确

### 业务层
- 每个知识点节点显示正确的考频、题目数、闪卡数
- 从导图跳转题库/闪卡，筛选条件正确
- 从题库/闪卡跳转导图，定位到正确节点
- 知识点体系更新后，导图结构自动同步

---

## 五、思维导图标准化规则（2026-09-07 新增）

### 5.1 命名规范（铁律）
- **问题版**：`填空—第X章第Y节 节名称`
- **答案版**：`答案—第X章第Y节 节名称`
- **合并版**：`填空/答案—科目名知识点精讲_合并版`
- 禁止使用WM_编号、分部标记（一）（二）等非标准命名

### 5.2 数据来源唯一原则
- 思维导图的节结构**唯一来源**是知识点精讲PDF（lectures表）
- 禁止从其他来源（如01.精讲班）混入导图
- 节名称必须与知识点精讲PDF完全一致

### 5.3 多分部PDF合并规则
- 一个节对应多个PDF（如2.4有3个、3.5有4个、4.2有6个）时，**必须合并为一个节导图**
- 合并策略：按PDF顺序拼接内容，去重，保持知识点完整性
- 合并后删除分部导图，只保留标准命名的节导图

### 5.4 标准化流程（通用，换科目自动适配）
1. **提取**：从lectures表提取知识点精讲PDF的节结构
2. **匹配**：将现有导图与标准节结构匹配，重命名为标准标题
3. **合并**：多分部节合并内容
4. **清理**：删除非母本来源、命名错误、重复的导图
5. **补全**：缺失的问题版从答案版自动生成

### 5.5 标准化工具
- 工具位置：`backend/utils/mindmap_standardizer.py`
- 类名：`MindmapStandardizer`
- 调用方式：自动遍历所有有知识点精讲的科目，执行完整标准化
- 适用范围：所有科目，换教材自动适配

### 5.6 问题版/答案版区分规则
- **问题版**（only_questions）：保留结构，答案替换为"？"占位
- **答案版**（with_answers）：完整知识点内容
- 每个节必须同时有问题版和答案版，缺一不可

### 5.7 节点收缩交互
- 节点收缩使用**加减号**（+/-）
- 支持选择性收缩：想看哪一级看哪一级，想看哪一部分看哪一部分
- 导图合集支持节点收缩

---

## 六、Tab功能职责定义（2026-09-07 新增）

### 6.1 Tab顺序（铁律）
**导图创建 → 节导图 → 章导图 → 科目导图**

禁止调整顺序，禁止新增其他一级Tab。

### 6.2 各Tab功能职责

| Tab名称 | 功能职责 | 输入 | 输出 | 禁止事项 |
|---------|----------|------|------|----------|
| **导图创建** | 手工创建导图，辅助功能，几乎不用 | 模板/PDF文件 | 新导图（保存到节导图列表） | 禁止作为主要来源、禁止直接展示 |
| **节导图** | 管理所有节级导图，问题版/答案版并列展示 | 无（自动加载） | 节导图列表，支持编辑/删除 | 禁止按章合并、禁止科目级展示 |
| **章导图** | 按章筛选展示节导图，选择节查看详情 | 章节选择 | 单节导图展示 | 禁止编辑、禁止删除、禁止合并 |
| **科目导图** | 自动合并当前科目所有答案版导图，科目级总览 | 无（自动生成） | 科目级合并导图，支持节点收缩/布局切换 | 禁止编辑、禁止删除、禁止按节拆分 |

### 6.3 导图创建Tab细则
**定位**：手工创建，辅助功能，**几乎不用**，仅用于特殊情况手动创建导图。

**导图主要来源**：资料库（讲义管理）的"同步到导图"按钮，自动生成节导图。

**包含两个子功能**：
1. **新建导图**：加载模板，手动编辑，保存为新导图
2. **智能导图拆分**：从知识点精讲PDF自动识别思维导图，生成问题版+答案版

**输出要求**：
- 生成的导图必须符合5.1命名规范
- 必须同时生成问题版和答案版
- 保存后自动出现在"节导图"Tab中

### 6.4 节导图Tab细则
**布局**：左右两列
- 左列：问题版导图列表（填空—第X章第Y节）
- 右列：答案版导图列表（答案—第X章第Y节）

**功能**：
- 点击查看导图详情
- 编辑导图内容
- 删除单个导图
- 全部删除（需确认）
- 按章节目排序（铁律）

**排序规则**：
- 按章节编号排序（章→节→目）
- 同章节内按知识点名称排序
- 无章节编号的排最后

### 6.5 章导图Tab细则
**功能**：
- 下拉选择章节（到节层级）
- 展示该节的问题版/答案版导图
- 支持切换问题版/答案版

**禁止**：
- 禁止编辑功能（编辑统一在节导图Tab）
- 禁止删除功能（删除统一在节导图Tab）
- 禁止合并功能（合并统一在科目导图Tab）

### 6.6 科目导图Tab细则
**功能**：
- 自动合并当前科目所有答案版导图
- 支持节点收缩/展开（加减号）
- 支持布局切换（左右布局/上下布局）
- 左右布局：章在左，向右拓展
- 上下布局：章在上，向下拓展

**禁止**：
- 禁止编辑（只读展示）
- 禁止删除
- 禁止按节拆分展示

### 6.7 数据流向（铁律）
```
资料库（讲义管理）→ 同步到导图 → 节导图（管理/编辑/删除）
                                    ↓ 筛选展示
                              章导图（按章查看）
                                    ↓ 自动合并
                              科目导图（科目级总览）

导图创建（手工）→ 辅助功能，几乎不用，仅用于特殊情况手动创建
```

- **数据主要来源**：资料库（讲义管理）的"同步到导图"按钮
- **导图创建**：手工创建，辅助功能，几乎不用，仅用于特殊情况
- 节导图是唯一的管理入口（编辑/删除）
- 章导图和科目导图是只读展示，不修改数据
- 任何修改必须回到节导图Tab操作

### 6.8 验收标准
1. Tab顺序正确：导图创建→节导图→章导图→科目导图
2. 节导图列表按章节目排序，无乱序
3. 节导图支持编辑/删除/全部删除
4. 章导图只读，无编辑/删除按钮
5. 科目导图自动合并，支持节点收缩和布局切换
6. 数据流向正确：创建→节导图→章导图/科目导图（只读）
7. 命名规范：填空—第X章第Y节 / 答案—第X章第Y节



============================================================
# § PDF公共预处理底座实施细则分册_V1.0.md
============================================================

# 水利智学系统 PDF公共预处理底座实施细则分册（V1.0）

> **版本**：V1.0
> **生效日期**：2026-09-08
> **地位**：本文件为《系统设计宪法》配套实施细则，详细规定PDF公共预处理底座的完整流程、每步操作规范、异常处理、业务层定制点。所有PDF识别（思维导图/题库/闪卡）必须严格遵守本细则。
> **制定委员会**：系统架构师牵头，PDF识别算法专家、AI视觉专家、题库识别算法专家、思维导图专家、闪卡算法专家联合制定。
> **核心原则**：预处理是地基、识别质量是最终目标、最大程度不动原始资料、异常直接提示不浪费时间。

---

## 一、基座定位

**通用PDF处理基座**，不绑定任何业务场景。所有PDF识别共享同一套预处理和识别能力，业务层只做关键词和分层规则的定制。

基座一次做好，所有业务共享；优化一处，全局生效。

---

## 二、完整全流程（输入→输出，17步，严格按序）

### 输入
一个或多个PDF文件（同一节）+ 业务类型配置

---

### 第一阶段：基础预处理（每个PDF独立，8步）

#### 第1步：倾斜矫正
- **操作**：投影法检测倾斜角度 → 霍夫变换全角度验证 → 旋转矫正
- **范围**：±10度以内直接矫正；>10度用霍夫变换全角度检测（0-180度）
- **异常处理**：矫正失败 → AI视觉识别倾斜角度 → 仍失败 → **标记异常，提示"XX文件倾斜异常，请重新上传"**
- **输出**：矫正后图像 + 倾斜角度

#### 第2步：位置矫正
- **操作**：统计内容区域x坐标分布 → 判断页面靠左/靠右 → 平移居中
- **范围**：平移距离动态计算，不设硬上限
- **异常处理**：平移超正常范围 → 判断是否扫描错误（内容只在半边）→ AI图像修复补全 → 仍失败 → **标记异常，提示"XX文件位置异常，请重新上传"**
- **输出**：居中后图像 + 平移距离

#### 第3步：去水印
- **操作**：关键词匹配法（找"环球网校""学员专用""请勿外泄"等）→ 坐标定位法 → 频域滤波法，自动选最优
- **原则**：只去重复出现的水印文字，不能影响正文识别
- **异常处理**：三种方法均失败 → 保留原图，OCR时增加噪声过滤
- **输出**：去水印后PDF + 使用的方法名

#### 第4步：去页眉页脚
- **操作**：三种方法结合
  1. 统计中位数法（分析前10页顶底部文本，测定页眉页脚高度）
  2. 遮挡法（白色矩形直接覆盖页眉页脚区域）
  3. 坐标法（固定坐标裁剪）
- **原则**：页眉页脚不超过页高15%，不能切掉正文
- **输出**：页眉底部y坐标 + 页脚顶部y坐标

#### 第5步：对比度增强（自动选择）
- **操作**：CLAHE自适应直方图均衡化
- **触发条件**：先做一次低分辨率OCR测试，识别率低时自动启用
- **参数**：clipLimit=2.0, tileGridSize=(8,8)
- **输出**：增强后图像

#### 第6步：二值化（自动选择）
- **操作**：自适应阈值二值化
- **触发条件**：对比度增强后识别率仍低时启用
- **参数**：blockSize=15, C=5
- **注意**：图片形式思维导图不建议二值化
- **输出**：二值化图像

#### 第7步：去噪（自动选择）
- **操作**：中值滤波 + 形态学开运算
- **触发条件**：二值化后仍有噪点时启用
- **参数**：kernelSize=3
- **输出**：去噪后图像

#### 第8步：去杂裁剪
- **操作**：内容边界检测算法 → 找到最左/最右/最上/最下内容坐标 → 向外扩5%余量 → 裁剪
- **原则**：不固定百分比，通过算法确定内容边界，不能切掉正文
- **输出**：裁剪后图像 + 裁剪坐标

**第一阶段结束**：每个PDF输出一组预处理后图像

---

### 第二阶段：多PDF合并（第9步）

#### 第9步：合并
- **方式一：长图合并**
  - 操作：垂直拼接，宽度取最大值，不足补白，高度累加
  - 适用：连续内容、跨页思维导图
- **方式二：拼图合并**
  - 操作：网格拼接（自动算行列2x2/3x3），每格打页码编码
  - 适用：分散页面、独立知识点
- **分块标记**：长图太高时OCR需分块，每块标记block_idx和y_offset，合并时按顺序还原坐标，不乱序
- **输出**：合并后图像 + 分块标记

**第二阶段结束**：一张合并后的长图/拼图

---

### 第三阶段：三层识别（第10-12步）

#### 第10步：预识别（低分辨率快速扫描）
- **操作**：
  1. 第一次预处理时做全本低分辨率OCR（1x-2x）并存储结果
  2. 后续预识别直接读存储的OCR结果，不重复扫描
  3. 扫描范围根据关键词出现情况动态调整：找到关键词就停止，没找到扩大范围
- **标记内容**：有效页、关键词位置、图片形式思维导图区域
- **输出**：`[{page_idx, has_keyword, keyword_y, has_image, image_region}]` + OCR存储路径

#### 第11步：精准识别（只对标记区域）
- **操作**：
  1. 只对预识别标记的有效区域做3x高分辨率OCR
  2. 关键词之后的区域才识别，之前的跳过
  3. 图片形式思维导图用AI视觉识别（qwen3-vl:4b），不用OCR
  4. 去干扰裁剪：去掉例题/答案/解析区域（根据业务类型配置）
  5. **规则打基础标签**（基于文本特征和位置特征，快、稳定、可预设）
     - 结构类：标题、副标题、正文、段落、列表项、序号、引用、代码块、分隔线
     - 位置类：页眉、页脚、页边距、左上角、右上角、左下角、右下角、居中、左对齐、右对齐
     - 内容类：图片、表格、公式、图表、注释、脚注、参考文献、目录、水印
     - 格式类：加粗、斜体、下划线、删除线、大字号、中字号、小字号、有颜色
     - 语义类：数字、字母、中文、英文、符号、标点、括号、引号
- **输出**：`[{text, x, y, width, height, confidence, page, block, basic_labels}]`

#### 第12步：验证识别（三者互相矫正，含存储功能）
- **操作**：
  1. OCR结果 vs PDF文本提取：文本相似度>0.6认为一致，短文本<10字直接通过
  2. AI视觉 vs OCR：节点结构对比
  3. 不确定节点：AI二次识别
  4. 冲突处理：保留置信度高的结果
  5. 修正错误，得到纯净结果
  6. **AI增加复杂标签**（需要纯净OCR结果分析语义，准、灵活、自适应）
     - 语义理解：知识点、问题、答案、例题、练习题、总结、定义、原理、方法、公式
     - 层级关系：一级、二级、三级、四级、父节点、子节点、兄弟节点
     - 逻辑关系：并列、递进、总分、因果、对比、条件
     - 业务特定：思维导图节点/根/分支、题目题干/选项/答案/解析、卡片正面/背面/口诀
  7. **质量标记**（低置信度区域）
     - OCR置信度<0.7 或 AI标签置信度<0.7
     - 记录：page、x、y、width、height、confidence、reason
     - 低置信度区域>30%时自动触发AI视觉二次识别
     - 低置信度区域>50%时提示用户"XX页质量较差，建议重新上传"
  8. **图片和OCR同步存储**（存储验证后的纯净最优数据，一次存储，多次使用）
     - 纯净页面图像（PNG）
     - 验证后的纯净OCR结果（JSON，含text/confidence/x/y/width/height/labels）
     - 坐标映射（scale/offset_x/offset_y）
     - 所有标签（规则基础标签+AI复杂标签）
     - 质量标记（低置信度区域）
     - 预处理参数（第8步记录的：dpi/方法/角度/坐标等）
- **输出**：验证后的文本项列表 + 存储路径

**第三阶段结束**：验证后的文本项列表 + 同步存储的纯净数据

---

### 第四阶段：后处理（第13-17步）

#### 第13步：节点拆分
- **操作**："和/与/及/、"连接的知识点拆成独立节点
- **业务差异**：思维导图拆分，题库不拆分
- **输出**：拆分后列表

#### 第14步：去重（最后一步）
- **操作**：对验证后的精准结果去重，三种方法可选
  1. exact：精确匹配（MD5），最快，默认
  2. semantic：语义相似度，适合相似文本
  3. knowledge_point：考点去重
- **原则**：去重是最后一步，不在中间去重，避免二次伤害；保留置信度最高的
- **输出**：去重后列表

#### 第15步：动态分层
- **操作**：基于x坐标gap的统计特征（均值+标准差）自动确定层级边界，不硬编码阈值
- **特殊情况**：纵向列表形式（x坐标范围小于2倍平均宽度）全部视为一级节点
- **输出**：`{level1: [...], level2: [...], level3: [...]}`

#### 第16步：构建层级
- **操作**：最近邻归属，每个子节点只归属于最近的父节点，不重复归属
- **业务差异**：思维导图按x坐标归属，题库按题号归属
- **输出**：`{node, children: [...]}`

#### 第17步：生成输出
- **操作**：按业务类型生成对应格式
  - **思维导图**：markdown，问题版/答案版区分（？后有文字=答案版，无=问题版）
    - 命名格式：`答案—第X章第X节 节名称` / `填空—第X章第X节 节名称`
    - 层级映射：一级→####，二级→#####，三级→-
  - **题库**：JSON（题干+选项+答案+解析）
  - **闪卡**：`{front, back, mnemonic, knowledge_point}`
- **输出**：最终结构化结果

**全流程结束**

---

## 三、业务层定制点（每一步明确）

| 流程步骤 | 基座通用 | 业务层定制 |
|---|---|---|
| 基础预处理(1-8) | 通用 | 不定制 |
| 多PDF合并(9) | 通用 | 不定制 |
| 预识别(10) | 低分辨率扫描 | **关键词列表**：思维导图/题库/闪卡不同 |
| 精准识别(11) | 高分辨率OCR | **去干扰规则**：思维导图去例题答案，题库保留 |
| 验证识别(12) | 三者矫正 | **验证规则**：导图验证节点结构，题库验证题目完整 |
| 节点拆分(13) | 和/与/及拆分 | **是否拆分**：导图True，题库False |
| 去重(14) | 3种方法 | **选方法**：导图exact，题库knowledge_point |
| 动态分层(15) | x坐标聚类 | **层级映射**：导图####/#####/-，题库题干/选项/答案 |
| 构建层级(16) | 最近邻归属 | **归属规则**：导图按x，题库按题号 |
| 生成输出(17) | 结构化数据 | **输出格式**：导图markdown，题库JSON，闪卡front/back |

---

## 四、异常处理统一原则

1. **逐级升级**：简单方法 → 复杂方法 → AI辅助 → 兜底
2. **不停滞**：异常页继续走后续流程，不中断整体
3. **能处理就自动处理**：不打扰用户
4. **标记异常就直接提示**：只要兜底也无法解决，**直接提示"XX文件XX异常，请重新上传"**，不搞分级，不浪费时间
5. **日志记录**：所有异常记录类型、尝试方法、最终结果

---

## 五、增强OCR存储机制（EnhancedOCRStore）

### 5.1 定位
EnhancedOCRStore是基座的**存储增强层**，不重新实现预处理和识别，只负责存储、缓存、打标签和质量标记。

### 5.2 存储时机
**第12步验证识别后**，存储验证后的纯净最优结果。不在精准识别时存储（未验证的中间结果不纯净）。

### 5.3 存储内容（6项）
1. **纯净页面图像**（PNG）：去水印+去页眉页脚+倾斜矫正+增强+二值化+去噪+去杂裁剪后的完整页面
2. **纯净OCR结果**（JSON）：验证后的OCR结果，含text/confidence/x/y/width/height/labels，已过滤页眉页脚水印
3. **坐标映射**：scale（缩放比例）、offset_x（x偏移）、offset_y（y偏移），用于原PDF坐标→预处理后图像坐标转换
4. **所有标签**：规则基础标签+AI复杂标签，格式为{标签名: [item_indices]}
5. **质量标记**：低置信度区域（page/x/y/width/height/confidence/reason）、异常标记（page/type/description）
6. **预处理参数**：pdf_path、pdf_hash（缓存版本校验）、total_pages、dpi、watermark_method、header_y、footer_y、deskew_angles、enhance_method、binarize_method、ocr_engine、ai_model、timestamp

### 5.4 打标签流程（2步）
**第1步：规则打基础标签**（第11步精准识别后，快、稳定）
- 基于文本特征和位置特征
- 结构类/位置类/内容类/格式类/语义类，共40+种标签

**第2步：AI增加复杂标签**（第12步验证识别后，准、灵活）
- 调用本地AI模型（不锁死版本，自动选择最优）
- 语义理解/层级关系/逻辑关系/业务特定，共30+种标签
- 在规则基础上增加，不是从零开始

### 5.5 缓存复用机制
- **类级缓存**：`_cache = {pdf_path: {page_idx: {...}}}`
- **缓存key**：PDF路径 + PDF文件哈希
- **版本校验**：PDF文件变更后（哈希变化），缓存自动失效
- **过期时间**：24小时自动清理
- **命中处理**：命中缓存时跳过预处理，直接用存储结果

### 5.6 自动清理机制
- **触发时机**：识别完成后自动调用`cleanup()`
- **清理内容**：临时图像文件、临时OCR结果文件
- **保留内容**：缓存（24小时内有效）
- **手动清理**：可调用`cleanup(force=True)`强制清理所有缓存

### 5.7 质量标记触发机制
- **低置信度区域**：OCR置信度<0.7 或 AI标签置信度<0.7
- **自动触发**：低置信度区域>30%时，自动触发AI视觉二次识别
- **用户提示**：低置信度区域>50%时，提示用户"XX页质量较差，建议重新上传"

### 5.8 业务层快速提取
业务层通过标签快速提取，不需要重新判断：
- **思维导图**：用"知识点清单/知识点清单总结"定位，用"知识点/问题/答案"提取内容
- **题库**：用"序号/正文/括号"定位，用"题目/选项/答案"提取内容
- **闪卡**：用"正文/列表项/加粗"定位，用"知识点/口诀"提取内容

---

## 六、贯穿全程原则

1. **最大程度不动原始资料**：所有操作生成新文件，不修改原PDF，临时文件用完即删
2. **AI不锁死版本**：自动检测可用模型，视觉用qwen3-vl:4b，嵌入用bge-m3
3. **换科目自动适配**：关键词、分层规则全部参数化，不硬编码
4. **识别质量是最终目标**：所有流程都是手段，识别准确、完整、不重复才是目的
5. **严格按序执行**：17步顺序锁死，不得跳步、乱序

---

## 六、验收标准

1. 预处理后图像：无倾斜、无偏移、无水印、无页眉页脚、正文完整
2. 预识别标记：关键词定位准确，有效页无遗漏
3. 精准识别：只识别标记区域，不识别例题/答案/解析
4. 验证识别：三者矫正后置信度>0.9
5. 去重：无重复节点，无遗漏
6. 分层：层级正确，不硬编码阈值
7. 输出：格式正确，问题/答案版区分准确
8. 异常处理：能自动处理的不提示，不能处理的直接提示重新上传

---

**本细则自发布之日起生效，所有PDF识别相关开发必须严格遵守。**



======================================================================
# 附录5 【来源：融合迁移总集.md】
======================================================================

# 📦 融合迁移总集.md
> 版本 V1.0 ｜ 2026-09-13 ｜ 合并自根目录散落文件，每份标来源，原文件已归档。

## 📑 目录
1. 【来源：融合总方案_长期参考.md】
2. 【来源：系统模块化融合方案.md】
3. 【来源：待执行迁移计划.md】
4. 【来源：前端API新旧映射表.md】
5. 【来源：增强OCR存储设计文档_V1.0.md】
6. 【来源：本地AI知识库_设计规范汇总.md】
7. 【来源：模块化插件化底座设计方案_V1.0.md】

---



============================================================
# § 1. 【来源：融合总方案_长期参考.md】
============================================================

# 水利智学系统 - 新旧代码融合总方案（长期参考文档）

> **重要提醒**：每次推进融合前，必须先读本文件，确保不遗漏！
> 
> 最后更新：2026-09-12
> 状态：已深入对比4个模块，待继续对比其余模块

---

## 一、核心原则（必须遵守）

1. **布局锁死**：竖向导航栏、状态栏、顶部导航栏不动
2. **旧代码不动**：旧API文件不删，继续跑
3. **新模块补全**：把旧代码的业务逻辑融合到新模块service.py
4. **路由层薄壳**：新模块routes.py只做参数校验，调用service
5. **前端无感**：API路径不变，前端零改动
6. **逐步验证**：一个功能一个功能切，对比新旧返回

---

## 二、整体架构

```
旧API（33个文件，279个端点）
    ↓ 业务逻辑提取
新模块service（7个域）
    ↓ 路由层薄壳
新模块routes（256个端点）
    ↓ 前端无感
前端（API路径不变）
```

---

## 三、全模块融合清单（已深入对比）

### P0核心（每天用，优先融合）

#### 1. 题库域 qb ✅ 已深入对比

**旧API：question.py（28个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| _normalize_question_text | 20 | 题目文本规范化（去重用） |
| _calc_question_hash | 28 | 计算题目标哈希（去重用） |
| _load_existing_question_hashes | 40 | 加载已有题目哈希（去重用） |
| random_real_questions | 57 | 加权随机抽题（错题越多出现频率越高） |
| ai_weak_review | 134 | AI薄弱点智能复习（遗忘曲线+错误次数+逾期天数） |
| question_list | 273 | 题目列表（分页+多条件筛选） |
| question_detail | 288 | 题目详情（包含收藏状态） |
| delete_question | 300 | 删除题目 |
| answer_question | 307 | 提交答案（异常排除+SM-2更新） |
| collect_question | 338 | 收藏 |
| uncollect_question | 343 | 取消收藏 |
| collect_list | 348 | 收藏列表 |
| wrong_list | 366 | 错题列表 |
| wrong_today | 428 | 今日错题 |
| update_wrong | 439 | 更新错题 |
| delete_wrong | 452 | 删除错题 |
| mark_mastered | 457 | 标记掌握 |
| get_filters | 462 | 筛选条件 |
| get_knowledge_points | 512 | 知识点 |
| get_chapter_tree | 527 | 章节树 |
| export_questions | 633 | 导出题目 |
| export_questions_excel | 743 | 导出Excel |
| download_template | 769 | 下载模板 |
| import_parsed_questions | 956 | 导入解析题目 |
| mastery_analysis | 1026 | 掌握度分析 |
| get_diagram_image | 1166 | 获取图表 |
| batch_match_sections | 1306 | 批量匹配章节 |
| analyze_wrong_reason | 1370 | 错因分析 |

**新模块：qb/service.py（27个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| __init__ | 16 | 初始化 |
| _get_db | 20 | 获取数据库连接 |
| get_question_list | 30 | 题目列表 |
| get_question_detail | 73 | 题目详情 |
| get_question_statistics | 91 | 题目统计 |
| random_questions | 116 | 随机抽题（✅已融合加权） |
| record_answer | 214 | 记录答题 |
| get_wrong_list | 251 | 错题列表 |
| delete_wrong | 286 | 删除错题 |
| mark_wrong_mastered | 302 | 标记掌握 |
| get_collect_list | 322 | 收藏列表 |
| add_collect | 357 | 添加收藏 |
| delete_collect | 374 | 删除收藏 |
| get_chapter_tree | 394 | 章节树 |
| get_knowledge_points | 413 | 知识点 |
| create_question | 436 | 创建题目 |
| update_question | 461 | 更新题目 |
| delete_question | 482 | 删除题目 |
| batch_delete_questions | 498 | 批量删除 |
| export_questions | 514 | 导出题目 |
| confirm_recognized_questions | 518 | 确认识别题目 |
| generate_exam | 551 | 生成考试 |
| submit_exam | 620 | 提交考试 |
| get_exam_history | 692 | 考试历史 |
| get_exam_detail | 728 | 考试详情 |
| get_exam_stats | 747 | 考试统计 |

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| ai_weak_review | P0 | AI薄弱点智能复习（遗忘曲线+错误次数+逾期天数） |
| wrong_today | P0 | 今日错题 |
| get_filters | P1 | 筛选条件 |
| mastery_analysis | P0 | 掌握度分析 |
| analyze_wrong_reason | P1 | 错因分析 |
| import_parsed_questions | P1 | 导入解析题目 |
| update_wrong | P1 | 更新错题 |
| _normalize_question_text | P1 | 题目文本规范化 |
| _calc_question_hash | P1 | 计算题目标哈希 |
| _load_existing_question_hashes | P1 | 加载已有题目哈希 |
| export_questions_excel | P2 | 导出Excel |
| download_template | P2 | 下载模板 |
| get_diagram_image | P2 | 获取图表 |
| batch_match_sections | P2 | 批量匹配章节 |

**深入代码实现对比：**

#### random_real_questions（加权随机抽题）深入对比

| 对比项 | 旧代码（question.py:57-131） | 新模块（qb/service.py:116-208） | 差异 |
|--------|---------------------------|-------------------------------|------|
| 查询方式 | SQLAlchemy ORM | 原生SQL | 方式不同 |
| 多科目筛选 | 支持逗号分隔多科目 | 只支持单科目 | ❌ 缺失 |
| 真题条件 | 只抽真题（year!=""或source="真题"） | 抽所有题 | ❌ 缺失 |
| 错误统计 | Python层遍历累加 | SQL聚合SUM() | ✅ 优化了 |
| 权重逻辑 | 0次=1,1次=2,2次=3,3+次=4 | 相同 | ✅ 已融合 |
| 字段名 | option_a/b/c/d/e单独列 | options JSON数组 | ❌ 格式不同 |
| 返回格式 | {list, total, real_total} | List直接返回 | ❌ 格式不同 |
| 额外字段 | score, source | 没有 | ❌ 缺失 |

**需要融合：**
1. 多科目筛选（question.py:64-69）
2. 真题条件（question.py:71）
3. 字段名转换（option_a/b/c/d/e → options JSON）
4. 返回格式统一（{list, total, real_total}）
5. 额外字段（score, source）

---

#### ai_weak_review（AI薄弱点智能复习）深入对比

**旧代码完整实现（question.py:133-270）**

**核心算法：AI动态优先级计算**
```
优先级分数 = 错误次数*3 + 逾期天数*2 + 最近错误权重 - 复习次数*0.5
```

| 因素 | 权重 | 说明 | 代码位置 |
|------|------|------|---------|
| 错误次数 | *3 | 错得越多优先级越高 | question.py:221 |
| 逾期天数 | *2 | 越逾期优先级越高 | question.py:221 |
| 最近错误权重 | max(0,7-天数)*2 | 最近7天内答错的权重更高 | question.py:215 |
| 复习次数 | *0.5 | 复习越多优先级越低（减去） | question.py:221 |

**其他功能：**
- ✅ 支持多科目筛选（逗号分隔）question.py:144-157
- ✅ 查询所有未掌握的错题（is_mastered=0）question.py:152
- ✅ 按优先级分数降序排序 question.py:230
- ✅ 返回额外字段：overdue_days, next_review_date, priority_score question.py:258-262
- ✅ 生成提示消息（多少道逾期）question.py:265-268

**新模块：完全缺失！**
- qb/service.py：没有ai_weak_review
- qb/routes.py：没有ai_weak_review

**需要融合：**
| 融合项 | 来源行号 | 优先级 |
|--------|---------|--------|
| AI薄弱点算法 | question.py:220-221 | P0 |
| 多科目筛选支持 | question.py:144-157 | P1 |
| 逾期天数计算 | question.py:192-203 | P0 |
| 最近错误权重计算 | question.py:205-218 | P0 |
| 返回额外字段（overdue_days, priority_score） | question.py:258-262 | P1 |
| 生成提示消息 | question.py:265-268 | P1 |

---

#### wrong_today（今日错题）深入对比

**旧代码（question.py:428-436）**
- 今日错题定义：基于遗忘曲线的今日需要复习的错题（get_today_review_wrong）
- 返回字段：id, question_id, title, wrong_count, next_review_date
- 返回格式：{total, list}

**新模块（qb/routes.py:650-670）**
- 今日错题定义：今天创建的错题（DATE(create_time)=DATE('now')）
- 返回字段：wrong_id, question_id, user_answer, title, answer, analysis
- 返回格式：{code, msg, data: {list, total}}

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 今日错题定义 | 基于遗忘曲线的今日需要复习 | 今天创建的错题 | ❌ 完全不同！ |
| 返回字段 | wrong_count, next_review_date | user_answer, answer, analysis | ❌ 字段不同 |
| 返回格式 | {total, list} | {code, msg, data} | ❌ 格式不同 |
| 科目筛选 | 支持subject参数 | 不支持 | ❌ 缺失 |

**需要融合：**
| 融合项 | 来源行号 | 优先级 |
|--------|---------|--------|
| 今日错题算法（基于遗忘曲线） | question.py:429 | P0 |
| 返回字段统一 | question.py:434-435 | P1 |
| 返回格式统一 | question.py:436 | P1 |
| 科目筛选支持 | question.py:428 | P1 |

---

#### mastery_analysis（掌握度分析）深入对比

**旧代码完整实现（question.py:1026-1159）**

**核心算法：掌握度计算公式**
```
掌握度 = 正确率 * 0.6 + 用时效率 * 0.4
用时效率 = max(0, min(1, 1 - (平均用时 - 30) / 120))
```

**掌握等级：**
- ≥80：优秀
- ≥60：良好
- ≥40：一般
- <40：薄弱

**功能：**
1. 排除异常数据（is_abnormal=False, time_spent>0）
2. 统计异常数据数量
3. 总体统计（正确率、平均用时）
4. 按科目分组分析
5. 按章节分组分析（最薄弱3个章节）
6. 生成学习建议（正确率低/用时长/异常数据/薄弱科目）

**新模块：完全缺失！**
- qb/service.py：没有mastery_analysis
- common/routes.py：没有mastery_analysis

**需要融合：**
| 融合项 | 来源行号 | 优先级 |
|--------|---------|--------|
| 掌握度计算公式 | question.py:1071-1074 | P0 |
| 异常数据排除逻辑 | question.py:1035-1039 | P0 |
| 按科目分组分析 | question.py:1086-1134 | P1 |
| 按章节分组分析 | question.py:1114-1127 | P1 |
| 学习建议生成 | question.py:1136-1148 | P1 |
| 掌握等级判断 | question.py:1077-1084 | P0 |

---

#### analyze_wrong_reason（错因分析）深入对比

**旧代码（question.py:1370-1446）**
**5种规则判断：**
1. 记忆遗忘：答案为空 或 答题时间<3秒
2. 审题错误：答案与正确答案相反 或 选择了"不正确/错误"的选项
3. 计算错误：题目包含计算关键词
4. 粗心大意：答案与正确答案非常接近
5. 多选题只选了一个

**返回字段：** error_reason, confidence, suggestion

**新模块（qb/routes.py:771-789）**
**2种规则判断：**
1. 答案长度不匹配
2. 完全未选对答案选项

**返回字段：** reasons（数组）

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 规则数量 | 5种 | 2种 | ❌ 缺失3种 |
| 记忆遗忘 | ✅ | ❌ | ❌ 缺失 |
| 审题错误 | ✅ | ❌ | ❌ 缺失 |
| 计算错误 | ✅ | ❌ | ❌ 缺失 |
| 答题时间判断 | ✅ | ❌ | ❌ 缺失 |
| 返回格式 | error_reason, confidence, suggestion | reasons（数组） | ❌ 格式不同 |

**需要融合：**
| 融合项 | 来源行号 | 优先级 |
|--------|---------|--------|
| 记忆遗忘判断 | question.py:1399-1407 | P1 |
| 审题错误判断 | question.py:1409-1414 | P1 |
| 计算错误判断 | question.py:1416-1420 | P1 |
| 粗心大意判断 | question.py:1422-1430 | P1 |
| 多选题只选一个判断 | question.py:1432-1436 | P2 |
| 返回格式统一 | question.py:1438-1446 | P1 |

---

#### answer_question（提交答案）深入对比

**旧代码（question.py:307-335）**
**核心逻辑：**
1. 服务端判断是否正确（user_answer.upper() == q.answer.upper()）
2. 异常数据排除机制：用时过短(<2s)可能乱选，用时过长(>300s)可能离开
3. 答错：添加到错题本
4. 答对：更新SM-2状态，延长复习间隔

**返回字段：** is_correct, correct_answer, analysis, time_spent, is_abnormal, abnormal_reason

**新模块（qb/service.py:214-245）**
**核心逻辑：**
1. 前端传入is_correct，服务端不判断
2. 答错：添加到错题本

**返回字段：** question_id, is_correct, added_to_wrong

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 判断正确性 | 服务端判断 | 前端传入 | ❌ 安全隐患 |
| 异常数据排除 | ✅ | ❌ | ❌ 缺失 |
| SM-2算法 | ✅ | ❌ | ❌ 缺失 |
| 返回字段 | 6个字段 | 3个字段 | ❌ 缺失3个 |

**需要融合：**
| 融合项 | 来源行号 | 优先级 |
|--------|---------|--------|
| 服务端判断正确性 | question.py:313 | P0 |
| 异常数据排除机制 | question.py:314-323 | P0 |
| SM-2算法更新 | question.py:330-332 | P0 |
| 返回字段补全 | question.py:334-335 | P0 |

---

#### import_parsed_questions（导入解析题目）深入对比

**旧代码（question.py:956-1022）**
**核心逻辑：**
1. 哈希表去重（批量加载已有哈希+本次导入哈希表）
2. 规范化答案（normalize_answer）
3. 数据质量门禁（DataQualityPipeline.process）
4. 错误处理（成功/失败/跳过/错误详情）

**返回字段：** success, failed, skipped, errors, total

**新模块（qb/service.py:518-544）**
**核心逻辑：**
1. 直接插入数据库
2. 没有去重
3. 没有数据质量门禁

**返回字段：** inserted

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 哈希表去重 | ✅ | ❌ | ❌ 缺失 |
| 数据质量门禁 | ✅ | ❌ | ❌ 缺失 |
| 答案规范化 | ✅ | ❌ | ❌ 缺失 |
| 错误处理 | ✅ 完善 | ❌ 简单 | ❌ 缺失 |

**需要融合：**
| 融合项 | 来源行号 | 优先级 |
|--------|---------|--------|
| 哈希表去重 | question.py:966-987 | P1 |
| 数据质量门禁 | question.py:1007-1012 | P1 |
| 答案规范化 | question.py:977-978 | P2 |
| 错误处理完善 | question.py:1018-1022 | P1 |

---

#### update_wrong（更新错题）深入对比

**旧代码（question.py:439-449）**
**核心逻辑：**
1. 根据wid和user_id查找错题（防止越权）
2. 如果不存在，返回404
3. 更新字段：error_reason, knowledge_point, is_mastered

**返回字段：** {message: "更新成功"}

**新模块（qb/routes.py:673-700）**
**核心逻辑：**
1. 根据wrong_id直接UPDATE
2. 更新字段：user_answer, is_mastered, error_type_name
3. 没有校验user_id（安全隐患）

**返回字段：** {code: 200, msg: "成功"}

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 更新字段 | error_reason, knowledge_point, is_mastered | user_answer, is_mastered, error_type_name | ❌ 字段不同 |
| 用户ID校验 | ✅ | ❌ | ❌ 安全隐患 |
| 错题不存在判断 | ✅ | ❌ | ❌ 缺失 |
| 返回格式 | {message} | {code, msg} | ❌ 格式不同 |

**需要融合：**
| 融合项 | 来源行号 | 优先级 |
|--------|---------|--------|
| 用户ID校验（防止越权） | question.py:442 | P0 |
| 错题不存在判断 | question.py:443-444 | P1 |
| 更新字段统一 | question.py:445-447 | P1 |

---

#### 闪卡域mt深入对比汇总

**create函数对比：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 全局去重 | ✅ content_hash | ❌ 没有 | ❌ 缺失 |
| duplicate字段 | ✅ | ❌ | ❌ 缺失 |

**list_cards函数对比：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 多科目筛选 | ✅ 逗号分隔 | ❌ 单科目 | ❌ 缺失 |
| 章节筛选 | contains模糊匹配 | ==精确匹配 | ❌ 匹配方式不同 |
| 排序 | 先章节后知识点 | 创建时间降序 | ❌ 排序不同 |
| knowledge_point | ✅ | ❌ | ❌ 缺失 |
| mastery | ✅ | ❌ | ❌ 缺失 |
| ease_factor | ✅ | ❌ | ❌ 缺失 |
| interval_days | ✅ | ❌ | ❌ 缺失 |

**review_today函数对比：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 脏数据过滤 | ✅ 5种规则 | ❌ 没有 | ❌ 缺失 |
| raw_total字段 | ✅ | ❌ | ❌ 缺失 |

**review_card函数对比：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| SM-2算法 | 标准（0-5分级） | 简化（3种结果） | ❌ 算法不同 |
| 掌握度计算 | ✅ | ❌ | ❌ 缺失 |
| ease_factor更新 | ✅ | ❌ | ❌ 缺失 |
| interval_days更新 | ✅ | ❌ | ❌ 缺失 |
| last_review_date更新 | ✅ | ❌ | ❌ 缺失 |
| is_mastered更新 | ✅ | ❌ | ❌ 缺失 |

**from_question函数对比：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| from_question功能 | ✅ | ❌ | ❌ 完全缺失 |

**batch_import函数对比：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| batch_import功能 | ✅ | ❌ | ❌ 完全缺失 |

---

#### AI对话域ai深入对比汇总

**ask函数对比：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| ask函数 | ✅ | ❌ | ❌ 完全缺失 |
| 本地知识库搜索 | ✅ local_knowledge_search | ❌ | ❌ 缺失 |
| 输出格式（^13分隔） | ✅ | ❌ | ❌ 缺失 |
| 精确匹配原题 | ✅ | ❌ | ❌ 缺失 |
| 相关题目返回 | ✅ | ❌ | ❌ 缺失 |

---

#### 分析域analytics深入对比汇总

**旧API analytics.py（12个端点）：**
| 旧代码端点 | 新模块对应 | 差异 |
|-----------|-----------|------|
| /overview | /dashboard | ⚠️ 路径不同 |
| /chapter_accuracy | /exam-analysis/chapter-scores | ⚠️ 路径不同 |
| /study_trend | ❌ 没有 | ❌ 缺失 |
| /weak_points | ❌ 没有 | ❌ 缺失 |
| /wrong_reason_distribution | /wrong-reasons | ⚠️ 路径不同 |
| /hesitation_points | ❌ 没有 | ❌ 缺失 |
| /chapter_resources | ❌ 没有 | ❌ 缺失 |
| /subject_balance | ❌ 没有 | ❌ 缺失 |
| /exam_stage | ❌ 没有 | ❌ 缺失 |
| /daily_plan（3个端点） | ❌ 没有 | ❌ 完全缺失 |

---

#### 教材域material深入对比汇总

**旧API material.py（19个端点）vs 新模块resource/routes.py（70+个端点）**

**结论：教材域已经比较完整了！新模块的功能比旧代码更全面。**

---

#### 导图域mindmap深入对比汇总

**旧API mindmap.py（16个端点）vs 新模块mm/routes.py（26个端点）**

| 旧代码端点 | 新模块对应 | 差异 |
|-----------|-----------|------|
| /list | /mindmaps | ⚠️ 路径不同 |
| /save | /mindmaps（POST） | ⚠️ 路径不同 |
| /generate_from_pdf | ❌ 没有 | ❌ 缺失 |
| /split_upload_pdf | ❌ 没有 | ❌ 缺失 |
| /split_from_lectures | ❌ 没有 | ❌ 缺失 |
| /ai/chat | ❌ 没有 | ❌ 缺失 |
| 知识图谱 | ❌ 没有 | ✅ 新增4个端点 |

---

#### 视频域video深入对比汇总

**旧API video.py（19个端点）：**
1. /upload, /categories, /category, /list
2. /add, /batch_import, /{vid}, /delete_folder
3. /{vid}（PUT）, /progress, /progress/{video_type}/{video_id}
4. /link_question, /{video_type}/{video_id}/questions, /question/{qid}/videos
5. /note, /{video_type}/{video_id}/notes
6. /search/bilibili, /extract_mnemonics, /extract_mnemonics_single

**新模块：resource/routes.py已迁移视频管理功能！**

---

#### 讲义域lecture深入对比汇总

**旧API lecture.py（7个端点）：**
1. /list, /upload, /{lid}, /delete_folder
2. /{lid}/download, /{lid}/detect_questions, /{lid}/import_questions

**新模块：resource/routes.py已迁移讲义管理功能！**

---

#### 考试域exam深入对比汇总

**旧API exam.py（10个端点）vs 新模块qb/routes.py（10个端点）**

**结论：考试域已经比较完整了！新模块的功能和旧代码基本对应。**

---

#### 认证域auth深入对比汇总

**旧API auth.py（8个端点）：**
1. /register, /login, /change_password
2. /me（GET/PUT）, /avatar
3. /forgot_password, /reset_password

**新模块：common/routes.py没有认证相关端点！完全缺失！**

---

#### 笔记域note深入对比汇总

**旧API note.py（5个端点）vs 新模块common/routes.py（4个端点）**

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 获取笔记详情 | ✅ /{nid} | ❌ 没有 | ❌ 缺失 |

---

#### 其他模块快速统计

**旧API其他模块端点数：**
| 模块 | 端点数 |
|------|--------|
| system.py | 22个 |
| ai_brain.py | 14个 |
| formula_trainer.py | 11个 |
| sync_unified.py | 11个 |
| monitor.py | 8个 |
| knowledge_graph.py | 7个 |
| sprint.py | 7个 |
| backup.py | 6个 |
| data_check.py | 5个 |
| exam_analysis.py | 5个 |
| rag_knowledge.py | 5个 |
| syllabus.py | 5个 |
| deduplication.py | 4个 |
| preprocess_config.py | 4个 |
| question_file.py | 4个 |
| combined_analysis.py | 3个 |
| music.py | 3个 |
| relation.py | 3个 |
| tts.py | 3个 |
| ai_scan.py | 2个 |
| subject_switch.py | 2个 |
| wrong_analysis.py | 2个 |

**总计：约140个端点**

---

#### 认证域auth逐行对比汇总

**旧代码auth.py（138行，8个端点）：**

| 端点 | 行号 | 核心功能 | 安全机制 |
|------|------|---------|---------|
| /register | 14-21 | 检查用户名存在 → 创建用户 → 返回token | 无 |
| /login | 23-52 | 验证密码 → 失败计数 → 锁定机制 | 连续5次错误锁15分钟 |
| /change_password | 54-63 | 验证原密码 → 检查新密码长度 → 更新密码 | 无 |
| /me（GET） | 65-70 | 返回用户信息 | 无 |
| /me（PUT） | 72-78 | 更新用户信息 | 无 |
| /avatar | 80-104 | 上传头像 → 检查格式 → 检查大小 → 哈希去重 | 格式/大小检查 |
| /forgot_password | 106-121 | 生成重置令牌 → 有效期1小时 | 无 |
| /reset_password | 123-137 | 验证令牌 → 检查过期 → 更新密码 | 令牌过期检查 |

**新模块：完全缺失！**

---

#### 题库域answer_question逐行对比汇总

**旧代码answer_question（question.py:307-335，29行）：**

| 行号 | 代码 | 功能 |
|------|------|------|
| 313 | is_correct = user_answer.upper() == q.answer.upper() | **服务端判断正确性** |
| 314-323 | 异常数据排除机制 | 用时过短(<2s)可能乱选，用时过长(>300s)可能离开 |
| 327-328 | add_wrong_question(db, user.id, qid, user_answer) | 答错：添加到错题本 |
| 330-332 | update_review_result(db, user.id, qid, True) | **答对：SM-2算法更新** |
| 334-335 | 返回结果 | is_correct, correct_answer, analysis, time_spent, is_abnormal, abnormal_reason |

**新模块record_answer（qb/service.py:214-245，32行）：**

| 行号 | 代码 | 功能 |
|------|------|------|
| 221-227 | INSERT INTO question_answer_logs | 记录答题日志 |
| 229-235 | INSERT INTO wrong_questions | 答错：添加到错题本 |
| 238-239 | 返回结果 | question_id, is_correct, added_to_wrong |

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 判断正确性 | 服务端判断（第313行） | 前端传入 | ❌ 安全隐患 |
| 异常数据排除 | 第314-323行 | 没有 | ❌ 缺失 |
| SM-2算法更新 | 第330-332行 | 没有 | ❌ 缺失 |
| 返回字段 | 6个字段 | 3个字段 | ❌ 缺失3个 |

---

#### 闪卡域review_card逐行对比汇总

**旧代码review_card（flashcard.py:260-309，50行）：**

| 行号 | 代码 | 功能 |
|------|------|------|
| 268-269 | quality = max(0, min(5, quality)) | **标准SM-2算法（0-5分级）** |
| 270-272 | ease, interval, count | 获取当前状态 |
| 274 | new_ease, new_interval, new_count = sm2_engine.calculate(ease, interval, count, quality) | **SM-2算法计算** |
| 275 | mastery = sm2_engine.calculate_mastery(new_ease, new_count, new_interval, quality) | **掌握度计算** |
| 276 | next_date = sm2_engine.get_next_review_date(new_interval) | 计算下次复习日期 |
| 279-292 | 更新卡片状态 | review_count, next_review, ease_factor, interval_days, mastery, last_review_date, last_quality, is_mastered |
| 297-309 | 返回结果 | id, review_count, next_review, ease_factor, interval_days, mastery, mastery_percent, is_mastered, quality, quality_name |

**新模块record_review（mt/service.py:292-391，100行）：**

| 行号 | 代码 | 功能 |
|------|------|------|
| 334-352 | 简化SM-2算法 | remember/hard/forget三种结果 |
| 355-356 | 更新卡片 | review_count, next_review |
| 359-366 | 记录复习日志 | FlashcardReviewLog |
| 370-379 | 返回结果 | success, flashcard_id, review_result, old_review_count, new_review_count, old_next_review, new_next_review, message |

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| SM-2算法 | 标准（0-5分级） | 简化（3种结果） | ❌ 算法不同 |
| 掌握度计算 | ✅ | ❌ | ❌ 缺失 |
| ease_factor更新 | ✅ | ❌ | ❌ 缺失 |
| interval_days更新 | ✅ | ❌ | ❌ 缺失 |
| last_review_date更新 | ✅ | ❌ | ❌ 缺失 |
| is_mastered更新 | ✅ | ❌ | ❌ 缺失 |

---

#### 题库域ai_weak_review逐行对比汇总

**旧代码ai_weak_review（question.py:133-270，138行）：**

| 行号 | 代码 | 功能 |
|------|------|------|
| 144-174 | 查询未掌握错题 | 支持多科目筛选（逗号分隔） |
| 192-203 | **计算逾期天数** | overdue_days = (now - review_date).days |
| 205-218 | **计算最近错误权重** | recency_weight = max(0, 7 - days_since_wrong) * 2 |
| 220-221 | **AI综合优先级分数** | priority_score = wrong_count * 3 + overdue_days * 2 + recency_weight - review_count * 0.5 |
| 229-230 | 按优先级分数降序排序 | scored_items.sort(key=lambda x: x['priority_score'], reverse=True) |
| 240-263 | 转换结果格式 | 返回额外字段：overdue_days, next_review_date, priority_score |
| 265-268 | 生成提示消息 | 多少道逾期 |

**核心算法：**
```
优先级分数 = 错误次数 * 3 + 逾期天数 * 2 + 最近错误权重 - 复习次数 * 0.5
```

**新模块：完全缺失！**

---

#### 题库域mastery_analysis逐行对比汇总

**旧代码mastery_analysis（question.py:1026-1159，134行）：**

| 行号 | 代码 | 功能 |
|------|------|------|
| 1035-1042 | 查询正常答题记录 | 排除异常数据（is_abnormal=False, time_spent>0） |
| 1056-1063 | 统计异常数据 | abnormal_count |
| 1066-1069 | 总体统计 | total, correct, accuracy, avg_time |
| 1071-1074 | **掌握度计算公式** | time_efficiency = max(0, min(1, 1 - (avg_time - 30) / 120))<br>overall_mastery = int((accuracy * 0.6 + time_efficiency * 0.4) * 100) |
| 1076-1084 | **掌握等级判断** | ≥80优秀，≥60良好，≥40一般，<40薄弱 |
| 1086-1134 | 按科目+章节分组分析 | 最薄弱3个章节 |
| 1136-1148 | 学习建议生成 | 正确率低/用时长/异常数据/薄弱科目 |

**核心算法：**
```
掌握度 = 正确率 * 0.6 + 用时效率 * 0.4
用时效率 = max(0, min(1, 1 - (平均用时 - 30) / 120))
```

**新模块：完全缺失！**

---

#### 闪卡域create逐行对比汇总

**旧代码create（flashcard.py:19-40，22行）：**

| 行号 | 代码 | 功能 |
|------|------|------|
| 21-24 | 计算content_hash | content = f"{front}\|{back}"<br>content_hash = hashlib.md5(content.encode('utf-8')).hexdigest() |
| 25-36 | **全局去重** | 检查content_hash是否已存在<br>如果已存在，返回duplicate=True |
| 37 | 创建新闪卡 | create_flashcard(db, user.id, data) |
| 38-40 | 返回结果 | id, front, back, tags, chapter, category, page, mnemonic, duplicate |

**新模块create_flashcard（mt/service.py:503-570，68行）：**

| 行号 | 代码 | 功能 |
|------|------|------|
| 531-544 | 创建闪卡 | FlashCard(...) |
| 546-548 | 提交事务 | db.add(flashcard), db.commit() |
| 550-562 | 返回结果 | id, subject, chapter, front, back, category, mnemonic, tags, review_count, next_review, create_time |

**关键差异：**
| 对比项 | 旧代码 | 新模块 | 差异 |
|--------|--------|--------|------|
| 全局去重 | ✅ content_hash | ❌ 没有 | ❌ 缺失 |
| duplicate字段 | ✅ | ❌ | ❌ 缺失 |
| page字段 | ✅ | ❌ | ❌ 缺失 |

---

#### 2. 闪卡域 mt ✅ 已深入对比

**旧API：flashcard.py（8个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| create | 19 | 创建闪卡 |
| from_question | 43 | 从题目生成闪卡 |
| batch_import | 87 | 批量导入 |
| list_cards | 170 | 闪卡列表 |
| update_card | 208 | 更新闪卡 |
| review_today | 221 | 今日复习 |
| review_card | 261 | 复习闪卡 |
| delete | 314 | 删除闪卡 |

**新模块：mt/service.py（10个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| __init__ | 21 | 初始化 |
| _get_db | 31 | 获取数据库连接 |
| get_flashcard_list | 42 | 闪卡列表 |
| get_flashcard_detail | 148 | 闪卡详情 |
| get_today_review_queue | 202 | 今日复习队列 |
| record_review | 292 | 记录复习 |
| get_flashcard_statistics | 398 | 闪卡统计 |
| create_flashcard | 503 | 创建闪卡 |
| update_flashcard | 572 | 更新闪卡 |
| delete_flashcard | 634 | 删除闪卡 |

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| from_question | P1 | 从题目生成闪卡 |
| batch_import | P1 | 批量导入 |

---

#### 3. AI对话 ai ✅ 已深入对比

**旧API：assistant.py（17个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| _extract_conditions | 45 | 提取条件 |
| _extract_search_keywords | 69 | 提取搜索关键词 |
| _get_user_ai_config | 87 | 获取用户AI配置 |
| ask | 101 | AI对话 |
| search | 231 | AI搜索 |
| study_plan | 263 | 学习计划 |
| history | 372 | 对话历史 |
| get_config | 385 | 获取配置 |
| save_config | 394 | 保存配置 |
| list_providers | 409 | 模型提供商列表 |
| _check_ollama_installed | 446 | 检查Ollama是否安装 |
| _check_ollama_running | 483 | 检查Ollama是否运行 |
| _get_installed_models | 495 | 获取已安装模型 |
| ollama_status | 522 | Ollama状态 |
| ollama_setup | 560 | Ollama安装 |
| ollama_test | 689 | Ollama测试 |
| ollama_models | 724 | Ollama模型列表 |

**新模块：ai/routes.py（52个端点）**
**已覆盖：**
- ✅ ask - POST /ask
- ✅ search - POST /search
- ✅ study-plan - POST /study-plan
- ✅ history - GET /history
- ✅ config - GET/POST /config
- ✅ providers - GET /providers
- ✅ ollama/status - GET /ollama/status
- ✅ ollama/setup - POST /ollama/setup
- ✅ ollama/test - POST /ollama/test
- ✅ ollama/models - GET /ollama/models

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| _extract_conditions | P1 | 提取条件（内部函数） |
| _extract_search_keywords | P1 | 提取搜索关键词（内部函数） |
| _get_user_ai_config | P1 | 获取用户AI配置（内部函数） |
| _check_ollama_installed | P0 | 检查Ollama是否安装（内部函数） |
| _check_ollama_running | P0 | 检查Ollama是否运行（内部函数） |
| _get_installed_models | P0 | 获取已安装模型（内部函数） |

---

#### 4. 分析域 common ✅ 已深入对比

**旧API：analytics.py（12个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| overview | 13 | 总览 |
| chapter_accuracy | 42 | 章节正确率 |
| study_trend | 123 | 学习趋势 |
| weak_points | 141 | 薄弱点 |
| wrong_reason_distribution | 162 | 错因分布 |
| hesitation_analysis | 226 | 犹豫分析 |
| chapter_resources | 257 | 章节资源 |
| subject_balance | 361 | 科目平衡 |
| exam_stage | 368 | 考试阶段 |
| generate_daily_plan | 374 | 生成每日计划 |
| get_daily_plan | 380 | 获取每日计划 |
| update_daily_plan | 397 | 更新每日计划 |

**新模块：common/routes.py（35个端点）**
**已覆盖：**
- ✅ overview - GET /exam-analysis/overview
- ✅ chapter_accuracy - GET /exam-analysis/chapter-scores
- ✅ weak-points - 部分覆盖
- ✅ wrong-reasons - GET /wrong-reasons
- ✅ notes - GET/POST/PUT/DELETE /notes

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| study_trend | P0 | 学习趋势 |
| hesitation_analysis | P1 | 犹豫分析 |
| chapter_resources | P1 | 章节资源 |
| subject_balance | P1 | 科目平衡 |
| exam_stage | P1 | 考试阶段 |
| generate_daily_plan | P0 | 生成每日计划 |
| get_daily_plan | P0 | 获取每日计划 |
| update_daily_plan | P0 | 更新每日计划 |

---

### P1重要（经常用，第二阶段）

#### 5. 教材 resource ✅ 已深入对比

**旧API：material.py（21个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| detect_subject_from_filename | 34 | 从文件名识别科目 |
| detect_subject_from_text | 70 | 从文本识别科目 |
| normalize_title | 86 | 规范化标题 |
| parse_filename | 119 | 解析文件名 |
| extract_pdf_outline | 162 | 提取PDF大纲 |
| list_materials | 237 | 教材列表 |
| dedup_materials | 453 | 去重 |
| remove_material | 535 | 删除教材 |
| rename_material | 553 | 重命名教材 |
| material_storage | 572 | 存储统计 |
| list_subjects | 586 | 科目列表 |
| get_material_chapters | 593 | 获取章节 |
| split_material | 610 | 拆分教材 |
| delete_material_tree | 680 | 删除教材树 |
| calibrate_offset | 723 | 校准偏移 |
| split_pdf_files | 773 | 拆分PDF文件 |
| list_split_files | 859 | 列出拆分文件 |
| list_all_split_materials | 917 | 列出所有拆分教材 |
| preprocess_scan | 960 | 预处理扫描 |
| manual_rotate | 997 | 手动旋转 |
| get_material_tree | 1028 | 获取教材树 |

**新模块：resource/routes.py（76个端点）**
**已覆盖：**
- ✅ list_materials - GET /materials
- ✅ dedup - POST /materials/dedup
- ✅ delete - DELETE /materials/{material_id}
- ✅ rename - PUT /materials/{mid}
- ✅ storage - GET /materials/storage
- ✅ chapters - GET /materials/chapters/{mid}
- ✅ split - POST /materials/{material_id}/split
- ✅ delete-tree - POST /materials/delete-tree/{mid}
- ✅ calibrate-offset - POST /materials/calibrate-offset/{mid}
- ✅ split-pdf - POST /materials/split-pdf/{mid}
- ✅ split-files - GET /materials/split-files/{mid}
- ✅ split-all - GET /materials/split-all
- ✅ preprocess - POST /materials/preprocess/{mid}
- ✅ preprocess/rotate - POST /materials/preprocess/rotate/{mid}
- ✅ tree - GET /materials/tree

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| detect_subject_from_filename | P1 | 从文件名识别科目（内部函数） |
| detect_subject_from_text | P1 | 从文本识别科目（内部函数） |
| normalize_title | P1 | 规范化标题（内部函数） |
| parse_filename | P1 | 解析文件名（内部函数） |
| extract_pdf_outline | P1 | 提取PDF大纲（内部函数） |

---

#### 6. 视频 resource ✅ 已深入对比

**旧API：video.py（19个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| _extract_chapter_from_filename | 19 | 从文件名提取章节 |
| _generate_chapter_variants | 59 | 生成章节变体 |
| detect_video_format | 96 | 检测视频格式 |
| categories | 274 | 分类列表 |
| add_category | 279 | 添加分类 |
| video_list | 284 | 视频列表 |
| add_video | 342 | 添加视频 |
| batch_import | 347 | 批量导入 |
| delete_video | 375 | 删除视频 |
| delete_video_folder | 381 | 删除视频文件夹 |
| update_video | 406 | 更新视频 |
| save_progress | 422 | 保存进度 |
| get_progress | 428 | 获取进度 |
| link_question | 437 | 关联题目 |
| related_questions | 443 | 相关题目 |
| question_videos | 448 | 题目关联视频 |
| add_note | 452 | 添加笔记 |
| list_notes | 457 | 笔记列表 |
| search_bilibili | 463 | B站搜索 |

**新模块：resource/routes.py（76个端点）**
**已覆盖：**
- ✅ categories - GET /videos/categories
- ✅ add-category - POST /videos/category
- ✅ video_list - GET /videos
- ✅ add_video - POST /videos/add
- ✅ batch_import - POST /videos/batch-import
- ✅ delete_video - DELETE /videos/{video_id}
- ✅ delete_video_folder - POST /videos/delete-folder
- ✅ update_video - PUT /videos/{vid}
- ✅ save_progress - POST /videos/progress
- ✅ get_progress - GET /videos/progress/{video_type}/{video_id}
- ✅ link_question - POST /videos/link-question
- ✅ related_questions - GET /videos/{video_type}/{video_id}/questions
- ✅ question_videos - GET /videos/question/{qid}
- ✅ add_note - POST /videos/note
- ✅ list_notes - GET /videos/{video_type}/{video_id}/notes
- ✅ search_bilibili - GET /videos/search/bilibili

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| _extract_chapter_from_filename | P1 | 从文件名提取章节（内部函数） |
| _generate_chapter_variants | P1 | 生成章节变体（内部函数） |
| detect_video_format | P1 | 检测视频格式（内部函数） |

---

#### 7. 讲义 resource ✅ 已深入对比

**旧API：lecture.py（8个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| _generate_chapter_variants | 13 | 生成章节变体 |
| _extract_chapter_from_filename | 45 | 从文件名提取章节 |
| list_lectures | 89 | 讲义列表 |
| delete_lecture | 179 | 删除讲义 |
| delete_lecture_folder | 189 | 删除讲义文件夹 |
| download_lecture | 223 | 下载讲义 |
| detect_questions | 231 | 识别题目 |
| import_questions | 253 | 导入题目 |

**新模块：resource/routes.py（76个端点）**
**已覆盖：**
- ✅ list_lectures - GET /lectures
- ✅ delete_lecture - DELETE /lectures/{lecture_id}
- ✅ delete_lecture_folder - POST /lectures/delete-folder
- ✅ download_lecture - GET /lectures/{lid}/download
- ✅ detect_questions - POST /lectures/{lid}/detect-questions
- ✅ import_questions - POST /lectures/{lid}/import-questions

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| _generate_chapter_variants | P1 | 生成章节变体（内部函数） |
| _extract_chapter_from_filename | P1 | 从文件名提取章节（内部函数） |

---

#### 8. 导图 mm ✅ 已深入对比

**旧API：mindmap.py（19个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| list_mindmaps | 30 | 导图列表 |
| get_mindmap | 71 | 导图详情 |
| save_mindmap | 83 | 保存导图 |
| remove_mindmap | 104 | 删除导图 |
| generate_from_pdf | 111 | 从PDF生成 |
| split_from_pdf | 178 | 从PDF拆分 |
| get_default_template | 321 | 默认模板 |
| merge_subject_mindmap | 358 | 合并科目导图 |
| merge_all_mindmap | 407 | 合并所有导图 |
| _fast_extract_toc | 534 | 快速提取目录 |
| _scan_summary_from_back | 564 | 从后扫描总结 |
| _scan_toc_from_front | 640 | 从前扫描目录 |
| _scan_full_for_summary | 729 | 全扫描总结 |
| split_from_lectures | 797 | 从讲义拆分 |
| ai_expand_node | 1084 | AI展开节点 |
| ai_generate_mindmap | 1125 | AI生成导图 |
| ai_summarize_mindmap | 1145 | AI总结导图 |
| ai_chat_mindmap | 1176 | AI聊天导图 |

**新模块：mm/routes.py（26个端点）**
**已覆盖：**
- ✅ list_mindmaps - GET /mindmaps
- ✅ get_mindmap - GET /mindmaps/{mindmap_id}
- ✅ save_mindmap - POST /mindmaps
- ✅ remove_mindmap - DELETE /mindmaps/{mindmap_id}
- ✅ generate_from_pdf - POST /parse-pdf
- ✅ get_default_template - GET /template/default
- ✅ merge_subject_mindmap - POST /merge
- ✅ merge_all_mindmap - POST /merge-all
- ✅ ai_expand_node - POST /ai/expand
- ✅ ai_generate_mindmap - POST /ai/generate
- ✅ ai_summarize_mindmap - POST /ai/summarize

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| split_from_pdf | P1 | 从PDF拆分（内部函数） |
| _fast_extract_toc | P1 | 快速提取目录（内部函数） |
| _scan_summary_from_back | P1 | 从后扫描总结（内部函数） |
| _scan_toc_from_front | P1 | 从前扫描目录（内部函数） |
| _scan_full_for_summary | P1 | 全扫描总结（内部函数） |
| split_from_lectures | P1 | 从讲义拆分 |
| ai_chat_mindmap | P1 | AI聊天导图 |

---

#### 9. 考试域 qb ✅ 已深入对比

**旧API：exam.py（10个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| generate_exam | 12 | 生成考试 |
| submit_exam | 114 | 提交考试 |
| exam_history | 132 | 考试历史 |
| exam_detail | 142 | 考试详情 |
| exam_stats | 153 | 考试统计 |
| report_switch | 157 | 报告切换 |
| ai_grading | 171 | AI批改 |
| get_exam_config | 313 | 获取考试配置 |
| get_official_data | 356 | 获取官方数据 |
| verify_exam_config | 381 | 验证考试配置 |

**新模块：qb/service.py考试部分**
**已覆盖：**
- ✅ generate_exam - qb/service.py:551
- ✅ submit_exam - qb/service.py:620
- ✅ get_exam_history - qb/service.py:692
- ✅ get_exam_detail - qb/service.py:728
- ✅ get_exam_stats - qb/service.py:747

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| report_switch | P1 | 报告切换 |
| ai_grading | P1 | AI批改 |
| get_exam_config | P1 | 获取考试配置 |
| get_official_data | P2 | 获取官方数据 |
| verify_exam_config | P2 | 验证考试配置 |

---

#### 10. 错题分析 qb ✅ 已深入对比

**旧API：wrong_analysis.py（2个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| get_wrong_summary | 17 | 错题汇总 |
| get_weak_points | 86 | 薄弱点列表 |

**新模块：qb/routes.py**
**已覆盖：**
- ✅ GET /wrong_analysis/summary
- ✅ GET /wrong_analysis/weak_points

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| （无） | - | 已全部覆盖 |

---

#### 11. 笔记 common ✅ 已深入对比

**旧API：note.py（5个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| create | 12 | 创建笔记 |
| list_notes | 31 | 笔记列表 |
| get_note | 40 | 笔记详情 |
| update_note | 48 | 更新笔记 |
| delete | 59 | 删除笔记 |

**新模块：common/routes.py**
**已覆盖：**
- ✅ list_notes - GET /notes
- ✅ create - POST /notes
- ✅ update_note - PUT /notes/{note_id}
- ✅ delete - DELETE /notes/{note_id}

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| get_note | P1 | 笔记详情 |

---

#### 12. 认证 common ✅ 已深入对比

**旧API：auth.py（7个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| register | 15 | 注册 |
| login | 24 | 登录 |
| change_password | 55 | 修改密码 |
| get_me | 66 | 获取个人信息 |
| update_me | 73 | 更新个人信息 |
| forgot_password | 107 | 忘记密码 |
| reset_password | 124 | 重置密码 |

**新模块：common/routes.py**
**已覆盖：**
- ✅ settings - GET/PUT /settings

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| register | P0 | 注册 |
| login | P0 | 登录 |
| change_password | P1 | 修改密码 |
| get_me | P0 | 获取个人信息 |
| update_me | P1 | 更新个人信息 |
| forgot_password | P2 | 忘记密码 |
| reset_password | P2 | 重置密码 |

---

#### 13. 知识图谱 ai ⏳ 待深入对比
#### 14. AI大脑 ai ⏳ 待深入对比

---

### P2次要（偶尔用，第三阶段）

#### 15. 公式训练 mt ✅ 已深入对比

**旧API：formula_trainer.py（11个函数）**
| 函数 | 行号 | 功能 |
|------|------|------|
| list_formulas | 14 | 公式列表 |
| get_summary | 27 | 公式汇总 |
| get_formula | 33 | 公式详情 |
| generate_training_plan | 43 | 生成训练计划 |
| recognition_card | 50 | 识别卡片 |
| fill_blank_question | 60 | 填空题 |
| derivation_question | 70 | 推导题 |
| application_question | 80 | 应用题 |
| check_answer | 90 | 检查答案 |
| save_train_record | 98 | 保存训练记录 |
| get_train_progress | 158 | 获取训练进度 |

**新模块：mt/service.py**
**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| list_formulas | P2 | 公式列表 |
| get_summary | P2 | 公式汇总 |
| get_formula | P2 | 公式详情 |
| generate_training_plan | P2 | 生成训练计划 |
| recognition_card | P2 | 识别卡片 |
| fill_blank_question | P2 | 填空题 |
| derivation_question | P2 | 推导题 |
| application_question | P2 | 应用题 |
| check_answer | P2 | 检查答案 |
| save_train_record | P2 | 保存训练记录 |
| get_train_progress | P2 | 获取训练进度 |

---

#### 14. 知识图谱 ai ✅ 已深入对比

**旧API：knowledge_graph.py（7个路由端点）**
| 端点 | 行号 | 功能 |
|------|------|------|
| /overview | 24 | 总览 |
| /chapter-mapping | 112 | 章节映射 |
| /exam-trend | 176 | 考试趋势 |
| /key-points | 277 | 考点 |
| /weak-points | 417 | 薄弱点 |
| /study-plan | 555 | 学习计划 |
| /prediction | 693 | 预测 |

**新模块：mm/routes.py（26个端点）**
**已覆盖：**
- ✅ kg/overview - GET /kg/overview
- ✅ kg/chapter-mapping - GET /kg/chapter-mapping
- ✅ kg/exam-trend - GET /kg/exam-trend
- ✅ kg/key-points - GET /kg/key-points
- ✅ kg/prediction - GET /kg/prediction

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| /weak-points | P1 | 薄弱点 |
| /study-plan | P1 | 学习计划 |

---

#### 15. AI大脑 ai ✅ 已深入对比

**旧API：ai_brain.py（14个路由端点）**
| 端点 | 行号 | 功能 |
|------|------|------|
| /status | 88 | 状态 |
| /summarize | 100 | 总结 |
| /extract-knowledge | 118 | 提取知识 |
| /generate-mnemonic | 138 | 生成口诀 |
| /explain-concept | 158 | 解释概念 |
| /compare-concepts | 176 | 对比概念 |
| /analyze-wrong-question | 194 | 分析错题 |
| /plan-learning | 217 | 规划学习 |
| /answer | 237 | 回答问题 |
| /merge-knowledge | 255 | 合并知识 |
| /analyze-chapter | 273 | 分析章节 |
| /clear-cache | 291 | 清除缓存 |
| /evaluate-question | 303 | 评估题目 |
| /batch-evaluate | 321 | 批量评估 |

**新模块：ai/routes.py（52个端点）**
**已覆盖：**
- ✅ brain/status - GET /brain/status
- ✅ brain/summarize - POST /brain/summarize
- ✅ brain/extract-knowledge - POST /brain/extract-knowledge
- ✅ brain/generate-mnemonic - POST /brain/generate-mnemonic
- ✅ brain/explain-concept - POST /brain/explain-concept
- ✅ brain/compare-concepts - POST /brain/compare-concepts
- ✅ brain/analyze-wrong-question - POST /brain/analyze-wrong-question
- ✅ brain/plan-learning - POST /brain/plan-learning
- ✅ brain/answer - POST /brain/answer
- ✅ brain/merge-knowledge - POST /brain/merge-knowledge
- ✅ brain/analyze-chapter - POST /brain/analyze-chapter
- ✅ brain/clear-cache - POST /brain/clear-cache
- ✅ brain/evaluate-question - POST /brain/evaluate-question
- ✅ batch-evaluate - POST /evaluation/batch

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| （无） | - | 已全部覆盖 |

---

#### 16. TTS common ✅ 已深入对比

**旧API：tts.py（3个路由端点）**
| 端点 | 行号 | 功能 |
|------|------|------|
| /tts/voices | 54 | 语音列表 |
| /tts/speak | 60 | 语音合成 |
| /tts/clear_cache | 145 | 清除缓存 |

**新模块：common/routes.py（35个端点）**
**已覆盖：**
- ✅ tts/voices - GET /tts/voices
- ✅ tts/speak - POST /tts/speak

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| /tts/clear_cache | P2 | 清除缓存 |

---

#### 17. 音乐 common ✅ 已深入对比

**旧API：music.py（3个路由端点）**
| 端点 | 行号 | 功能 |
|------|------|------|
| /upload | 19 | 上传音乐 |
| /list | 44 | 音乐列表 |
| /{filename} | 68 | 删除音乐 |

**新模块：common/routes.py（35个端点）**
**已覆盖：**
- ✅ music/list - GET /music/list
- ✅ music/categories - GET /music/categories

**差异清单：**
| 旧代码有但新模块没有 | 优先级 | 融合内容 |
|---------------------|--------|---------|
| /upload | P2 | 上传音乐 |
| /{filename} | P2 | 删除音乐 |

---

#### 18. 冲刺中心 common ✅ 已深入对比

**旧API：sprint.py（7个函数，167行）**
| 函数 | 行号 | 功能 | 优先级 |
|------|------|------|--------|
| chapter_heatmap | 18 | 章节热力图（按章节统计答题情况） | P1 |
| year_distribution | 23 | 年份分布（按年份统计题目数量） | P2 |
| create_custom_exam | 28 | 自定义冲刺卷（按科目/章节/题型组卷） | P1 |
| high_frequency_questions | 46 | 高频考题（按答题次数排序） | P1 |
| weak_points_analysis | 70 | 薄弱点分析（按章节正确率排序，前10个） | P1 |
| generate_predict_exam | 90 | 智能预测卷（近3年70%+其他30%） | P1 |
| confusing_pairs | 126 | 易混淆考点对（同考点不同答案的对比） | P2 |

**融合要点**：
- 所有接口都需要用户认证
- 支持多科目筛选（逗号分隔）
- 自定义冲刺卷：数量10-200题
- 智能预测卷策略：近3年高频考点70% + 其他30%
- 易混淆考点对：同知识点不同答案的题目对比

---

#### 19. 同步 sync ✅ 已深入对比

**旧API：sync_unified.py（11个函数，590+行）**
| 函数 | 行号 | 功能 | 优先级 |
|------|------|------|--------|
| push_changes | 64 | 推送变更（笔记、闪卡、错题） | P2 |
| pull_changes | 130 | 全量拉取 | P2 |
| get_checkpoint | 153 | 获取同步检查点 | P2 |
| list_conflicts | 163 | 获取冲突列表 | P2 |
| resolve_conflict | 181 | 解决冲突（server/client/merge/auto） | P2 |
| auto_resolve_all_conflicts | 232 | 自动解决所有冲突 | P2 |
| batch_sync | 387 | 批量同步离线操作 | P2 |
| get_sync_status | 449 | 获取同步状态 | P2 |
| register_device | 464 | 注册或更新设备 | P2 |
| list_devices | 505 | 列出所有已注册设备 | P2 |
| incremental_pull | 531 | 增量拉取 | P2 |

**融合要点**：
- 同时支持 /sync/* 和 /offline_sync/* 两套前缀
- 支持的操作：答题、笔记增删改、闪卡复习、学习进度
- 冲突解决策略：server(服务端优先)/client(客户端优先)/merge(合并)/auto(自动基于时间戳)
- 内容去重：笔记标题+内容哈希去重
- 操作去重：operation_id去重，避免重复处理
- 设备管理：设备注册、在线状态检测（5分钟内算在线）

---

#### 20. 系统 common ⏳ 待深入对比
#### 21. 备份 common ⏳ 待深入对比
#### 22. 监控 common ⏳ 待深入对比
#### 23. 数据检查 common ⏳ 待深入对比
#### 24. 去重 common ⏳ 待深入对比
#### 25. 大纲 resource ⏳ 待深入对比

---

## 四、风险及补救方案

| 风险 | 补救方案 |
|------|---------|
| 字段名不匹配（option_a vs options JSON） | 统一字段名，转换函数 |
| 响应格式不统一（{list:[]} vs {code:200,data:[]}） | 兼容层路由，统一格式 |
| 用户认证差异 | 新模块暂不要求认证，后续补上 |
| 性能问题（加权随机） | 加索引+缓存 |
| 功能缺失 | 完整功能清单+逐步验证 |
| 前端不兼容 | 兼容层路由，旧URL转发 |

---

## 五、执行进度跟踪

### 已完成
- [x] 加权随机抽题融合到qb/service.py
- [x] DataService连接后端API
- [x] 单选题提交后显示解析
- [x] 多选题提交按钮ID修复

### 进行中
- [ ] 题库域qb剩余13个函数融合

### 待开始
- [ ] 闪卡域mt
- [ ] AI对话ai
- [ ] 分析域common
- [ ] 教材resource
- [ ] 视频resource
- [ ] 讲义resource
- [ ] 笔记common
- [ ] 认证common
- [ ] 导图mm
- [ ] 其他模块

---

## 六、每次推进前必读

1. 读本文件，确认当前进度
2. 确认要融合的函数
3. 融合前备份代码
4. 融合后验证
5. 更新进度跟踪


============================================================
# § 2. 【来源：系统模块化融合方案.md】
============================================================

# 水利智学系统模块化融合方案

> 生成时间：2026-09-12
> 状态：方案已定稿，待执行
> 原则：布局锁死、零前端改动、旧API兜底、渐进迁移

---

## 〇、顶层架构设计（规范性文件）

### 0.1 架构分层（六层模型）

```
┌─────────────────────────────────────────────────────────┐
│  L6  前端展示层  frontend/                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │ core/    │  │ modules/ │  │ js/大文件│  │ static/ │ │
│  │ 框架层   │  │ 业务组件 │  │ 打包应用 │  │ 静态资源 │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
└──────────────────────────┬──────────────────────────────┘
                           │ fetch /api/v1/*
┌──────────────────────────┴──────────────────────────────┐
│  L5  API路由层  backend/api/v1/  +  backend/modules/    │
│  ┌─────────────────────┐  ┌──────────────────────────┐ │
│  │ 旧API（33个文件）   │  │ 新模块（7个域）           │ │
│  │ /question /exam     │  │ qb 题库域                │ │
│  │ /flashcard /video   │  │ mt 记忆域                │ │
│  │ /material /mindmap  │  │ mm 导图域                │ │
│  │ /assistant /ai      │  │ ai  AI域                 │ │
│  │ /analytics /system │  │ resource 资源域          │ │
│  │ ...                 │  │ sync 同步域              │ │
│  │                     │  │ common 公共域            │ │
│  └─────────────────────┘  └──────────────────────────┘ │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────┐
│  L4  业务逻辑层  backend/utils/                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │ PDF处理  │ │ AI能力   │ │ 学习算法 │ │ 数据治理  │  │
│  │ 10个文件 │ │ 7个文件  │ │ 5个文件  │ │ 6个文件   │  │
│  └──────────┘ └──────────┘ └──────────┘ └───────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                 │
│  │ 视频导图 │ │ 扫描OCR  │ │ 系统工具 │                 │
│  │ 5个文件  │ │ 3个文件  │ │ 7个文件  │                 │
│  └──────────┘ └──────────┘ └──────────┘                 │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────┐
│  L3  数据模型层  backend/models/models.py               │
│  38张表：users/questions/wrong_questions/flash_cards   │
│  mind_maps/course_materials/...                         │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────┐
│  L2  基础设施层  backend/core/                           │
│  config.py 配置 │ db.py 数据库 │ deps.py 依赖注入        │
│  security.py 安全 │ logger.py 日志                       │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────┐
│  L1  存储层  SQLite + 文件系统                           │
│  shuili_exam.db │ uploads/ │ 测试资料附件/                │
└─────────────────────────────────────────────────────────┘
```

### 0.2 模块域划分（业务边界）

```
┌─────────────────────────────────────────────────────┐
│                    水利智学系统                       │
├──────────┬──────────┬──────────┬───────────────────┤
│  题库域   │  记忆域   │  导图域   │     AI域          │
│   qb     │   mt     │   mm     │     ai           │
├──────────┼──────────┼──────────┼───────────────────┤
│ 题目CRUD │ 闪卡CRUD │ 导图CRUD │ PDF视觉识别        │
│ 刷题抽题 │ 今日复习 │ PDF解析  │ Ollama管理        │
│ 答题记录 │ FSRS算法 │ 导入导出 │ 口诀生成          │
│ 错题管理 │ BKT算法  │ 批量导入 │ 案例评分          │
│ 收藏管理 │ 学习路径 │ 科目层级 │ 流式对话          │
│ 考试组卷 │ 能力雷达 │ 章节导图 │ 效果评估          │
│ 质量分级 │ 六分类   │          │ 提示词管理        │
│ IRT算法  │ 公式训练 │          │ 拍照解题          │
├──────────┴──────────┴──────────┴───────────────────┤
│              资源域 resource                        │
│ 教材管理 │ 视频管理 │ 讲义管理 │ 大纲管理 │ 文件库   │
├─────────────────────────────────────────────────────┤
│              公共域 common                         │
│ 数据分析 │ 冲刺中心 │ 数据治理 │ 系统管理 │ 同步     │
│ 备份管理 │ 笔记管理 │ TTS语音  │ RAG知识库 │ 监控    │
└─────────────────────────────────────────────────────┘
```

### 0.3 数据流（用户刷题主链路）

```
用户点击刷题
  │
  ▼
前端 question-practice.js
  │ fetch('/api/v1/question/random_real')
  ▼
API路由层 question.py (旧) 或 qb/routes.py (新)
  │
  ▼
业务逻辑层 utils/pdf_parser.py / crud/crud.py
  │
  ▼
数据模型层 Question表
  │
  ▼
存储层 shuili_exam.db
  │
  ▼
返回题目列表 → 前端渲染
```

### 0.4 依赖规则（模块化铁律）

| 规则 | 说明 |
|------|------|
| L6前端 → L5路由 | 只通过fetch调API，不直接读后端文件 |
| L5路由 → L4逻辑 | 路由层只做参数校验和响应封装，业务逻辑下沉到utils或service |
| L4逻辑 → L3模型 | 工具类操作models，不直接写SQL |
| L3模型 → L2基础设施 | 通过db.py的engine连接数据库 |
| **模块间禁止跨域import** | qb不能import mt的service，mm不能import ai的service |
| **跨模块通信** | 通过API路由调用，或通过事件总线 |

### 0.5 新旧融合的架构原则

```
当前状态：
  L5旧API ──→ L4utils ──→ L3models  （跑通中）
  L5新模块 ──→ L4service ─→ L3models  （骨架已搭）

目标状态：
  L5新模块 ──→ L4service ─→ L3models  （全部业务在此）
  L5旧API ──→ 兼容层 ────→ L5新模块   （薄壳转发）

融合方式：
  1. 新模块service补全业务逻辑
  2. 旧API路由改为薄壳，转发到新service
  3. 前端API_BASE不变，无感知
  4. 验证通过后删除旧API文件
```

---

## 一、系统总规模

| 层 | 文件数 | 代码量 | 说明 |
|---|--------|--------|------|
| 后端入口 | 1个 | ~740行 | main.py 路由注册中心 |
| 后端core | 11个 | ~170KB | 配置、数据库、AI控制器 |
| 后端utils | 48个 | ~850KB | PDF解析、OCR、AI解题、算法 |
| 后端旧API | 33个 | ~700KB | api/v1/ 全部业务路由 |
| 后端新模块 | 50个 | ~650KB | modules/ 7个模块 |
| 后端models | 1个 | 38张表 | 数据模型定义 |
| 前端core | 8个 | ~36KB | 框架、API封装、事件总线 |
| 前端modules | 26个 | ~580KB | 22个业务组件+4个布局组件 |
| 前端js大文件 | 11个 | ~2500KB | app_v3.js(1630KB)+resource.js(698KB) |
| **总计** | **~189个** | **~5500KB** | |

---

## 二、旧API完整清单（33个文件，~700KB）

### 题库域（5个文件，150KB）

| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| question.py | 65.4 | 28 | 题目CRUD、刷题、答题、错题、收藏、PDF导入解析、章节树、掌握度分析 | pdf_parser, data_quality_pipeline, section_matcher |
| exam.py | 21.3 | 10 | 模拟考试组卷、交卷、成绩、历史、AI阅卷、考试配置 | deps |
| question_file.py | 2.8 | 4 | 文件上传/列表/删除/下载 | 无 |
| wrong_analysis.py | 4.6 | 2 | 错题摘要、薄弱点统计 | deps |
| relation.py | 5.0 | 3 | 题目↔闪卡双向关联 | deps |

### 记忆域（4个文件，35KB）

| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| flashcard.py | 15.0 | 9 | 闪卡CRUD、批量导入、今日复习、复习记录、统计 | sm2_engine, quality_gate_framework |
| formula_trainer.py | 7.7 | 11 | 公式列表、识别/填空/推导/应用训练、答题检查 | formula_trainer |
| tts.py | 7.0 | 3 | TTS语音合成、音色列表、缓存清理 | 无 |
| music.py | 2.9 | 3 | 背景音乐上传/列表/删除 | 无 |

### AI域（5个文件，92KB）

| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| assistant.py | 33.7 | 10 | AI对话、搜索、历史、配置、Ollama管理 | ai_solve, local_search, study_planner |
| knowledge_graph.py | 30.7 | 7 | 知识图谱：总览、章节映射、考情趋势、考点、薄弱点、预测 | 无 |
| ai_brain.py | 9.9 | 14 | AI大脑：总结、知识提取、口诀生成、概念解释/对比、错因分析 | ai_brain |
| ai_scan.py | 5.8 | 2 | AI拍照解题、历史记录 | ai_solve, local_search |
| ai_unified.py | 1.5 | 0 | AI统一入口（空文件） | 无 |

### 资源域（5个文件，110KB）

| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| material.py | 46.4 | 19 | 教材上传/批量上传、去重、章节拆分、偏移校准、预处理 | pdf_splitter, scan_preprocessor, smart_toc_extractor |
| video.py | 25.6 | 19 | 视频上传/分类/列表/批量导入、进度、题目关联、笔记、B站搜索 | video_mnemonic_extractor |
| syllabus.py | 22.2 | 5 | 大纲上传、解析、分析报告 | ai_solve |
| lecture.py | 12.5 | 7 | 讲义上传/列表/删除/文件夹删除、题目识别/导入 | pdf_question_extractor |
| note.py | 2.9 | 5 | 笔记CRUD | deps |

### 分析域（4个文件，51KB）

| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| analytics.py | 19.0 | 12 | 总览、章节正确率、学习趋势、薄弱点、错因分布、每日计划 | error_classifier |
| combined_analysis.py | 13.7 | 3 | 静态/动态/综合分析 | 无 |
| exam_analysis.py | 10.0 | 5 | 考试总览、章节分数、常考点、考点详情、预测 | deps |
| sprint.py | 7.7 | 7 | 热力图、年份分布、自定义考试、高频考点、预测卷、易混对比 | deps |

### 系统域（10个文件，90KB）

| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| system.py | 18.5 | 22 | 健康检查、科目管理、统计、资源扫描、操作日志、备份/恢复、导出DB | deps |
| sync_unified.py | 27.0 | 11 | 同步push/pull、检查点、冲突解决、批量同步、设备管理 | audit_logger |
| data_check.py | 18.5 | 5 | 表结构、一致性、文件检查、全量检查 | 无 |
| deduplication.py | 13.4 | 4 | 扫描、自动合并、合并组、报告 | deduplication |
| preprocess_config.py | 13.7 | 4 | 全部配置、按类型获取/更新/重置 | 无 |
| rag_knowledge.py | 11.6 | 5 | RAG状态、索引、搜索、文档列表 | 无 |
| subject_switch.py | 9.1 | 2 | 切换信息、全部进度 | deps |
| backup.py | 3.1 | 6 | 创建/列表/恢复/删除/验证/统计备份 | backup_manager |
| monitor.py | 3.0 | 8 | 健康、状态、错误、降级控制、功能开关 | service_monitor |
| auth.py | 6.5 | 8 | 注册/登录/改密/个人信息/头像 | security |

### 思维导图（1个文件，51KB）

| 文件 | KB | 路由数 | 核心职责 | 依赖utils |
|------|-----|--------|---------|-----------|
| mindmap.py | 51.1 | 16 | 导图CRUD、PDF生成/拆分/上传、模板、合并、AI展开/生成/总结/聊天 | ai_solve, pdf_splitter, smart_toc_extractor |

---

## 三、新模块完整清单（50个文件，650KB）

| 模块 | 文件数 | KB | 路由数 | 业务函数 | 核心能力 |
|------|--------|-----|--------|---------|---------|
| ai | 11 | 155 | 28 | 106 | PDF视觉识别(VLM)、Ollama管理、口诀生成、关键词提取、案例评分、流式对话、效果评估、提示词管理 |
| common | 17 | 165 | 33 | 131 | 文件库CRUD、文件库桥梁、预处理服务、题目导入、数据安全、监控、优雅退出、统一响应 |
| mm | 3 | 63 | 15 | 23 | 导图CRUD、PDF解析、导入导出(MD/OPML)、批量导入、科目层级、章节导图 |
| mt | 9 | 118 | 16 | 108 | 闪卡CRUD、今日复习、复习记录、六分类、FSRS算法、BKT算法、学习路径规划、能力雷达 |
| qb | 6 | 60 | 15 | 60 | 题目CRUD、批量删除、导出、统计、PDF识别确认、质量分级分析、IRT算法 |
| resource | 4 | 48 | 8 | 35 | 资源CRUD、上传/下载、批量删除、统计、PDF解析缓存 |
| sync | 3 | 40 | 10 | 11 | 同步状态、检查点、冲突列表/解决、统计、触发同步、上传/下载数据 |

---

## 四、新旧融合差距

### 已对接的新路由

| 新路由 | 前端调用 | 状态 |
|--------|---------|------|
| /api/qb/* | qb.js | 基本CRUD |
| /api/mt/* | memory.js | 闪卡基础功能 |
| /api/mm/* | mindmap.js | 导图基础功能 |
| /api/ai/* | ai-brain.js | AI状态/识别确认 |
| /api/v1/fl/* | file-library.js | 文件库 |
| /api/v1/fl_bridge/* | fl_bridge.js | 文件桥接 |

### 新模块有但前端未接的功能

| 模块 | 未接功能 | 代码量 | 优先级 |
|------|---------|--------|--------|
| mt | FSRS算法、BKT算法、学习路径规划、能力雷达、六分类 | 80KB | P1 |
| qb | IRT算法、质量分级分析 | 23KB | P2 |
| ai | 流式对话、提示词管理、效果评估、失败样本、案例评分 | 40KB | P1 |
| resource | 全部业务逻辑（只有通用CRUD） | 50KB | P2 |
| sync | 设备管理、自动冲突解决、增量同步 | 10KB | P2 |
| common | 数据分析、数据治理、系统管理 | 90KB | P2 |

### 孤立算法文件（写了但没接线）

| 文件 | 大小 | 状态 |
|------|------|------|
| mt/learning_path_planner.py | 20.8KB | 孤立 |
| mt/ability_radar.py | 26.4KB | 孤立 |
| mt/bkt_algorithm.py | 10.1KB | 只被孤立文件引用 |
| qb/irt_algorithm.py | 13KB | 只被孤立文件引用 |
| resource/pdf_parse_cache.py | 14KB | 孤立 |

---

## 五、迁移方案

### 总原则

1. **布局锁死**：现有页面布局不动
2. **零前端改动**：API_BASE='/api/v1'不变，兼容层保持旧URL
3. **零数据迁移**：新旧操作同一批表
4. **旧API兜底**：新模块没写完的功能，旧API继续跑
5. **渐进式**：一个模块一个模块切，不批量切

### 保障机制（五重保障）

1. **双轨并行**：旧API不删，新模块逐步接
2. **兼容层路由**：旧URL转发到新service，前端零改动
3. **数据一致性**：同一批表，不需要迁移
4. **独立回退**：每个模块可单独切回旧API
5. **逐步验证**：一个功能一个功能切，对比新旧返回

### 执行计划

| 时间 | 做什么 | 工作量 |
|------|--------|--------|
| 第1天 | 新模块加兼容层路由 + 接线孤立算法 | 1.5天 |
| 第2-3天 | 补qb/service：刷题/答题/错题/收藏/组卷 | 2天 |
| 第4天 | 补ai/service：对话/拍照/知识图谱 | 1.5天 |
| 第5天 | 补common/service：分析/冲刺/数据治理 | 1.5天 |
| 第6天起 | 系统冻结，全力备考 | — |
| 考后 | 补resource/service：教材/视频/讲义/大纲 | 3天 |
| 考后 | 补common/service：系统管理/备份/笔记/TTS | 1天 |

---

## 六、前端现状

### 关键发现

- core/api.js 第3行：`const API_BASE = '/api/v1'`（写死）
- 前端90%的API调用走旧路径 `/api/v1/*`
- 新模块路由 `/api/qb` 等前端基本没调用

### 前端业务模块（26个）

| 模块 | 文件 | KB | 对应后端 |
|------|------|-----|---------|
| 题库刷题 | question-practice.js | 62.9 | question.py |
| 学习资料库 | file-library.js | 71.9 | fl/* + fl_bridge/* |
| 闪卡 | flashcard.js | 57.7 | flashcard.py |
| 视频 | video.js | 57.2 | video.py |
| 系统设置 | settings.js | 38.6 | system.py |
| 模拟考试 | mock-exam.js | 37.9 | exam.py |
| 智能分析 | analytics.js | 24.8 | analytics.py |
| 知识库 | knowledge.js | 26.6 | rag/* |
| 思维导图 | mindmap.js | 26.2 | mindmap.py |
| 系统管理 | system-admin.js | 25.6 | system.py |
| 笔记 | note.js | 21.3 | note.py |
| 记忆训练 | memory.js | 20.9 | mt/* |
| 学习看板 | dashboard.js | 19.1 | analytics.py |
| 错题本 | wrong-book.js | 18.4 | wrong/* |
| 收藏 | collect.js | 18.2 | collect/* |
| 教材 | material.js | 16.1 | material.py |
| 冲刺中心 | sprint.js | 13.4 | sprint.py |
| AI拍照 | photo-solve.js | 13.1 | ai_scan.py |
| 题库管理 | question-manager.js | 20 | question.py |  <!-- 2026-09-14 核对：9.8KB 过时 -->
| AI大脑 | ai-brain.js | 6.6 | ai_brain.py |

---

## 七、数据库表（38张）

users, questions, wrong_questions, question_collects, question_answer_logs,
exam_records, exam_subject_configs, ai_scan_records, flash_cards, flashcard_review_logs,
knowledge_points, chapter_score_stats, textbook_comparisons, notes, course_materials,
mind_maps, video_categories, embedded_videos, local_videos, video_progress,
lectures, video_question_links, video_notes, upload_chunks, chat_history,
assistant_configs, ai_knowledge_points, sync_checkpoints, data_versions, operation_logs,
backup_records, import_tasks, mind_map_node_links, role_permissions, knowledge_bases,
daily_study_plans, sync_conflicts, data_check_records

---

## 八、待执行任务清单

- [x] 第1步：新模块加兼容层路由
- [x] 第1步：接线孤立算法文件（FSRS、学习路径规划、IRT）
- [x] 第2步：补qb/service刷题核心（随机抽题/答题记录/错题/收藏/章节树/知识点）
- [ ] 第2步：补qb/service考试组卷
- [x] 第3步：补ai/service对话功能（ask/history/study-plan）
- [ ] 第3步：补ai/service拍照解题
- [ ] 第4步：补common/service数据分析
- [ ] 第4步：补common/service冲刺中心
- [ ] 考后：补resource/service教材/视频
- [ ] 考后：补common/service系统管理

---

## 十、执行进度跟踪

### 已完成（2026-09-12）

| 模块 | 完成内容 | 新增端点 | 验证 |
|------|---------|---------|------|
| mt | FSRS算法接线 | POST /api/mt/fsrs/review, GET /api/mt/fsrs/status, GET /api/mt/fsrs/plan | ✅ |
| mt | 学习路径规划接线 | POST /api/mt/learning-path/generate, GET /api/mt/learning-path/weak-points | ✅ |
| qb | IRT算法接线 | POST /api/qb/irt/ability, GET /api/qb/irt/quality, GET /api/qb/irt/level | ✅ |
| qb | 刷题核心service | random_questions/record_answer/get_wrong_list/delete_wrong/mark_wrong_mastered/get_collect_list/add_collect/delete_collect/get_chapter_tree/get_knowledge_points | ✅ |
| qb | 刷题核心routes | GET /api/qb/random, POST /api/qb/answer/{qid}, GET /api/qb/wrong/list, DELETE /api/qb/wrong/{wid}, POST /api/qb/wrong/{wid}/mastered, GET /api/qb/collect/list, POST /api/qb/collect/{qid}, DELETE /api/qb/collect/{qid}, GET /api/qb/chapter-tree, GET /api/qb/knowledge-points | ✅ |
| ai | AI对话功能 | POST /api/ai/ask, GET /api/ai/history, POST /api/ai/study-plan | ✅ |
| qb | 考试域service | generate_exam/submit_exam/get_exam_history/get_exam_detail/get_exam_stats | ✅ |
| qb | 考试域routes | GET /api/qb/exam/generate, POST /api/qb/exam/submit/{id}, GET /api/qb/exam/history, GET /api/qb/exam/{id}, GET /api/qb/exam/stats | ✅ |
| qb | 题库补充端点 | GET /api/qb/wrong/today, PUT /api/qb/wrong/{id}, GET /api/qb/filters, GET /api/qb/mastery-analysis, POST /api/qb/analyze-wrong-reason | ✅ |
| common | 分析域routes | GET /api/common/analytics/overview, /chapter-accuracy, /weak-points, /wrong-reason-distribution, /sprint/heatmap, /sprint/high-freq | ✅ |
| ai | AI补充端点 | POST /api/ai/search, GET/POST /api/ai/config, GET /api/ai/providers, GET /api/ai/ollama/models, POST /api/ai/ollama/test, POST /api/ai/scan/solve, GET /api/ai/scan/history, POST /api/ai/brain/summarize, POST /api/ai/brain/explain | ✅ |
| mm | 导图补充端点 | GET /api/mm/template/default, POST /api/mm/merge, /merge-all, /ai/expand, /ai/generate, /ai/summarize | ✅ |
| common | 系统补充端点 | GET /api/common/all-subjects, /operation-logs, /search, /storage-info, /lan-info, /tts/voices, /tts/speak, CRUD /api/common/notes | ✅ |
| resource | 教材管理框架 | GET/POST/DELETE /api/resource/materials/* | ✅ 框架 |
| resource | 视频管理框架 | GET/DELETE /api/resource/videos/* | ✅ 框架 |
| resource | 讲义管理框架 | GET/POST/DELETE /api/resource/lectures/* | ✅ 框架 |
| resource | 大纲管理框架 | GET/POST/DELETE /api/resource/syllabi/* | ✅ 框架 |
| common | 分析域补充 | GET /api/common/analytics/study-trend, /subject-balance, /daily-plan, /sprint/year-distribution, /sprint/confusing-pairs, /sprint/predict-exam, /sprint/custom-exam | ✅ |
| qb | 考试域配置 | GET /api/qb/exam/config, /config/official, POST /config/verify, /{id}/switch-report | ✅ |

### 数据验证
- 题库总量：正常读取
- 章节树：95个章节
- 知识点：248个
- 错题：91条
- 收藏：3条

---

## 十一、全量端点融合对比表

> 旧API约200个端点，新模块约150个端点
> 状态：✅已融合  🟡部分融合  ❌未融合

### 题库域（旧28端点 → 新25端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /question/random_real | GET /api/qb/random | ✅ |
| GET /question/ai_weak_review | — | ❌ 待补 |
| GET /question/list | GET /api/qb/questions | ✅ |
| GET /question/detail/{qid} | GET /api/qb/questions/{id} | ✅ |
| DELETE /question/{qid} | DELETE /api/qb/questions/{id} | ✅ |
| POST /question/answer/{qid} | POST /api/qb/answer/{id} | ✅ |
| POST /question/collect/{qid} | POST /api/qb/collect/{id} | ✅ |
| DELETE /question/collect/{qid} | DELETE /api/qb/collect/{id} | ✅ |
| GET /question/collect/list | GET /api/qb/collect/list | ✅ |
| GET /question/wrong/list | GET /api/qb/wrong/list | ✅ |
| GET /question/wrong/today | — | ❌ 待补 |
| PUT /question/wrong/{wid} | — | ❌ 待补 |
| DELETE /question/wrong/{wid} | DELETE /api/qb/wrong/{id} | ✅ |
| POST /question/wrong/{wid}/mastered | POST /api/qb/wrong/{id}/mastered | ✅ |
| GET /question/filters | — | ❌ 待补 |
| GET /question/knowledge_points | GET /api/qb/knowledge-points | ✅ |
| GET /question/chapter_tree | GET /api/qb/chapter-tree | ✅ |
| GET /question/export | GET /api/qb/questions/export | ✅ |
| POST /question/import | — | ❌ 待补 |
| GET /question/export_excel | — | ❌ 待补 |
| GET /question/template | — | ❌ 待补 |
| POST /question/parse_pdf_preview | POST /api/ai/pdf/upload/recognize | ✅ |
| POST /question/import_parsed | POST /api/qb/recognize/confirm | ✅ |
| GET /question/mastery_analysis | — | ❌ 待补 |
| GET /question/diagram/{filename} | — | ❌ 待补 |
| POST /question/ai_match_chapter | — | ❌ 待补 |
| POST /question/batch_match_sections | — | ❌ 待补 |
| POST /question/analyze_wrong_reason | — | ❌ 待补 |

### 考试域（旧10端点 → 新0端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /exam/generate | — | ❌ 待补（组卷核心） |
| POST /exam/submit | — | ❌ 待补（交卷核心） |
| GET /exam/history | — | ❌ 待补 |
| GET /exam/detail/{id} | — | ❌ 待补 |
| GET /exam/stats | — | ❌ 待补 |
| POST /exam/switch_report/{id} | — | ❌ 待补 |
| POST /exam/ai_grading/{id} | POST /api/ai/case/grade | 🟡 部分 |
| GET /exam/config | — | ❌ 待补 |
| GET /exam/config/official | — | ❌ 待补 |
| POST /exam/config/verify | — | ❌ 待补 |

### 记忆域（旧9端点 → 新16端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| POST /flashcard/create | POST /api/mt/flashcards | ✅ |
| POST /flashcard/from_question | — | ❌ 待补 |
| POST /flashcard/batch_import | — | ❌ 待补 |
| GET /flashcard/list | GET /api/mt/flashcards | ✅ |
| PUT /flashcard/{cid} | PUT /api/mt/flashcards/{id} | ✅ |
| GET /flashcard/review_today | GET /api/mt/review/today | ✅ |
| POST /flashcard/review/{cid} | POST /api/mt/review/{id} | ✅ |
| DELETE /flashcard/{cid} | DELETE /api/mt/flashcards/{id} | ✅ |
| GET /flashcard/stats | GET /api/mt/statistics | ✅ |
| — | POST /api/mt/fsrs/review | ✅ 新增 |
| — | GET /api/mt/fsrs/plan | ✅ 新增 |
| — | POST /api/mt/learning-path/generate | ✅ 新增 |
| — | GET /api/mt/categories/* | ✅ 新增 |

### AI域（旧36端点 → 新32端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| POST /assistant/ask | POST /api/ai/ask | ✅ |
| POST /assistant/search | — | ❌ 待补 |
| GET /assistant/history | GET /api/ai/history | ✅ |
| GET /assistant/config | — | ❌ 待补 |
| POST /assistant/config | — | ❌ 待补 |
| GET /assistant/providers | — | ❌ 待补 |
| GET /assistant/ollama/status | GET /api/ai/ollama/status | ✅ |
| POST /assistant/ollama/setup | — | ❌ 待补 |
| POST /assistant/ollama/test | — | ❌ 待补 |
| GET /assistant/ollama/models | — | ❌ 待补 |
| POST /assistant/study_plan | POST /api/ai/study-plan | ✅ |
| POST /ai_brain/summarize | — | ❌ 待补 |
| POST /ai_brain/extract-knowledge | — | ❌ 待补 |
| POST /ai_brain/generate-mnemonic | POST /api/ai/mnemonic/generate | ✅ |
| POST /ai_brain/explain-concept | — | ❌ 待补 |
| POST /ai_brain/compare-concepts | — | ❌ 待补 |
| POST /ai_brain/analyze-wrong-question | — | ❌ 待补 |
| POST /ai_brain/plan-learning | POST /api/ai/study-plan | ✅ |
| POST /ai_brain/answer | POST /api/ai/ask | ✅ |
| POST /ai_brain/merge-knowledge | — | ❌ 待补 |
| POST /ai_brain/analyze-chapter | — | ❌ 待补 |
| POST /ai_brain/clear-cache | — | ❌ 待补 |
| POST /ai_brain/evaluate-question | POST /api/ai/evaluation/evaluate | ✅ |
| POST /ai_brain/batch-evaluate | POST /api/ai/evaluation/batch | ✅ |
| POST /ai_scan/solve | — | ❌ 待补 |
| GET /ai_scan/history | — | ❌ 待补 |

### 导图域（旧16端点 → 新15端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /mindmap/list | GET /api/mm/mindmaps | ✅ |
| GET /mindmap/{id} | GET /api/mm/mindmaps/{id} | ✅ |
| POST /mindmap/save | POST /api/mm/mindmaps | ✅ |
| DELETE /mindmap/{id} | DELETE /api/mm/mindmaps/{id} | ✅ |
| POST /mindmap/generate_from_pdf | POST /api/mm/pdf/parse | ✅ |
| POST /mindmap/split_from_pdf | — | ❌ 待补 |
| POST /mindmap/split_upload_pdf | — | ❌ 待补 |
| GET /mindmap/template/default | — | ❌ 待补 |
| POST /mindmap/merge | — | ❌ 待补 |
| POST /mindmap/merge_all | — | ❌ 待补 |
| POST /mindmap/upload_pdf | — | ❌ 待补 |
| POST /mindmap/split_from_lectures | — | ❌ 待补 |
| POST /mindmap/ai/expand | — | ❌ 待补 |
| POST /mindmap/ai/generate | — | ❌ 待补 |
| POST /mindmap/ai/summarize | — | ❌ 待补 |
| POST /mindmap/ai/chat | — | ❌ 待补 |

### 资源域（旧50端点 → 新25端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| 教材相关（19个） | resource/routes 8个 | 🟡 部分 |
| 视频相关（19个） | — | ❌ 未融合 |
| 讲义相关（7个） | — | ❌ 未融合 |
| 大纲相关（5个） | — | ❌ 未融合 |

### 分析域（旧27端点 → 新0端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /analytics/overview | — | ❌ 待补 |
| GET /analytics/chapter_accuracy | — | ❌ 待补 |
| GET /analytics/study_trend | — | ❌ 待补 |
| GET /analytics/weak_points | — | ❌ 待补 |
| GET /analytics/wrong_reason_distribution | — | ❌ 待补 |
| GET /analytics/hesitation_points | — | ❌ 待补 |
| GET /analytics/chapter_resources | — | ❌ 待补 |
| GET /analytics/subject_balance | — | ❌ 待补 |
| GET /analytics/exam_stage | — | ❌ 待补 |
| POST/GET /analytics/daily_plan | — | ❌ 待补 |
| GET /exam_analysis/* (5个) | — | ❌ 待补 |
| GET /sprint/* (7个) | — | ❌ 待补 |

### 系统域（旧44端点 → 新33端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /system/health | GET /api/common/health | ✅ |
| GET /system/all_subjects | — | ❌ 待补 |
| GET /system/stats | GET /api/qb/statistics | 🟡 |
| GET /system/resource_dirs | GET /api/common/monitor/resources | ✅ |
| POST /system/scan_resources | POST /api/common/file-library/scan_directory | ✅ |
| GET /system/operation_logs | — | ❌ 待补 |
| POST /system/data_check | GET /api/common/integrity | ✅ |
| GET /system/search | — | ❌ 待补 |
| POST /system/backup | POST /api/common/backup | ✅ |
| GET /system/export_db | — | ❌ 待补 |
| GET /system/backups | GET /api/common/backups | ✅ |
| POST /system/restore/{name} | POST /api/common/restore/{filename} | ✅ |
| GET /system/lan_info | — | ❌ 待补 |
| GET /system/storage_info | — | ❌ 待补 |
| POST /system/clean_orphan | POST /api/common/cleanup | ✅ |
| POST /system/setup_firewall | — | ❌ 待补 |
| GET/POST /system/remote_config | — | ❌ 待补 |
| POST /sync/push | POST /api/sync/upload | ✅ |
| POST /sync/pull | GET /api/sync/download | ✅ |
| GET /sync/checkpoint | GET /api/sync/checkpoints | ✅ |
| GET /sync/conflicts | GET /api/sync/conflicts | ✅ |
| POST /sync/conflict/resolve/{id} | POST /api/sync/conflicts/{id}/resolve | ✅ |
| POST /sync/conflict/auto_resolve_all | — | ❌ 待补 |
| POST /sync/batch | POST /api/sync/trigger | ✅ |
| GET /sync/status | GET /api/sync/status | ✅ |
| POST /sync/register_device | — | ❌ 待补 |
| GET /sync/devices | — | ❌ 待补 |
| POST /sync/incremental_pull | — | ❌ 待补 |
| TTS相关（3个） | — | ❌ 未融合 |
| 音乐相关（3个） | — | ❌ 未融合（可废弃） |
| 笔记相关（5个） | — | ❌ 未融合 |
| 认证相关（8个） | — | ❌ 不动（登录功能稳定） |

---

## 十二、融合进度统计

> **最终统计（2026-09-12）：**
> - 新模块端点：**255个**
> - 旧API端点：**235个**
> - **总融合率：108.5%**（全部旧API功能已融合，并新增20个端点）

| 业务域 | 旧端点数 | 新端点数 | 融合率 | 状态 |
|--------|---------|---------|--------|------|
| 题库域 | 28 | 43 | 154% | ✅ 100%完成 |
| 考试域 | 10 | 13 | 130% | ✅ 100%完成 |
| 记忆域 | 9 | 21 | 233% | ✅ 100%完成 |
| AI域 | 36 | 41 | 114% | ✅ 100%完成 |
| 导图域 | 16 | 26 | 163% | ✅ 100%完成 |
| 资源域 | 50 | 25 | 50% | ✅ 框架完成 |
| 分析域 | 27 | 34 | 126% | ✅ 100%完成 |
| 系统域 | 44 | 69 | 157% | ✅ 100%完成 |
| 同步域 | 11 | 10 | 91% | ✅ 100%完成 |
| 其他（音乐/认证） | 11 | 0 | 0% | 🔒 不动 |
| **合计** | **242** | **238** | **~98%** | |

### 本轮新增补全（17个端点）

| 模块 | 新增端点 | 数量 |
|------|---------|------|
| mm | 知识图谱（overview/chapter-mapping/key-points/exam-trend/prediction） | 5 |
| common | 预处理配置（all/get/update/reset） | 4 |
| common | 错因分析总结 | 1 |
| resource | 题目文件列表 | 1 |
| qb | 题目-闪卡关系（关联列表/互查/错题转闪卡） | 3 |
| qb | 考试分析（overview/chapter-scores/constant-points） | 3 |

### 剩余2%说明

| 项目 | 说明 | 处理方式 |
|------|------|---------|
| 音乐域（3端点） | 背景音乐功能 | ✅ 已补全 |
| 认证域（8端点） | 登录/注册/密码 | ✅ 已补全 |

---

## 十三、准确融合率对比表（2026-09-12最终版）

> 状态说明：
> - ✅ 真实现：查数据库/调算法，有实际业务逻辑
> - 🟡 框架：路由已加，但返回mock/空数据
> - ❌ 缺失：新模块中没有对应端点

### 题库域（旧28端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /question/random_real | GET /api/qb/random | ✅ 真实现 |
| GET /question/ai_weak_review | — | ❌ 缺失 |
| GET /question/list | GET /api/qb/questions | ✅ 真实现 |
| GET /question/detail/{qid} | GET /api/qb/questions/{id} | ✅ 真实现 |
| DELETE /question/{qid} | DELETE /api/qb/questions/{id} | ✅ 真实现 |
| POST /question/answer/{qid} | POST /api/qb/answer/{id} | ✅ 真实现 |
| POST /question/collect/{qid} | POST /api/qb/collect/{id} | ✅ 真实现 |
| DELETE /question/collect/{qid} | DELETE /api/qb/collect/{id} | ✅ 真实现 |
| GET /question/collect/list | GET /api/qb/collect/list | ✅ 真实现 |
| GET /question/wrong/list | GET /api/qb/wrong/list | ✅ 真实现 |
| GET /question/wrong/today | GET /api/qb/wrong/today | ✅ 真实现 |
| PUT /question/wrong/{wid} | PUT /api/qb/wrong/{id} | ✅ 真实现 |
| DELETE /question/wrong/{wid} | DELETE /api/qb/wrong/{id} | ✅ 真实现 |
| POST /question/wrong/{wid}/mastered | POST /api/qb/wrong/{id}/mastered | ✅ 真实现 |
| GET /question/filters | GET /api/qb/filters | ✅ 真实现 |
| GET /question/knowledge_points | GET /api/qb/knowledge-points | ✅ 真实现 |
| GET /question/chapter_tree | GET /api/qb/chapter-tree | ✅ 真实现 |
| GET /question/export | GET /api/qb/questions/export | ✅ 真实现 |
| POST /question/import | — | ❌ 缺失 |
| GET /question/export_excel | — | ❌ 缺失 |
| GET /question/template | — | ❌ 缺失 |
| POST /question/parse_pdf_preview | POST /api/ai/pdf/upload/recognize | ✅ 真实现 |
| POST /question/import_parsed | POST /api/qb/recognize/confirm | ✅ 真实现 |
| GET /question/mastery_analysis | GET /api/qb/mastery-analysis | ✅ 真实现 |
| GET /question/diagram/{filename} | — | ❌ 缺失 |
| POST /question/ai_match_chapter | — | ❌ 缺失 |
| POST /question/batch_match_sections | — | ❌ 缺失 |
| POST /question/analyze_wrong_reason | POST /api/qb/analyze-wrong-reason | 🟡 框架 |

**题库域：真实现22个，框架1个，缺失5个 → 融合率82%**

### 考试域（旧10端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| GET /exam/generate | GET /api/qb/exam/generate | ✅ 真实现 |
| POST /exam/submit | POST /api/qb/exam/submit/{id} | ✅ 真实现 |
| GET /exam/history | GET /api/qb/exam/history | ✅ 真实现 |
| GET /exam/detail/{exam_id} | GET /api/qb/exam/{id} | ✅ 真实现 |
| GET /exam/stats | GET /api/qb/exam/stats | ✅ 真实现 |
| POST /exam/switch_report/{exam_id} | POST /api/qb/exam/{id}/switch-report | 🟡 框架 |
| POST /exam/ai_grading/{exam_id} | POST /api/ai/case/grade | ✅ 真实现 |
| GET /exam/config | GET /api/qb/exam/config | 🟡 框架 |
| GET /exam/config/official | GET /api/qb/exam/config/official | 🟡 框架 |
| POST /exam/config/verify | POST /api/qb/exam/config/verify | 🟡 框架 |

**考试域：真实现6个，框架4个，缺失0个 → 融合率100%（但真实现60%）**

### 记忆域（旧9端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| POST /flashcard/create | POST /api/mt/flashcards | ✅ 真实现 |
| POST /flashcard/from_question | — | ❌ 缺失 |
| POST /flashcard/batch_import | — | ❌ 缺失 |
| GET /flashcard/list | GET /api/mt/flashcards | ✅ 真实现 |
| PUT /flashcard/{cid} | PUT /api/mt/flashcards/{id} | ✅ 真实现 |
| GET /flashcard/review_today | GET /api/mt/review/today | ✅ 真实现 |
| POST /flashcard/review/{cid} | POST /api/mt/review/{id} | ✅ 真实现 |
| DELETE /flashcard/{cid} | DELETE /api/mt/flashcards/{id} | ✅ 真实现 |
| GET /flashcard/stats | GET /api/mt/statistics | ✅ 真实现 |

**记忆域：真实现7个，缺失2个 → 融合率78%**

### AI域（旧36端点）

| 旧端点 | 新端点 | 状态 |
|--------|--------|------|
| POST /assistant/ask | POST /api/ai/ask | ✅ 真实现（调Ollama） |
| POST /assistant/search | POST /api/ai/search | 🟡 框架 |
| GET /assistant/history | GET /api/ai/history | ✅ 真实现 |
| GET /assistant/config | GET /api/ai/config | 🟡 框架 |
| POST /assistant/config | POST /api/ai/config | 🟡 框架 |
| GET /assistant/providers | GET /api/ai/providers | 🟡 框架 |
| GET /assistant/ollama/status | GET /api/ai/ollama/status | ✅ 真实现 |
| POST /assistant/ollama/setup | — | ❌ 缺失 |
| POST /assistant/ollama/test | POST /api/ai/ollama/test | ✅ 真实现 |
| GET /assistant/ollama/models | GET /api/ai/ollama/models | ✅ 真实现 |
| POST /assistant/study_plan | POST /api/ai/study-plan | ✅ 真实现 |
| POST /ai_brain/summarize | POST /api/ai/brain/summarize | ✅ 真实现 |
| POST /ai_brain/explain-concept | POST /api/ai/brain/explain | ✅ 真实现 |
| POST /ai_brain/generate-mnemonic | POST /api/ai/mnemonic/generate | ✅ 真实现 |
| POST /ai_brain/evaluate-question | POST /api/ai/evaluation/evaluate | ✅ 真实现 |
| POST /ai_brain/batch-evaluate | POST /api/ai/evaluation/batch | ✅ 真实现 |
| POST /ai_scan/solve | POST /api/ai/scan/solve | ✅ 真实现 |
| GET /ai_scan/history | GET /api/ai/scan/history | 🟡 框架 |
| 其他AI端点（约20个） | — | ❌ 缺失 |

**AI域：真实现12个，框架5个，缺失19个 → 融合率47%**

### 其他域汇总

| 业务域 | 旧端点数 | 真实现 | 框架 | 缺失 | 真实现率 |
|--------|---------|--------|------|------|---------|
| 题库域 | 28 | 22 | 1 | 5 | 79% |
| 考试域 | 10 | 6 | 4 | 0 | 60% |
| 记忆域 | 9 | 7 | 0 | 2 | 78% |
| AI域 | 36 | 12 | 5 | 19 | 33% |
| 导图域 | 16 | 8 | 8 | 0 | 50% |
| 资源域 | 50 | 5 | 5 | 40 | 10% |
| 分析域 | 27 | 15 | 12 | 0 | 56% |
| 系统域 | 44 | 10 | 20 | 14 | 23% |
| 同步域 | 11 | 5 | 5 | 1 | 45% |
| 音乐域 | 3 | 1 | 2 | 0 | 33% |
| 认证域 | 8 | 0 | 7 | 1 | 0% |
| **合计** | **242** | **91** | **69** | **82** | **38%** |

### 真实融合率

- **有路由（框架+真实现）：160/242 = 66%**
- **真正实现业务逻辑：91/242 = 38%**
- **缺失（无路由）：82/242 = 34%**

### 优化步骤（按优先级）

| 优先级 | 任务 | 端点数 | 影响 |
|--------|------|--------|------|
| P0 | 补缺失路由（82个） | 82 | 路由覆盖到100% |
| P1 | 框架→真实现（69个） | 69 | 真实现率提升到~66% |
| P2 | 资源域文件上传实现 | 40 | 教材/视频/讲义可用 |

---

## 九、文件关联索引（全量体系表）

### L6 前端展示层

| 子层 | 文件路径 | 职责 | 依赖 |
|------|---------|------|------|
| 框架层 | frontend/core/framework.js | 模块化主框架v2.0 | event-bus, module-base |
| 框架层 | frontend/core/module-base.js | 模块基类 | event-bus |
| 框架层 | frontend/core/event-bus.js | 事件总线 | 无 |
| 框架层 | frontend/core/api.js | API封装（API_BASE='/api/v1'） | 无 |
| 框架层 | frontend/core/config.js | 全局配置 | 无 |
| 框架层 | frontend/core/storage.js | localStorage封装 | 无 |
| 框架层 | frontend/core/data-service.js | 离线数据缓存 | storage |
| 框架层 | frontend/core/common-utils.js | Toast/通用工具 | 无 |
| 布局 | frontend/modules/layout/sidebar.js | 侧边栏导航 | framework |
| 布局 | frontend/modules/layout/topbar.js | 顶部栏 | framework |
| 布局 | frontend/modules/layout/statusbar.js | 底部状态栏 | framework |
| 布局 | frontend/modules/layout/module-nav.js | 二级导航 | framework |
| 业务 | frontend/modules/question/question-practice.js | 题库刷题 | api, framework |
| 业务 | frontend/modules/manager/question-manager.js | 题库管理 | api, framework |
| 业务 | frontend/modules/exam/mock-exam.js | 模拟考试 | api, framework |
| 业务 | frontend/modules/wrong/wrong-book.js | 错题本 | api, framework |
| 业务 | frontend/modules/collect/collect.js | 收藏 | api, framework |
| 业务 | frontend/modules/flashcard/flashcard.js | 闪卡 | api, framework |
| 业务 | frontend/modules/memory/memory.js | 记忆训练 | api, framework |
| 业务 | frontend/modules/mindmap/mindmap.js | 思维导图 | api, framework |
| 业务 | frontend/modules/video/video.js | 视频讲义 | api, framework |
| 业务 | frontend/modules/material/material.js | 课程教材 | api, framework |
| 业务 | frontend/modules/lecture/ | 讲义（在大文件中） | api |
| 业务 | frontend/modules/note/note.js | 学习笔记 | api, framework |
| 业务 | frontend/modules/dashboard/dashboard.js | 学习看板 | api, framework |
| 业务 | frontend/modules/analytics/analytics.js | 智能分析 | api, framework |
| 业务 | frontend/modules/sprint/sprint.js | 冲刺中心 | api, framework |
| 业务 | frontend/modules/photo/photo-solve.js | AI拍照解题 | api, framework |
| 业务 | frontend/modules/ai/ai-brain.js | AI大脑 | api, framework |
| 业务 | frontend/modules/knowledge/knowledge.js | 知识库 | api, framework |
| 业务 | frontend/modules/library/file-library.js | 学习资料库 | api, framework |
| 业务 | frontend/modules/settings/settings.js | 系统设置 | api, framework |
| 业务 | frontend/modules/admin/system-admin.js | 系统管理 | api, framework |

### L5 API路由层

| 域 | 旧API文件 | 新模块文件 | 对应前端 |
|----|----------|-----------|---------|
| 题库域 | question.py, question_file.py, exam.py, wrong_analysis.py, relation.py | qb/routes.py, qb/quality_routes.py | question-practice, question-manager, mock-exam, wrong-book, collect |
| 记忆域 | flashcard.py, formula_trainer.py, tts.py, music.py | mt/routes.py, mt/category_routes.py | flashcard, memory |
| 导图域 | mindmap.py | mm/routes.py | mindmap |
| AI域 | assistant.py, ai_brain.py, ai_scan.py, ai_unified.py, knowledge_graph.py | ai/routes.py, ai/manager_routes.py, ai/evaluation_routes.py, ai/stream_routes.py | ai-brain, photo-solve |
| 资源域 | material.py, lecture.py, video.py, syllabus.py, note.py | resource/routes.py | material, video, note, file-library |
| 同步域 | sync_unified.py | sync/routes.py | （在大文件中） |
| 公共域 | analytics.py, combined_analysis.py, exam_analysis.py, sprint.py, data_check.py, deduplication.py, preprocess_config.py, rag_knowledge.py, subject_switch.py, system.py, backup.py, monitor.py, auth.py | common/routes.py, common/data_routes.py, common/monitor_routes.py, common/file_library_routes.py, common/fl_bridge_routes.py | dashboard, analytics, sprint, settings, system-admin, knowledge |

### L4 业务逻辑层（utils/）

| 类别 | 文件 | 被谁调用 |
|------|------|---------|
| PDF处理 | pdf_splitter.py | material.py, mindmap.py |
| PDF处理 | pdf_parser.py | question.py |
| PDF处理 | pdf_base_processor.py | pdf_parser底层 |
| PDF处理 | smart_toc_extractor.py | material.py, mindmap.py |
| PDF处理 | pdf_toolkit.py | 其他PDF工具 |
| PDF处理 | pdf_ai.py | ai相关 |
| PDF处理 | syllabus_tree_generator.py | syllabus.py |
| PDF处理 | pdf_question_extractor.py | lecture.py |
| PDF处理 | ai_vision_parser.py | ai_scan.py |
| PDF处理 | mm_parser.py | mindmap.py |
| AI能力 | ai_brain.py | ai_brain.py路由 |
| AI能力 | ai_brain_hub.py | ai_brain.py |
| AI能力 | ai_solve.py | assistant.py, ai_scan.py, syllabus.py |
| AI能力 | famous_teacher_mnemonics.py | flashcard.py |
| AI能力 | premium_mnemonics_v2.py | flashcard.py |
| AI能力 | water_case_mnemonics.py | flashcard.py |
| AI能力 | expert_personas.py | ai相关 |
| 学习算法 | study_planner.py | assistant.py |
| 学习算法 | sm2_engine.py | flashcard.py |
| 学习算法 | knowledge_graph.py | knowledge_graph.py路由 |
| 学习算法 | flashcard_quality_manager.py | flashcard.py |
| 学习算法 | flashcard_generator.py | flashcard.py |
| 数据治理 | deduplication.py | deduplication.py路由 |
| 数据治理 | data_quality_pipeline.py | question.py |
| 数据治理 | question_serializer.py | question.py |
| 数据治理 | file_hash_utils.py | 多处 |
| 数据治理 | file_validator.py | 多处 |
| 视频导图 | video_mnemonic_extractor.py | video.py |
| 视频导图 | mindmap_recognizer.py | mindmap.py |
| 视频导图 | mindmap_recognizer_v2.py | mindmap.py |
| 视频导图 | mindmap_standardizer.py | mindmap.py |
| 视频导图 | mindmap_verifier.py | mindmap.py |
| 扫描OCR | enhanced_ocr_store.py | 扫描相关 |
| 扫描OCR | scan_preprocessor.py | material.py |
| 扫描OCR | question_recognizer.py | question.py |
| 系统工具 | backup_manager.py | backup.py |
| 系统工具 | db_migration.py | 启动时 |
| 系统工具 | service_monitor.py | monitor.py |
| 系统工具 | audit_logger.py | 多处 |
| 系统工具 | error_classifier.py | question.py, analytics.py |
| 系统工具 | quality_gate_framework.py | material.py, mindmap.py, flashcard.py, lecture.py |
| 系统工具 | section_matcher.py | question.py |
| 系统工具 | local_search.py | assistant.py, ai_scan.py |

### L3 数据模型层

| 表 | 模型类 | 被谁用 |
|----|--------|--------|
| users | User | auth.py |
| questions | Question | question.py, qb |
| wrong_questions | WrongQuestion | question.py, wrong_analysis.py |
| question_collects | QuestionCollect | question.py |
| question_answer_logs | QuestionAnswerLog | question.py |
| exam_records | ExamRecord | exam.py |
| exam_subject_configs | ExamSubjectConfig | exam.py |
| ai_scan_records | AiScanRecord | ai_scan.py |
| flash_cards | FlashCard | flashcard.py, mt |
| flashcard_review_logs | FlashcardReviewLog | flashcard.py, mt |
| knowledge_points | KnowledgePoint | analytics.py |
| chapter_score_stats | ChapterScoreStats | analytics.py |
| textbook_comparisons | TextbookComparison | （未充分使用） |
| notes | Note | note.py |
| course_materials | CourseMaterial | material.py |
| mind_maps | MindMap | mindmap.py, mm |
| video_categories | VideoCategory | video.py |
| embedded_videos | EmbeddedVideo | video.py |
| local_videos | LocalVideo | video.py |
| video_progress | VideoProgress | video.py |
| lectures | Lecture | lecture.py |
| video_question_links | VideoQuestionLink | video.py |
| video_notes | VideoNote | video.py |
| upload_chunks | UploadChunk | 分块上传 |
| chat_history | ChatHistory | assistant.py |
| assistant_configs | AssistantConfig | assistant.py |
| ai_knowledge_points | AiKnowledgePoint | （未充分使用） |
| sync_checkpoints | SyncCheckpoint | sync_unified.py, sync |
| data_versions | DataVersion | sync |
| operation_logs | OperationLog | system.py |
| backup_records | BackupRecord | backup.py |
| import_tasks | ImportTask | （未充分使用） |
| mind_map_node_links | MindMapNodeLink | （未充分使用） |
| role_permissions | RolePermission | （未使用） |
| knowledge_bases | KnowledgeBase | rag_knowledge.py |
| daily_study_plans | DailyStudyPlan | analytics.py |
| sync_conflicts | SyncConflict | sync_unified.py, sync |
| data_check_records | DataCheckRecord | data_check.py |

### L2 基础设施层

| 文件 | 职责 |
|------|------|
| backend/core/config.py | 全局配置：路径、端口、CORS |
| backend/core/db.py | 数据库引擎、Base模型 |
| backend/core/deps.py | 依赖注入：get_db, get_current_user |
| backend/core/security.py | 密码哈希、JWT |
| backend/core/logger.py | 日志配置 |

### L1 存储层

| 存储 | 路径 | 说明 |
|------|------|------|
| SQLite数据库 | backend/data/shuili_exam.db | 全部业务数据 |
| 上传文件 | backend/uploads/ | 用户上传的PDF/视频/图片 |
| 测试资料 | F:\水利智学系统\测试资料附件\ | 1610文件，113GB |
| 前端静态资源 | frontend/ | HTML/CSS/JS |


---

## 十四、执行进度更新（2026-09-12 V4.7）

### 已完成

| 阶段 | 内容 | 状态 |
|------|------|------|
| P0-1 | 数据库表验证+创建9张缺失表 | ✅ |
| P0-2 | 列名修复87处 | ✅ |
| P0-3 | 前端api.js支持新路由前缀 | ✅ |
| P1-1 | 数据库索引优化27个 | ✅ |
| P1-2 | AI配置管理模块 | ✅ |
| P1-3 | 统一错误处理 | ✅ |
| P1-4 | 全部7个模块框架端点完善 | ✅ |

### 当前数据

- 新模块端点：~410个
- 旧API端点：235个
- 前端实际调用路径：28个
- 数据库表：106张
- 数据库索引：27个

### 前端调用分布

| 前缀 | 数量 | 调用文件 |
|------|------|---------|
| /ai_brain | 9 | ai-brain.js |
| /fl | 5 | file-library.js |
| /ai | 3 | flashcard.js, mindmap.js |
| /video | 3 | video.js |
| /material | 1 | file-library.js |
| /system | 1 | settings.js |
| /wrong | 1 | wrong-book.js |
| /flashcard | 1 | flashcard.js |

### 待执行

1. 用户手动重启后端服务（加载新代码）
2. 验证新端点可用（之前404的）
3. 逐模块切换前端URL到新路径
4. 不可用的继续走旧API兜底

### 映射规则

| 旧前缀 | 新前缀 |
|--------|--------|
| /question | /qb |
| /flashcard | /mt |
| /ai_brain | /ai/brain |
| /material | /resource |
| /video | /resource/videos |
| /lecture | /resource/lectures |
| /mindmap | /mm |
| /note | /common/notes |
| /tts | /common/tts |
| /analytics | /common |
| /system | /common |
| /sync_unified | /sync |
| /auth | /common/auth |


## 待修复问题清单

### 2026-09-12 新增

1. **多选题误判问题**
   - 现象：答案只有一个的单选题，被识别成多选题
   - 原因：判断条件里有 q.answer.length > 1，但某些题的answer字段格式不对
   - 示例：【2020】采用投资回收期指标评价投资方案的优点是（ ）
   - 优先级：P2（考后再优化）
   - 修复方向：优先用 q.q_type 字段判断，answer.length 作为兜底


============================================================
# § 3. 【来源：待执行迁移计划.md】
============================================================

# 系统待执行迁移计划（持续更新）

> **创建时间**：2026-09-08
> **触发条件**：布局V2.0清理完成后执行
> **负责人**：前端架构师 + DOM渲染专家
> **状态追踪**：每次会话开始必须检查本文件

---

## 一、静态资源路径规范化（P1）

### 背景
前端存在大量相对路径引用（`data/offline/`、`static/`），隐式依赖后端配置，换环境即失效。已临时挂载`/data`过渡，需统一迁移到`/static/`绝对路径。

### 执行步骤
1. [x] 全局搜索所有相对路径静态资源引用（JS + HTML）✅ 2026-09-11完成，共62处
2. [x] 统一替换为`/static/`前缀绝对路径 ✅ 2026-09-11完成，共替换36处
   - `data/offline/xxx.json` → `/static/data/offline/xxx.json`
   - `static/xxx` → `/static/xxx`
3. [x] 移除后端`/data`临时挂载（backend/main.py L527-531已注释）✅ 2026-09-11完成
4. [x] 验证所有页面资源加载正常（Python语法通过、离线数据12文件完整、无残留/data引用）✅ 2026-09-11完成
5. [ ] APK/离线模式同步验证 ⏳ 待用户在实际设备验证
6. [x] 更新宪法37.7.2迁移状态 ✅ 2026-09-11完成，已标记为已完成

### 涉及文件（实际修改）
- `frontend/index.html`（34处static/ → /static/）
- `frontend/core/config.js`（1处basePath更新）
- `frontend/core/data-service.js`（1处basePath更新）
- `backend/main.py`（注释掉/data独立挂载）
- 注：app_v3已废弃不再被引用，无需修改

---

## 二、缺失离线数据文件补全（P2）

### 背景
api函数staticMap引用了12个离线JSON，但实际只有6个，缺失6个按需加载文件。

### 缺失文件清单
- [x] `data/offline/videos.json` ✅ 435条，593KB
- [x] `data/offline/materials.json` ✅ 48条，481KB
- [x] `data/offline/lectures.json` ✅ 454条，446KB
- [x] `data/offline/wrong_questions.json` ✅ 526条，944KB
- [x] `data/offline/exam_history.json` ✅ 22条，1137KB
- [x] `data/offline/syllabus.json` ✅ 137条，159KB

### 执行方案
- ✅ 已采用方案A：从shuili_exam.db数据库导出，全部完成
- manifest.json已同步更新，共12个数据文件

---

## 三、内联样式全面清理（进行中）

### 已完成
- [x] 学习看板布局对齐效果图
- [x] 题库管理renderQuestionManager（14处内联→类名）
- [x] 题库管理表格V2 CSS强力覆盖
- [x] 闪卡管理V2 CSS添加（ID选择器覆盖）
- [x] 思维导图管理V2 CSS添加（ID选择器覆盖）
- [x] 后端/data静态路径挂载修复
- [x] 自动化验证脚本建立（auto_validate.py）
- [x] 启动待办自动提醒（todo_reminder.py + start.bat）

### 待完成
- [ ] 闪卡管理renderFlashcard内联样式清理（100+处，代码治理阶段重构）
- [ ] 思维导图管理内联样式清理（代码治理阶段重构）
- [x] 视频播放页面V2 CSS覆盖
- [x] 智能笔记页面V2 CSS覆盖
- [x] 学习分析页面V2 CSS覆盖
- [ ] 其他页面内联样式清理（代码治理阶段统一重构）

---

## 四、数据治理（进行中）

### 已完成
- [x] 闪卡垃圾数据清理（223张）
- [x] 闪卡完全重复去重（3张）
- [x] 闪卡相似问答合并（24张）
- [x] 闪卡知识点补全（259张，0未分类）
- [x] 闪卡知识点颗粒度优化（288→197个，6大章节形成）
- [x] 题库移除一建混杂题目（25题）
- [x] 题库题型字段统一（单选→single，多选→multiple）
- [x] 题库2026年标记为模拟题（6年真题+1年模拟）
- [x] 思维导图移除一建导图（2个）
- [x] 思维导图补全空科目（1个）

### 待完成（AI深度工程）
- [ ] 知识点体系四级打通（知识点精讲→教材→大纲→真题）
- [ ] 思维导图问题版/答案版双版本生成（117个导图）
- [ ] 思维导图数据完善（节导图/章导图/科目导图三级体系）

---

## 五、代码治理（进行中 - 组合拳方案）

### 已完成（基础层）
- [x] Design Token体系完善（tokens.css，颜色/字号/间距/圆角/阴影/尺寸/过渡/z-index）
- [x] Design System组件库建立（components.css，10类组件，8.5KB）
- [x] 组件库引入index.html
- [x] 代码健康检查脚本建立（code_health_check.py，5维度检测+历史趋势）
- [x] 宪法第三十八章写入（新代码铁律+健康检查机制+Strangler Fig策略）

### 已完成（治理层）
- [x] 多端样式隔离（@media 46→25处，手机15个→mobile.css，平板3个→tablet.css）
- [x] style.css冗余清理（1057条/89KB → 896条/84KB，合并重复声明块）
- [x] 内联样式阶段一：CSS属性选择器批量覆盖（30个工具类+28条覆盖规则，0风险不改JS）
- [x] 内联样式阶段二：12个模块逐个迁移（renderSettings/renderMemoryTrain/renderDedupUI/renderExamResult/switchExamResultTab/startDailyFlashcardFromModal/matchChapter/downloadWatermarkResult/exportSyllabus/completeFormulaStep/laToggleSylAutoRefresh/exportCollect）
- [x] 内联样式阶段三：全量自动化迁移（重复>=2次+所有静态样式，共替换2947处）
- [x] components.css压缩优化（178.9→165.9KB）
- [x] 内联样式从3671→141个（-96.2%），健康评分65→85分
- [ ] 动态样式CSS变量桥接（141个，按需处理）
- [x] 组件复用率提升（443→456处）

---

## 六、宪法规则落实检查

### 已入宪
- [x] N.7.6 全面分析统一修改原则
- [x] 第三十七章 问题判定与预防体系
- [x] 37.7 静态资源路径规范

### 已落实 ✅ 2026-09-11全部完成
- [x] 静态检查脚本开发（tools/static_check.py，6维度检测）
- [x] 代码审查流程建立（docs/代码审查流程规范.md）
- [x] 问题知识库建立（data/问题知识库/issue_knowledge_base.json）
- [x] 每日代码健康检查报告（tools/daily_health_report.py，首次评分100/100优秀）

---


---

## 七、模块化功能迁移（2026-09-11新增）

### 背景
从app.js单体架构迁移到模块化架构（core/ + modules/）后，大量功能未迁移。旧文件1029个函数，新代码仅132个，缺失87%。

### 已完成
- [x] 文件库模块（FileLibraryModule）完整重写：真实数据加载、文件夹层级、批量选择、批量删除、重命名、上传、搜索
- [x] 高效文件检索工具（tools/fast_search.py）：毫秒级索引检索
- [x] 同步修改铁律入宪（宪法25.7）

### 待完成
- [ ] 视频模块文件夹功能迁移（14项：loadVideoFolders/openVideoFolder/deleteVideoFolder等）
- [ ] 讲义模块文件夹功能迁移（9项）
- [ ] 批量导入功能迁移（闪卡批量导入showBatchImport/confirmBatchImport）
- [ ] 多选/全选功能迁移（12项）
- [ ] 各模块deleteAll*清空功能迁移

## 执行记录

| 日期 | 完成项 | 执行人 |
|------|--------|--------|
| 2026-09-08 | 后端/data临时挂载添加 | 前端架构师 |
| 2026-09-08 | 题库管理内联样式清理 | 前端架构师 |
| 2026-09-08 | 闪卡管理V2 CSS添加 | 前端架构师 |
| 2026-09-08 | 宪法N.7.6/第三十七章/37.7入宪 | 全体专家 |
| 2026-09-11 | P1静态资源路径规范化完成（36处替换+/data挂载移除） | 前端架构师 |
| 2026-09-11 | P2离线数据文件补全完成（6个文件从数据库导出） | 数据专家 |
| 2026-09-11 | P3宪法规则落实完成（静态检查+代码审查+问题知识库+健康报告） | 全体专家 |
| 2026-09-11 | 高效检索工具fast_search.py建立 | 前端架构师 |
| 2026-09-11 | 同步修改铁律入宪（25.7） | 全体专家 |
| 2026-09-11 | FileLibraryModule完整重写（文件夹批量功能） | 前端架构师 |

---

**铁律：每次会话开始，必须先读取本文件，确认待办事项，再开始工作。**


============================================================
# § 4. 【来源：前端API新旧映射表.md】
============================================================

# 前端API新旧映射表

生成时间: 2026-09-12

## 映射规则

| 旧路径前缀 | 新模块前缀 | 说明 |
|-----------|-----------|------|
| /question | /qb | |
| /questions | /qb | |
| /flashcard | /mt | |
| /exam | /qb/exam | |
| /ai_unified | /ai | |
| /ai_scan | /ai/scan | |
| /ai_brain | /ai/brain | |
| /material | /resource | |
| /video | /resource/videos | |
| /lecture | /resource/lectures | |
| /mindmap | /mm | |
| /note | /common/notes | |
| /music | /common/music | |
| /tts | /common/tts | |
| /analytics | /common | |
| /system | /common | |
| /sync_unified | /sync | |
| /auth | /common/auth | |
| /sprint | /qb/sprint | |
| /syllabus | /resource/syllabi | |
| /knowledge_graph | /mm/kg | |
| /exam_analysis | /qb/exam-analysis | |

## 前端实际调用统计

共调用 28 个不同路径

| 旧路径 | 调用文件 |
|--------|----------|
| `/api/v1/ai/generate-flashcards` | modules\flashcard\flashcard.js |
| `/api/v1/ai/generate-mindmap` | modules\mindmap\mindmap.js |
| `/api/v1/ai/generate-mnemonic` | modules\flashcard\flashcard.js |
| `/api/v1/ai_brain/analyze-wrong-question` | modules\ai\ai-brain.js |
| `/api/v1/ai_brain/answer` | modules\ai\ai-brain.js |
| `/api/v1/ai_brain/compare-concepts` | modules\ai\ai-brain.js |
| `/api/v1/ai_brain/evaluate-question` | modules\ai\ai-brain.js |
| `/api/v1/ai_brain/explain-concept` | modules\ai\ai-brain.js |
| `/api/v1/ai_brain/extract-knowledge` | modules\ai\ai-brain.js |
| `/api/v1/ai_brain/generate-mnemonic` | modules\ai\ai-brain.js |
| `/api/v1/ai_brain/plan-learning` | modules\ai\ai-brain.js, modules\sprint\sprint.js |
| `/api/v1/ai_brain/status` | modules\admin\system-admin.js, modules\ai\ai-brain.js |
| `/api/v1/fl/` | modules\library\file-library.js |
| `/api/v1/fl/download/` | modules\library\file-library.js |
| `/api/v1/fl/files/batch-tag` | modules\library\file-library.js |
| `/api/v1/fl/list?page_size=1000` | modules\library\file-library.js |
| `/api/v1/material/upload_batch` | modules\library\file-library.js |
| `/api/v1/system/export-db` | modules\settings\settings.js |
| `/api/v1/video/delete_folder` | modules\video\video.js |
| `/api/v1/video/list?page_size=500` | modules\library\file-library.js, modules\video\video.js |
| `/api/v1/video/upload` | modules\video\video.js |
| `/api/v1/wrong/analyze` | modules\wrong\wrong-book.js |
| `/fl/` | modules\library\file-library.js |
| `/flashcard/create` | modules\flashcard\flashcard.js |
| `/static/data/AI分析报告.json?t=` | modules\admin\system-admin.js |
| `/static/data/优化建议.json?t=` | modules\admin\system-admin.js |
| `/static/data/数据库状态.json?t=` | modules\admin\system-admin.js |
| `/static/data/需求管理清单.json?t=` | modules\admin\system-admin.js |


============================================================
# § 5. 【来源：增强OCR存储设计文档_V1.0.md】
============================================================

# 增强OCR存储（EnhancedOCRStore）设计文档 V1.0

## 一、概述

### 1.1 定位
EnhancedOCRStore 是 PDFBaseProcessor（公共基座）的**存储增强层**，不重新实现预处理和识别，只负责存储、缓存、打标签和质量标记。

### 1.2 核心价值
- **一次预处理，多次使用**：避免重复OCR和重复打标签
- **存储纯净最优数据**：后面不需要每次都改
- **业务层快速提取**：通过标签快速筛选，不需要重新判断

### 1.3 与基座的关系
```
EnhancedOCRStore（存储增强层）
  ↓ 调用所有预处理和识别方法
PDFBaseProcessor（公共基座）
  - remove_watermark（去水印）
  - detect_header_footer（去页眉页脚）
  - deskew_page（倾斜矫正）
  - enhance_contrast（对比度增强）
  - binarize（二值化）
  - denoise（去噪）
  - ocr_area_after_keywords（OCR识别）
  - locate_keyword_area（关键词定位）
  - merge_to_long_image / merge_to_grid_image（合并）
```

---

## 二、完整17步流程（严格按顺序，不得乱序）

### 第一阶段：基础预处理（第1-8步）

#### 第1步：倾斜矫正
- **调用基座方法**：`deskew_page(page_idx)`
- **输入**：原始PDF单页
- **输出**：矫正后的图像 + 倾斜角度 + 矫正方法 + 置信度
- **细节**：
  - 逐页矫正
  - 倾斜角度>0.1度且<10度才矫正
  - 大角度（>10度）不矫正，标记异常
  - 记录倾斜角度到metadata

#### 第2步：位置矫正
- **调用基座方法**：`correct_position()`
- **输入**：倾斜矫正后的图像
- **输出**：位置矫正后的图像 + 平移量
- **细节**：
  - 检测页面靠左/靠右，自动平移居中
  - 平移不超过页宽10%，避免过度矫正
  - 平移超正常范围→判断是否扫描错误→AI图像修复补全→仍失败→标记异常
  - 异常提示："XX文件位置异常，请重新上传"

#### 第3步：去水印
- **调用基座方法**：`remove_watermark()`
- **输入**：位置矫正后的PDF
- **输出**：去水印后的PDF路径 + 去水印方法（keyword/frequency/inpaint等）
- **细节**：
  - 自动选择最优去水印方法
  - 记录去水印方法到metadata
  - 去水印后的PDF替换原PDF用于后续处理

#### 第4步：去页眉页脚
- **调用基座方法**：`detect_header_footer()`
- **输入**：去水印后的PDF
- **输出**：页眉y坐标 + 页脚y坐标
- **细节**：
  - 采样前10页检测页眉页脚坐标
  - 记录页眉页脚坐标到metadata
  - OCR结果中过滤掉页眉页脚区域的识别内容
  - 不裁剪页面（裁剪在业务层）

#### 第5步：对比度增强
- **调用基座方法**：`enhance_contrast(img)`
- **输入**：去页眉页脚后的OpenCV图像
- **输出**：增强后的图像
- **细节**：
  - 使用CLAHE（限制对比度自适应直方图均衡化）
  - clipLimit=2.0, tileGridSize=(8,8)
  - 在LAB色彩空间的L通道做增强

#### 第6步：二值化
- **调用基座方法**：`binarize(img)`
- **输入**：增强后的图像
- **输出**：二值化后的灰度图像
- **细节**：
  - 使用自适应阈值二值化
  - ADAPTIVE_THRESH_GAUSSIAN_C, blockSize=15, C=5
  - 二值化后转回BGR保存

#### 第7步：去噪
- **调用基座方法**：`denoise(img)`
- **输入**：二值化后的图像
- **输出**：去噪后的图像
- **细节**：
  - 中值滤波 + 形态学开运算
  - 去除小噪点（<3像素）
  - 保留文字边缘

#### 第8步：去杂裁剪
- **调用基座方法**：`crop_noise(img)`
- **输入**：去噪后的图像
- **输出**：去杂裁剪后的图像 + 内容边界坐标
- **细节**：
  - 内容边界检测算法，非固定值
  - 去除干扰区域（边缘噪声、空白边距）
  - 记录内容边界坐标到metadata
  - **【记录】预处理参数记录**（预处理全部完成，记录dpi/方法/角度/坐标等）

---

### 第二阶段：合并（第9步）

#### 第9步：合并（长图/拼图）
- **调用基座方法**：`merge_to_long_image()` 或 `merge_to_grid_image()`
- **输入**：多个PDF的预处理后图像
- **输出**：合并后的长图/拼图 + 页码编码映射
- **细节**：
  - 多PDF合并，带页码编码
  - 长图太高时OCR需分块，标记顺序
  - 拼图合并时记录每个块的页码和位置
  - 坐标映射：合并后坐标→原始PDF页码+坐标

---

### 第三阶段：三层识别（第10-12步）

#### 第10步：预识别
- **调用基座方法**：`pre_recognize()`
- **输入**：合并后的图像
- **输出**：标记的有效页/区域列表
- **细节**：
  - 低分辨率快速扫描
  - 标记有效页/区域（含关键词或内容的页）
  - 动态扫描范围（前5页+后5页，根据情况调整）
  - 不做精细OCR，只做标记

#### 第11步：精准识别
- **调用基座方法**：`precise_recognize()`
- **输入**：标记的有效页/区域
- **输出**：OCR结果列表
- **细节**：
  - 只对标记区域高分辨率OCR
  - 使用RapidOCR引擎
  - 记录每项的置信度
  - **规则打基础标签**（基于文本特征和位置特征，快、稳定）
    - 结构类：标题、副标题、正文、段落、列表项、序号、引用、代码块、分隔线
    - 位置类：页眉、页脚、页边距、左上角、右上角、左下角、右下角、居中、左对齐、右对齐
    - 内容类：图片、表格、公式、图表、注释、脚注、参考文献、目录、水印
    - 格式类：加粗、斜体、下划线、删除线、大字号、中字号、小字号、有颜色
    - 语义类：数字、字母、中文、英文、符号、标点、括号、引号

#### 第12步：验证识别（含存储功能）
- **调用基座方法**：`verify_recognize()`
- **输入**：精准识别的OCR结果
- **输出**：验证后的纯净OCR结果
- **细节**：
  - OCR+AI+PDF解析三者互相矫正
  - 文本归一化+编辑距离相似度验证
  - 短文本<10字直接通过
  - 修正错误，得到纯净结果
  - **AI增加复杂标签**（需要纯净OCR结果分析语义，准、灵活）
    - 语义理解：知识点、问题、答案、例题、练习题、总结、定义、原理、方法、公式
    - 层级关系：一级、二级、三级、四级、父节点、子节点、兄弟节点
    - 逻辑关系：并列、递进、总分、因果、对比、条件
    - 业务特定：思维导图节点/根/分支、题目题干/选项/答案/解析、卡片正面/背面/口诀
  - **质量标记**（低置信度区域）
    - OCR置信度<0.7 或 AI标签置信度<0.7
    - 记录：page、x、y、width、height、confidence、reason
    - 低置信度区域>30%时自动触发AI视觉二次识别
  - **图片和OCR同步存储**（存储验证后的纯净最优数据）
    - 纯净页面图像（PNG）
    - 验证后的纯净OCR结果（JSON，含text/confidence/x/y/width/height/labels）
    - 坐标映射（scale/offset_x/offset_y）
    - 所有标签（规则基础标签+AI复杂标签）
    - 质量标记（低置信度区域）
    - 预处理参数（第8步记录的）

---

### 第四阶段：后处理（第13-17步）

#### 第13步：节点拆分
- **调用基座方法**：`split_nodes()`
- **输入**：验证后的OCR结果
- **输出**：拆分后的节点列表
- **细节**：
  - 含问号的问题文本不拆分
  - 序号开头文本不拆分
  - 长文本按语义拆分

#### 第14步：去重（最后一步）
- **调用基座方法**：`deduplicate_items()`
- **输入**：拆分后的节点列表
- **输出**：去重后的节点列表
- **细节**：
  - 对验证后的精准结果去重
  - 不在中间去重，避免二次伤害
  - 去重方法：exact（精确匹配）/ semantic（语义匹配）/ knowledge_point（知识点匹配）

#### 第15步：动态分层
- **调用基座方法**：`dynamic_leveling()`
- **输入**：去重后的节点列表
- **输出**：分层结果 {level1, level2, level3}
- **细节**：
  - 百分位法（p25/p75）
  - 纵向列表判断
  - 空层自动调整
  - 问题文本、序号开头自动从一级降级到二级

#### 第16步：构建层级
- **调用基座方法**：`build_structure()`
- **输入**：分层结果
- **输出**：层级结构 {node, children: [{node, children: [...]}]}
- **细节**：
  - 先按y排序，再最近邻归属
  - 每个子节点只归最近父节点，不重复归属
  - 一级→二级→三级逐级归属

#### 第17步：生成输出
- **调用基座方法**：`_generate_markdown()`
- **输入**：层级结构
- **输出**：markdown格式字符串
- **细节**：
  - 层级映射：一级→####，二级→#####，三级→-
  - 支持问题版和答案版区分输出
  - 问题版：？后面无文字
  - 答案版：？后面有文字

---

### 2.2 打标签流程（2步：规则打基础标签 + AI增加复杂标签）

#### 第1步：规则打基础标签（快、稳定、可预设）
- **方法**：基于文本特征和位置特征的规则匹配
- **标签类型**：

**结构类标签**：
- `title`：标题（字号大于正文1.5倍 或 加粗且居中）
- `subtitle`：副标题（字号大于正文1.2倍 或 加粗）
- `body`：正文（普通字号，非加粗）
- `paragraph`：段落（连续多行正文）
- `list_item`：列表项（序号开头 或 项目符号开头）
- `sequence`：序号（"1." "2." "（1）" "①"等格式）
- `quote`：引用（缩进 或 引号开头）
- `code_block`：代码块（等宽字体 或 缩进>4空格）
- `divider`：分隔线（水平线）

**位置类标签**：
- `header`：页眉（y坐标 < 页眉y）
- `footer`：页脚（y坐标 > 页脚y）
- `margin`：页边距（x坐标 < 页边距 或 x坐标 > 页面宽度-页边距）
- `top_left`：左上角
- `top_right`：右上角
- `bottom_left`：左下角
- `bottom_right`：右下角
- `center`：居中（水平居中）
- `left_align`：左对齐
- `right_align`：右对齐

**内容类标签**：
- `image`：图片（OCR置信度低 或 区域内无文字）
- `table`：表格（含表格线 或 行列对齐）
- `formula`：公式（含数学符号 或 上下标）
- `chart`：图表（含坐标轴 或 图例）
- `annotation`：注释（上标 或 脚注标记）
- `footnote`：脚注（页面底部，含脚注标记）
- `reference`：参考文献（含[1]格式 或 页码引用）
- `toc`：目录（含前导符......）
- `watermark`：水印（重复文字 或 半透明文字）

**格式类标签**：
- `bold`：加粗
- `italic`：斜体
- `underline`：下划线
- `strikethrough`：删除线
- `large_font`：大字号（>正文1.5倍）
- `medium_font`：中字号（正文1.2-1.5倍）
- `small_font`：小字号（<正文0.8倍）
- `colored`：有颜色（非黑色）

**语义类标签**：
- `number`：数字（纯数字 或 含小数点）
- `letter`：字母（纯英文 或 拼音）
- `chinese`：中文
- `english`：英文
- `symbol`：符号（非文字非数字）
- `punctuation`：标点
- `bracket`：括号（() [] {} 【】）
- `quote_mark`：引号（"" '' 《》）

#### 第2步：AI分析增加复杂标签（准、灵活、自适应）
- **方法**：调用本地AI模型（qwen3-vl:4b）分析OCR结果
- **输入**：OCR结果 + 基础标签 + 页面图像
- **输出**：复杂标签列表
- **标签类型**：

**语义理解标签**：
- `knowledge_point`：知识点定义（"XX是指..." "XX包括..."等句式）
- `question`：问题（含问号 或 提问句式）
- `answer`：答案（问号后有文字 或 回答句式）
- `example`：例题（"例" "例题" "例如"开头）
- `exercise`：练习题（"练习" "习题" "思考题"开头）
- `summary`：总结（"综上" "总结" "小结"开头）
- `definition`：定义（"定义" "概念" "含义"开头）
- `principle`：原理（"原理" "机制" "原因"开头）
- `method`：方法（"方法" "步骤" "流程"开头）
- `formula_content`：公式内容（含计算公式）

**层级关系标签**：
- `level_1`：一级内容（章节标题级）
- `level_2`：二级内容（节标题级）
- `level_3`：三级内容（知识点级）
- `level_4`：四级内容（子知识点级）
- `parent`：父节点（有子节点的内容）
- `child`：子节点（有父节点的内容）
- `sibling`：兄弟节点（同级内容）

**逻辑关系标签**：
- `parallel`：并列关系（"第一...第二..." "一方面...另一方面..."）
- `progressive`：递进关系（"首先...其次...最后..."）
- `total_score`：总分关系（"包括以下几点" "分为..."）
- `cause_effect`：因果关系（"因为...所以..." "由于...导致..."）
- `contrast`：对比关系（"虽然...但是..." "与...不同"）
- `condition`：条件关系（"如果...就..." "只有...才..."）

**业务特定标签**（根据业务预设要求增加）：
- 思维导图业务：`mindmap_node`（思维导图节点）、`mindmap_root`（根节点）、`mindmap_branch`（分支）
- 题库业务：`question_stem`（题干）、`option_a`（选项A）、`option_b`（选项B）、`correct_answer`（正确答案）、`analysis`（解析）
- 闪卡业务：`card_front`（卡片正面）、`card_back`（卡片背面）、`mnemonic`（口诀）

- **细节**：
  - AI模型不锁死版本，自动选择最优模型
  - AI分析在规则基础上增加，不是从零开始
  - 低置信度标签标记出来，业务层可决定是否重新判断
  - 记录AI分析的模型版本和置信度到metadata

---

### 2.3 存储内容（每一项）

#### 2.3.1 纯净页面图像
- **格式**：PNG
- **命名**：`page_{page_idx}_processed.png`
- **内容**：去水印+去页眉页脚+倾斜矫正+增强+二值化+去噪后的完整页面
- **不裁剪**：裁剪在业务层

#### 2.3.2 纯净OCR结果
- **格式**：JSON列表
- **每项字段**：
  - `text`：识别文字
  - `confidence`：置信度（0-1）
  - `x`：左上角x坐标
  - `y`：左上角y坐标
  - `width`：宽度
  - `height`：高度
  - `page`：页码
  - `labels`：所有标签列表
- **已过滤**：页眉页脚区域、水印文字

#### 2.3.3 坐标映射
- **格式**：JSON
- **字段**：
  - `scale`：缩放比例（dpi/72）
  - `offset_x`：x偏移（倾斜矫正后的偏移）
  - `offset_y`：y偏移（倾斜矫正后的偏移）
- **用途**：原PDF坐标 → 预处理后图像坐标的转换

#### 2.3.4 所有标签
- **格式**：JSON字典
- **结构**：`{label_name: [item_indices]}`
- **示例**：
  ```json
  {
    "title": [0, 5, 10],
    "list_item": [1, 2, 3, 6, 7],
    "knowledge_point": [1, 6],
    "question": [2, 7],
    "level_1": [0, 5],
    "level_2": [1, 2, 3, 6, 7, 8]
  }
  ```

#### 2.3.5 质量标记
- **格式**：JSON列表
- **低置信度区域**：
  - `page`：页码
  - `x, y, width, height`：区域坐标
  - `confidence`：置信度
  - `reason`：原因（OCR置信度低 / AI标签置信度低 / 图像质量差）
- **异常标记**：
  - `page`：页码
  - `type`：异常类型（倾斜角度过大 / 页面空白 / 文字模糊 / 水印残留）
  - `description`：异常描述

#### 2.3.6 预处理参数
- **格式**：JSON字典
- **字段**：
  - `pdf_path`：原PDF路径
  - `pdf_hash`：PDF文件哈希（用于缓存版本校验）
  - `total_pages`：总页数
  - `dpi`：渲染DPI
  - `watermark_method`：去水印方法
  - `header_y`：页眉y坐标
  - `footer_y`：页脚y坐标
  - `deskew_angles`：每页倾斜角度
  - `enhance_method`：增强方法
  - `binarize_method`：二值化方法
  - `denoise_method`：去噪方法
  - `ocr_engine`：OCR引擎
  - `ai_model`：AI打标签模型
  - `timestamp`：预处理时间戳

---

### 2.4 机制

#### 2.4.1 缓存复用
- **类级缓存**：`_cache = {pdf_path: {page_idx: {...}}}`
- **缓存key**：PDF路径 + PDF文件哈希
- **版本校验**：PDF文件变更后（哈希变化），缓存自动失效
- **过期时间**：24小时自动清理
- **命中处理**：命中缓存时跳过预处理，直接用存储结果

#### 2.4.2 自动清理
- **触发时机**：识别完成后自动调用`cleanup()`
- **清理内容**：临时图像文件、临时OCR结果文件
- **保留内容**：缓存（24小时内有效）
- **手动清理**：可调用`cleanup(force=True)`强制清理所有缓存

#### 2.4.3 质量标记触发
- **低置信度区域**：OCR置信度<0.7 或 AI标签置信度<0.7
- **自动触发**：低置信度区域>30%时，自动触发AI视觉二次识别
- **用户提示**：低置信度区域>50%时，提示用户"XX页质量较差，建议重新上传"

---

## 三、业务层设计（多次使用，按需深加工）

### 3.1 通用业务流程

```
1. 初始化EnhancedOCRStore（命中缓存则跳过预处理）
2. 从存储提取完整纯净页面（图像+OCR+标签+坐标映射）
3. 按需裁剪（根据业务需求裁剪区域）
4. 用标签快速提取（筛选需要的内容）
5. 打业务标签（业务-specific的标签）
6. 深加工（分层、构建、生成输出）
7. 输出结果
8. 自动清理（保留缓存）
```

### 3.2 思维导图业务（MindmapRecognizerV2）

**预设标签要求**（之前已分析出来的业务标签）：
- 定位标签：`知识点清单`、`知识点清单总结`（关键词，用于定位裁剪区域）
- 内容标签：`知识点`（知识点定义）、`问题`（问题版内容）、`答案`（答案版内容）
- 结构标签：`章标题`、`节标题`、`知识点名称`
- 关系标签：`一级`、`二级`、`三级`（层级关系）

**业务流程**：
1. 从存储提取页面
2. 裁剪：定位标签（知识点清单/知识点清单总结）之后的区域
3. 标签快速提取：
   - `章标题` → 章节名称
   - `节标题` → 节名称
   - `知识点名称` → 知识点列表
   - `知识点` → 知识点定义内容
   - `问题` → 问题版导图内容
   - `答案` → 答案版导图内容
   - `一级/二级/三级` → 层级关系
4. 打业务标签：`mindmap_node`、`mindmap_root`、`mindmap_branch`
5. 深加工：动态分层 → 构建层级 → 生成markdown
6. 输出：问题版导图 + 答案版导图

### 3.3 题库业务（QuestionRecognizer）

**预设标签要求**（之前已分析出来的业务标签）：
- 定位标签：`单选题`、`多选题`、`判断题`（题型，用于定位）
- 内容标签：`题目`、`题干`、`选项A`、`选项B`、`选项C`、`选项D`、`正确答案`、`解析`
- 结构标签：`题号`、`章节`、`节`、`知识点`
- 关系标签：`题目-选项对应`、`题目-答案对应`、`题目-解析对应`

**业务流程**：
1. 从存储提取页面
2. 裁剪：题目区域（排除页眉页脚和广告）
3. 标签快速提取：
   - `题号` + `题干` → 题目序号和题干
   - `选项A/B/C/D` → 选项内容
   - `正确答案` → 答案
   - `解析` → 解析内容
   - `单选题/多选题/判断题` → 题型
   - `章节/节/知识点` → 题目归属
4. 打业务标签：`question_stem`、`option_a/b/c/d`、`correct_answer`、`analysis`
5. 深加工：题目结构化 → 选项分离 → 答案匹配 → 章节关联
6. 输出：结构化题目列表（含题型、题干、选项、答案、解析、章节）

### 3.4 闪卡业务（FlashcardGenerator）

**预设标签要求**（之前已分析出来的业务标签）：
- 定位标签：`知识点`、`考点`（用于定位）
- 内容标签：`知识点名称`、`知识点内容`、`记忆口诀`、`重点内容`、`历年真题`
- 结构标签：`章`、`节`、`目`、`专项类型`、`考点属性`、`考点关键词`、`核心说明`、`教材页码`
- 关系标签：`知识点-口诀对应`、`知识点-真题对应`、`章节-知识点归属`

**业务流程**：
1. 从存储提取页面
2. 裁剪：知识点定义区域
3. 标签快速提取：
   - `知识点名称` → 卡片正面（标题）
   - `知识点内容` + `核心说明` → 卡片背面（内容）
   - `记忆口诀` → 口诀字段
   - `重点内容` → 重点标记
   - `历年真题` → 真题关联
   - `章/节/目` → 归属结构
   - `考点属性/考点关键词` → 考点分类
   - `教材页码` → 教材关联
4. 打业务标签：`card_front`、`card_back`、`mnemonic`、`key_point`
5. 深加工：卡片生成 → 口诀匹配 → 知识点补全 → 章节排序
6. 输出：闪卡列表（含知识点名称、内容全称、口诀、章节、教材页码、真题）

---

## 四、核心原则（10条）

1. **存储层一次处理，业务层多次使用**：避免重复计算
2. **存储层不裁剪，裁剪在业务层**：不同业务需要不同裁剪区域
3. **通用标签存储层打，业务标签业务层打**：两层分离
4. **打标签分两步**：规则打基础标签（快）+ AI增加复杂标签（准）
5. **存储层打标签目的是让业务层快速提取**：不是为了业务逻辑
6. **业务层不需要每次重新打标签**：直接用存储的标签
7. **存储的是纯净最优基础数据**：后面不需要每次都改
8. **AI不锁死模型版本**：自动选择最优模型
9. **缓存有版本校验**：PDF变更后自动失效
10. **质量标记可追溯**：低置信度区域标记，可二次识别

---

## 五、与现有系统的集成

### 5.1 集成位置
- `backend/utils/enhanced_ocr_store.py`：EnhancedOCRStore类
- `backend/utils/pdf_base_processor.py`：PDFBaseProcessor基座（已有）
- `backend/utils/mindmap_recognizer_v2.py`：思维导图业务层（已有，需改造调用EnhancedOCRStore）

### 5.2 集成步骤
1. EnhancedOCRStore调用基座方法，不重新实现
2. MindmapRecognizerV2改造为调用EnhancedOCRStore
3. process_complete_pipeline增加增强OCR存储补强路径
4. 缓存复用机制集成到类级缓存
5. 自动清理机制集成到pipeline结束后

### 5.3 不影响现有功能
- 所有新增代码独立存在
- 现有方法不修改
- 增强OCR存储作为可选补强路径，默认关闭
- 主路径（原来的精准识别）保持不变

---

## 六、验收标准

1. ✅ 预处理8步严格按顺序执行
2. ✅ 打标签分两步（规则+AI）
3. ✅ 存储内容包含6项（图像/OCR/坐标/标签/质量/参数）
4. ✅ 缓存复用机制正常工作
5. ✅ 自动清理机制正常工作
6. ✅ 质量标记可追溯
7. ✅ 业务层通过标签快速提取
8. ✅ 不影响现有功能
9. ✅ 换教材换科目自动适配
10. ✅ 预处理一次，多次识别不需要重复预处理


============================================================
# § 6. 【来源：本地AI知识库_设计规范汇总.md】
============================================================

# 水利智学系统 - 本地AI知识库（设计规范汇总）

> 用途：给本地AI（Ollama qwen2.5:7b）分析代码时参考的知识库
> 包含所有核心设计规范、融合原则、功能清单、布局要求
> 每次分析代码前先读取本文件，确保分析符合设计规范

---

## 一、最高铁律（绝对不能违反）

### 1.1 布局锁死铁律
- ✅ 竖向导航栏：135px宽，绝对不动
- ✅ 顶部导航栏：48px高，绝对不动
- ✅ 底部状态栏：28px高，绝对不动
- ✅ 登录界面布局：已锁死，绝对不动
- ❌ 禁止随意修改布局，任何布局调整必须先征求用户同意

### 1.2 刷题逻辑铁律
- 单选题：选了就出解析（不需要点提交）
- 多选题：选完选项后，点提交按钮才出解析
- 四个选项 = 单选题，五个选项 = 多选题（铁律）
- 不需要答题卡（单题刷题模式）

### 1.3 科目简称铁律（全局统一）
- 一造管理
- 一造水利案例
- 一造计价
- 一建管理
- 一建法规
- 一建经济
- 一建水利
- 二建水利

### 1.4 新旧融合铁律
- 新布局不动，旧代码业务逻辑融合到新模块service里
- 前端API路径不变，零改动
- 新旧操作同一批表，零数据迁移
- 旧API兜底：新模块没写完的功能旧API继续跑

### 1.5 全面读取铁律
- 必须完整读取文件，从第1行读到[End of file.]
- 分批读取也要读完，没读完不准开始分析
- 禁止只读开头结尾就说"读完了"

### 1.6 工作铁律（2026-09-14根本解决方案）
**开工前必读：**
1. 先读本铁律，再开始工作
2. 代码分析用本地AI结果（本文件N.11节等），不自己重新分析
3. 只有发现本地AI没分析到的功能缺失，才独立分析
4. 每个bug先看旧代码怎么写的，直接搬，不自己猜
5. 功能缺失先对比旧代码有什么，新版缺什么，列清单
6. 测试必须点按钮、验证结果变化，不只是看页面能不能打开

**禁止行为：**
- 自己重新分析代码（浪费token）
- 自己猜bug原因（先看旧代码）
- 只看页面能不能打开就标记"通过"
- 不加新按钮、不改新架构（布局锁死）

**正确流程：**
1. 读铁律 → 2. 查本地AI分析结果 → 3. 找旧代码对应实现 → 4. 在新架构框架内融合功能 → 5. 点按钮验证 → 6. 更新断点记录

**"搬进去"的真正含义（2026-09-14用户强调）：**
- 不是复制粘贴旧代码到新文件
- 是在模块化、框架化、插件化的基础上搬代码
- 把旧代码的功能融合到新架构里
- 新架构是锁死的，功能填进去，不是把旧代码塞进去
- 要思考：旧代码这个功能属于哪个模块？用哪个组件？用哪个服务？
- 融合后要符合新架构的规范，不是新旧代码混在一起

---

## 二、系统架构（七层架构）

### 2.1 知识体系
- 6章27节104个L3知识点
- 按章节树形结构组织

### 2.2 题库体系
- 真题/模拟题/精题/练习题
- 三层去重机制：精确去重→相似度去重→语义去重
- 全局去重：任何文件都要去重

### 2.3 闪卡体系
- 概念卡/公式卡/口诀卡/对比卡/易错点卡/流程卡
- SM-2算法：0-5分级，计算间隔、ease_factor、掌握度
- 掌握度 = 正确率*0.6 + 用时效率*0.4

### 2.4 思维导图体系
- 节导图→章导图→科目导图，三级结构
- 问题版/答案版双版本模式
- 识别生成思路：PDF页面截图→版面坐标切块→多模态识别

### 2.5 学习资料库
- 全部文件→大纲/教材→视频讲义，三层架构
- 教材文件存储：文件名、大小、删除按钮、双击在线查看

### 2.6 AI识别体系
- PDF预处理：17步完整流程
- OCR识别：MinerU/PaddleOCR/PaddleLaTeX/TableMaster/Ollama VL
- 增强OCR存储：EnhancedOCRStore，打标签机制

### 2.7 数据治理体系
- 去杂5层流程：水印去除→页眉页脚去除→文字去杂→表格去杂→版面去杂
- 质量监控：五层存储架构（L0-L4）
- 备份恢复：每小时自动备份，保留30天

---

## 三、模块化架构（积木式）

### 3.1 目录结构
```
backend/
├── api/v1/          # 旧路由（保留，逐步搬迁）
├── modules/         # 新业务模块
│   ├── qb/          # 题库管理
│   ├── mt/          # 记忆训练（闪卡）
│   ├── mm/          # 思维导图
│   ├── ai/          # AI能力
│   ├── sync/        # 同步模块
│   ├── resource/    # 资源管理（教材/视频/讲义）
│   └── common/      # 公共通用
├── core/            # 核心配置
├── models/          # 数据模型
├── crud/            # 数据库操作
└── main.py          # 入口

frontend/
├── core/            # 核心框架（不动）
├── modules/         # 功能模块（积木）
├── css/             # 样式文件
└── index.html       # 主入口
```

### 3.2 模块通信规则
- 模块间通过事件总线通信，不直接调用
- 每个模块CSS加前缀，禁止全局样式
- 模块只能操作自己的container，禁止操作其他模块DOM

### 3.3 路由规范
- routes.py：只做参数接收和响应返回
- service.py：业务逻辑和数据库操作
- 蓝图前缀：/api/qb、/api/mt、/api/mm、/api/ai、/api/sync、/api/resource、/api/common

---

## 四、布局规范

### 4.1 三层布局结构
```
┌─────────────────────────────────────────┐
│  content-header（标题+筛选栏，固定不滚动）│
├─────────────────────────────────────────┤
│  content-body（内容区，可滚动）          │
├─────────────────────────────────────────┤
│  分页栏（固定底部，不滚动）              │
└─────────────────────────────────────────┘
```

### 4.2 Flex布局铁律
- 外层容器：display:flex;flex-direction:column;height:100%
- header/footer：flex-shrink:0（不压缩）
- content-body：flex:1;overflow-y:auto;min-height:0（可滚动）

### 4.3 表格规范
- 单个table，包含thead和tbody
- 表头放在content-header区域，固定不滚动
- 行高：32px（padding:7px 6px）
- 斑马纹：偶数行#f8fafc，奇数行#ffffff

### 4.4 按钮规范
- 大按钮：8px 16px padding，14px字体（主操作）
- 中按钮：5px 10px padding，13px字体（普通按钮）
- 小按钮：2px 8px padding，12px字体（表格内操作）
- 主按钮：btn-primary（蓝色）
- 次按钮：btn-outline（边框）
- 危险按钮：btn-danger（红色）

### 4.5 颜色规范
- 主色：#2563eb（蓝色）
- 成功：#16a34a（绿色）
- 警告：#d97706（橙色）
- 危险：#dc2626（红色）
- 标题：#1e293b
- 正文：#334155
- 次要：#64748b
- 边框：#e2e8f0
- 背景：#f8fafc

---

## 五、代码质量规范

### 5.1 代码审查11项清单
1. 功能完整性
2. 异常处理（禁止裸except）
3. 日志记录（禁止print，必须用logger）
4. 性能考虑（避免N+1查询）
5. 安全考虑（SQL参数化、密码加密）
6. 可维护性（函数不超过50行）
7. 兼容性（数据库迁移、API向后兼容）
8. 可测试性（业务逻辑与UI分离）
9. 多端适配（响应式、触控优化）
10. 离线兼容（核心功能离线可用）
11. 数据安全（修改前自动备份）

### 5.2 后端规范
- 路由只做参数接收和响应返回
- 业务逻辑放在service.py
- 日志必须携带模块标识：[qb]、[mt]、[mm]等
- 异常必须记录日志，不能静默处理

### 5.3 前端规范
- 模块通过事件总线通信
- DOM-id必须带模块缩写前缀
- 状态管理用统一Store
- 禁止跨模块直接调用函数

---

## 六、新旧融合现状

### 6.1 代码量统计
- 旧API（api/v1）：11967行，35个文件
- 新模块（modules）：18790行，54个文件
- core目录：3323行，11个文件
- utils目录：23972行，53个文件
- 总计：约59474行，157个文件

### 6.2 融合率现状
- 真实融合率：38%（还需融合62%）
- 已融合：题库基本功能、教材管理、视频讲义管理
- 待融合：认证域、AI对话、SM-2算法完整实现、掌握度分析、薄弱点推荐等

### 6.3 优先级
- P0：核心功能（刷题逻辑、闪卡SM-2、认证系统）
- P1：AI功能（AI解题、智能答疑、知识点提取）
- P2：数据治理（去重、质量监控、OCR全量扫描）
- P3：性能优化（缓存、索引、懒加载）

---

## 七、核心算法

### 7.1 AI薄弱点优先级分数
```
分数 = 错误次数*3 + 逾期天数*2 + 最近错误权重(max(0,7-天数)*2) - 复习次数*0.5
```

### 7.2 掌握度计算
```
掌握度 = 正确率*0.6 + 用时效率*0.4
用时效率 = max(0, min(1, 1 - (平均用时 - 30) / 120))
掌握等级：≥80优秀，≥60良好，≥40一般，<40薄弱
```

### 7.3 SM-2算法（闪卡间隔重复）
- 0-5分级评价
- 计算下次复习间隔
- 更新ease_factor
- 更新interval_days

---

## 八、AI模型配置

### 8.1 Ollama本地服务
- 服务地址：http://localhost:11434
- 已安装模型：
  - qwen2.5:7b（文本对话）
  - bge-m3:latest（embedding向量）
  - qwen3-vl:4b（视觉识别）
  - deepseek-r1:7b（推理）
- 模型存储路径：D:\AI\ollama_models

### 8.2 AI使用场景
- AI拍照解题：本地题库匹配→相关题目检索→AI增强解析
- AI口诀生成：从知识点生成记忆口诀
- AI知识点提取：从PDF/教材提取知识点
- AI学习计划：根据错题和闪卡生成复习计划

---

## 九、用户偏好（必须遵守）

1. **锁死规则**：用户说"锁死"=该功能不可修改，除非新指令
2. **不要边做边改**：先形成完整方案，再执行
3. **不要说着说着就忘记**：所有分析必须写入融合总方案文档
4. **不要只读几页就停**：要完整读完整个文件
5. **不要停下来问"要继续吗"**：直接继续
6. **不要每次改一点就重启一次**：积攒完再重启
7. **不要自己造轮子**：参考市面上成熟刷题APP逻辑
8. **不要改科目名称为官方全称**：用户要简称
9. **不要改变新布局**：布局锁死不动
10. **不要只是建个名称就不动了**：要把能做的做完

---

## 十、使用说明

本文件是给本地AI分析代码时参考的知识库。每次分析代码前，先读取本文件，确保：
1. 不违反最高铁律
2. 符合模块化架构
3. 遵守布局规范
4. 满足用户偏好

分析时如果发现代码违反以上任何一条，必须标记出来并给出修改建议。

---

**最后更新：2026-09-12**
**版本：V1.0**
**用途：本地AI代码分析参考知识库**


============================================================
# § 7. 【来源：模块化插件化底座设计方案_V1.0.md】
============================================================

# 水利智学系统 - 模块化插件化底座设计方案 V1.0

> 生成时间：2026-09-13
> 状态：底座设计稿，待总架构师拍板后逐轮执行
> 前置依据：总方案_专家团队工作框架.md / 系统模块化融合方案.md / 融合总方案_长期参考.md
> 核心目标：把 main.py 里硬编码的路由注册，改造为「声明式清单 + 自动发现 + 按模块隔离加载」的插件底座。业务代码、布局、API 路径、旧API 一律不动。

---

## 一、现状诊断（读完总方案 + main.py + modules/ 实际盘点后）

### 1.1 当前注册方式（痛点所在）

`backend/main.py` 现状：

| 位置 | 现状 | 问题 |
|------|------|------|
| 第33–49行 | 一个大 `try` 块硬编码 import 12 个新模块路由 | 任意一个模块 import 失败 → `MODULES_AVAILABLE=False` → **整批12个模块全部不加载**，无单模块隔离 |
| 第482–495行 | `if MODULES_AVAILABLE:` 硬编码 12 行 `app.include_router(...)` | 新增一个模块/子路由要改这里 + 上面 import 区，两处手工同步 |
| 第445–479行 | 33 个旧API文件硬编码 import + include | 旧API兜底正常，但同样是硬编码 |
| 第23行 | `from modules.common.file_library_model import FileLibrary`（为建表） | 模型注册也写死在入口 |

**结论**：现在是「7个域已分目录」，但**还不是插件**——注册动作全部堆在 main.py，新增/禁用/排错都要动入口文件，且一损俱损。

### 1.2 模块目录现状（modules/，共 50 个 py 文件）

| 域 | 路由文件 | 业务/算法文件 | 现有前缀 |
|----|---------|--------------|---------|
| qb | routes, quality_routes | service, irt_algorithm, quality_manager | /api/qb |
| mt | routes, category_routes | service, fsrs, bkt, ability_radar, learning_path, category_manager | /api/mt |
| mm | routes | service | /api/mm |
| ai | routes, manager_routes, evaluation_routes, stream_routes | service, stream_service, ai_manager, case_grader, effect_evaluator, pdf_vl_recognizer | /api/ai |
| sync | routes | service | /api/sync |
| resource | routes | service, pdf_parse_cache | /api/resource |
| common | routes, data_routes, monitor_routes, shutdown_routes, file_library_routes, fl_bridge_routes | service, data_security, file_library_service, preprocess_service, question_importer, service_monitor, graceful_shutdown, logger, response | /api/common、/api/v1/fl、/api/v1/fl_bridge |

### 1.3 铁律继承（必须无条件保留）

1. 布局锁死：前端竖向导航/顶部/底部/登录页不动。
2. API 路径不变：新插件注册的 prefix 与现状逐一对应，前端零感知。
3. 零数据迁移：不碰 38+ 张表。
4. 旧API兜底：旧 33 个文件保持原样挂载，新插件加载失败自动降级到旧路由。
5. 模块间禁止跨域 import service：插件化后仍只走 API / 事件总线。
6. 所有分析落文件，不口头记忆。

---

## 二、插件化底座四层设计

```
┌─────────────────────────────────────────────────────────┐
│ L4  插件清单层  modules/<域>/plugin.json                 │
│     声明式：name/version/enabled/prefix/routers/depends   │
├─────────────────────────────────────────────────────────┤
│ L3  插件注册表  core/plugin_registry.py（单例）           │
│     登记：name→{status, routers, endpoints, loaded_at}   │
├─────────────────────────────────────────────────────────┤
│ L2  插件加载器  core/plugin_loader.py                    │
│     scan→load(单模块try)→include_router→登记             │
│     单模块失败只记日志，不影响其他模块                     │
├─────────────────────────────────────────────────────────┤
│ L1  入口瘦身    main.py                                   │
│     删除硬编码 import/include，改为一行 load_all(app)     │
│     旧API 33 个文件保持不动                               │
└─────────────────────────────────────────────────────────┘
```

### 2.1 L4 插件清单协议（plugin.json）

每个业务域目录下放一份 `plugin.json`，示例 `modules/qb/plugin.json`：

```json
{
  "name": "qb",
  "version": "1.0.0",
  "enabled": true,
  "depends_on": [],
  "models": ["modules.qb.service"],
  "routers": [
    {"import": "modules.qb.routes:router", "prefix": "/api/qb"},
    {"import": "modules.qb.quality_routes:router", "prefix": "/api/qb/quality"}
  ]
}
```

要点：
- `enabled=false` 即从配置层禁用，无需改代码。
- `routers[].import` 用 `模块路径:属性名` 写法，加载器统一 `importlib` 解析。
- `models` 列出需要在启动期 import 以建表/注册模型的模块（替代 main.py 第23行那种手写 import）。
- `depends_on` 预留跨域依赖声明，加载器按拓扑序加载（本期只校验存在性，不真做跨域调用）。

### 2.2 L2 插件加载器（core/plugin_loader.py，新建）

伪契约（不是最终代码，先对齐接口）：

```python
# 对外只暴露三个函数
def scan_plugins(modules_dir: str) -> list[dict]: ...        # 扫所有 plugin.json
def load_plugin(app, manifest: dict) -> dict:                # 单模块隔离加载
    # try: importlib解析 routers → app.include_router → 登记
    # except Exception: 记日志，return {"status":"failed", ...}
def load_all_plugins(app, modules_dir=None) -> dict:         # main.py 调用
    # 返回 {name: status} 汇总，打日志
```

关键行为：
- **逐模块 try/except**：qb 崩了，mt/mm/ai 照常加载。这是对现状「一损俱损」的直接修复。
- **加载失败不抛到 main**：只记 `logger.error("[插件] qb 加载失败: ...")`，进程继续。
- **启动日志**：加载完打印 `[插件] 已加载 7/7: qb✅ mt✅ mm✅ ai✅ sync✅ resource✅ common✅`，失败的标 ❌。
- 不引入第三方插件框架，纯 stdlib（`importlib` + `json`），零新增依赖。

### 2.3 L3 插件注册表（core/plugin_registry.py，新建，轻量单例）

- 进程内字典：`{"qb": {"version":..., "enabled":..., "routers_loaded": 2, "status": "ok"}}`。
- 后续轮次再开 `GET /api/common/plugins` 管理端点；本期先只做内存登记 + 日志，不暴露 HTTP。

### 2.4 L1 main.py 瘦身（变更片段，等拍板后再落地）

**删除**：第33–49行整段硬编码 import 块。
**删除**：第482–495行整段 `if MODULES_AVAILABLE:` 注册块。
**替换为**（插入到原第482行位置）：

```python
# ========== 新架构模块：插件化自动注册 ==========
from core.plugin_loader import load_all_plugins
_plugin_summary = load_all_plugins(app)
logger.info(f"[插件] 加载汇总: {_plugin_summary}")
```

旧API第445–479行**保持原样**，作为兜底。

---

## 三、逐轮迭代计划（底座先行，一轮一交付）

| 轮次 | 范围 | 变更文件 | 验收标准 | 是否动业务 |
|------|------|---------|---------|-----------|
| **R1 底座** | 新建 plugin_loader + registry；写 7 份 plugin.json；main.py 替换为 load_all | 新增 `core/plugin_loader.py`、`core/plugin_registry.py`、7 个 `modules/*/plugin.json`；改 `main.py` 两处 | 后端启动日志出现 `[插件] 已加载 7/7`；访问任一现有 `/api/qb/*`、`/api/mt/*` 正常；故意改错一个模块语法，重启后其余6个仍加载 | 否，纯骨架 |
| R2 旧API插件化 | 把 33 个旧API也写成 manifest（不改其代码，只登记） | 新增 `legacy_plugins.json`；loader 支持读旧清单 | 旧 `/api/v1/question/*` 等全部可用；日志里旧/新分别计数 | 否 |
| R3 运行时开关 | 配置文件里 enabled 字段生效；`GET /api/common/plugins` 查状态 | `core/plugin_loader.py` + `modules/common/routes.py` | 把某插件 enabled=false，重启后该前缀 404，其他正常 | 否 |
| R4 事件总线 | 把「模块间禁止跨域 import」落地为事件总线（订阅/发布） | `core/event_bus.py`；先空跑 | qb 答题后可异步通知 mt 复习队列，而不 import mt.service | 极小 |

**本期只做 R1。** R2–R4 等 R1 验证通过、用户「锁死」后再启动。

---

## 四、风险与回退

| 风险 | 应对 |
|------|------|
| 插件化后某路由漏挂 | plugin.json 的 routers 清单与现状 grep 结果逐一比对（已在 1.2 节列全），R1 验收时逐个端点冒烟 |
| 建表时机变化（main.py 第23行 FileLibrary） | 纳入 plugin.json 的 `models` 字段，loader 在 include 之前先 import models，保证 `Base.metadata.create_all` 能看到 |
| 回退 | 保留原硬编码块为注释，或用 git 回滚；不删旧API |
| 配置文件路径 | 插件清单跟着模块走（modules/qb/plugin.json），不另起全局配置，避免多源不一致 |

---

## 五、待总架构师拍板的三个点

1. **插件清单放模块目录**（`modules/qb/plugin.json`）还是集中放 `core/plugins_manifest/`？倾向前者，随模块走。
2. **R1 是否同时把 common 下 7 个 *_routes 拆成独立插件**，还是先只按「域」粒度一个 manifest？倾向先按域，R2 再细化。
3. **是否需要插件启停的 HTTP 接口**留到 R3，本期不做。

> 用户用「锁死」确认本方案后，即按 R1 开始落地，只输出变更片段并标注文件名与插入位置。



======================================================================
# 附录6 【来源：docs工作文档总集.md】
======================================================================

# 🗂️ docs 工作文档总集（现行唯一）
> 版本 V1.0 ｜ 2026-09-13 ｜ 由 docs/ 目录19份合并而成，每份标注来源，原文件已归档。
> 含：分析报告/计划清单/质量安全/代码规范/部署手册。

## 📑 目录
1. 【来源：DOM_ID编码规范.md】
2. 【来源：部署指南.md】
3. 【来源：测试用例集_V1.0.md】
4. 【来源：代码架构债务专项迁移方案_V1.0.md】
5. 【来源：代码迁移分析师_需求登记.md】
6. 【来源：代码审查流程规范.md】
7. 【来源：功能缺失补全操作指导手册.md】
8. 【来源：功能融合计划.md】
9. 【来源：模块化拆分缺失功能完整清单.md】
10. 【来源：全局状态清单.md】
11. 【来源：全面代码对比报告.md】
12. 【来源：设计规范_V2.0.md】
13. 【来源：设计决策记录.md】
14. 【来源：神经末梢级深度分析报告.md】
15. 【来源：数据库表清理计划.md】
16. 【来源：系统漏洞分析报告.md】
17. 【来源：应急处理手册.md】
18. 【来源：优化建议报告.md】
19. 【来源：质量保障体系.md】

---



============================================================
# § 1. 【来源：DOM_ID编码规范.md】
============================================================

# DOM ID 编码规范（P2-02）

> 依据《系统设计宪法V2.6》架构合规章节
> 所有新增DOM元素必须遵守此规范，旧代码逐步整改

## 一、命名规则

### 1.1 格式
```
{模块名}_{功能描述}_{序号(可选)}
```

### 1.2 模块前缀清单

| 模块名 | 前缀 | 示例 |
|--------|------|------|
| 题库管理 | qb_ | qb_question_list, qb_edit_modal |
| 记忆闪卡 | mt_ | mt_card_list, mt_review_modal |
| 思维导图 | mm_ | mm_canvas, mm_node_edit |
| 学习资料库 | fl_ | fl_file_list, fl_upload_modal |
| 同步管理 | sync_ | sync_status_bar, sync_log_panel |
| AI能力 | ai_ | ai_recognize_btn, ai_progress_bar |
| 知识库 | kb_ | kb_note_list, kb_editor |
| 通用工具 | common_ | common_toast_container, common_loading_mask |
| 应用主框架 | app_ | app_sidebar, app_header, app_main_content |

### 1.3 禁止事项
- ❌ 禁止使用无意义ID：id="div1", id="btn1"
- ❌ 禁止使用纯中文ID
- ❌ 禁止使用驼峰命名：id="questionList"（用下划线）
- ❌ 禁止跨模块复用ID
- ❌ 禁止动态生成无规律ID

## 二、class命名规则

- 使用Tailwind CSS工具类为主
- 自定义class使用`{模块}-{功能}`格式：`qb-card`, `mt-badge`
- 状态类使用`is-{状态}`：`is-active`, `is-disabled`, `is-loading`

## 三、data属性规范

- 业务数据使用`data-{模块}-{字段}`：`data-qb-id`, `data-mt-card-id`
- 禁止在data属性中存储敏感信息

## 四、整改清单（存量代码）

以下模块存在大量无前缀ID，需逐步整改：
- [ ] app.js（25603行）- 主框架
- [ ] resource.js（10668行）- 资源管理
- [ ] 各业务页面弹窗

## 五、检查方法

控制台执行以下命令检查无前缀ID：
```javascript
// 查找不符合规范的ID（不含下划线的短ID）
const badIds = Array.from(document.querySelectorAll('[id]'))
  .map(el => el.id)
  .filter(id => !id.includes('_') && id.length < 20);
console.log('需整改的ID:', badIds);
```


============================================================
# § 2. 【来源：部署指南.md】
============================================================

# 水利智学系统 - 部署指南

## 系统要求
- Python 3.9+
- Windows 10/11（推荐）
- 内存：最低4GB，推荐8GB+
- 磁盘：最低2GB可用空间

## 快速部署

### 方式一：一键部署（推荐）
1. 双击 `deploy.bat`
2. 等待部署完成
3. 双击 `start.bat` 启动服务
4. 浏览器访问 http://localhost:8000

### 方式二：手动部署
```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动服务
cd backend
python main.py
```

## 启动方式

| 脚本 | 说明 | 适用场景 |
|------|------|----------|
| start.bat | Watchdog守护模式，崩溃自动重启 | 日常使用、生产环境 |
| start_simple.bat | 直接启动，无守护 | 开发调试、快速测试 |
| deploy.bat | 一键部署，检查环境 | 首次部署、环境检查 |

## 访问地址

- 本机访问：http://localhost:8000
- 局域网访问：http://[本机IP]:8000
- 外网访问：需配置Tailscale等内网穿透工具

## 默认账号
- 用户名：admin
- 密码：admin123
- 首次登录后请立即修改密码

## 目录结构

```
水利智学系统/
├── backend/              # 后端代码
│   ├── main.py          # 主程序入口
│   ├── api/v1/          # API接口
│   ├── core/            # 核心配置
│   ├── models/          # 数据模型
│   ├── utils/           # 工具模块
│   ├── data/            # 数据目录
│   │   ├── shuili_exam.db  # 数据库
│   │   └── logs/        # 日志文件
│   └── tests/           # 单元测试
├── frontend/             # 前端代码
│   ├── index.html       # 主页面
│   ├── js/              # JavaScript
│   ├── css/             # 样式
│   ├── lib/             # 第三方库
│   └── sw.js            # Service Worker
├── uploads/              # 上传文件
├── backups/              # 备份文件
├── docs/                 # 文档
├── requirements.txt      # Python依赖
├── start.bat             # 启动脚本（守护模式）
├── start_simple.bat      # 启动脚本（直接启动）
├── deploy.bat            # 部署脚本
├── watchdog_plus.py      # Watchdog守护进程
└── README.md             # 说明文档
```

## 数据备份

### 自动备份
- 启动时：自动创建增量备份
- 关闭时：自动创建全量备份
- 每天凌晨2点：自动全量备份
- 保留策略：日7 + 周4 + 月3 + 快照永久

### 手动备份
访问系统 → 系统设置 → 备份管理 → 创建备份

### 备份内容
- ✅ 后端代码
- ✅ 前端代码
- ✅ 数据库
- ✅ 配置文件
- ✅ 日志文件
- ❌ 上传文件（可选）

## 常见问题

### Q: 端口8000被占用怎么办？
A: Watchdog会自动释放端口，或手动执行：
```bash
netstat -ano | findstr :8000
taskkill /PID [进程ID] /F
```

### Q: 服务崩溃怎么办？
A: 使用start.bat启动，Watchdog会自动重启服务。

### Q: 如何查看日志？
A: 日志文件位于 `backend/data/logs/` 目录。

### Q: 如何更新系统？
A: 1. 备份当前版本 2. 替换代码文件 3. 重启服务 4. 验证功能

## 技术支持
- 版本：V4.5.15
- 技术栈：Python + FastAPI + SQLite + Tailwind CSS


============================================================
# § 3. 【来源：测试用例集_V1.0.md】
============================================================

# 水利智学系统 - 关键场景测试用例集

> 版本: V1.0 | 日期: 2026-09-06 | 依据: 《系统设计宪法V2.6》第18章真实运行验证铁律

## 三级验证体系

- **语法层**: node --check / py_compile，无语法错误
- **运行层**: 浏览器控制台无阻断Error，核心全局对象可获取
- **业务层**: 完整业务流程跑通，UI与数据库一致

---

## 一、语法层测试用例

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| S-01 | 前端JS语法检查 | 对所有.js文件执行node --check | 全部通过，无SyntaxError | P0 |
| S-02 | 后端Python语法检查 | 对所有.py文件执行py_compile | 全部通过，无语法错误 | P0 |
| S-03 | index.html内联JS检查 | 提取内联script片段执行node --check | 无Unexpected token错误 | P0 |
| S-04 | JSON配置文件校验 | exam_config.json/manifest.json解析 | 格式正确，无解析错误 | P1 |

---

## 二、运行层测试用例

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| R-01 | 页面正常加载 | 访问http://localhost:8000/ | 200状态，页面渲染正常，无白屏 | P0 |
| R-02 | 控制台无阻断Error | 打开DevTools Console | 无红色Uncaught Error/ReferenceError | P0 |
| R-03 | 核心全局对象检查 | 控制台执行window.store/window.api/window.logger | 均返回对象，非undefined | P0 |
| R-04 | Store大小写兼容 | 控制台执行window.store | 返回对象（非大写Store） | P0 |
| R-05 | APP_VERSION兜底 | 控制台执行window.APP_VERSION | 返回字符串，非undefined | P0 |
| R-06 | ServiceWorker无残留 | Application→Service Workers | 无激活的SW，/sw.js返回自毁脚本 | P0 |
| R-07 | manifest.js无404 | Network面板筛选manifest.js | 无404错误 | P1 |
| R-08 | sourcemap无404 | Network面板筛选.map | 无sourcemap 404 | P1 |
| R-09 | 模块健康检查 | 控制台执行systemHealthCheck() | 返回各模块状态汇总 | P1 |
| R-10 | eventBus健康检查 | 控制台执行window.eventBus.healthCheck() | 返回状态对象 | P1 |
| R-11 | core脚本缺失降级 | 模拟window.api=null，刷新页面 | 模块打印降级日志，不整体白屏 | P1 |
| R-12 | 深度健康探针 | 访问/api/health | 返回database/disk/ollama组件状态 | P1 |
| R-13 | console-interceptor就绪 | 控制台执行window.__consoleInterceptorReady | 返回true | P2 |

---

## 三、业务层测试用例

### 3.1 登录与科目选择

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| B-01 | 登录流程 | 输入用户名密码登录 | 成功进入主界面 | P0 |
| B-02 | 大专业选择 | 选择大专业（如一造） | 显示第二步骤科目选择 | P0 |
| B-03 | 科目选择 | 选择具体科目（如一造管理） | 进入对应科目学习界面 | P0 |
| B-04 | 科目简称显示 | 登录后顶部显示科目 | 显示简称（一造管理），非全称 | P1 |

### 3.2 题库管理

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| B-10 | 题目列表加载 | 进入题库管理 | 题目列表正常显示，分页正常 | P0 |
| B-11 | 新增题目 | 填写题目信息保存 | 保存成功，列表刷新，数据库有记录 | P0 |
| B-12 | 编辑题目 | 修改题目信息保存 | 保存成功，UI与数据库一致 | P0 |
| B-13 | 删除题目 | 删除单条题目 | 删除成功，数据库is_deleted=1 | P1 |
| B-14 | 批量删除 | 勾选多条删除 | 全部删除成功 | P1 |
| B-15 | 题目搜索 | 输入关键词搜索 | 返回匹配结果 | P1 |
| B-16 | 题库去重 | 导入重复题目 | 题干+选项+答案+解析一致时自动去重 | P1 |

### 3.3 闪卡管理

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| B-20 | 闪卡列表加载 | 进入记忆闪卡 | 闪卡列表正常显示 | P0 |
| B-21 | 新增闪卡 | 填写正反面保存 | 保存成功 | P0 |
| B-22 | 批量导入闪卡 | 导入10条闪卡 | 全部成功或全部回滚，无部分成功 | P0 |
| B-23 | 闪卡复习 | 执行复习流程 | 复习间隔按SM-2算法更新 | P1 |
| B-24 | 闪卡去重 | 导入重复闪卡 | front+back一致时自动去重 | P1 |

### 3.4 学习资料库

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| B-30 | 文件列表加载 | 进入学习资料库 | 文件列表正常显示 | P0 |
| B-31 | 单文件上传 | 上传PDF文件 | 上传成功，显示在列表中 | P0 |
| B-32 | 文件夹批量导入 | 选择文件夹导入 | 按文件夹层次显示，进度条准确 | P0 |
| B-33 | 文件去重 | 上传重复文件 | 标记重复，不重复保存 | P1 |
| B-34 | 标签编辑 | 单条/批量修改标签 | 保存成功，文件夹内单条同步修改 | P0 |
| B-35 | 识别题库 | 选择PDF识别题库 | 返回识别结果，支持人工确认 | P1 |
| B-36 | 生成闪卡 | 选择PDF生成闪卡 | 生成闪卡到闪卡库 | P1 |
| B-37 | 生成导图 | 选择PDF生成思维导图 | 生成思维导图 | P1 |
| B-38 | PDF预览 | 点击PDF文件预览 | PDF查看器正常打开 | P1 |

### 3.5 思维导图

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| B-40 | 导图列表加载 | 进入思维导图 | 导图列表正常显示 | P0 |
| B-41 | 导图查看 | 点击查看导图 | MindElixir渲染正常 | P0 |
| B-42 | 导图编辑 | 编辑节点保存 | 保存成功 | P1 |

### 3.6 数据一致性

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| B-50 | 保存后刷新 | 编辑题目后刷新页面 | 数据与编辑后一致 | P0 |
| B-51 | 网络失败处理 | 断网时保存 | UI不显示虚假成功，提示失败 | P0 |
| B-52 | 批量导入回滚 | 导入含错误数据的批量 | 全部回滚，无半截数据 | P0 |
| B-53 | 系统字段过滤 | POST请求携带create_time | 后端忽略该字段，使用后端生成时间 | P1 |

### 3.7 异常与降级

| ID | 用例名称 | 操作步骤 | 预期结果 | 优先级 |
|----|---------|---------|---------|--------|
| B-60 | Ollama离线 | 关闭Ollama后识别PDF | 返回明确错误"Ollama未运行"，不崩溃 | P0 |
| B-61 | PDF识别超时 | 超大PDF识别 | 300秒后返回408超时错误 | P1 |
| B-62 | 离线状态提示 | 断网 | 顶部显示橙色离线banner | P1 |
| B-63 | IndexedDB异常 | 隐私模式打开 | 提示离线缓存不可用 | P2 |
| B-64 | 接口限流 | 高频请求上传接口 | 返回429，不耗尽资源 | P1 |

---

## 四、回归测试必跑清单（每次变更后）

1. ✅ S-01~S-04 语法层全部通过
2. ✅ R-01~R-06 运行层P0项全部通过
3. ✅ B-01~B-03 登录流程正常
4. ✅ B-10~B-12 题库CRUD正常
5. ✅ B-20~B-22 闪卡CRUD+批量导入正常
6. ✅ B-30~B-31 资料库文件上传正常
7. ✅ B-50 保存后刷新数据一致

---

## 五、测试环境要求

- 后端: Python 3.11, FastAPI, SQLite
- 前端: Chrome 最新版, 1920x1080
- 测试账号: admin / 已配置
- 测试数据: 一造管理（1835题/5230闪卡）


============================================================
# § 4. 【来源：代码架构债务专项迁移方案_V1.0.md】
============================================================

# 水利智学系统 代码架构债务专项迁移方案

> 版本：V1.1（38位专家评审补充版）
> 依据：《系统设计宪法 V2.6》增量迁移铁律、黄金备份机制、真实运行验证铁律
> 专家组：38位专家委员会联合制定
> V1.1更新：补充函数调用追踪、内存泄漏检测、数据库版本兼容校验、SW强制注销、审计事务感知、时间戳签名6项机制

---

## 一、迁移总览

### 1.1 迁移目标

| 维度 | 现状 | 目标 |
|------|------|------|
| 重复函数 | app.js/resource.js 458个重复函数 | 0个重复，统一收敛到modules |
| 全局变量 | 81个冲突变量互相覆盖 | 0个业务级裸全局变量，统一入store |
| 接口规范 | mt模块混用新旧API | 100%统一到/api/mt新接口 |
| 审计覆盖 | text SQL绕过ORM审计 | 100%数据变更有审计记录 |
| 状态管理 | 模块_state/全局变量/store混杂 | 跨模块共享状态100%入store |

### 1.2 迁移批次与时间线

```
批次0：基线锁定（0.5天）
  ↓
批次1：P0-06 重复函数+全局变量迁移（5阶段，预计5-7天）
  阶段1：通用工具层 → 阶段2：非核心业务 → 阶段3：核心业务
  → 阶段4：全局变量收敛 → 阶段5：去重收尾
  ↓
批次2：P1高风险技术债务（2-3天）
  P1-03 sync空壳 → P1-05 mt API统一 → P1-16 text SQL审计 → P1-19 uvicorn优雅关闭
  ↓
批次3：P2架构合规（1-2天）
  P2-01 状态治理 → P2-04 枚举常量统一
  ↓
批次4：P3业务数据一致性（1-2天）
  P3-01 UI更新顺序 → P3-03 后端时间戳
  ↓
暂缓项（不纳入本次）：P3-04游标分页、P3-08后台任务、P2-02存量DOM ID整改
```

### 1.3 核心原则

1. **新旧共存**：旧文件保留兼容壳，禁止直接删除
2. **增量搬迁**：逐函数/逐域迁移，每步可独立验证
3. **兼容兜底**：旧函数签名100%不变，内部代理到新模块
4. **逐段验证**：每阶段通过三级验证才进入下一阶段
5. **一键回滚**：每阶段前创建快照，故障分钟级恢复

---

## 二、前置准备（任务0）

### 2.1 黄金基线锁定

```bash
# 1. 生成迁移前专属基线快照
python tools/rollback_to_golden.py --snapshot "架构迁移前_黄金基线"

# 2. 验证基线完整性
python tools/diff_vs_golden.py --check
```

**【PWA专家强制要求】SW强制注销（任务0必做，否则所有验证不可信）**：
```javascript
// 浏览器控制台执行，确保无SW缓存残留
if ('serviceWorker' in navigator) {
    navigator.serviceWorker.getRegistrations().then(regs => {
        regs.forEach(r => r.unregister());
    });
    caches.keys().then(keys => keys.forEach(k => caches.delete(k)));
}
// 验证：Application → Service Workers 显示无注册，Cache Storage 为空
```

**交付物**：
- `backups/架构迁移前_黄金基线_YYYYMMDD/` 完整代码快照
- `backups/架构迁移前_黄金基线_YYYYMMDD.db` 数据库快照
- 基线MD5校验清单
- SW注销确认截图

### 2.2 冲突清单输出

运行冲突检测脚本，生成全量清单：

```
docs/迁移冲突清单/
├── 01_重复函数清单.md          # 458个重复函数，按业务域分类
├── 02_冲突全局变量清单.md      # 81个冲突变量，标注归属
├── 03_通用工具函数清单.md      # 阶段1迁移对象
├── 04_非核心业务函数清单.md    # 阶段2迁移对象
└── 05_核心业务函数清单.md      # 阶段3迁移对象
```

**清单格式**：
| 序号 | 函数名/变量名 | app.js行号 | resource.js行号 | 业务域 | 迁移目标模块 | 风险等级 |
|------|-------------|-----------|----------------|--------|-------------|---------|

### 2.3 环境准备

- [ ] 测试环境与生产环境1:1对齐（数据库、配置、资料文件）
- [ ] node --check 语法校验工具就绪
- [ ] 浏览器自动化测试脚本就绪
- [ ] 黄金回滚脚本验证可用

---

## 三、第一批次：P0-06 重复函数+全局变量迁移

### 阶段1：通用工具层迁移（风险最低）

**迁移对象**：时间格式化、DOM操作、字符串处理、本地存储封装等纯工具函数

**目标落点**：`static/js/modules/common-utils.js`

**操作步骤**：

1. **对照清单补全common-utils**
   - 核对common-utils已有能力
   - 缺失函数100%对齐旧逻辑补全，**不做任何逻辑优化**
   - 纯工具常量（如SUBJECT_COLORS）同步迁移

2. **旧文件改为代理壳**
   ```javascript
   // app.js / resource.js 中保留原函数签名
   function formatTime(seconds) {
       return window.commonModule.formatTime(seconds);
   }
   ```

3. **三级验证**
   - 语法层：`node --check` 全部通过
   - 运行层：控制台无新增红色报错
   - 业务层：随机抽取10个工具函数，输出结果与迁移前完全一致

**验收标准**：
- [ ] common-utils包含所有迁移的工具函数
- [ ] app.js/resource.js中对应函数为代理壳
- [ ] 10个抽样函数输出完全一致
- [ ] 控制台无新增报错

---

### 阶段2：非核心业务域迁移

**迁移对象**：视频播放、笔记、PDF标记三类重复函数

**目标落点**：对应业务模块（缺失则新建子模块）

**操作步骤**：

1. **视频播放域**
   - 业务逻辑完整剪切到video模块
   - 模块内部状态私有化到`_state`
   - 旧文件保留代理壳

2. **笔记域**
   - 同上，迁移到note模块

3. **PDF标记域**
   - 同上，迁移到pdf模块

4. **全局变量处理**
   - 跨模块用的写入`window.store`
   - 模块内部用的放模块`_state`

**验收标准**：
- [ ] 视频播放全流程正常（打开/暂停/进度/全屏）
- [ ] 笔记编辑正常（新建/编辑/删除/保存）
- [ ] PDF标记正常（高亮/批注/保存）
- [ ] 数据读写与迁移前一致
- [ ] 控制台无新报错

---

### 阶段3：核心业务域迁移（最高风险）

**迁移对象**：公式训练、记忆训练、思维导图

**执行顺序**：记忆训练 → 思维导图 → 公式训练（**禁止并行**）

**每个域的操作步骤**：

1. 先迁状态变量到store
2. 再迁业务函数到对应模块（mt.js / mm.js）
3. 旧文件留代理壳
4. 81个变量中该域业务变量逐个验证状态读写一致性

**记忆训练域验收**：
- [ ] 闪卡列表加载正常
- [ ] 复习流程正常（显示/答对/答错/下次复习时间）
- [ ] SM-2算法计算结果与迁移前一致
- [ ] 新建/编辑/删除闪卡正常

**思维导图域验收**：
- [ ] 脑图加载/渲染正常
- [ ] 节点增删改正常
- [ ] 拖拽/缩放正常
- [ ] 保存/导出正常

**公式训练域验收**：
- [ ] 公式列表加载正常
- [ ] 训练流程正常
- [ ] 进度记录正常

---

### 阶段4：全局变量收敛到Store

**迁移对象**：剩余所有冲突全局变量

**操作步骤**：

1. **逐个变量评估归属**
   - 跨模块共享 → `window.store`
   - 模块内部 → 模块`_state`

2. **旧文件保留兼容层**
   ```javascript
   // 兼容旧代码直接读写全局变量
   Object.defineProperty(window, '_formulaCards', {
       get() { return window.store.get('formula.cards') || []; },
       set(val) { window.store.set('formula.cards', val); }
   });
   ```

3. **新代码全部直接调用store**

**验收标准**：
- [ ] 所有读写状态的业务点数据一致
- [ ] 无覆盖、无丢失
- [ ] 旧代码直接读写全局变量不报错
- [ ] 输出《全局状态清单》

---

### 阶段5：重复函数去重收尾

**操作步骤**：
1. 全量检索确认所有外部调用都走新模块
2. 旧文件中重复函数标记`/* 兼容代理，后续废弃 */`
3. 保留函数壳不删除，保留至少30天兼容期

**验收标准**：
- [ ] 无功能异常
- [ ] 控制台无报错
- [ ] 所有重复函数已标记

---

## 四、第二批次：P1高风险技术债务

### P1-03：sync同步空壳处理

**操作**：
- 前端UI隐藏同步手动触发按钮
- 状态栏标注「同步功能内测中」
- 不删除底层代码

**验收**：用户看不到不可用的同步入口

---

### P1-05：mt模块新旧API统一

**操作**：
1. mt模块内部所有接口调用统一切换为`/api/mt`
2. 后端旧`/api/v1/flashcard`接口保留30天兼容期
3. 监控旧接口访问量，归零后下线

**验收**：
- [ ] mt模块不再调用`/api/v1/flashcard`
- [ ] 闪卡列表/复习/新建/编辑/删除正常
- [ ] 后端旧接口访问量为0

---

### P1-16：原生text SQL补齐审计记录

**操作**：
1. 封装`execute_text_with_audit(db, sql, params, table_name, operate_type)`
2. 【后端架构师强制要求】**事务感知**：在事务中执行的SQL，审计日志在事务提交后写入，避免回滚后留下虚假审计记录
3. 工具内部执行SQL后手动写入审计日志表
4. fl_bridge所有原生SQL调用替换为该工具

**事务感知实现**：
```python
def execute_text_with_audit(db, sql, params, table_name, operate_type, request=None):
    result = db.execute(text(sql), params)
    # 检查是否在事务中
    if db.in_transaction():
        # 注册事务提交后回调，确保审计日志与业务数据一致
        @db.event.listens_for(db, "after_commit")
        def _write_audit_after_commit(session):
            audit_log(action=operate_type, module=table_name, ...)
    else:
        # 非事务中直接写入
        audit_log(action=operate_type, module=table_name, ...)
    return result
```

**验收**：
- [ ] 批量题库导入有审计记录
- [ ] 闪卡生成有审计记录
- [ ] 审计日志包含：操作表、类型、时间、参数摘要
- [ ] 事务回滚后无虚假审计记录

---

### P1-19：uvicorn守护进程优雅关闭

**操作**：
1. 外层守护循环增加SIGINT/SIGTERM信号监听
2. 收到关闭信号后：停止接收新请求 → 等待当前请求完成（最大30秒）→ 退出
3. 超时未完成则强制终止，记录未完成任务日志

**验收**：
- [ ] 服务重启时，正在进行的文件上传不中断
- [ ] PDF识别任务可以正常完成
- [ ] 不产生脏数据

---

## 五、第三批次：P2架构合规

### P2-01：状态治理

**边界划分**：
| 状态类型 | 归属 | 示例 |
|---------|------|------|
| 跨模块共享业务状态 | window.store | 当前科目、用户信息、全局设置 |
| 模块内部临时UI状态 | 模块_state | 筛选条件、分页、弹窗显隐 |

**交付物**：《全局状态清单》，明确每个状态的归属、读写权限

---

### P2-04：前后端统一业务枚举常量

**操作**：
1. 后端`constants.py`定义：科目映射、文件标签、业务状态、题型枚举
2. 前端通过`/api/common/constants`接口获取枚举
3. 业务代码全部引用常量，禁止手写字符串

**验收**：
- [ ] 前后端标签、科目、状态值完全一致
- [ ] 修改一处全局生效
- [ ] 无业务魔法字符串硬编码

---

## 六、第四批次：P3业务数据一致性

### P3-01：UI更新顺序统一修复

**统一执行顺序**：
```
调用接口 → 后端返回成功 → 更新前端内存与DOM
     ↓失败
  弹出错误提示 → UI回滚到修改前状态
```

**覆盖范围**：文件标签编辑、闪卡编辑、题目编辑、科目切换等所有写操作

**验收**：断网情况下提交编辑，UI不会虚假显示成功

---

### P3-03：业务时间戳后端优先

**操作**：
1. 所有写操作接口，时间字段由后端生成，忽略前端传入
2. 前端时间仅用于界面展示
3. SM-2复习间隔计算以后端返回的下次复习时间为准
4. 【安全专家强制要求】**时间戳HMAC签名**：后端返回的时间戳带HMAC-SHA256签名，前端验证签名后才使用，防止中间人篡改

**时间戳签名实现**：
```python
# 后端：生成带签名的时间戳
import hmac, hashlib, json, time
def get_signed_timestamp():
    ts = int(time.time())
    payload = json.dumps({"ts": ts}, separators=(',', ':'))
    signature = hmac.new(SECRET_KEY.encode(), payload.encode(), hashlib.sha256).hexdigest()
    return {"timestamp": ts, "signature": signature}

# 前端：验证签名后才使用
function verifySignedTimestamp(data) {
    const payload = JSON.stringify({ts: data.timestamp});
    const expectedSig = CryptoJS.HmacSHA256(payload, SECRET_KEY).toString();
    return expectedSig === data.signature;
}
```

**验收**：
- [ ] 修改本地电脑时间，不改变复习计划顺序
- [ ] 时间戳签名验证失败时，前端拒绝使用并报错
- [ ] 篡改时间戳后签名验证不通过

---

## 七、验收标准保障机制

### 7.1 三级验证体系（每阶段必过）

```
┌─────────────────────────────────────────────────┐
│ 语法层验证（自动，1分钟）                         │
│  node --check 全部JS文件                          │
│  python -m py_compile 全部PY文件                  │
│  零语法错误才能进入下一步                          │
└──────────────────────┬──────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│ 运行层验证（半自动，5分钟）                        │
│  浏览器打开页面，控制台无阻断性红色报错             │
│  window.store/api/logger全局对象可访问             │
│  所有模块healthCheck()状态正常                    │
│  ServiceWorker确认完全注销                        │
└──────────────────────┬──────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│ 业务层验证（人工，10-30分钟）                      │
│  该阶段涉及的业务功能全流程跑通                     │
│  输出结果与迁移前完全一致                          │
│  数据读写正常，无丢失/覆盖                         │
└─────────────────────────────────────────────────┘
```

### 7.2 每步验收检查清单

**迁移前检查**：
- [ ] 黄金备份已创建
- [ ] SW已强制注销，无缓存残留
- [ ] 冲突清单已输出
- [ ] 目标模块已准备
- [ ] 回滚脚本已验证
- [ ] 函数调用追踪埋点已启用

**迁移中检查**：
- [ ] 函数签名100%不变
- [ ] 入参/返回值完全一致
- [ ] 未修改未提及的函数
- [ ] 旧文件保留代理壳
- [ ] 代理壳记录调用次数（调用追踪埋点）

**迁移后检查**：
- [ ] node --check 通过
- [ ] 控制台无新增报错
- [ ] 业务功能全流程通过
- [ ] 数据一致性验证通过
- [ ] 内存泄漏检测通过（对比迁移前后内存占用）
- [ ] 事件监听器泄漏检测通过
- [ ] 函数调用追踪：代理壳调用次数为0（全部走新模块）
- [ ] 阶段快照已创建

### 7.3 自动化验证脚本

```bash
# 语法校验脚本
scripts/verify_syntax.sh
  ├── 遍历所有JS文件执行node --check
  ├── 遍历所有PY文件执行py_compile
  └── 输出语法错误报告

# 健康检查脚本
scripts/verify_health.py
  ├── 调用/api/health检查后端组件状态
  ├── 浏览器自动化检查控制台报错
  └── 调用各模块healthCheck()

# 业务回归脚本
scripts/verify_business.py
  ├── 题库：列表/详情/答题/保存
  ├── 闪卡：列表/复习/新建/编辑
  ├── 思维导图：加载/编辑/保存
  └── 学习资料库：上传/列表/标签

# 【前端运行时调试专家】函数调用追踪脚本
scripts/verify_call_tracking.js
  ├── 迁移前：记录所有函数的调用次数基线
  ├── 迁移后：代理壳调用次数应为0（全部走新模块）
  ├── 不为0说明有遗漏的直接调用点，输出具体函数名和调用栈
  └── 全量函数输出对比：同一输入运行所有函数，输出diff为空才算通过

# 【浏览器内核专家】内存/事件泄漏检测脚本
scripts/verify_memory_leak.js
  ├── 迁移前后内存快照对比（heap snapshot）
  ├── 事件监听器计数对比（getEventListeners）
  ├── 代理壳闭包引用检测
  ├── 反复进出页面10次，内存无持续上涨
  └── DOM节点数无持续增长

# 【数据库专家】store并发读写一致性检测
scripts/verify_store_concurrency.js
  ├── 多模块同时读写同一store键
  ├── 验证无竞态条件、无数据覆盖
  └── store版本号机制验证
```

### 7.4 验收结果记录模板

```
## 阶段X 验证报告
日期：YYYY-MM-DD HH:MM
执行人：XXX
迁移范围：XX个函数，XX个变量

### 语法层
- [ ] node --check 全部通过
- [ ] py_compile 全部通过
- 结果：✅通过 / ❌失败（附错误日志）

### 运行层
- [ ] 控制台无阻断性红色报错
- [ ] window.store/api/logger 正常
- [ ] 模块healthCheck() 全部正常
- [ ] ServiceWorker 已注销
- 结果：✅通过 / ❌失败（附控制台截图）

### 业务层
- [ ] 功能1：XXX 正常
- [ ] 功能2：XXX 正常
- [ ] 数据一致性：与迁移前一致
- 结果：✅通过 / ❌失败（附业务页面截图）

### 结论
□ 全部通过，进入下一阶段
□ 存在问题，需修复后重新验证
问题描述：...
```

---

## 八、回滚方案及风险管控

### 8.1 回滚层级

```
L1：函数级回滚（秒级）
  单个函数迁移出问题 → 恢复该函数旧实现
  适用：单个函数逻辑不一致

L2：域级回滚（分钟级）
  某个业务域迁移出问题 → 恢复该域所有函数旧实现
  适用：阶段2/3单个域整体异常

L3：阶段级回滚（分钟级）
  整个阶段迁移出问题 → 回滚到该阶段开始前的快照
  适用：阶段验证不通过，无法快速定位

L4：全局回滚（5分钟内）
  出现白屏/数据丢失等严重故障 → 一键回滚黄金基线
  适用：P0级阻断故障
```

### 8.2 回滚操作流程

**【运维专家强制要求】回滚前置检查：数据库版本兼容校验**
```bash
# 回滚前必须执行，检查代码与数据库版本兼容性
python tools/check_db_compatibility.py --target backups/阶段X快照/
# 输出：兼容 / 不兼容（需先执行数据库迁移脚本）
# 不兼容时禁止直接回滚代码，需先恢复对应版本数据库
```

**L1 函数级回滚**：
```bash
# 从阶段快照恢复单个函数
git diff backups/阶段X快照/frontend/js/app.js | grep "函数名"
# 手动恢复该函数旧实现
```

**L2 域级回滚**：
```bash
# 恢复该域所有函数
cp backups/阶段X快照/frontend/js/app.js frontend/js/app.js
# 但只恢复该域相关函数（需精确定位）
```

**L3 阶段级回滚**：
```bash
# 1. 先检查数据库兼容性
python tools/check_db_compatibility.py --target backups/阶段X开始前快照/
# 2. 兼容则恢复代码
cp -r backups/阶段X开始前快照/* ./
# 3. 不兼容则先恢复数据库
cp backups/阶段X开始前快照.db backend/data/shuili_exam.db
# 4. 再恢复代码
```

**L4 全局回滚**：
```bash
# 1. 检查数据库兼容性
python tools/check_db_compatibility.py --target backups/黄金基线/
# 2. 一键回滚黄金基线（含数据库）
python tools/rollback_to_golden.py --all
```

### 8.3 风险识别与管控矩阵

| 风险点 | 风险等级 | 触发条件 | 预防措施 | 应急响应 |
|--------|---------|---------|---------|---------|
| 白屏 | P0 | 语法错误/全局变量冲突 | node --check+浏览器验证 | L4全局回滚 |
| 数据丢失 | P0 | 状态迁移错误 | 数据库备份+读写验证 | L3阶段回滚+数据库恢复 |
| 功能瘫痪 | P1 | 业务函数迁移错误 | 业务层全流程验证 | L2域级回滚 |
| 行为不一致 | P2 | 函数逻辑细微差异 | 抽样对比输出 | L1函数级回滚 |
| 性能下降 | P2 | 代理调用层级过深 | 性能基准测试 | 优化代理层 |
| 兼容壳失效 | P3 | 旧代码未走代理 | 全量调用点检索 | 修复代理壳 |

### 8.4 黄金备份机制

**备份时机**：
- 迁移开始前：黄金基线
- 每个阶段开始前：阶段快照
- 每个阶段完成后：阶段完成快照
- 每天结束时：日备份

**备份内容**：
- 完整代码（frontend/ + backend/）
- 数据库快照（backend/data/shuili_exam.db）
- 配置文件
- 迁移进度记录

**备份验证**：
- 每个备份创建后立即验证MD5
- 每周抽查一次回滚可用性

### 8.5 故障响应流程

```
发现故障
  ↓
1分钟内：判断故障等级
  ├── P0（白屏/数据丢失）→ 立即L4全局回滚
  ├── P1（功能瘫痪）→ 尝试L2域级回滚
  └── P2/P3 → 定位问题，L1函数级回滚
  ↓
回滚后验证
  ├── 页面正常加载
  ├── 数据完整
  └── 功能可用
  ↓
记录故障原因
  ├── 哪个函数/变量导致
  ├── 为什么验证没发现
  └── 如何改进验证流程
  ↓
重新规划迁移策略
```

### 8.6 迁移纪律红线

❌ **禁止**一次性批量删除/重写app.js/resource.js全部代码
❌ **禁止**修改函数名、入参、返回值，必须100%兼容旧调用
❌ **禁止**同时修改多个业务域，每阶段最多1个域
❌ **禁止**跳过验证直接进入下一阶段
❌ **禁止**提前删除旧函数、旧变量兼容壳，必须保留至少30天
❌ **禁止**未做黄金备份就开始修改
❌ **禁止**在迁移过程中做逻辑优化，只做纯搬运

---

## 九、暂缓任务说明

| 任务 | 暂缓原因 | 后续计划 |
|------|---------|---------|
| P3-04 offset分页改游标分页 | 改动涉及所有列表接口前后端全量修改，当前功能可用 | 随业务迭代逐步改造 |
| P3-08 后台任务持久化追踪 | 需新增数据库表与任务调度框架，工程量大 | 任务量增长后优先处理 |
| P2-02 DOM ID存量整改 | 存量ID量大，不影响功能 | 随业务迭代逐步整改，不集中批量改造 |

---

## 十、最终交付物清单

1. **各阶段验证报告**（语法校验截图 + 控制台截图 + 业务页面截图）
2. **黄金备份diff对比报告**（迁移前后代码差异）
3. **全局状态清单**（每个状态的归属、读写权限）
4. **枚举常量清单**（前后端统一枚举定义）
5. **重复函数迁移清单**（458个函数的迁移状态）
6. **冲突变量迁移清单**（81个变量的迁移状态）
7. **迁移后完整代码包**
8. **回滚操作手册**

---

## 十一、迁移进度跟踪表

| 批次 | 任务 | 计划时间 | 实际时间 | 状态 | 验证结果 | 回滚点 |
|------|------|---------|---------|------|---------|--------|
| 任务0 | 基线锁定 | 0.5天 | | ⏳ | - | 黄金基线 |
| 批次1 | 阶段1：通用工具 | 1天 | | ⏳ | - | 阶段1快照 |
| 批次1 | 阶段2：非核心业务 | 1.5天 | | ⏳ | - | 阶段2快照 |
| 批次1 | 阶段3：核心业务 | 2.5天 | | ⏳ | - | 阶段3快照 |
| 批次1 | 阶段4：变量收敛 | 1天 | | ⏳ | - | 阶段4快照 |
| 批次1 | 阶段5：去重收尾 | 0.5天 | | ⏳ | - | 阶段5快照 |
| 批次2 | P1-03~P1-19 | 2-3天 | | ⏳ | - | 批次2快照 |
| 批次3 | P2-01/P2-04 | 1-2天 | | ⏳ | - | 批次3快照 |
| 批次4 | P3-01/P3-03 | 1-2天 | | ⏳ | - | 批次4快照 |

---

## 十二、38位专家评审补充机制汇总（V1.1新增）

### 12.1 六项强制补充机制

| 序号 | 机制名称 | 提出专家 | 实施位置 | 目的 |
|------|---------|---------|---------|------|
| 1 | SW强制注销 | PWA/Service Worker专家 | 任务0前置 | 确保验证时加载新代码，不被SW缓存干扰 |
| 2 | 函数调用追踪埋点 | 前端运行时调试专家 | 每阶段迁移中 | 确保没有遗漏的直接调用点，代理壳调用次数为0 |
| 3 | 内存/事件泄漏检测 | 浏览器内核专家 | 每阶段验证 | 防止代理壳闭包引用和事件绑定导致内存泄漏 |
| 4 | 数据库版本兼容校验 | 运维专家 | 所有回滚操作前置 | 防止代码与数据库schema不兼容导致二次故障 |
| 5 | 审计工具事务感知 | 后端架构师 | P1-16实现 | 事务回滚后不留下虚假审计记录 |
| 6 | 时间戳HMAC签名 | 安全专家 | P3-03实现 | 防止中间人篡改时间戳 |

### 12.2 函数调用追踪埋点实现规范

```javascript
// 代理壳模板（必须包含调用追踪）
function formatTime(seconds) {
    // 调用追踪：记录调用次数和调用栈
    window.__callTracker = window.__callTracker || {};
    window.__callTracker['formatTime'] = (window.__callTracker['formatTime'] || 0) + 1;
    if (window.__callTracker['formatTime'] === 1) {
        console.warn('[迁移追踪] 代理壳被直接调用: formatTime', new Error().stack);
    }
    return window.commonModule.formatTime(seconds);
}

// 迁移完成后验证
function verifyMigrationComplete() {
    const directCalls = Object.entries(window.__callTracker || {})
        .filter(([name, count]) => count > 0);
    if (directCalls.length > 0) {
        console.error('[迁移验证] 以下函数仍有直接调用:', directCalls);
        return false;
    }
    console.log('[迁移验证] 所有调用已走新模块，迁移完成');
    return true;
}
```

### 12.3 内存泄漏检测标准

| 检测项 | 通过标准 | 检测方法 |
|--------|---------|---------|
| 堆内存增长 | 反复进出页面10次，增长<5MB | heap snapshot对比 |
| 事件监听器 | 页面销毁后无残留监听器 | getEventListeners计数 |
| DOM节点 | 页面销毁后无游离节点 | getEventListeners + DOM查询 |
| 代理壳闭包 | 无未释放的闭包引用 | Chrome DevTools Memory面板 |

### 12.4 数据库版本兼容校验实现

```python
# tools/check_db_compatibility.py
def check_compatibility(target_snapshot_path):
    # 1. 读取目标代码的数据库迁移版本要求
    target_version = read_schema_version(target_snapshot_path)
    # 2. 读取当前数据库的实际版本
    current_version = get_current_db_version()
    # 3. 比较版本
    if target_version == current_version:
        return {"compatible": True}
    elif target_version < current_version:
        return {
            "compatible": False,
            "action": "需要先回滚数据库到版本" + target_version,
            "rollback_script": f"python tools/migrate_db.py --to {target_version}"
        }
    else:
        return {
            "compatible": False,
            "action": "需要先升级数据库到版本" + target_version,
            "upgrade_script": f"python tools/migrate_db.py --to {target_version}"
        }
```

---

> **文档版本**：V1.1（38位专家评审补充版）
> **创建日期**：2026-09-06
> **V1.1更新**：2026-09-06 补充6项专家建议机制
> **审批**：38位专家委员会一致通过
> **下次评审**：每阶段完成后


============================================================
# § 5. 【来源：代码迁移分析师_需求登记.md】
============================================================

# 代码迁移分析师 - 需求登记与追踪系统
# 用于记录所有功能需求、迁移状态、问题追踪
# 最后更新：2026-09-11 全面代码对比完成

## 一、已完成需求

### 1.1 学习资料库 - 数据来源
- [x] 使用 /fl/list API 获取含tags的文件数据
- [x] 使用 /video/list API 获取视频数据
- [x] 合并文档（506）+ 视频（64）= 570个文件
- [x] 创建 core/api.js 通用API封装
- [x] 修复 window.api 未初始化问题

### 1.2 学习资料库 - 标签体系
- [x] 预设标签扩展为18个，分3组（资料类型/练习类型/记忆工具）
- [x] 文件夹头部显示标签集合
- [x] 文件夹级标签修改（批量修改文件夹内所有文件）
- [x] 单文件标签修改（仅"其他"文件夹）
- [x] 标签保存到后端API（PUT /api/v1/fl/:id，FormData格式）
- [x] 文件夹标签批量保存到后端API
- [x] 标签管理库功能

### 1.3 学习资料库 - 批量操作
- [x] 识别题库（根据真题/模拟题/精题/练习题标签筛选）
- [x] 生成闪卡（根据闪卡标签筛选）
- [x] 生成导图（根据思维导图标签筛选）
- [x] 添加 fl_bridge.js 引用
- [x] 批量操作按钮放在Tab栏

### 1.4 学习资料库 - 布局
- [x] 上下布局（文档在上，视频在下）
- [x] 文档区域占更多空间（1.6:1）

### 1.5 学习资料库 - 边缘功能
- [x] 批量删除API路径修复（/material→/fl）
- [x] 单文件删除API路径修复（/material→/fl）
- [x] 文件预览功能添加

### 1.6 系统设计宪法
- [x] 新增25.7同步修改铁律（联动修改总纲）
- [x] 11类联动修改清单
- [x] 同步验证三步流程
- [x] 高效检索工具强制使用

### 1.7 基础设施
- [x] 创建 tools/fast_search.py 高效检索工具
- [x] 创建 tools/static_check.py 静态代码检查
- [x] 创建 tools/daily_health_report.py 健康报告
- [x] 创建 docs/代码审查流程规范.md
- [x] 创建 data/问题知识库/issue_knowledge_base.json
- [x] 创建 docs/全面代码对比报告.md

### 1.8 全面代码对比
- [x] 对比旧file_library.js（30方法）与新file-library.js（27方法）
- [x] 检查全部24个模块的事件绑定状态
- [x] 发现5个模块bindEvents为空
- [x] 识别3个真正需要修复的模块（collect/memory/sprint）

## 二、进行中需求

### 2.1 file-library缺失功能迁移（8项）
- [x] 单文件识别题库（已移除，用户要求用标签批量识别代替）
- [x] 单文件生成导图（已移除，用户要求用标签批量生成代替）
- [x] 标签颜色（getTagColor，按类型分3组颜色）
- [ ] 状态颜色（getStatusColor）
- [ ] 视频讲义专用渲染（视频+讲义左右同步）
- [ ] 类型/状态筛选（changeFilter）
- [x] 分页功能（不需要，page_size=1000已加载全部）
- [x] 批量标签模态框（showBatchTagModal）

### 2.2 事件绑定缺失模块修复（3个）
- [x] collect.js - 搜索/导出/题目点击/取消收藏/去练习/题型筛选
- [x] sprint.js - 快捷入口跳转（真题模考/错题重练/高频考点/AI出题）+ 薄弱/高频考点点击
- [x] memory.js - 记忆法详情弹窗/工具功能调用/专项训练/记忆曲线

## 三、待完成需求

### 3.1 其他模块检查
- [x] system-admin 模块事件绑定检查（纯展示，不需要）
- [x] statusbar 模块事件绑定检查（纯展示，不需要）
- [ ] 其他模块API路径一致性检查
- [ ] 其他模块数据来源一致性检查

### 3.2 代码治理
- [ ] 内联样式清理（剩余141个动态样式）
- [ ] 数据治理AI深度工程
- [ ] 知识点四级打通
- [ ] 思维导图双版本
- [ ] 三级体系

### 3.3 批量功能测试
- [ ] 测试批量识别题库实际调用
- [ ] 测试批量生成闪卡实际调用
- [ ] 测试批量生成导图实际调用

## 四、问题记录

### 4.1 已解决问题
1. window.api未初始化 → 创建core/api.js
2. 数据来源错误（/material/list）→ 改为/fl/list
3. 视频文件为0 → 合并/video/list数据
4. 标签只保存localStorage → 添加后端API保存
5. 后端API使用Form格式 → 前端改为FormData
6. 左右布局空间不足 → 改为上下布局
7. 标签库显示不全 → 扩展为3组18个标签
8. 删除API路径错误 → /material改为/fl
9. 文件预览功能缺失 → 已添加previewFile方法

### 4.2 待解决问题
1. 浏览器缓存旧JS文件（需强制刷新）
2. collect.js事件绑定为空（搜索/导出/题目点击无效）
3. sprint.js事件绑定为空（快捷入口点击无效）
4. memory.js事件绑定为空（记忆法/工具点击无效）

## 五、设计决策记录

### 5.1 标签体系
- 预设标签：18个分3组（资料类型6个/练习类型6个/记忆工具6个）
- 标签化目的：识别提取信息（真题→识别题库、闪卡→生成闪卡、导图→生成导图）
- 有明确文件夹的文件只在文件夹级修改标签
- 只有"其他"文件夹中的单个文件才显示单文件标签按钮
- 全局科目（如一造管理）不作为文件标签

### 5.2 布局决策
- 文档在上，视频在下（上下布局）
- 文档区域占1.6份，视频区域占1份
- 搬的是内容显示区，二级标题栏不动

### 5.3 功能取舍
- 移除文件夹级别的重命名/删除/全选（鸡肋功能）
- 移除类型/分类/大小/上传时间列（无意义）
- 文件名缩略显示
- 批量标签用简便逻辑，不用复杂模态框
- showUploadModal用原生input替代
- showScanModal用folderUpload替代
- setFileTag/batchTagFolder用标签面板替代
- editTags/editFile用标签面板替代

## 六、模块状态总览

### 功能完整模块（16个）
analytics, dashboard, mock-exam, flashcard, knowledge, module-nav, sidebar, topbar, file-library, question-manager, material, mindmap, note, photo-solve, question-practice, settings, video, wrong-book

### 需要修复模块（3个）
- collect.js - 事件绑定为空
- memory.js - 无bindEvents方法
- sprint.js - 无bindEvents方法

### 纯展示模块（2个）
- system-admin.js - 注释"暂无交互事件"
- statusbar.js - 纯状态栏展示

### 演示模块（1个）
- hello-demo.js - 演示用

## 七、题库质量专项问题登记（2026-09-11 用户反馈，共29项）

### 7.1 UI交互问题（5项，P0优先级）

| 编号 | 问题描述 | 模块 | 优先级 | 状态 |
|------|---------|------|--------|------|
| Q-01 | 题库刷题选多了，取消选择后，底纹还在 | question-practice | P0 | ✅已修复（明确已作答不可修改逻辑） |
| Q-12 | 题库刷题模式下同一批题做过之后，要显示做过的结果，左滑后还显示做过的结果。退出后就清除记录 | question-practice | P0 | ❌待修复 |
| Q-13 | 刷题要提供草稿模式 | question-practice | P1 | ❌待修复 |
| Q-15 | 解析无换行显示 | question-practice | P0 | ✅已修复（\n转<br>） |
| Q-18 | 答案解析无法滚动，看不全 | question-practice | P0 | ✅已修复（添加max-height+overflow-y） |

### 7.2 数据质量-缺失类（6项，P0优先级）

| 编号 | 问题描述 | 涉及题目 | 优先级 | 状态 |
|------|---------|---------|--------|------|
| Q-02 | 题库管理里面存在题目没有选项 | 多题 | P0 | ✅已修复（前端优先options字段，包含option_e） |
| Q-03 | 题库管理存在无解析 | 多题 | P0 | ❌待排查 |
| Q-04 | 题库的题目没有图 | 多题 | P0 | ❌待排查 |
| Q-07 | 融资决策分析阶段的题目，无解析 | 融资决策分析 | P0 | ❌待修复 |
| Q-08 | 2023年属于项目总经理职权的，无解析 | 2023年项目总经理职权 | P0 | ❌待修复 |
| Q-11 | 最适宜的功能水平应是，无图 | 价值工程功能水平 | P0 | ❌待修复 |
| Q-24 | 题库管理前端错用 /api/qb/random（随机抽题接口），只返回十几条，一屏显示不全 | question-manager.js | P0 | ✅已修复（改用 /api/qb/questions 列表接口，服务端分页 page_size=100） |
| Q-25 | 后端 service.py 的 get_question_list / get_question_detail 漏查 year 字段，导致前端年份列全显示"模拟" | qb/service.py | P0 | ✅已修复（SELECT 补 year，items dict 加 "year": r[10]） |
| Q-26 | 数据库脏数据 year=2069（5条广告污染题，题干含"提供最新VIP课程"） | questions 表 | P1 | ✅已清理（备份后 UPDATE 为"模拟题"，备份：backups/shuili_exam_before_year_fix_20260914_181851.db） |
| Q-27 | q_type 返回英文 single/multiple/judge，前端直接显示成英文 | question-manager.js | P1 | ✅已修复（前端 typeMap 映射 single→单选、multiple→多选、judge→判断） |
| Q-28 | 学习资料库前端调错接口：列表/删除/下载走 `/api/common/file-library/*`、上传走 `/api/resource/upload_batch`，而后端真实路由是 `/api/v1/fl/*`（表 fl_file_library），导致已上传文件在资料库看不到 | file-library.js | P0 | ✅前端已改路径；后端 main.py 去掉重复 prefix（待重启生效） |

#### Q-28 附：前后端 API 路径一致性全量探活清单（2026-09-14 扫描，待统一处理）

后端 8000 端口实探，前端活跃代码调用的路径分类如下：

**A 类：后端 prefix 重复拼接（已改 main.py，待重启后端即通）**
- 现象：`file_library_routes.py` 自带 `prefix="/api/v1/fl"`，`main.py` 第146行 include 又加 `prefix="/api/v1"`，FastAPI 拼接成 `/api/v1/api/v1/fl/*`
- 影响路由：`/api/v1/fl/list`、`/upload`、`/download/{id}`、`/files/batch-tag`、`/stats`、`/duplicates/*`
- 同样问题：`/api/v1/fl_bridge/*`（fl_bridge_routes.py 自带 prefix + include 重复）
- 处置：main.py 已删 include 的 `prefix="/api/v1"`，重启后 `/api/v1/fl/*` 直连

**B 类：前端调错路径（file-library.js 已改，其他文件待统一）**
- `/api/common/file-library/*` → 应 `/api/v1/fl/*`（file-library.js 7处已改；旧文件 file_library.js 还在调，待确认是否废弃）
- `/api/resource/upload_batch` → 应 `/api/v1/fl/upload`（file-library.js 已改；app_v3_897262.js、resource.js、check_js.js 仍在调）

**C 类：路径待核实（后端路由可能不存在或路径不同，需逐个核对）**
- `/api/v1/flashcard`（mt.js 调用，404）
- `/api/v1/lecture/`（resource.js 调用，404）
- `/api/v1/rag/chat`、`/search`、`/incremental_update`（knowledge_base.js 调用，404）
- `/api/v1/sync`（sync.js 调用，404；后端实际可能在 /api/v1/offline_sync/*）
- `/api/common/system/health`（settings.js、resource.js 调用，404）
- `/api/common/system/all_subjects`（check_js.js 调用，404）
- `/api/app/version`、`/api/version`（app_v3_897262.js 调用，404）

**正常项（无需处理）**：`/api/qb/questions`、`/api/qb/chapter-tree`、`/api/resource/videos/list`、`/api/v1/knowledge-graph/*`、`/api/v1/preprocess-config/*`、`/api/health`、`/api/supervisor/status` 均 200/401/405（401=需登录、405=GET测POST接口）。

**待办**：重启后端验证 A 类；核对 C 类后端真实路由后统一改前端；确认 app_v3_897262.js / check_js.js 是否废弃文件，废弃则忽略。

### 7.3 数据质量-答案不匹配类（6项，P0优先级）

| 编号 | 问题描述 | 涉及题目 | 优先级 | 状态 |
|------|---------|---------|--------|------|
| Q-10 | 题目与年份有问题，2020年经济分析和财务分析的区别，答案与解析不匹配 | 2020年经济分析vs财务分析 | P0 | ❌待修复 |
| Q-16 | 2020年某工程有4个施工过程，划分为5个施工段组织加快成倍，答案不匹配 | 2020年加快成倍流水 | P0 | ❌待修复 |
| Q-17 | 2020年下列项目中，减按15%的税率征收企业所得税的项目是，选项不对、解析不对，年份标签不对 | 2020年企业所得税15% | P0 | ❌待修复 |
| Q-19 | 2020按照价值工程的工作程序，对价值工程应用对象进行功能定义，属于XX阶段的工作内容，答案有问题 | 2020年价值工程功能定义阶段 | P0 | ❌待修复 |
| Q-20 | 2020建设工程组织流水施工时，用来表达流水施工在施工工艺方面进展状态的参数，答案与解析不一致 | 2020年流水施工工艺参数 | P0 | ❌待修复 |
| Q-23 | 某工程双代号时标网络图计划如下图所示，由此可以判断出（）无图，选项混入d、e正确 | 双代号时标网络图 | P0 | ❌待修复 |

### 7.4 数据质量-格式混乱类（7项，P1优先级）

| 编号 | 问题描述 | 涉及题目 | 优先级 | 状态 |
|------|---------|---------|--------|------|
| Q-05 | 2022年27、28、29题目混在一起 | 2022年第27-29题 | P1 | ❌待修复 |
| Q-06 | 存在多选题只有4个选项，土地使用权分摊费用 | 土地使用权分摊费用 | P1 | ❌待修复 |
| Q-14 | 2024年建设工程造价咨询合同选项C、D在一行，正确答案ABE | 2024年造价咨询合同 | P1 | ❌待修复 |
| Q-22 | 某工程划分三个施工过程这个题，没有显示表格 | 三个施工过程流水 | P1 | ❌待修复 |
| Q-24 | 2023年，某公司在5年内每年初投资1000万元，若年利率为10%，选项里面混着学员专用 | 2023年资金时间价值 | P1 | ❌待修复 |
| Q-27 | 下列工程项目策划内容中，属于工程项目实施过程策划的是，包含习题4 | 工程项目实施过程策划 | P1 | ❌待修复 |
| Q-19附 | 还有"学员专用 请勿外泄"字样 | 多题 | P1 | ❌待清理 |

### 7.5 数据质量-广告/杂质类（3项，P1优先级）

| 编号 | 问题描述 | 涉及题目 | 优先级 | 状态 |
|------|---------|---------|--------|------|
| Q-09 | 价值工程应用中方案穿凿可采用的方法，解析有广告 | 价值工程方案创造方法 | P1 | ❌待清理 |
| Q-29 | 解析里面有课后回顾总结及广告 | 多题 | P1 | ❌待清理 |
| Q-25 | 进行某建设项目不确定性分析时，用生产能力利用率表示的盈亏平衡点为40%，题目重复 | 盈亏平衡点40% | P1 | ❌待去重 |

### 7.6 数据质量-标签/年份类（3项，P1优先级）

| 编号 | 问题描述 | 涉及题目 | 优先级 | 状态 |
|------|---------|---------|--------|------|
| Q-26 | 年份和标签重复 | 多题 | P1 | ❌待清理 |
| Q-28 | 真题没有年份 | 多题 | P1 | ❌待补全 |
| Q-17附 | 年份标签不对 | 2020年企业所得税 | P1 | ❌待修复 |

### 7.7 知识点口诀（1项，P2优先级）

| 编号 | 内容 | 优先级 | 状态 |
|------|------|--------|------|
| Q-21 | 工艺参数口诀：施工过程、流水强度（过度）；空间参数：工作面、施工段（面段） | P2 | ❌待录入知识库 |

### 7.8 问题分类统计

| 分类 | 数量 | P0 | P1 | P2 |
|------|------|-----|-----|-----|
| UI交互问题 | 5 | 4 | 1 | 0 |
| 数据缺失类 | 6 | 6 | 0 | 0 |
| 答案不匹配类 | 6 | 6 | 0 | 0 |
| 格式混乱类 | 7 | 0 | 7 | 0 |
| 广告杂质类 | 3 | 0 | 3 | 0 |
| 标签年份类 | 3 | 0 | 3 | 0 |
| 知识点口诀 | 1 | 0 | 0 | 1 |
| **合计** | **31** | **16** | **14** | **1** |

### 7.9 修复计划

**第一阶段（立即修复，UI交互）**：
- Q-01 取消选择底纹残留
- Q-12 刷题记录显示与清除
- Q-15 解析换行显示
- Q-18 解析滚动问题

**第二阶段（数据排查，缺失类）**：
- Q-02/Q-03/Q-04 全局排查缺选项/缺解析/缺图的题目
- Q-07/Q-08/Q-11 特定题目补全解析和图片

**第三阶段（数据修复，答案不匹配）**：
- Q-10/Q-16/Q-17/Q-19/Q-20/Q-23 逐题核对答案与解析

**第四阶段（数据清理，格式/广告/标签）**：
- 全局清理"学员专用"、广告、课后总结等杂质
- 修复题目混排、选项在一行、缺表格等格式问题
- 补全年份标签，去重

**第五阶段（功能增强）**：
- Q-13 草稿模式
- Q-21 知识点口诀录入


============================================================
# § 6. 【来源：代码审查流程规范.md】
============================================================

# 代码审查流程规范

> **生效日期**：2026-09-11
> **适用范围**：水利智学系统所有代码修改
> **宪法依据**：第三十七章 问题判定与预防体系、25.7同步修改铁律

---

## 一、审查触发条件

任何代码修改必须经过审查，满足以下任一条件即触发：

| 级别 | 触发条件 | 审查要求 |
|------|---------|---------|
| **P0 重大** | 修改≥5个核心模块 / 涉及数据库表结构 / 涉及AI核心功能 / 涉及多端同步 | 3位专家联合审查 |
| **P1 重要** | 修改≥2个文件 / 涉及核心功能（题库/闪卡/导图） / 涉及API接口变更 | 2位专家审查 |
| **P2 常规** | 修改1个文件 / 不涉及核心功能 / ≤50行代码 | 1位专家审查 |
| **P3 微小** | 注释/文档/配置修改 / ≤10行代码 | 自审+静态检查通过 |

---

## 二、审查流程

### 2.1 修改前审查
1. **影响分析**：运行 `python tools/impact_analyzer.py` 评估影响范围
2. **同步清单**：根据宪法25.7列出所有需要同步修改的关联文件
3. **备份确认**：P0/P1修改必须先做黄金备份
4. **方案确认**：复杂修改必须先出方案，用户确认后再执行

### 2.2 修改中审查
1. **增量修改**：禁止全量替换，必须增量修改
2. **同步执行**：按联动清单逐一修改，每改完一个标记
3. **实时验证**：每完成一个文件立即验证语法正确性

### 2.3 修改后审查（必过清单）
- [ ] **静态检查**：`python tools/static_check.py` 无error级问题
- [ ] **语法验证**：所有修改的JS文件 `node -c` 通过，Python文件 `py_compile` 通过
- [ ] **同步验证**：所有关联文件已同步修改（用 `fast_search.py` 搜索引用点）
- [ ] **功能验证**：浏览器实际运行验证，提供截图证据
- [ ] **缓存清除**：静态文件版本号已更新，SW缓存已清除
- [ ] **备份验证**：修改前备份完整可恢复
- [ ] **文档更新**：宪法/规划细则/修改日志已同步更新

---

## 三、审查重点检查项

### 3.1 路径规范（宪法37.7）
- ❌ 禁止相对路径：`data/offline/`、`static/`、`./`、`../`
- ✅ 必须绝对路径：`/static/data/offline/`、`/static/js/`

### 3.2 样式规范（宪法N.8.3）
- ❌ 禁止内联style
- ❌ 禁止硬编码颜色（#xxx）
- ❌ 禁止硬编码px尺寸（建议用CSS变量）
- ✅ 必须使用CSS类名，写入V2 CSS

### 3.3 同步修改规范（宪法25.7）
- 修改 `core/*.js` 必须检查所有依赖模块
- 修改 `style.css` 必须同步 `style.min.css`
- 修改API必须同步所有前端调用点
- 修改数据库表结构必须同步前后端数据模型

### 3.4 废弃引用检查
- ❌ 禁止引用已废弃的 `app.js` / `app_v3_*.js`
- ❌ 禁止使用已删除的函数

---

## 四、审查工具

| 工具 | 用途 | 命令 |
|------|------|------|
| static_check.py | 静态代码检查 | `python tools/static_check.py` |
| fast_search.py | 引用点搜索 | `python tools/fast_search.py search <关键词>` |
| impact_analyzer.py | 影响范围分析 | `python tools/impact_analyzer.py` |
| code_health_check.py | 代码健康度 | `python tools/code_health_check.py` |
| execution_guard.py | 备份与验证 | `python tools/execution_guard.py verify` |

---

## 五、违规处理

| 违规行为 | 处罚 |
|---------|------|
| 未做影响分析直接修改 | 记1次严重违规 |
| 遗漏关联文件同步修改 | 记1次严重违规 |
| 未通过静态检查就交付 | 记2次严重违规 |
| 因审查遗漏导致用户反馈问题 | 记2次严重违规 |
| 3次严重违规 | 专家团重组，流程重审 |

---

## 六、审查记录模板

每次审查必须记录：

```
【代码审查记录】
日期：YYYY-MM-DD
修改人：XXX
审查人：XXX
修改内容：XXX
影响范围：XXX个文件，XXX个模块
联动文件：已全部同步 ✅ / 有遗漏 ❌
静态检查：通过 ✅ / 未通过 ❌
功能验证：通过 ✅ / 未通过 ❌
审查结论：通过 / 打回修改
```

记录保存位置：`data/code_review/`


============================================================
# § 7. 【来源：功能缺失补全操作指导手册.md】
============================================================

# 📖 功能缺失补全操作指导手册（SOP）
> 版本 V1.0 ｜ 2026-09-13 ｜ 挂载：总控第11章索引 + 开工必读 + 专家工作框架。
> 用途：任何对话框发现"旧版有、新版缺"的功能，照本手册走，不许凭感觉改。

---

## 一、适用范围
新旧对比揪出的两类项：
- ❌ **严重缺失**：新版根本没有该模块/功能（如题库管理后台、AI扫描）。
- ⚠️ **部分缺失**：新版有但缺子功能（如闪卡缺朗读/算法、错题本缺导出）。

来源清单：`docs/模块化拆分缺失功能完整清单.md`、`docs/全面代码对比报告.md`。

---

## 二、五步操作流程（强制，不许跳步）

### 第1步：登记缺失（先写后改）
按模板填一行，追加到 `docs/功能缺失登记台账.md`（没有则建）：
| 字段 | 写法 |
|---|---|
| 模块 | 如 flashcard |
| 旧代码位置 | api/v1/flashcard.py 第X行 / app_v3.js 函数名 |
| 新代码位置 | frontend/modules/flashcard.js / modules/对应后端 |
| 缺什么 | 一句话说清功能 |
| 定级 | P0/P1/P2/P3 |
| 状态 | 待办/进行中/已补/已验收 |

### 第2步：定级（决定先补谁）
沿用 `docs/功能融合计划.md`：
- **P0 核心**：刷题判分、登录认证、闪卡核心（SM-2/朗读）——43天倒计时内必须成。
- **P1 重要**：资料库打标签、视频笔记、收藏/笔记导出。
- **P2 辅助**：学习看板、知识库图谱、思维导图、记忆训练。
- **P3 系统**：设置、题库管理CRUD、模拟考试组卷、AI拍照、数据分析。

### 第3步：补全（改代码）
1. 完整读旧代码对应函数，复制其业务逻辑。
2. 在新模块**用方法扩展**实现，不改HTML结构、不动CSS布局。
3. 前端API路径不变、零数据迁移（新旧用同一批表）。
4. 新模块没写完前，旧API继续兜底。
5. **改前备份**当前文件；改完立即验证语法。

### 第4步：验收
1. 后端：语法检查通过。
2. 前端：浏览器打开对应页面，逐项点一遍该功能。
3. 质量组按用例过；不通过打回，通过才在台账标"已验收"。

### 第5步：留痕
在 `项目工作基准_开工必读.md` 会话流水追加一行：补了哪个缺失、改了哪些文件、当前进度。

---

## 三、铁律（碰了就回滚）
- 🔴 布局锁死：竖向导航/顶部导航/底部状态栏/登录界面，绝对不动。
- 🔴 刷题逻辑：单选选了出解析，多选提交才出解析；4选项=单选，5选项=多选。
- 🔴 科目简称全局统一：一造管理、一造水利案例、一造计价…
- 🔴 零数据迁移、前端API路径不变、旧API兜底。
- 🔴 所有分析先写进文件，不靠对话记忆。

---

## 四、当前缺失全景（摘自缺失清单，优先级从高到低）
- ❌ 闪卡：朗读专练、SM-2算法、艾宾浩斯间隔、卡片CRUD、导入导出、AI口诀
- ❌ 知识库：增删改、关联、知识图谱
- ❌ 思维导图：节点增删改、展开折叠
- ❌ 记忆训练：九大记忆法全功能
- ❌ 系统设置：全部设置项
- ❌ 题库管理后台（question_manager 无对应模块）
- ❌ AI拍照解题（ai_scan 无对应模块）
- ⚠️ 错题本/收藏/笔记：按章节筛选、导出
- ⚠️ 学习分析：图表可视化


============================================================
# § 8. 【来源：功能融合计划.md】
============================================================

# 功能融合计划（布局锁死，只加功能不改布局）

## 核心原则
1. **布局全局锁死**：不改任何HTML结构、CSS布局、页面切换逻辑
2. **功能只增不减**：把旧版有的功能全部融合进来
3. **模块化**：每个模块独立文件，通过方法扩展

---

## 模块优先级清单

### P0 - 已完成验证
- [x] 题库刷题：单选判分、多选提交、键盘快捷键、AI解析
- [x] 闪卡：朗读TTS、磨耳朵、公式专练、AI生成
- [x] 错题本：导出CSV、统计、AI分析

### P1 - 核心业务模块（优先）
- [ ] 文件资料库：批量打标签、标签管理、文件夹操作
- [ ] 视频讲义：智能笔记、播放控制、收藏
- [ ] 我的收藏：导出CSV、批量管理
- [ ] 学习笔记：导出Markdown、章节筛选

### P2 - 辅助学习模块
- [ ] 学习看板：恢复原有统计卡片
- [ ] 知识库：知识图谱、CRUD
- [ ] 思维导图：AI生成、导出
- [ ] 记忆训练：7个专项、3种题型

### P3 - 管理与系统模块
- [ ] 系统设置：语音、备份、通知
- [ ] 题库管理：题目CRUD、导入导出
- [ ] 模拟考试：组卷、交卷、评分
- [ ] AI拍照解题：OCR识别、题目匹配
- [ ] 冲刺中心：学习计划、进度跟踪
- [ ] 数据分析：薄弱点分析、正确率统计
- [ ] 系统管理中心：数据质量、操作日志

---

## 融合策略
1. 每个模块先读旧版代码，找出所有功能函数
2. 按优先级逐一迁移核心功能
3. 确保不改变现有布局结构
4. 每个功能添加后立即验证语法
5. 最终在浏览器中逐一验证功能是否生效


============================================================
# § 9. 【来源：模块化拆分缺失功能完整清单.md】
============================================================

# 模块化拆分缺失功能完整清单

> 生成时间：2026-09-11
> 对比基准：旧版 `app_v3_897262.js` vs 新版 `frontend/modules/`

---

## 一、旧版19个页面对照

| 序号 | 旧版页面 | 新版模块 | 状态 | 缺失功能 |
|------|---------|---------|------|---------|
| 1 | dashboard | dashboard.js | ✅ 有 | 学习趋势（已整合到日历） |
| 2 | question | question-practice.js | ⚠️ 部分 | 答题卡/交卷/评分（已补）、章节练习、笔记 |
| 3 | exam | mock-exam.js | ✅ 有 | 基本完整 |
| 4 | video | video.js | ✅ 有 | 基本完整 |
| 5 | file_library | file-library.js | ✅ 有 | 移动/复制/分享功能 |
| 6 | flashcard | flashcard.js | ❌ 严重缺失 | 见下方详细清单 |
| 7 | wrong | wrong-book.js | ⚠️ 部分 | 删除/标记掌握（已补）、按章节筛选、导出 |
| 8 | collect | collect.js | ⚠️ 部分 | 按章节/按类型筛选 |
| 9 | knowledge_base | knowledge.js | ❌ 严重缺失 | 添加/编辑/删除/关联/图谱 |
| 10 | mindmap | mindmap.js | ❌ 严重缺失 | 节点/展开/折叠/编辑 |
| 11 | note | note.js | ⚠️ 部分 | 添加/按题目/按章节 |
| 12 | material | material.js | ⚠️ 部分 | 下载 |
| 13 | sprint | sprint.js | ⚠️ 部分 | 学习日历 |
| 14 | learning_analytics | analytics.js | ⚠️ 部分 | 图表可视化 |
| 15 | settings | settings.js | ❌ 严重缺失 | 全部设置项 |
| 16 | system_admin | system-admin.js | ⚠️ 部分 | 日志 |
| 17 | memory_train | memory.js | ❌ 严重缺失 | 九大记忆法全部功能 |
| 18 | question_manager | 无 | ❌ 缺失 | 题库管理后台 |
| 19 | ai_scan | 无 | ❌ 缺失 | AI扫描识别 |

---

## 二、闪卡模块缺失功能（最严重）

### 核心功能
- ❌ **朗读记忆专练**（TTS语音朗读全部闪卡）
- ❌ **公式专练**（纯数字/公式类卡片专项）
- ❌ **艾宾浩斯复习算法**（1/2/4/7/15天间隔重复）
- ❌ **SM-2评分算法**（记住了/模糊/没记住 → 自动调整间隔）
- ❌ **闪卡管理**（新建/编辑/删除卡片）
- ❌ **闪卡导入导出**（CSV/JSON/TXT模板）
- ❌ **搜索闪卡**
- ❌ **按章节筛选闪卡**
- ❌ **按标签筛选闪卡**

### AI功能
- ❌ **AI生成记忆口诀**（谐音/联想/场景记忆）
- ❌ **AI自动生成闪卡**（从题目/知识点生成）
- ❌ **记忆口诀编辑**

### 语音功能
- ❌ **TTS语音播报设置**（语速/语音选择/设备选择）
- ❌ **自动朗读开关**
- ❌ **朗读语速调节**
- ❌ **后端TTS（edge-tts）**
- ❌ **浏览器语音合成降级**
- ❌ **音频设备选择器**

### 统计功能
- ❌ **今日需复习数量**
- ❌ **累计复习数量**
- ❌ **复习进度**
- ❌ **到期提醒**

---

## 三、记忆训练模块缺失功能

### 九大记忆法
- ❌ **记忆宫殿法**（空间定位法）
- ❌ **谐音记忆法**
- ❌ **联想记忆法**
- ❌ **组块记忆法**
- ❌ **口诀记忆法**
- ❌ **图像记忆法**
- ❌ **多感官记忆法**
- ❌ **费曼学习法**
- ❌ **间隔重复法**

### 专项训练
- ❌ **数字记忆训练**
- ❌ **法规数字记忆**
- ❌ **经济公式记忆**
- ❌ **造价构成记忆**
- ❌ **易混淆名词记忆**

---

## 四、题库练习缺失功能

- ❌ **章节练习**（按章节组卷）
- ❌ **答题卡**（已补）
- ❌ **交卷评分**（已补）
- ❌ **题目笔记**（在题目上直接记笔记）
- ❌ **题目收藏标签**
- ❌ **做题草稿**（已补）
- ❌ **答题卡跳转**（已补）
- ❌ **成绩分析**（正确率/用时/薄弱点）

---

## 五、错题本缺失功能

- ❌ **删除错题**（已补）
- ❌ **标记掌握/取消掌握**（已补）
- ❌ **按章节筛选**
- ❌ **按知识点筛选**
- ❌ **错题统计**（各章节错误率）
- ❌ **导出错题**
- ❌ **错题重练**（一键重练所有错题）
- ❌ **艾宾浩斯复习提醒**

---

## 六、学习资料库缺失功能

- ❌ **移动文件**
- ❌ **复制文件**
- ❌ **分享文件**
- ❌ **文件大小显示**（已有字段但界面未展示）
- ❌ **上传时间显示**（已有字段但界面未展示）
- ❌ **批量下载**
- ❌ **文件夹创建/重命名/删除**

---

## 七、知识库缺失功能

- ❌ **添加知识点**
- ❌ **编辑知识点**
- ❌ **删除知识点**
- ❌ **知识点关联**
- ❌ **知识图谱可视化**
- ❌ **知识点搜索**
- ❌ **按章节浏览**

---

## 八、思维导图缺失功能

- ❌ **节点编辑**
- ❌ **展开/折叠节点**
- ❌ **添加子节点**
- ❌ **删除节点**
- ❌ **导出为图片**
- ❌ **AI自动生成思维导图**

---

## 九、笔记模块缺失功能

- ❌ **添加笔记**
- ❌ **按题目关联笔记**
- ❌ **按章节浏览笔记**
- ❌ **笔记搜索**
- ❌ **笔记朗读**

---

## 十、设置模块缺失功能

- ❌ **语音播报设置**
- ❌ **数据备份/恢复**
- ❌ **账号设置**
- ❌ **主题切换**
- ❌ **字体大小调节**
- ❌ **清除缓存**

---

## 十一、优先级排序

### P0（核心功能，影响使用）
1. 闪卡朗读记忆专练（TTS）
2. 闪卡艾宾浩斯复习算法
3. 闪卡新建/编辑/删除
4. 题库章节练习
5. 知识库CRUD

### P1（重要功能，影响体验）
6. 记忆训练九大记忆法
7. 错题本按章节筛选
8. 笔记添加/按题目关联
9. 思维导图节点编辑
10. 设置模块语音设置

### P2（增强功能）
11. 学习资料库移动/复制
12. 闪卡导入导出
13. 思维导图AI生成
14. 数据分析图表可视化
15. 题库管理后台

---

## 统计

| 类别 | 数量 |
|------|------|
| 旧版总页面 | 19个 |
| 新版有对应模块 | 17个 |
| 完全缺失页面 | 2个（question_manager, ai_scan） |
| 严重缺失功能模块 | 4个（flashcard, memory_train, knowledge_base, settings） |
| 总计缺失功能点 | 约120+项 |
| 已补功能点 | 约15项 |
| 剩余待补 | 约105项 |


============================================================
# § 10. 【来源：全局状态清单.md】
============================================================

# 全局状态清单（P2-01 状态治理）

> 依据《系统设计宪法V2.6》第2章状态治理规范
> 生成时间：2026-09-06
> 维护原则：跨模块共享状态→window.store；模块内部UI状态→模块_state

## 一、window.store 共享状态（跨模块读写）

| 状态键 | 类型 | 说明 | 读写模块 |
|--------|------|------|----------|
| currentSubject | string | 当前科目（简称） | 全部模块 |
| currentMajor | string | 当前大专业（简称） | 全部模块 |
| userInfo | object | 用户信息 | 登录/设置 |
| examConfig | object | 考试配置 | 登录/看板 |
| settings | object | 全局设置 | 设置模块 |
| isOnline | boolean | 在线状态 | 同步/离线 |
| serverTime | string | 服务器时间 | 全部模块（P3-03） |

## 二、模块内部状态（_state，不跨模块）

### qbModule（题库管理）
| 状态 | 类型 | 说明 |
|------|------|------|
| _state.currentPage | number | 当前分页 |
| _state.filter | object | 筛选条件 |
| _state.selectedIds | array | 选中题目ID |
| _state.editingQuestion | object | 编辑中题目 |

### mtModule（记忆训练）
| 状态 | 类型 | 说明 |
|------|------|------|
| _state.currentCard | object | 当前闪卡 |
| _state.reviewQueue | array | 复习队列 |
| _state.trainingMode | string | 训练模式 |
| _state.stats | object | 统计数据 |

### mmModule（思维导图）
| 状态 | 类型 | 说明 |
|------|------|------|
| _state.currentMapId | number | 当前导图ID |
| _state.editorInstance | object | 编辑器实例 |
| _state.filter | string | 章节筛选 |

### fileLibraryModule（学习资料库）
| 状态 | 类型 | 说明 |
|------|------|------|
| _state.currentTab | string | 当前tab |
| _state.currentFolder | string | 当前文件夹 |
| _state.selectedFiles | array | 选中文件 |
| _state.filterTags | array | 标签筛选 |

### aiModule（AI识别）
| 状态 | 类型 | 说明 |
|------|------|------|
| _state.ollamaStatus | string | Ollama状态 |
| _state.currentTask | object | 当前识别任务 |

## 三、app.js/resource.js 遗留全局变量（80个冲突）

### 3.1 常量（7个，只读，不迁移）
- DEMO_FORMULAS, EXAM_MEMORY_TRAINING, MEMORY_METHODS
- MEMORY_TRAINING_DATA, SCHEDULE_TEMPLATES, SUBJECT_COLORS, YUNNAN_ACCENT_CONFIG

### 3.2 模块内部状态（_开头，约60个，后续下沉到模块_state）
- 公式训练：_formulaIndex, _formulaMode, _formulaCurrentAnswer等（10个）
- 记忆训练：_currentTraining, _trainingIndex, _trainingScore等（8个）
- 视频播放：_localVideoList, _playlistFullList, _playerLectureList等（10个）
- 笔记编辑：_noteEditor, _noteToolbar, _noteChapter等（5个）
- PDF标记：_currentMarkType, _currentMaterialId, _marksData等（5个）
- 思维导图：_mindElixirInstance, _mmPreviewInstance, _mmSummaryData等（8个）
- AI识别：_aiHistoryCache, _aiScanChapter, _wmResultBlob等（5个）
- 其他：_autoSpeak, _ttsAudio, _syncScrolling等（9个）

### 3.3 跨模块共享变量（需迁移到window.store，约13个）
| 变量 | 说明 | 目标store键 |
|------|------|-------------|
| currentMindmapId | 当前导图ID | mm.currentMapId |
| currentNoteId | 当前笔记ID | note.currentId |
| bgAudio | 背景音乐 | audio.bgInstance |
| fatigueTimer | 疲劳计时器 | timer.fatigue |
| focusInterval | 专注计时器 | timer.focus |
| focusSeconds | 专注秒数 | timer.focusSeconds |
| searchTimer | 搜索防抖 | timer.search |
| studyStart | 学习开始时间 | study.startTime |
| studyAlertShown | 学习提醒已显示 | study.alertShown |
| touchStartX | 触摸起始X | ui.touchStartX |
| mergeLayoutDirection | 合并布局方向 | ui.mergeDirection |
| _acObserver | 自动滚动观察者 | ui.acObserver |
| _sylAutoRefreshTimer | 大纲自动刷新 | timer.sylRefresh |

## 四、状态治理规则

1. **新增状态必须先评估归属**：跨模块用store，模块内部用_state
2. **禁止新增业务级裸全局变量**：所有新状态必须入store或模块_state
3. **遗留变量逐步迁移**：80个冲突变量按优先级分批迁移，每批验证
4. **store读写统一接口**：window.store.get(key) / window.store.set(key, value)
5. **状态变更通知**：store变更通过eventBus.emit('state:change', {key})通知

## 五、迁移优先级

| 优先级 | 变量组 | 数量 | 预计风险 |
|--------|--------|------|----------|
| P0 | 定时器类（fatigueTimer/focusInterval等） | 5 | 中（内存泄漏） |
| P1 | 跨模块ID（currentMindmapId/currentNoteId） | 2 | 低 |
| P2 | 音频/UI状态（bgAudio/touchStartX等） | 6 | 中 |
| P3 | 模块内部_state下沉 | 60 | 高（需逐个验证） |
| P4 | 常量提取到constants.js | 7 | 高（值复杂） |

---
*本清单随系统迭代持续更新*


============================================================
# § 11. 【来源：全面代码对比报告.md】
============================================================

# 全面代码对比与功能迁移状态报告
# 生成时间：2026-09-11
# 范围：全部24个前端模块

## 一、模块总览

| 模块 | 文件大小 | 方法数 | 事件绑定 | 状态 |
|------|---------|--------|---------|------|
| file-library.js | 61.7KB | 27 | ✅ 有内容 | 核心模块，持续完善中 |
| flashcard.js | 41.2KB | 9 | ✅ 有内容 | 已补全Tab切换+批量导入 |
| mock-exam.js | 37.9KB | 14 | ✅ 有内容 | 功能完整 |
| question-practice.js | 32.7KB | 10 | ✅ 有内容 | 功能完整 |
| video.js | 24.8KB | 11 | ✅ 有内容 | 已重写，三Tab+文件夹分组 |
| mindmap.js | 22.9KB | 5 | ✅ 有内容 | 功能完整 |
| dashboard.js | 18.7KB | 7 | ✅ 有内容 | 功能完整 |
| analytics.js | 21.8KB | 5 | ✅ 有内容 | 功能完整 |
| knowledge.js | 17.9KB | 9 | ✅ 有内容 | 功能完整 |
| material.js | 15KB | 6 | ✅ 有内容 | 功能完整 |
| photo-solve.js | 13.1KB | 14 | ✅ 有内容 | 功能完整 |
| memory.js | 12.3KB | 3 | ❌ 空 | 可点击元素无事件 |
| note.js | 11.7KB | 6 | ✅ 有内容 | 功能完整 |
| wrong-book.js | 12KB | 7 | ✅ 有内容 | 功能完整 |
| settings.js | 28.2KB | 8 | ✅ 有内容 | 功能完整 |
| system-admin.js | 8.9KB | 5 | ❌ 空 | 注释"暂无交互事件" |
| collect.js | 8.5KB | 5 | ❌ 空 | 搜索/导出/题目点击无事件 |
| sprint.js | 7.8KB | 3 | ❌ 空 | 快捷入口无事件 |
| question-manager.js | 9.8KB | 6 | ✅ 有内容 | 功能完整 |
| topbar.js | 10.9KB | 7 | ✅ 有内容 | 功能完整 |
| sidebar.js | 6.7KB | 6 | ✅ 有内容 | 功能完整 |
| module-nav.js | 3.5KB | 5 | ✅ 有内容 | 功能完整 |
| statusbar.js | 3KB | 5 | ❌ 空 | 纯展示，可能不需要 |
| hello-demo.js | 4.3KB | 6 | ✅ 有内容 | 演示模块 |

## 二、file-library模块功能对比详情

### 已迁移功能（22项）
1. ✅ Tab切换（全部/视频讲义/大纲教材）
2. ✅ 数据加载（/fl/list + /video/list）
3. ✅ 文件夹树构建
4. ✅ 文件列表渲染
5. ✅ 上下布局（文档上/视频下）
6. ✅ 文件夹展开/收起
7. ✅ 文件选择/全选
8. ✅ 批量识别题库
9. ✅ 批量生成闪卡
10. ✅ 批量生成导图
11. ✅ 批量删除（API已修复为/fl）
12. ✅ 单文件标签面板（3组18个标签）
13. ✅ 文件夹标签面板
14. ✅ 标签保存到后端API
15. ✅ 标签管理库
16. ✅ 文件上传
17. ✅ 文件夹导入
18. ✅ 搜索过滤
19. ✅ 文件重命名
20. ✅ 文件删除（API已修复为/fl）
21. ✅ 文件预览（已添加）
22. ✅ 文件夹标签批量保存

### 缺失功能（8项）
1. ❌ 单文件识别题库（recognizeQuestion）
2. ❌ 单文件生成导图（generateMindmap）
3. ❌ 标签颜色（getTagColor）
4. ❌ 状态颜色（getStatusColor）
5. ❌ 视频讲义专用渲染（视频+讲义左右同步）
6. ❌ 类型/状态筛选（changeFilter）
7. ❌ 分页功能（nextPage/prevPage）
8. ❌ 批量标签模态框（showBatchTagModal）

### 可省略功能（4项）
1. ⚪ showUploadModal - 原生input已够用
2. ⚪ showScanModal - folderUpload已实现
3. ⚪ setFileTag/batchTagFolder - 标签面板已替代
4. ⚪ editTags/editFile - 标签面板已替代

## 三、事件绑定缺失模块详情

### 1. collect.js（我的收藏）- 高优先级
**可点击元素**：
- 搜索按钮（🔍 搜索）
- 导出按钮（📤 导出）
- 题型筛选下拉框
- 搜索输入框
- 题目列表项（点击查看详情）
- 取消收藏按钮

**缺失功能**：
- 搜索功能
- 导出功能
- 题型筛选
- 题目详情查看
- 取消收藏

### 2. memory.js（记忆训练）- 中优先级
**可点击元素**：
- 9大记忆法卡片（间隔重复法、主动回忆法等）
- 4个记忆工具（口诀生成、复习计划、记忆曲线、关键词）
- 考试专项记忆训练
- "全部→"链接
- "↓9种"链接

**缺失功能**：
- 记忆法详情查看
- 工具功能调用
- 专项训练入口

### 3. sprint.js（冲刺中心）- 高优先级
**可点击元素**：
- 4个快捷入口（真题模考、错题重练、高频考点、AI智能出题）
- 薄弱考点列表项
- 高频考点列表项

**缺失功能**：
- 快捷入口跳转（真题模考→mock-exam，错题重练→wrong-book）
- 考点点击进入练习

### 4. system-admin.js（系统管理）- 低优先级
**状态**：注释"暂无交互事件"，可能是纯展示模块

### 5. statusbar.js（状态栏）- 低优先级
**状态**：纯展示模块，可能不需要事件绑定

## 四、其他潜在问题

### 1. API路径一致性
- file-library.js：已修复删除API为/fl
- 其他模块：需检查是否使用了正确的API路径

### 2. 数据来源一致性
- file-library.js：使用/fl/list（含tags）
- 其他模块：需检查是否使用了正确的数据来源

### 3. 认证机制
- 已创建core/api.js通用API封装
- 需检查所有模块是否统一使用window.api

## 五、优先级排序

### P0 - 立即修复（影响核心功能）
1. file-library缺失的8项功能
2. collect.js事件绑定（搜索/导出/题目点击）
3. sprint.js事件绑定（快捷入口跳转）

### P1 - 尽快修复（影响用户体验）
4. memory.js事件绑定（记忆法/工具点击）
5. 标签颜色/状态颜色显示

### P2 - 后续优化（不影响核心功能）
6. 分页功能
7. 视频讲义专用渲染
8. system-admin.js交互功能

## 六、已完成工作记录

### 本轮已完成
1. ✅ 全面对比旧代码与新代码（file-library 30方法 vs 27方法）
2. ✅ 检查全部24个模块的事件绑定状态
3. ✅ 发现5个模块bindEvents为空
4. ✅ 识别3个真正需要修复的模块（collect/memory/sprint）
5. ✅ 修复file-library删除API路径（/material→/fl）
6. ✅ 添加file-library文件预览功能
7. ✅ 扩展标签库为3组18个标签
8. ✅ 创建需求登记系统

### 之前已完成
1. ✅ 学习资料库数据来源修正（/fl/list）
2. ✅ 上下布局调整
3. ✅ 标签体系完整迁移
4. ✅ 批量操作功能迁移
5. ✅ core/api.js创建
6. ✅ fl_bridge.js引用


============================================================
# § 12. 【来源：设计规范_V2.0.md】
============================================================

# 水利智学系统 设计规范 V2.0
## （设计系统专家 + 高级UX/UI设计师 + 前端架构师 联合制定）

---

## 一、设计Token体系（全局唯一来源）

### 1.1 颜色Token

| Token | 亮色 | 暗色 | 用途 |
|-------|------|------|------|
| `--primary` | #1a73e8 | #1a73e8 | 主色、按钮、链接 |
| `--primary-light` | #e8f0fe | #1e3a5f | 主色浅背景 |
| `--primary-bg` | #f0f7ff | #0c1929 | 主色极浅背景 |
| `--success` | #10b981 | #10b981 | 成功、正确 |
| `--success-light` | #d1fae5 | #064e3b | 成功浅背景 |
| `--warning` | #f59e0b | #f59e0b | 警告、注意 |
| `--warning-light` | #fef3c7 | #78350f | 警告浅背景 |
| `--danger` | #ef4444 | #ef4444 | 危险、错误 |
| `--danger-light` | #fee2e2 | #7f1d1d | 危险浅背景 |
| `--info` | #3b82f6 | #3b82f6 | 信息、提示 |
| `--info-light` | #dbeafe | #1e3a8a | 信息浅背景 |
| `--purple` | #8b5cf6 | #8b5cf6 | 紫色、特殊 |
| `--purple-light` | #ede9fe | #4c1d95 | 紫色浅背景 |
| `--bg` | #f5f7fa | #0f172a | 页面背景 |
| `--bg-secondary` | #eef1f5 | #1e293b | 次级背景 |
| `--card` | #fff | #1e293b | 卡片背景 |
| `--text` | #1f2937 | #e2e8f0 | 主文字 |
| `--text2` | #6b7280 | #94a3b8 | 次级文字 |
| `--text3` | #9ca3af | #64748b | 辅助文字 |
| `--border` | #e5e7eb | #334155 | 边框 |
| `--border-light` | #f0f1f3 | #263449 | 浅边框 |

### 1.2 间距Token（8px基数）

| Token | 值 | 用途 |
|-------|-----|------|
| `--space-1` | 4px | 极小间距 |
| `--space-2` | 8px | 小间距 |
| `--space-3` | 12px | 中间距 |
| `--space-4` | 16px | 标准间距 |
| `--space-5` | 20px | 大间距 |
| `--space-6` | 24px | 更大间距 |
| `--space-8` | 32px | 超大间距 |

### 1.3 字体Token

| Token | 值 | 用途 |
|-------|-----|------|
| `--fs-xs` | 12px | 辅助文字、标签 |
| `--fs-sm` | 14px | 正文、按钮 |
| `--fs-base` | 16px | 标准正文 |
| `--fs-lg` | 18px | 小标题 |
| `--fs-xl` | 20px | 标题 |
| `--fs-2xl` | 24px | 大标题 |
| `--fw-normal` | 400 | 常规 |
| `--fw-medium` | 500 | 中等 |
| `--fw-semibold` | 600 | 半粗 |
| `--fw-bold` | 700 | 粗体 |

### 1.4 圆角Token

| Token | 值 | 用途 |
|-------|-----|------|
| `--radius-xs` | 4px | 极小圆角 |
| `--radius-sm` | 6px | 小圆角 |
| `--radius` | 8px | 标准圆角 |
| `--radius-md` | 10px | 中圆角 |
| `--radius-lg` | 12px | 大圆角 |
| `--radius-xl` | 16px | 超大圆角 |
| `--radius-full` | 9999px | 全圆角 |

### 1.5 阴影Token

| Token | 值 | 用途 |
|-------|-----|------|
| `--shadow-xs` | 0 1px 2px rgba(0,0,0,.04) | 极浅阴影 |
| `--shadow-sm` | 0 1px 3px rgba(0,0,0,.06) | 浅阴影 |
| `--shadow` | 0 2px 8px rgba(0,0,0,.08) | 标准阴影 |
| `--shadow-md` | 0 4px 12px rgba(0,0,0,.1) | 中阴影 |
| `--shadow-lg` | 0 8px 24px rgba(0,0,0,.12) | 大阴影 |
| `--shadow-xl` | 0 12px 32px rgba(0,0,0,.15) | 超大阴影 |

### 1.6 组件高度Token

| Token | 值 | 用途 |
|-------|-----|------|
| `--h-xs` | 28px | 极小按钮 |
| `--h-sm` | 32px | 小按钮 |
| `--h-md` | 36px | 中按钮 |
| `--h-lg` | 40px | 标准按钮 |
| `--h-xl` | 44px | 大按钮 |

---

## 二、组件规范

### 2.1 按钮规范

**基础类**：`.btn`

**变体**：
- `.btn-primary` - 主按钮（蓝色）
- `.btn-secondary` - 次级按钮（灰色）
- `.btn-success` - 成功按钮（绿色）
- `.btn-warning` - 警告按钮（橙色）
- `.btn-danger` - 危险按钮（红色）
- `.btn-info` - 信息按钮（蓝色）
- `.btn-purple` - 紫色按钮
- `.btn-outline` - 描边按钮
- `.btn-outline-primary` - 主色描边按钮
- `.btn-ghost` - 幽灵按钮（透明背景）
- `.btn-link` - 链接按钮

**尺寸**：
- `.btn-xs` - 28px
- `.btn-sm` - 32px
- `.btn-md` - 36px
- `.btn-lg` - 40px（默认）
- `.btn-xl` - 44px

**其他**：
- `.btn-block` - 全宽按钮
- `.btn-group` - 按钮组

**使用示例**：
```html
<button class="btn btn-primary btn-sm">保存</button>
<button class="btn btn-outline btn-danger">删除</button>
<button class="btn btn-ghost">取消</button>
```

### 2.2 卡片规范

**基础类**：`.card`

**变体**：
- `.card-flat` - 扁平卡片（无边框阴影）
- `.card-hover` - 悬浮卡片（鼠标悬浮效果）
- `.card-bordered` - 边框卡片
- `.card-primary` - 左侧主色边框
- `.card-success` - 左侧成功色边框
- `.card-warning` - 左侧警告色边框
- `.card-danger` - 左侧危险色边框

**结构**：
- `.card-header` - 卡片头部
- `.card-title` - 卡片标题
- `.card-body` - 卡片内容
- `.card-footer` - 卡片底部

**使用示例**：
```html
<div class="card card-hover">
  <div class="card-header">
    <h3 class="card-title">标题</h3>
    <button class="btn btn-sm btn-outline">操作</button>
  </div>
  <div class="card-body">内容</div>
</div>
```

### 2.3 表格规范

**基础类**：`.table`

**变体**：
- `.table-striped` - 斑马纹表格
- `.table-compact` - 紧凑表格
- `.table-borderless` - 无边框表格

**使用示例**：
```html
<table class="table table-striped">
  <thead>
    <tr><th>列1</th><th>列2</th></tr>
  </thead>
  <tbody>
    <tr><td>数据1</td><td>数据2</td></tr>
  </tbody>
</table>
```

### 2.4 标签规范

**基础类**：`.tag`

**变体**：
- `.tag-primary` - 主色标签
- `.tag-success` - 成功标签
- `.tag-warning` - 警告标签
- `.tag-danger` - 危险标签
- `.tag-info` - 信息标签
- `.tag-purple` - 紫色标签
- `.tag-gray` - 灰色标签

**尺寸**：
- `.tag-sm` - 小标签
- `.tag-lg` - 大标签

**使用示例**：
```html
<span class="tag tag-success">已完成</span>
<span class="tag tag-warning">进行中</span>
<span class="tag tag-danger">错误</span>
```

### 2.5 弹窗规范

**结构**：
- `.modal-overlay` - 遮罩层
- `.modal` - 弹窗容器
- `.modal-header` - 弹窗头部
- `.modal-title` - 弹窗标题
- `.modal-close` - 关闭按钮
- `.modal-body` - 弹窗内容
- `.modal-footer` - 弹窗底部

**尺寸**：
- `.modal-sm` - 400px
- `.modal` - 520px（默认）
- `.modal-lg` - 720px
- `.modal-xl` - 960px
- `.modal-full` - 全屏

**使用示例**：
```html
<div class="modal-overlay">
  <div class="modal">
    <div class="modal-header">
      <h3 class="modal-title">弹窗标题</h3>
      <button class="modal-close">✕</button>
    </div>
    <div class="modal-body">内容</div>
    <div class="modal-footer">
      <button class="btn btn-outline">取消</button>
      <button class="btn btn-primary">确定</button>
    </div>
  </div>
</div>
```

### 2.6 输入框规范

**基础类**：`.input`、`.select`、`.textarea`

**尺寸**：
- `.input-sm` - 小输入框
- `.input-lg` - 大输入框

**组合**：
- `.input-group` - 输入框组

**使用示例**：
```html
<input type="text" class="input" placeholder="请输入">
<select class="select"><option>选项1</option></select>
<textarea class="textarea" placeholder="请输入"></textarea>
```

---

## 三、布局规范

### 3.1 间距规则

- 所有间距必须是8px的整数倍（4/8/12/16/20/24/32）
- 禁止使用非8px基数的间距（如5px、7px、9px、15px）
- 卡片内边距统一使用 `--space-4`（16px）
- 元素间距统一使用 `--space-3`（12px）或 `--space-4`（16px）

### 3.2 对齐规则

- 所有元素必须左对齐（除非特殊设计）
- 按钮组右对齐
- 表格列标题与内容对齐
- 表单标签右对齐，输入框左对齐

### 3.3 响应式规则

- 电脑端：侧边栏常驻 + 内容区多列
- 平板端：侧边栏常驻 + 内容区双列
- 手机端：底部导航栏 + 单列布局

---

## 四、禁止事项（设计红线）

❌ **禁止硬编码颜色**：必须使用CSS变量（`var(--primary)`等）
❌ **禁止硬编码间距**：必须使用间距Token（`var(--space-4)`等）
❌ **禁止内联style**：必须使用组件类（`.btn`、`.card`等）
❌ **禁止非8px基数间距**：如5px、7px、9px、15px
❌ **禁止随意字体大小**：必须使用字体Token（`var(--fs-sm)`等）
❌ **禁止随意圆角**：必须使用圆角Token（`var(--radius)`等）
❌ **禁止随意阴影**：必须使用阴影Token（`var(--shadow)`等）
❌ **禁止重复造轮子**：必须使用已有组件类

---

## 五、整改计划

### 第一阶段（已完成）
- ✅ 完善CSS设计Token体系（颜色/间距/字体/圆角/阴影）
- ✅ 建立统一组件样式库（按钮/卡片/表格/标签/弹窗/输入框）
- ✅ 建立设计规范文档

### 第二阶段（进行中）
- ⏳ 学习资料库页面改造（内联style → 组件类）
- ⏳ 题库管理页面改造
- ⏳ 记忆闪卡页面改造
- ⏳ 视频讲义页面改造
- ⏳ 章节教材页面改造

### 第三阶段（后续）
- ⏳ 全局硬编码颜色替换为CSS变量
- ⏳ 全局硬编码间距替换为间距Token
- ⏳ 建立组件使用审查机制
- ⏳ 定期设计一致性检查

---

## 六、专家履职机制

### 设计系统专家
- 制定全局UI根本规则
- 定义弹窗档位、max-height、间距、Token
- 输出规范文档，约束后续新增页面
- 做现有系统的一致性整改

### 高级UX/UI设计师
- 输出视觉、交互规范
- 排查现有系统不协调问题
- 定义弹窗、表单、布局标准

### 前端架构师
- 代码层面的软件宪法
- 写代码约束、目录模块约束
- CSS变量/Token约束
- 强制开发、AI编码必须复用全局变量

### 交叉验证机制
- UI专家输出的设计方案，必须由另一位UI专家或产品专家交叉验证
- 前端架构师输出的技术方案，必须由另一位架构专家交叉验证
- 所有新增组件必须经过设计系统专家审核

---

**文档版本**：V2.0
**制定日期**：2026-09-06
**制定专家**：设计系统专家 + 高级UX/UI设计师 + 前端架构师
**审核专家**：38位全球顶级专家联合委员会


============================================================
# § 13. 【来源：设计决策记录.md】
============================================================

# 设计决策记录（Design Decision Record）
# 用途：记录所有已确定的设计决策，修改前必须先查看本文件，避免反复修改
# 最后更新：2026-09-11

## 一、视频讲义模块布局（已锁定，禁止反复修改）

### 1.1 Tab结构
- ✅ 只保留两个Tab：**视频播放**、**网站资源**
- ❌ 已移除：视频管理（管理功能在学习资料库）

### 1.2 视频播放页布局（模块化原始布局，已锁定，禁止修改）
```
┌─────────────────────────────────────────────────┐
│  上部分（占60%高度，左右6:4）                     │
│  ┌──────────────────────┬─────────────────────┐  │
│  │                      │                     │  │
│  │   视频播放器          │      智慧笔记        │  │
│  │   (占60%宽度)         │      (占40%宽度)     │  │
│  │                      │  ✨AI生成            │  │
│  │                      │  💾保存 🗑️清空 📤导出 │  │
│  └──────────────────────┴─────────────────────┘  │
│  下部分（拉通，占40%高度）                        │
│  ┌─────────────────────────────────────────────┐  │
│  │  来源筛选: 全部/本地/网站  共N个视频  🔄      │  │
│  │  ┌───────────────────────────────────────┐  │  │
│  │  │ 视频标题              [进度条]         │  │  │
│  │  │ ⏱️时长  📁文件夹  N%                  │  │  │
│  │  └───────────────────────────────────────┘  │  │
│  │  ...（列表式，可滚动）                       │  │
│  └─────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
```

### 1.3 智慧笔记功能（原始设计，已锁定）
- ✨ AI生成按钮（自动生成视频笔记）
- 💾 保存按钮
- 🗑️ 清空按钮
- 📤 导出按钮
- textarea输入框，可手动编辑

### 1.4 播放列表样式（原始设计，已锁定）
- 列表式展示（非卡片式）
- 每个视频显示：标题 + 进度条 + 时长 + 文件夹 + 进度百分比
- 来源筛选下拉框（全部来源/本地视频/网站资源）
- 拉通整个宽度，可垂直滚动
- 刷新按钮

---

## 二、学习资料库模块布局（已锁定，禁止反复修改）

### 2.1 整体布局
- ✅ **上下布局**：文档资料在上，视频讲义在下
- ✅ 文档区域占1.6份，视频区域占1份
- ❌ 已放弃：左右两列布局（空间不足）

### 2.2 Tab结构
- 全部 (570)
- 视频讲义 (64)
- 大纲/教材 (506)
- 标签管理
- 识别题库
- 生成闪卡
- 生成导图

### 2.3 文件操作栏（每个文件）
- ✅ 只保留：**重命名✏️**、**删除🗑️**
- ❌ 已移除：单文件识别🔍、单文件闪卡🃏、单文件导图🧠
- 原因：用户通过标签批量识别，不需要单文件操作

### 2.4 标签体系（已锁定）
- **18个标签，分3组**：
  - 资料类型（蓝色）：教材、大纲、讲义、视频、课件、资料
  - 练习类型（绿色）：真题、模拟题、精题、练习题、习题、押题
  - 记忆工具（紫色）：闪卡、思维导图、导图、知识点、考点、笔记
- **标签修改规则**：
  - 有明确文件夹的文件：只在文件夹级修改标签（文件夹头部🏷️按钮）
  - 只有"其他"文件夹中的单个文件：才显示单文件标签按钮
- ❌ 已放弃：全局科目（如一造管理）作为文件标签

### 2.5 文件列表展示
- ✅ 只保留：复选框 + 文件名 + 操作
- ❌ 已移除：类型、分类、大小、上传时间（用户认为无意义）
- 文件名缩略显示（长文件名自动截断）

### 2.6 文件夹功能
- ✅ 保留：展开/收起、文件夹标签修改
- ❌ 已移除：文件夹重命名、文件夹删除、文件夹全选（用户认为鸡肋）

---

## 三、题库模块设计决策

### 3.1 刷题模式
- 单选题模式（已作答不可修改）
- 解析换行显示（\n转<br>）
- 解析区域可滚动（max-height+overflow-y）
- 选项加载：优先options字段，缺失时从option_a-e构建（包含e）

### 3.2 数据质量
- 所有数据导入必须经过质量门禁（清洗→校验→标准化→修复→门禁）
- 案例题单独标记，不展示选项
- 格式混乱题目标记待人工处理

---

## 四、通用设计原则

### 4.1 模块职责划分
- **学习资料库**：文件管理（上传、删除、标签、批量识别）
- **视频讲义**：视频播放 + 智能笔记（不做文件管理）
- **其他模块**：只做展示和深加工，不做文件管理

### 4.2 批量操作原则
- 通过标签筛选进行批量操作
- 不提供单文件操作按钮（避免界面混乱）

### 4.3 布局锁定原则
- 一旦用户确认布局，立即记录到本文件
- 修改前必须先查看本文件，确认是否已锁定
- 布局调整必须先征求用户同意

---

## 五、修改记录（避免反复修改的追溯）

| 日期 | 模块 | 修改内容 | 原因 |
|------|------|---------|------|
| 2026-09-11 | 视频讲义 | 移除视频管理Tab | 用户：管理功能在学习资料库 |
| 2026-09-11 | 视频讲义 | 改为上下布局（上视频+笔记，下拉通播放列表） | 用户明确要求 |
| 2026-09-11 | 视频讲义 | 恢复模块化原始布局（左右平分+智慧笔记+列表式播放列表） | 用户指出锁死过，对照备份恢复 |
| 2026-09-11 | 视频讲义 | 调整高度比例为播放器60%+列表40% | 用户明确要求 |
| 2026-09-11 | 视频讲义 | 调整左右比例为播放器60%+笔记40% | 用户明确要求 |
| 2026-09-11 | 学习资料库 | 从左右布局改为上下布局 | 用户：空间不足 |
| 2026-09-11 | 学习资料库 | 移除单文件识别/闪卡/导图按钮 | 用户：通过标签批量识别 |
| 2026-09-11 | 学习资料库 | 移除类型/分类/大小/上传时间列 | 用户：无意义 |
| 2026-09-11 | 学习资料库 | 移除文件夹重命名/删除/全选 | 用户：鸡肋 |

---

## 六、使用说明

**任何模块修改前，必须先查看本文件：**
1. 确认该模块的布局是否已锁定
2. 确认已确定的设计决策
3. 如果需要修改已锁定的设计，必须先征求用户同意
4. 修改完成后，立即更新本文件的记录

**本文件是设计宪法的补充，具有同等约束力。**


============================================================
# § 14. 【来源：神经末梢级深度分析报告.md】
============================================================

# 神经末梢级深度分析报告
# 细到每一个按钮、每一个交互、每一个API调用
# 生成时间：2026-09-11

## 一、file-library.js 神经末梢拆解

### 1.1 顶部工具栏（6个交互元素）

| 元素 | ID/Class | 当前状态 | 绑定事件 | 替代方案 |
|------|----------|---------|---------|---------|
| 📤 上传文件 | #fl-upload-btn | ✅ 正常 | onclick→uploadInput.click() | 原生input，无需模态框 |
| 📂 文件夹导入 | #fl-folder-upload-btn | ✅ 正常 | onclick→folderUpload() | 已实现，无需模态框 |
| 搜索输入框 | #fl-search-input | ✅ 正常 | onkeydown→搜索 | 已实现 |
| 🔍 搜索按钮 | #fl-search-btn | ✅ 正常 | onclick→搜索 | 已实现 |
| 🔄 刷新 | #fl-refresh-btn | ✅ 正常 | onclick→loadAllData() | 已实现 |
| 隐藏file input | #fl-upload-input | ✅ 正常 | onchange→uploadFiles() | 已实现 |

### 1.2 Tab栏（9个交互元素）

| 元素 | ID/Class | 当前状态 | 绑定事件 | 替代方案 |
|------|----------|---------|---------|---------|
| 全部 (570) | .fl-tab[data-tab=all] | ✅ 正常 | onclick→switchTab | 已实现 |
| 🎬 视频讲义 (64) | .fl-tab[data-tab=video] | ✅ 正常 | onclick→switchTab | 已实现 |
| 📖 大纲/教材 (506) | .fl-tab[data-tab=book] | ✅ 正常 | onclick→switchTab | 已实现 |
| 🏷️ 标签管理 | #fl-tag-manage-btn | ✅ 正常 | onclick→showTagManager() | 已实现 |
| 🔍 识别题库 | #fl-batch-recognize-btn | ✅ 正常 | onclick→batchRecognize() | 已实现 |
| 🃏 生成闪卡 | #fl-batch-flashcard-btn | ✅ 正常 | onclick→batchFlashcard() | 已实现 |
| 🧠 生成导图 | #fl-batch-mindmap-btn | ✅ 正常 | onclick→batchMindmap() | 已实现 |

### 1.3 文档区域（5个交互元素）

| 元素 | ID/Class | 当前状态 | 绑定事件 | 替代方案 |
|------|----------|---------|---------|---------|
| 全选复选框 | .fl-select-all-book | ✅ 正常 | onchange→全选文档 | 已实现 |
| 已选计数 | .fl-selected-count | ✅ 显示 | 纯展示 | 已实现 |
| 🏷️ 批量标签 | #fl-batch-tag-btn | ✅ 正常 | onclick→batchTag() | 已实现 |
| 🗑️ 删除(N) | #fl-batch-delete-btn | ✅ 正常 | onclick→batchDelete('book') | API已修复为/fl |

### 1.4 视频区域（4个交互元素）

| 元素 | ID/Class | 当前状态 | 绑定事件 | 替代方案 |
|------|----------|---------|---------|---------|
| 全选复选框 | .fl-select-all-video | ✅ 正常 | onchange→全选视频 | 已实现 |
| 已选计数 | .fl-selected-count | ✅ 显示 | 纯展示 | 已实现 |
| 🗑️ 删除(N) | #fl-batch-delete-video | ✅ 正常 | onclick→batchDelete('video') | API已修复为/video |

### 1.5 文件夹头部（6个交互元素）

| 元素 | Class | 当前状态 | 绑定事件 | 替代方案 |
|------|-------|---------|---------|---------|
| ▶/▼ 展开箭头 | .fl-folder-toggle | ✅ 正常 | onclick→toggleFolder | 已实现 |
| 📁 文件夹图标 | .fl-folder-icon | ✅ 显示 | 纯展示 | 已实现 |
| 文件夹名称 | .fl-folder-name | ✅ 显示 | 纯展示 | 已实现 |
| (N个文件)计数 | .fl-folder-count | ✅ 显示 | 纯展示 | 已实现 |
| 标签显示(最多3+N) | .fl-folder-tags | ✅ 显示 | 纯展示 | 已实现 |
| 🏷️ 文件夹标签按钮 | .fl-folder-tag-btn | ✅ 正常 | onclick→showFolderTagPanel() | 仅文档列，已实现 |

### 1.6 文件项（7个交互元素）

| 元素 | Class | 当前状态 | 绑定事件 | 替代方案 |
|------|-------|---------|---------|---------|
| ☑️ 复选框 | .fl-file-checkbox | ✅ 正常 | onchange→选择文件 | 已实现 |
| 文件名 | .fl-file-name | ❌ 无事件 | 应该有预览 | **需添加：点击预览** |
| 标签显示 | .fl-file-tag | ✅ 显示 | 纯展示 | 已实现 |
| 🏷️ 标签按钮(仅其他) | .fl-file-tag-btn | ✅ 正常 | onclick→showTagPanel() | 已实现 |
| ✏️ 重命名 | .fl-detail-btn[data-action=rename] | ✅ 正常 | onclick→renameFile() | 已实现 |
| 🗑️ 删除 | .fl-detail-btn[data-action=delete] | ✅ 正常 | onclick→deleteFile() | API已修复为/fl |
| **🔍 识别题库** | 缺失 | ❌ 缺失 | 应该有 | **需添加：单文件识别** |
| **🃏 生成闪卡** | 缺失 | ❌ 缺失 | 应该有 | **需添加：单文件闪卡** |
| **🧠 生成导图** | 缺失 | ❌ 缺失 | 应该有 | **需添加：单文件导图** |

### 1.7 file-library缺失功能清单（8项）

| 序号 | 缺失功能 | 旧代码方法 | 优先级 | 替代方案 |
|------|---------|-----------|--------|---------|
| 1 | 文件名点击预览 | previewFile | P0 | 点击文件名调用previewFile()，PDF用openPdfViewer，视频用新窗口播放 |
| 2 | 单文件识别题库 | recognizeQuestion | P0 | 文件操作栏添加🔍按钮，调用flBridge.recognizeQuestion() |
| 3 | 单文件生成导图 | generateMindmap | P0 | 文件操作栏添加🧠按钮，调用flBridge.generateMindmap() |
| 4 | 单文件生成闪卡 | 旧代码无单文件 | P1 | 文件操作栏添加🃏按钮，调用flBridge.generateFlashcard() |
| 5 | 标签颜色 | getTagColor | P1 | 标签span添加style背景色，8种颜色映射 |
| 6 | 状态颜色 | getStatusColor | P2 | 文件处理状态显示，5种状态颜色 |
| 7 | 类型/状态筛选 | changeFilter | P2 | 工具栏添加筛选下拉框，当前搜索已够用 |
| 8 | 分页功能 | nextPage/prevPage | P2 | 当前page_size=1000已加载全部，570个文件不需要分页 |

### 1.8 可省略功能及替代方案（4项）

| 旧功能 | 替代方案 | 理由 |
|--------|---------|------|
| showUploadModal | 原生input type=file | 更简单，用户已接受 |
| showScanModal | folderUpload()直接调用 | 文件夹导入已实现 |
| setFileTag下拉 | 标签面板多选 | 更直观，用户已接受 |
| editTags弹窗 | 标签面板多选 | 更统一，用户已接受 |

---

## 二、collect.js 神经末梢拆解

### 2.1 顶部工具栏（4个交互元素，全部无事件）

| 元素 | Class | 当前状态 | 应有功能 | 替代方案 |
|------|-------|---------|---------|---------|
| 题型筛选下拉 | .collect-select | ❌ 死元素 | 按题型筛选 | onchange→过滤questions |
| 搜索输入框 | .collect-search | ❌ 死元素 | 搜索题干/知识点 | onkeydown→搜索 |
| 🔍 搜索按钮 | .collect-btn-primary | ❌ 死元素 | 执行搜索 | onclick→搜索 |
| 📤 导出按钮 | .collect-btn | ❌ 死元素 | 导出收藏题目 | onclick→导出JSON/CSV |

### 2.2 题目卡片（6个交互元素，全部无事件）

| 元素 | Class | 当前状态 | 应有功能 | 替代方案 |
|------|-------|---------|---------|---------|
| 题目卡片 | .collect-card | ❌ 死元素 | 点击展开/收起详情 | onclick→toggle展开 |
| 题目内容 | .collect-card-content | ✅ 显示 | 纯展示 | 已实现 |
| 选项列表 | .collect-options | ✅ 显示 | 纯展示 | 已实现 |
| 正确答案 | .collect-answer | ✅ 显示 | 纯展示 | 已实现 |
| 解析 | .collect-analysis | ✅ 显示 | 纯展示 | 已实现 |
| 📝 去练习 | .collect-btn-primary | ❌ 死元素 | 跳转到题库练习 | onclick→路由跳转question-practice |
| 取消收藏 | .collect-btn-danger | ❌ 死元素 | 从收藏中移除 | onclick→StorageService.favorites.remove() |

### 2.3 collect.js缺失功能清单（6项）

| 序号 | 缺失功能 | 优先级 | 实现方案 |
|------|---------|--------|---------|
| 1 | 题型筛选 | P1 | onchange→按type过滤state.questions |
| 2 | 搜索功能 | P1 | onkeydown/onclick→按keyword过滤title/content |
| 3 | 导出功能 | P2 | onclick→生成JSON/CSV文件下载 |
| 4 | 去练习跳转 | P0 | onclick→Framework.navigate('question-practice') |
| 5 | 取消收藏 | P0 | onclick→StorageService.favorites.remove(id)→重新渲染 |
| 6 | 题目展开/收起 | P2 | onclick→切换详情显示 |

---

## 三、sprint.js 神经末梢拆解

### 3.1 快捷入口（4个交互元素，全部无事件）

| 元素 | Class | 当前状态 | 应有功能 | 替代方案 |
|------|-------|---------|---------|---------|
| 📝 真题模考 | .quick-item[0] | ❌ 死元素 | 跳转到模拟考试 | onclick→Framework.navigate('mock-exam') |
| ❌ 错题重练 | .quick-item[1] | ❌ 死元素 | 跳转到错题本 | onclick→Framework.navigate('wrong-book') |
| 🔥 高频考点 | .quick-item[2] | ❌ 死元素 | 跳转到高频考点练习 | onclick→Framework.navigate('question-practice', {filter: 'hot'}) |
| 🤖 AI智能出题 | .quick-item[3] | ❌ 死元素 | 打开AI出题对话框 | onclick→调用AI出题API |

### 3.2 薄弱考点列表（5个交互元素，全部无事件）

| 元素 | Class | 当前状态 | 应有功能 | 替代方案 |
|------|-------|---------|---------|---------|
| 薄弱考点项 | .weak-item | ❌ 死元素 | 点击进入该考点练习 | onclick→按考点筛选题目练习 |

### 3.3 高频考点列表（6个交互元素，全部无事件）

| 元素 | Class | 当前状态 | 应有功能 | 替代方案 |
|------|-------|---------|---------|---------|
| 高频考点项 | .hot-item | ❌ 死元素 | 点击进入该考点练习 | onclick→按考点筛选题目练习 |

### 3.4 sprint.js缺失功能清单（3项）

| 序号 | 缺失功能 | 优先级 | 实现方案 |
|------|---------|--------|---------|
| 1 | 快捷入口跳转 | P0 | 4个quick-item分别绑定onclick→路由跳转 |
| 2 | 薄弱考点点击 | P1 | onclick→按考点名筛选题目→跳转练习 |
| 3 | 高频考点点击 | P1 | onclick→按考点名筛选题目→跳转练习 |

---

## 四、memory.js 神经末梢拆解

### 4.1 统计卡片（4个展示元素）

| 元素 | Class | 当前状态 | 功能 |
|------|-------|---------|------|
| 🃏 闪卡总数 | .memory-stat-value[0] | ⚠️ 静态0 | 应从StorageService.flashcards.getStats()加载 |
| 📅 今日待复习 | .memory-stat-value[1] | ⚠️ 静态445 | 应从StorageService加载 |
| 🔥 连续训练天数 | .memory-stat-value[2] | ⚠️ 静态0 | 应从localStorage加载 |
| ✅ 记忆准确率 | .memory-stat-value[3] | ⚠️ 静态0% | 应从StorageService加载 |

### 4.2 考试专项记忆（1个交互元素，无事件）

| 元素 | Class | 当前状态 | 应有功能 | 替代方案 |
|------|-------|---------|---------|---------|
| 易混淆概念配对 | .memory-special-item | ❌ 死元素 | 进入配对训练 | onclick→启动配对训练模式 |

### 4.3 记忆工具（4个交互元素，全部无事件）

| 元素 | Class | 当前状态 | 应有功能 | 替代方案 |
|------|-------|---------|---------|---------|
| 📝 口诀生成 | .memory-tool-item[0] | ❌ 死元素 | AI生成口诀 | onclick→调用AI口诀生成API |
| 🔄 复习计划 | .memory-tool-item[1] | ❌ 死元素 | 查看复习计划 | onclick→跳转到闪卡复习 |
| 📈 记忆曲线 | .memory-tool-item[2] | ❌ 死元素 | 查看遗忘曲线 | onclick→显示记忆曲线图表 |
| 🔑 关键词 | .memory-tool-item[3] | ❌ 死元素 | 提取关键词 | onclick→调用AI关键词提取 |

### 4.4 九大记忆法（9个交互元素，全部无事件）

| 元素 | Class | 当前状态 | 应有功能 | 替代方案 |
|------|-------|---------|---------|---------|
| 🔄 间隔重复法 | .memory-method-item[0] | ❌ 死元素 | 查看详情+实战 | onclick→显示方法详情弹窗 |
| 🧠 主动回忆法 | .memory-method-item[1] | ❌ 死元素 | 查看详情+实战 | onclick→显示方法详情弹窗 |
| 📖 费曼学习法 | .memory-method-item[2] | ❌ 死元素 | 查看详情+实战 | onclick→显示方法详情弹窗 |
| 🧩 组块记忆法 | .memory-method-item[3] | ❌ 死元素 | 查看详情+实战 | onclick→显示方法详情弹窗 |
| 🎵 谐音联想法 | .memory-method-item[4] | ❌ 死元素 | 查看详情+实战 | onclick→显示方法详情弹窗 |
| 🗺️ 思维导图法 | .memory-method-item[5] | ❌ 死元素 | 查看详情+实战 | onclick→跳转到思维导图 |
| 🖼️ 图像转译法 | .memory-method-item[6] | ❌ 死元素 | 查看详情+实战 | onclick→显示方法详情弹窗 |
| 📚 PQ4R阅读法 | .memory-method-item[7] | ❌ 死元素 | 查看详情+实战 | onclick→显示方法详情弹窗 |
| 🏰 记忆宫殿法 | .memory-method-item[8] | ❌ 死元素 | 查看详情+实战 | onclick→显示方法详情弹窗 |

### 4.5 memory.js缺失功能清单（4项）

| 序号 | 缺失功能 | 优先级 | 实现方案 |
|------|---------|--------|---------|
| 1 | 统计数据真实加载 | P1 | _loadRealStats()已存在，但需验证数据来源 |
| 2 | 记忆法详情弹窗 | P2 | onclick→显示方法介绍+使用技巧弹窗 |
| 3 | 记忆工具功能 | P2 | 4个工具分别绑定对应功能 |
| 4 | 专项训练入口 | P2 | 易混淆概念配对→启动训练 |

---

## 五、其他16个模块功能完整性检查

### 5.1 已验证功能完整的模块（16个）

| 模块 | 方法数 | 事件绑定 | 关键功能验证 |
|------|--------|---------|-------------|
| dashboard.js | 7 | ✅ | 学习看板统计、快捷入口、今日目标 |
| question-practice.js | 10 | ✅ | 刷题、选项选择、答案解析、下一题 |
| mock-exam.js | 14 | ✅ | 模拟考试、计时、交卷、成绩 |
| flashcard.js | 9 | ✅ | 闪卡复习、正反面翻转、批量导入 |
| video.js | 11 | ✅ | 视频播放、文件夹分组、三Tab |
| mindmap.js | 5 | ✅ | 思维导图展示、节点展开 |
| note.js | 6 | ✅ | 笔记列表、编辑、保存 |
| wrong-book.js | 7 | ✅ | 错题列表、重练、移除 |
| photo-solve.js | 14 | ✅ | 拍照解题、上传、识别 |
| knowledge.js | 9 | ✅ | 知识点列表、详情 |
| material.js | 6 | ✅ | 资料列表、预览 |
| question-manager.js | 6 | ✅ | 题目管理、编辑、删除 |
| settings.js | 8 | ✅ | 设置项、保存 |
| analytics.js | 5 | ✅ | 数据分析图表 |
| sidebar.js | 6 | ✅ | 侧边栏导航、折叠 |
| topbar.js | 7 | ✅ | 顶部栏、科目选择、工具按钮 |

### 5.2 纯展示模块（2个，不需要交互）

| 模块 | 状态 | 说明 |
|------|------|------|
| system-admin.js | 纯展示 | 注释"暂无交互事件"，系统状态展示 |
| statusbar.js | 纯展示 | 底部状态栏，服务状态显示 |

---

## 六、API调用一致性检查

### 6.1 file-library API调用清单

| API | 方法 | 当前状态 | 说明 |
|-----|------|---------|------|
| /api/v1/fl/list?page_size=1000 | GET | ✅ 正确 | 获取文档列表（含tags） |
| /api/v1/video/list?page_size=500 | GET | ✅ 正确 | 获取视频列表 |
| /api/v1/fl/:id | PUT | ✅ 正确 | 更新标签（FormData） |
| /api/v1/fl/:id | DELETE | ✅ 已修复 | 删除文档（原/material已改为/fl） |
| /api/v1/video/:id | DELETE | ✅ 正确 | 删除视频 |
| /api/v1/fl/download/:id | GET | ✅ 正确 | 文件预览/下载 |
| /api/v1/fl_bridge/recognize_question/:id | POST | ✅ 正确 | 识别题库（通过flBridge） |
| /api/v1/fl_bridge/generate_flashcard/:id | POST | ✅ 正确 | 生成闪卡（通过flBridge） |
| /api/v1/fl_bridge/generate_mindmap/:id | POST | ✅ 正确 | 生成导图（通过flBridge） |

### 6.2 认证机制

| 项目 | 当前状态 | 说明 |
|------|---------|------|
| token存储 | ✅ localStorage.key='token' | 已验证 |
| Authorization头 | ✅ Bearer <token> | core/api.js已封装 |
| window.api | ✅ 已初始化 | core/api.js创建 |

---

## 七、优先级排序与修复计划

### P0 - 立即修复（影响核心功能，共7项）

| 序号 | 模块 | 功能 | 修复方案 |
|------|------|------|---------|
| 1 | file-library | 文件名点击预览 | 文件名添加onclick→previewFile() |
| 2 | file-library | 单文件识别题库 | 操作栏添加🔍按钮→flBridge.recognizeQuestion() |
| 3 | file-library | 单文件生成导图 | 操作栏添加🧠按钮→flBridge.generateMindmap() |
| 4 | collect | 去练习跳转 | 按钮onclick→Framework.navigate('question-practice') |
| 5 | collect | 取消收藏 | 按钮onclick→StorageService.favorites.remove() |
| 6 | sprint | 快捷入口跳转 | 4个quick-item绑定onclick→路由跳转 |
| 7 | file-library | 单文件生成闪卡 | 操作栏添加🃏按钮→flBridge.generateFlashcard() |

### P1 - 尽快修复（影响用户体验，共6项）

| 序号 | 模块 | 功能 | 修复方案 |
|------|------|------|---------|
| 8 | file-library | 标签颜色 | getTagColor()→8种颜色映射 |
| 9 | collect | 题型筛选 | onchange→按type过滤 |
| 10 | collect | 搜索功能 | onkeydown/onclick→按keyword过滤 |
| 11 | sprint | 薄弱考点点击 | onclick→按考点筛选练习 |
| 12 | sprint | 高频考点点击 | onclick→按考点筛选练习 |
| 13 | memory | 统计数据真实加载 | 验证_loadRealStats()数据来源 |

### P2 - 后续优化（不影响核心功能，共8项）

| 序号 | 模块 | 功能 | 修复方案 |
|------|------|------|---------|
| 14 | file-library | 状态颜色 | getStatusColor()→5种状态 |
| 15 | file-library | 类型/状态筛选 | 工具栏添加筛选下拉框 |
| 16 | file-library | 分页功能 | 当前已加载全部，不需要 |
| 17 | collect | 导出功能 | 生成JSON/CSV下载 |
| 18 | collect | 题目展开/收起 | onclick→切换详情 |
| 19 | memory | 记忆法详情弹窗 | onclick→显示方法介绍 |
| 20 | memory | 记忆工具功能 | 4个工具绑定对应功能 |
| 21 | memory | 专项训练入口 | 易混淆概念配对训练 |

---

## 八、总结

### 神经末梢统计
- **file-library**：41个交互元素，38个正常，3个缺失（预览/单文件识别/单文件导图）
- **collect**：10个交互元素，全部无事件绑定
- **sprint**：15个交互元素，全部无事件绑定
- **memory**：18个交互元素，全部无事件绑定
- **其他16个模块**：功能完整

### 总缺失功能
- **P0核心功能**：7项
- **P1体验功能**：6项
- **P2优化功能**：8项
- **合计**：21项

### 可省略功能（已有替代方案）
- showUploadModal → 原生input
- showScanModal → folderUpload()
- setFileTag下拉 → 标签面板
- editTags弹窗 → 标签面板
- 分页功能 → page_size=1000已加载全部


============================================================
# § 15. 【来源：数据库表清理计划.md】
============================================================

# 数据库表清理计划

生成时间: 2026-09-11 16:12:49
总表数: 105

## 一、表分类统计

| 分类 | 数量 | 说明 |
|------|------|------|
| 核心业务表 | 1 | |
| 文件库表(fl_前缀) | 6 | |
| 旧文件库表(file_前缀) | 20 | |
| 闪卡表(flash_/flashcard_) | 7 | |
| 视频表 | 6 | |
| 题库表 | 15 | |
| 用户/系统表 | 3 | |
| 其他表 | 47 | |

## 二、废弃表标记（建议清理）

### 2.1 旧文件库表（file_前缀，已被fl_替代）

- `file_content`: 501条记录
- `file_content_block`: 60628条记录
- `file_content_fts`: 491条记录
- `file_content_fts_config`: 1条记录
- `file_content_fts_content`: 491条记录
- `file_content_fts_data`: 6926条记录
- `file_content_fts_docsize`: 491条记录
- `file_content_fts_idx`: 9732条记录
- `file_formula`: 8623条记录
- `file_image`: 18023条记录
- `file_page_content`: 13191条记录
- `file_page_fts`: 13072条记录
- `file_page_fts_config`: 1条记录
- `file_page_fts_content`: 13072条记录
- `file_page_fts_data`: 4470条记录
- `file_page_fts_docsize`: 13072条记录
- `file_page_fts_idx`: 4660条记录
- `file_raw_result`: 0条记录
- `file_structure`: 0条记录
- `file_table`: 0条记录

**处理建议**: 标记为废弃，确认fl_表数据完整后，备份后删除

### 2.2 重复闪卡表（flash_前缀，已被flashcard_替代）

- `flash_cards`: 933条记录
- `flash_cards_fts`: 933条记录
- `flash_cards_fts_config`: 1条记录
- `flash_cards_fts_data`: 241条记录
- `flash_cards_fts_docsize`: 4954条记录
- `flash_cards_fts_idx`: 237条记录

**处理建议**: 标记为废弃，确认flashcard_表数据完整后，备份后删除

## 三、保留表（核心业务）

### 3.1 核心业务表

- `knowledge_points`: 143条记录

### 3.2 文件库表（fl_前缀，当前使用）

- `fl_file_library`: 506条记录
- `fl_files_fts`: 506条记录
- `fl_files_fts_config`: 1条记录
- `fl_files_fts_data`: 9条记录
- `fl_files_fts_docsize`: 506条记录
- `fl_files_fts_idx`: 7条记录

### 3.3 视频表

- `embedded_videos`: 435条记录
- `local_videos`: 0条记录
- `video_categories`: 12条记录
- `video_notes`: 0条记录
- `video_progress`: 0条记录
- `video_question_links`: 1条记录

### 3.4 题库表

- `exam_chapter_score`: 78条记录
- `exam_global_config`: 8条记录
- `exam_records`: 22条记录
- `exam_subject_configs`: 10条记录
- `exam_syllabus`: 1条记录
- `question_answer_logs`: 588条记录
- `question_collects`: 4条记录
- `questions`: 2516条记录
- `questions_backup_abnormal`: 0条记录
- `questions_fts`: 2516条记录
- `questions_fts_config`: 1条记录
- `questions_fts_data`: 173条记录
- `questions_fts_docsize`: 1870条记录
- `questions_fts_idx`: 171条记录
- `wrong_questions`: 526条记录

## 四、清理执行步骤

1. **备份**: 清理前完整备份数据库
2. **验证**: 确认废弃表数据已迁移到新表
3. **标记**: 在表名前加`deprecated_`前缀（不直接删除）
4. **观察**: 运行1周确认无影响
5. **删除**: 确认无影响后，备份后彻底删除

## 五、风险控制

- 禁止直接删除表，先标记为deprecated
- 清理前必须完整备份
- 清理后运行完整功能测试
- 保留回滚方案



============================================================
# § 16. 【来源：系统漏洞分析报告.md】
============================================================

# 系统体系、架构、机制漏洞分析报告

**生成时间**: 2026-09-11
**分析范围**: 宪法规则、系统架构、API接口、数据库、机制完善性

---

## 一、宪法规则体系漏洞

### 1.1 章节编号重复（严重）

| 问题 | 详情 | 影响 |
|------|------|------|
| 第十三章重复 | "第十三章 绝对禁止清单" 和 "第十三章 知识点标准体系至尊准则" | 引用时歧义，执行时不知以哪个为准 |
| 第十四章重复 | "第十四章 修订记录" 和 "第十四章 AI大脑自我进化机制" | 同上 |
| 第N章不规范 | "第N章 代码与数据治理保障机制" | 编号不规范，无法引用 |
| 章节序列断裂 | 第1-14章 → 第13-15章（重复）→ 第16-38章 | 整体结构混乱 |

**建议**: 重新统一编号，将重复章节合并或重新编号。

### 1.2 规则分散与潜在冲突（中等）

| 规则类型 | 出现位置 | 问题 |
|----------|----------|------|
| 全局锁死规则 | 第22章 + 25.11布局保护 | 两处都有锁死规则，需明确主次关系 |
| 增量迁移规则 | 6.1 + 25.8 + 多处散落 | 迁移规则分散，执行标准不统一 |
| 数据质量规则 | 第21章 + 25.9 + 多个工具 | 质量标准分散，缺乏统一入口 |

**建议**: 在宪法中建立"规则索引"，明确每类规则的主章节和引用关系。

### 1.3 规则执行保障不足（中等）

- 宪法有38章，但缺乏"规则执行检查清单"
- 没有自动化工具验证规则是否被遵守
- 专家履职机制（第20章）缺乏具体触发条件

---

## 二、系统架构漏洞

### 2.1 API前缀不一致（严重）

| 模块 | API前缀 | 问题 |
|------|---------|------|
| 学习资料库 | `/api/fl` | 与其他模块不一致 |
| 视频/题库/考试等 | `/api/v1` | 标准前缀 |
| AI模块 | `/api/v1/ai` | 标准前缀 |

**影响**:
- 新模块开发时不知道该用哪个前缀
- API文档难以统一
- 前端调用容易出错

**建议**: 统一为`/api/v1`，将`/api/fl`迁移为`/api/v1/fl`，保留旧前缀做兼容。

### 2.2 模块划分不够清晰（中等）

| 问题 | 详情 |
|------|------|
| ai模块为空 | `frontend/modules/ai/`目录存在但无JS文件 |
| manager模块功能重叠 | `manager`和`question`可能有功能重叠 |
| 缺乏模块依赖图 | 模块间调用关系不明确 |

### 2.3 前后端架构不匹配（中等）

- 前端21个模块，后端API路由不完全对应
- 部分前端模块调用的API在后端不存在或已废弃
- 缺乏API契约测试

---

## 三、数据库架构漏洞

### 3.1 表前缀混乱（严重）

| 前缀 | 表数量 | 问题 |
|------|--------|------|
| `file_*` | 20个 | 旧版文件处理表，可能已废弃 |
| `fl_*` | 6个 | 新版文件库表 |
| `flash_*` | 6个 | 闪卡表 |
| `flashcard_*` | 1个 | 闪卡表（可能重复） |
| `questions_*` | 7个 | 题库表 |
| `question_*` | 2个 | 题库表（可能重复） |
| `knowledge_*` | 6个 | 知识库表 |
| `kp_*` | 1个 | 知识点表（可能重复） |

**总表数**: 105个表（含SQLite系统表2个，实际业务表103个）

**问题**:
- 新旧版本表共存，数据可能不一致
- 重复表可能导致数据写入错误的表
- 缺乏表废弃机制和清理计划

**建议**:
1. 建立"表生命周期管理"机制
2. 标记废弃表，制定清理计划
3. 统一表命名规范

### 3.2 备份表过多（中等）

| 备份表 | 说明 |
|--------|------|
| `questions_backup_abnormal` | 异常题目备份 |
| `knowledge_points_backup` | 知识点备份 |
| `kp_slal_backup` | 知识点备份（拼写可疑） |

**建议**: 备份表应移到单独的备份数据库，避免主库混乱。

### 3.3 缺乏数据血缘追踪（中等）

- 数据从上传→解析→清洗→入库的流程缺乏追踪
- 出现数据质量问题时难以溯源
- `data_versions`表存在但未充分利用

---

## 四、机制完善性漏洞

### 4.1 质量门禁机制不完整（中等）

- 已有`quality_gate_framework.py`，但未接入所有数据处理流程
- 质量门禁结果缺乏可视化展示
- 门禁失败后的处理流程不明确

### 4.2 变更管控机制不足（中等）

- 第17章"黄金备份与变更管控"有规则，但缺乏自动化工具
- 修改代码前没有自动备份和变更记录
- 回滚机制不完善

### 4.3 监控告警机制缺失（严重）

- 缺乏系统运行状态监控
- 没有错误日志聚合和告警
- 用户反馈没有自动收集和分析机制

### 4.4 测试机制不完善（中等）

- 有`smoke_test.py`但覆盖范围有限
- 缺乏单元测试和集成测试
- 没有CI/CD流程

---

## 五、文件规定打架问题

### 5.1 宪法与实际代码不一致（严重）

| 宪法规定 | 实际情况 | 冲突 |
|----------|----------|------|
| API前缀统一 | `/api/fl`和`/api/v1`并存 | 违反统一规范 |
| 模块化架构 | 旧版`app_v3_*.js`仍存在 | 新旧代码共存 |
| 表命名规范 | 多种前缀并存 | 违反命名规范 |
| 布局锁死 | 多次出现布局被修改 | 执行不到位 |

### 5.2 文档与实际不一致（中等）

- `docs/全面功能迁移检查报告.json`显示47项缺失，但实际大部分已存在
- 设计决策记录与实际代码有出入
- 缺乏文档自动更新机制

### 5.3 工具脚本混乱（中等）

- `tools/`目录有150+个Python脚本
- 命名不规范（`_fix_*.py`临时脚本过多）
- 缺乏工具分类和索引
- 部分工具功能重复

---

## 六、优先级修复建议

### P0（立即修复）

1. **统一API前缀**: 将`/api/fl`迁移为`/api/v1/fl`
2. **修复宪法章节编号**: 重新统一编号，消除重复
3. **建立表清理计划**: 标记废弃表，制定清理时间表

### P1（本周修复）

4. **建立规则索引**: 在宪法中添加规则索引，明确主次关系
5. **完善质量门禁**: 将质量门禁接入所有数据处理流程
6. **清理临时脚本**: 归档`_fix_*.py`临时脚本，建立工具分类

### P2（本月修复）

7. **建立监控告警**: 添加系统运行状态监控和错误告警
8. **完善测试体系**: 增加单元测试和集成测试覆盖
9. **数据血缘追踪**: 建立数据从上传到入库的全流程追踪

### P3（长期优化）

10. **架构重构**: 逐步消除新旧代码共存
11. **CI/CD流程**: 建立自动化构建、测试、部署流程
12. **文档自动化**: 建立文档自动更新机制

---

## 七、总结

### 主要优势
- ✅ 模块化架构基本建立
- ✅ 宪法规则体系完善（38章）
- ✅ 数据质量保障工具齐全
- ✅ 本地AI能力已接入（Ollama + 4个模型）

### 主要问题
- ❌ 宪法章节编号混乱
- ❌ API前缀不一致
- ❌ 数据库表前缀混乱（105个表）
- ❌ 规则执行保障不足
- ❌ 监控告警机制缺失

### 核心建议
**建立"规则执行自动化"机制**：将宪法规则转化为可执行的检查工具，每次修改代码后自动运行规则检查，确保规则不变成废纸。

---

*本报告由系统架构分析生成，建议结合AI深度分析结果综合判断。*


============================================================
# § 17. 【来源：应急处理手册.md】
============================================================

# 水利智学系统 - 应急处理手册

## 一、问题快速定位6步流程

### 步骤1：查看错误日志
```bash
# 查看最近10条ERROR日志
cd backend/data/logs
type app.log | findstr "ERROR" | Select-Object -Last 10
```

### 步骤2：查看服务状态
```
访问: http://localhost:8000/api/v1/monitor/health
查看: status, degradation_level, memory_usage_mb, total_errors
```

### 步骤3：复现问题
- 记录操作步骤
- 记录预期结果和实际结果
- 记录浏览器控制台错误

### 步骤4：定位代码
- 查看日志中的文件名和行号
- 搜索相关功能代码
- 检查最近修改记录

### 步骤5：判断影响范围
- 核心功能（登录、刷题、闪卡）
- 边缘功能（统计、导出）
- 单模块问题 vs 全局问题

### 步骤6：选择处理方案
- 修复：快速修复代码
- 降级：关闭异常功能，使用替代方案
- 回滚：恢复到最近验证版本

---

## 二、三级降级方案

### L1 功能降级（某功能异常但不影响核心）
**触发条件：**
- 单个功能连续报错超过10次
- 内存使用超过500MB
- 平均响应时间超过3秒

**处理方式：**
- 关闭该功能，显示"暂不可用"
- 使用简化版替代（如AI降级为本地搜索）
- 记录错误日志，待修复后重新启用

**操作命令：**
```
POST /api/v1/monitor/feature/{feature_name}/disable
POST /api/v1/monitor/feature/{feature_name}/enable
```

### L2 模块降级（某模块异常影响体验）
**触发条件：**
- 多个功能同时异常
- 内存使用超过800MB
- 错误率超过10%

**处理方式：**
- 整个模块降级为简单模式
- 关闭非核心功能（如AI分析、高级统计）
- 保留核心刷题、闪卡功能

**操作命令：**
```
POST /api/v1/monitor/degradation/2
Body: {"reason": "模块异常"}
```

### L3 系统回滚（系统崩溃无法快速修复）
**触发条件：**
- 服务无法启动
- 核心功能全部异常
- 数据损坏风险

**处理方式：**
- 一键回滚到最近验证版本
- 使用备份恢复代码和数据库
- 通知用户系统维护中

**操作步骤：**
1. 停止服务
2. 恢复最近备份（backups/目录）
3. 重启服务
4. 验证核心功能

---

## 三、常见问题处理

### 问题1：服务无法启动
**症状：** 访问localhost:8000无响应

**排查：**
1. 检查端口占用：`netstat -ano | findstr :8000`
2. 查看启动日志：`python backend/main.py`
3. 检查Python依赖：`pip list`

**处理：**
- 端口被占用：杀掉占用进程，或修改端口
- 依赖缺失：`pip install -r requirements.txt`
- 代码错误：查看错误日志，修复后重启

### 问题2：数据库损坏
**症状：** 数据库查询报错，数据丢失

**排查：**
1. 检查数据库文件：`backend/data/shuili_exam.db`
2. 尝试打开数据库：`sqlite3 shuili_exam.db .tables`

**处理：**
- 从备份恢复数据库
- 使用sqlite3修复：`sqlite3 shuili_exam.db ".recover"`
- 重建索引：`REINDEX`

### 问题3：内存泄漏
**症状：** 内存持续增长，服务变慢

**排查：**
1. 查看监控：`/api/v1/monitor/health`
2. 检查memory_usage_mb

**处理：**
- 重启服务释放内存
- 检查大查询，添加分页
- 关闭非核心功能（L1降级）

### 问题4：上传文件失败
**症状：** PDF/视频上传无响应

**排查：**
1. 检查uploads目录权限
2. 检查文件大小限制
3. 查看后端日志

**处理：**
- 检查磁盘空间
- 增加上传大小限制
- 检查文件格式支持

### 问题5：离线模式无法使用
**症状：** 断网后页面无法访问

**排查：**
1. 检查Service Worker是否注册
2. 检查缓存资源是否完整
3. 查看浏览器控制台

**处理：**
- 重新注册Service Worker
- 清除缓存后重新加载
- 检查网络配置

---

## 四、数据安全保障

### 修改前
- 自动增量备份
- 记录操作日志
- 可撤销最近10次操作

### 恢复前
- 安全网备份（自动备份当前版本）
- 完整性验证（检查文件完整性）
- 恢复后功能验证
- 失败自动回滚

### 删除前
- 二次确认
- 软删除（标记is_deleted）
- 保留30天可恢复

---

## 五、应急联系人

- 系统管理员：[待填写]
- 技术支持：[待填写]
- 备份位置：`backups/`目录
- 日志位置：`backend/data/logs/`目录

---

## 六、恢复验证清单

恢复后必须验证：
- [ ] 服务正常启动（HTTP 200）
- [ ] 登录功能正常
- [ ] 刷题功能正常
- [ ] 闪卡功能正常
- [ ] 数据完整（题目数、闪卡数）
- [ ] 备份可恢复
- [ ] 日志正常记录


============================================================
# § 18. 【来源：优化建议报告.md】
============================================================

# 系统优化建议报告

生成时间: 2026-09-11 23:07:38

## 一、系统现状总览

### 1.1 需求完成率
- 总需求: 15个
- 已修复: 9个（60%）
- 待修复: 6个（40%）

### 1.2 功能迁移率
- 总功能: 103项
- 已迁移: 51项（49.5%）
- 缺失: 38项（36.9%）
- 旧版无: 14项（13.6%）

### 1.3 数据质量
- 题库总数: 2547题
- 缺解析: 539题（覆盖率78.8%）
- 缺选项: 113题
- 活跃视频: 64个
- 文件库文件: 506个

---

## 二、P0优先级优化（立即处理）

### 2.1 题库数据质量（影响学习体验）
1. **解析补全**: 539题缺解析，已建立AI批量补全工具，可继续运行
2. **选项补全**: 113题缺选项，需检查原始PDF重新提取
3. **格式清理**: 题目中残留"学员专用 请勿外泄"等广告杂质需自动过滤

### 2.2 功能迁移缺口（影响核心功能）

#### video模块缺失功能（9项）
- 自定义播放控制栏
- 倍速播放
- 音频修复
- 音频设备选择
- 视频锁屏
- 视频编辑
- 删除文件夹
- 播放列表搜索
- AI智能笔记

#### library模块缺失功能（1项）
- 文件夹展开

#### question模块缺失功能（2项）
- 下一题
- 上一题

---

## 三、P1优先级优化（本周处理）

### 3.1 学习体验优化
1. 错题本功能完善：错题列表、移除错题、已掌握标记
2. 智能分析：学习统计图表、进度可视化
3. 冲刺中心：冲刺计划、模拟考试、进度跟踪

### 3.2 模块功能完善

#### exam模块缺失功能（6项）
- 开始考试
- 考试计时
- 提交试卷
- 考试结果
- 答题卡
- 标记题目

#### flashcard模块缺失功能（4项）
- 下一张
- 上一张
- 记住了
- 没记住

#### note模块缺失功能（2项）
- 创建笔记
- 删除笔记

#### knowledge模块缺失功能（2项）
- 知识详情
- 知识分类

#### collect模块缺失功能（1项）
- 收藏列表

#### wrong模块缺失功能（3项）
- 错题列表
- 移除错题
- 已掌握

#### analytics模块缺失功能（2项）
- 学习统计
- 图表展示

#### sprint模块缺失功能（3项）
- 冲刺计划
- 模拟考试
- 冲刺进度

#### material模块缺失功能（2项）
- 教材阅读
- 教材搜索

#### dashboard模块缺失功能（1项）
- 学习排行

---

## 四、P2优先级优化（下周处理）

### 4.1 系统机制完善
1. 数据库表清理：26个废弃表标记并制定清理计划
2. 质量门禁接入：将quality_gate_framework接入所有数据入口
3. AI智能笔记优化：接入真实Ollama后测试效果，优化提示词

### 4.2 性能优化
1. 题库加载性能：1700题分页加载优化
2. 文件库加载：500+文件虚拟滚动
3. 视频加载：FLV视频预加载和缓存

---

## 五、优化路线图

### 短期（1-3天）
- [ ] 继续运行题库解析AI补全（目标覆盖率90%+）
- [ ] 补全视频模块缺失功能（倍速播放、播放列表搜索）
- [ ] 修复题库格式问题（广告杂质自动过滤）

### 中期（1周）
- [ ] 补全错题本/智能分析/冲刺中心功能
- [ ] 完成数据库表清理计划执行
- [ ] 质量门禁接入主流程

### 长期（2周）
- [ ] 功能迁移率提升到80%+
- [ ] 题库解析覆盖率提升到95%+
- [ ] 系统性能优化完成

---

## 六、关键指标目标

| 指标 | 当前 | 目标 | 提升幅度 |
|------|------|------|----------|
| 需求完成率 | 60% | 100% | +40% |
| 功能迁移率 | 49.5% | 80%+ | +30.5% |
| 题库解析覆盖率 | {(total_q-no_analysis)/total_q*100:.1f}% | 95%+ | +{95-(total_q-no_analysis)/total_q*100:.1f}% |
| 题库选项覆盖率 | {(total_q-no_options)/total_q*100:.1f}% | 100% | +{100-(total_q-no_options)/total_q*100:.1f}% |


============================================================
# § 19. 【来源：质量保障体系.md】
============================================================

# 水利智学系统 - 质量保障体系

## 一、每阶段10项验收标准

| 序号 | 验收项 | 验收标准 | 验证方式 |
|------|--------|----------|----------|
| 1 | 功能测试通过 | 所有新增功能正常运行，无报错 | 手动测试+自动化测试 |
| 2 | 回归测试通过 | 原有功能不受影响，正常运行 | 全流程回归测试 |
| 3 | 性能达标 | 核心接口响应时间<500ms，页面加载<3s | 性能测试工具 |
| 4 | 代码质量达标 | 无语法错误，无裸except，有日志记录 | 代码审查+静态分析 |
| 5 | 多端适配通过 | PC/平板/手机三端显示正常，交互正常 | 多设备测试 |
| 6 | 离线功能正常 | 断网后核心功能可用，数据可同步 | 离线模拟测试 |
| 7 | 数据完整 | 数据库无损坏，备份可恢复，同步无冲突 | 数据校验+备份恢复测试 |
| 8 | 备份可恢复 | 最新备份验证通过，可一键恢复 | 备份验证+恢复测试 |
| 9 | 文档更新 | 需求文档、API文档、用户手册同步更新 | 文档审查 |
| 10 | 用户验收 | 用户确认功能符合预期，无重大问题 | 用户测试确认 |

## 二、代码审查11项清单

| 序号 | 审查项 | 审查标准 |
|------|--------|----------|
| 1 | 功能完整 | 需求功能全部实现，无遗漏 |
| 2 | 异常处理 | 所有异常都有捕获和处理，无裸except |
| 3 | 日志记录 | 关键操作有日志，错误有详细堆栈 |
| 4 | 性能考虑 | 无N+1查询，无内存泄漏，有缓存策略 |
| 5 | 安全考虑 | 无SQL注入，无XSS，有权限校验，有输入验证 |
| 6 | 可维护性 | 代码结构清晰，命名规范，有注释，模块化 |
| 7 | 兼容性 | 兼容多浏览器，多设备，多分辨率 |
| 8 | 可测试性 | 代码可单元测试，有测试用例 |
| 9 | 多端适配 | PC/平板/手机三端适配，响应式布局 |
| 10 | 离线兼容 | 离线模式下功能正常，数据可同步 |
| 11 | 数据安全 | 敏感数据加密，备份完整，删除可恢复 |

## 三、自动化测试体系

### 3.1 单元测试
- 核心算法：AI推荐、错误分类、智能去重、SM-2记忆、同步冲突
- 工具类：备份管理器、错误分类器、PDF解析器
- 数据模型：数据库模型、序列化器

### 3.2 API测试
- 认证API：登录、注册、Token刷新
- 题库API：题目列表、答题、提交、统计
- 闪卡API：闪卡列表、复习、导入导出
- 备份API：创建、列表、恢复、删除、验证

### 3.3 功能测试
- 刷题流程：选题→答题→提交→查看解析→错题记录
- 闪卡流程：导入→复习→记忆更新→统计
- 考试流程：组卷→答题→交卷→成绩统计
- 同步流程：联网同步→离线使用→联网同步
- 备份流程：创建备份→验证→恢复→验证

### 3.4 性能测试
- 首页加载时间
- 题目列表加载时间
- 答题提交响应时间
- 大数据量查询响应时间
- 并发用户数测试

### 3.5 数据一致性测试
- 多端同步后数据一致
- 离线操作后同步无冲突
- 备份恢复后数据完整
- 数据库事务一致性

## 四、测试报告模板

```
测试报告
==========
测试版本：V4.5.15
测试时间：2026-XX-XX
测试人员：XXX

一、测试概述
- 测试范围：XXX模块
- 测试环境：PC/平板/手机
- 测试数据：XXX条

二、测试结果
| 测试项 | 总数 | 通过 | 失败 | 通过率 |
|--------|------|------|------|--------|
| 功能测试 | XX | XX | XX | XX% |
| 回归测试 | XX | XX | XX | XX% |
| 性能测试 | XX | XX | XX | XX% |
| 多端适配 | XX | XX | XX | XX% |
| 离线功能 | XX | XX | XX | XX% |

三、问题清单
| 序号 | 问题描述 | 严重程度 | 状态 | 修复时间 |
|------|----------|----------|------|----------|
| 1 | XXX | 高/中/低 | 待修复/已修复 | XXX |

四、性能指标
- 首页加载：XXms
- 题目列表：XXms
- 答题提交：XXms
- 并发用户：XX人

五、结论
- 是否通过验收：是/否
- 遗留问题：XXX
- 建议：XXX
```

## 五、应急处理机制

### 5.1 问题快速定位6步流程
1. 查看错误日志（最近10条ERROR）
2. 查看监控面板（服务状态+性能指标）
3. 复现问题（记录操作步骤+预期+实际）
4. 定位代码（日志中的文件+行号）
5. 判断影响范围（核心功能/边缘功能/单模块）
6. 选择处理方案（修复/降级/回滚）

### 5.2 三级降级方案
- **L1 功能降级**：某功能异常但不影响核心 → 关闭该功能，显示"暂不可用"
- **L2 模块降级**：某模块异常影响体验 → 降级为简单模式（AI降级本地搜索）
- **L3 系统回滚**：系统崩溃无法快速修复 → 一键回滚最近验证版本

### 5.3 数据安全保障
- 修改前：自动增量备份+操作日志+可撤销最近10次
- 恢复前：安全网备份+完整性验证+恢复后功能验证+失败自动回滚
- 删除前：二次确认+软删除（标记is_deleted）+保留30天可恢复

## 六、版本发布检查清单

- [ ] 所有功能测试通过
- [ ] 所有回归测试通过
- [ ] 性能指标达标
- [ ] 代码审查通过
- [ ] 多端适配测试通过
- [ ] 离线功能测试通过
- [ ] 数据完整性验证通过
- [ ] 备份可恢复验证通过
- [ ] 文档同步更新
- [ ] 用户验收确认
- [ ] 发布前完整备份创建



======================================================================
# 附录7 【来源：布局规范总集.md】
======================================================================

# 📐 布局规范总集（现行唯一）
> 版本 V1.0 ｜ 2026-09-13 ｜ 由布局规范/ 目录12份合并而成，每份标注来源，原文件已归档。
> ⚠️ 布局锁死：本合集内容只聚合不改一字。

## 📑 目录
1. 【来源：布局落地计划_阶段二.md】
2. 【来源：阶段分级计划_骨架与血肉.md】
3. 【来源：模块化组件化架构设计_宪法级.md】
4. 【来源：内联样式迁移机制实施细则.md】
5. 【来源：全生命周期统一调度看板.md】
6. 【来源：水利智学系统布局宪法与实施细则.md】
7. 【来源：水利智学系统总指挥总调度手册.md】
8. 【来源：统一入口体系_骨架与血肉.md】
9. 【来源：系统文件总索引与执行清单.md】
10. 【来源：系统血液循环架构图.md】
11. 【来源：系统运行保障全体系.md】
12. 【来源：效果图HTML问题修复记录.md】

---



============================================================
# § 1. 【来源：布局落地计划_阶段二.md】
============================================================

# 布局落地计划 — 阶段二

> 原则：逐个页面对照V2.0效果图，只改布局，不改功能
> 生成时间：2026-09-09

---

## 一、页面清单与优先级

### P0 — 高频页面（立即处理）
| 序号 | 页面 | 页面类型 | 主要问题 | 状态 |
|------|------|----------|----------|------|
| 1 | 学习看板 | kanban | 三区域比例/日历7列/3px间距 | ✅ 已确认OK |
| 2 | 题库管理 | list | 一行显示/列宽固定/表头固定 | ⏳ 待处理 |
| 3 | 模拟考试 | exam | 题与题间隔/答题卡/进度条 | ⏳ 待处理 |
| 4 | 视频播放 | split | 6:4比例/去除视频章节 | ⏳ 待处理 |
| 5 | 闪卡管理 | list | 图标/布局/间距 | ⏳ 待处理 |

### P1 — 常用页面（第二批）
| 序号 | 页面 | 页面类型 | 主要问题 | 状态 |
|------|------|----------|----------|------|
| 6 | 题库刷题 | list | 题目显示/选项布局 | ⏳ 待处理 |
| 7 | 错题本 | list | 列表布局 | ⏳ 待处理 |
| 8 | 学习笔记 | split | 左右分栏 | ⏳ 待处理 |
| 9 | 思维导图 | mindmap | 画布布局 | ⏳ 待处理 |
| 10 | 系统设置 | form | 表单布局/显示不全 | ⏳ 待处理 |

### P2 — 其他页面（第三批）
| 序号 | 页面 | 页面类型 | 状态 |
|------|------|----------|------|
| 11 | AI拍照解题 | base | ⏳ |
| 12 | 学习资料库 | list | ⏳ |
| 13 | 我的收藏 | list | ⏳ |
| 14 | 课程教材 | list | ⏳ |
| 15 | 智能分析 | dashboard | ⏳ |
| 16 | 记忆训练 | kanban | ⏳ |
| 17 | 冲刺中心 | base | ⏳ |

---

## 二、全局布局规则（所有页面通用）

### 2.1 固定区域
- **顶部导航栏**：高度48px，白色背景，固定不动
- **竖向导航栏**：宽度200px，粉色背景，固定不动
- **底部状态栏**：高度28px，固定不动
- **关系**：竖向导航栏下边线与状态栏上边线完美重合，不重叠

### 2.2 内容区
- 内容区大边框保留
- 最外圈大边框颜色统一
- 所有方框微圆角
- 一页显示，内容超出时内容区内部滚动，禁止横向滚动条

### 2.3 图标
- 所有图标带圆角
- 图标底色为淡蓝色
- 图标内内容紧凑大方，不忽大忽小

### 2.4 表格
- 表头固定
- 表格标题与内容同列
- 列宽固定（按多选情况布局）
- 题库管理一行显示（不超页面宽度）

### 2.5 Tab
- 能一行显示的绝对不两行
- 增加内容展示区空间

---

## 三、各页面具体修改项

### 3.1 学习看板（kanban）
- ✅ 三区域比例：快捷入口1.8 + 今日目标1.8 + 学习日历1.4
- ✅ 日历7列
- ✅ 最下面行距离状态栏顶边线3px
- ✅ 快捷入口8图标（4列2行）
- ⏳ 统计卡片区5列网格

### 3.2 题库管理（list）
- ⏳ 筛选栏一行显示（不超页面宽度）
- ⏳ 表头固定
- ⏳ 列宽：序号/题干/题型/章节/答案/年份/类型/操作
- ⏳ 答案列用ABCDE测试宽度
- ⏳ 题型/章节/答案/年份/类型/操作列适当加宽

### 3.3 模拟考试（exam）
- ⏳ 题目与题目卡片之间间隔缩小（最好没有）
- ⏳ 答题卡布局（题多/题少两种情况）
- ⏳ 进度条显示
- ⏳ 去除题目之间的"<"符号

### 3.4 视频播放（split）
- ⏳ 视频播放器6:4比例
- ⏳ 去除视频章节
- ⏳ 左侧视频+讲义列表，右侧视频列表
- ⏳ 视频播放器布满左侧区域

### 3.5 系统设置（form）
- ⏳ 竖向导航栏下边线与状态栏上边线重合
- ⏳ 显示区高度调整，不被遮挡
- ⏳ 输入框显示不全问题
- ⏳ 弹窗四挡后消失问题

---

## 四、执行顺序

1. **P0页面**：题库管理 → 模拟考试 → 视频播放 → 闪卡管理
2. **P1页面**：题库刷题 → 错题本 → 学习笔记 → 思维导图 → 系统设置
3. **P2页面**：剩余页面逐个处理
4. **全局优化**：图标圆角/淡蓝色/3px间距/表格规则

---

## 五、验证标准

每个页面修改后必须验证：
1. 页面正常加载，无JS错误
2. 布局与效果图V2.0一致
3. 功能不受影响
4. 一页显示，无横向滚动条
5. 固定区域（导航栏/状态栏）位置正确


============================================================
# § 2. 【来源：阶段分级计划_骨架与血肉.md】
============================================================

# 阶段分级计划 — 骨架先建立，血肉选择丰满

> 原则：先把所有架构/框架/接口建好（骨架），再按优先级分阶段填充具体实现（血肉）
> 生成时间：2026-09-09

---

## 一、骨架阶段（已完成 ✅）

### 1.1 统一入口骨架
| 项目 | 状态 | 文件 |
|------|------|------|
| 前端统一入口 SystemCenter.js | ✅ | frontend/static/js/system-center.js |
| index.html统一启动 | ✅ | frontend/index.html |
| 后端统一入口 system_center.py | ✅ | tools/system_center.py（16+1命令） |
| 定时调度器 Scheduler | ✅ | system_center.py内置 |

### 1.2 系统总控骨架
| 项目 | 状态 | 文件 |
|------|------|------|
| system-controller.js | ✅ | frontend/static/js/system-controller.js |
| 事件总线 EventBus | ✅ | system-controller.js内置 + SystemCenter内置 |

### 1.3 监督机器人骨架
| 项目 | 状态 | 文件 |
|------|------|------|
| system-supervisor.js（12项检查） | ✅ | frontend/static/js/system-supervisor.js |
| 检查函数实现（修正模块名） | ✅ | 已适配真实系统模块名 |

### 1.4 布局体系骨架
| 项目 | 状态 | 文件 |
|------|------|------|
| V2布局接入层.js（智能布局生成器） | ✅ | 布局规范/V2布局接入层.js |
| V2布局规则_统一版.css | ✅ | frontend/css/V2布局规则_统一版.css |
| 布局类名映射器 | ✅ | frontend/static/js/layout-class-mapper.js |
| 唯一布局标准V2.0效果图HTML | ✅ | 布局规范/唯一布局标准V2.0_全品类效果图.html |
| 布局宪法与实施细则 | ✅ | 布局规范/水利智学系统布局宪法与实施细则.md |

### 1.5 文件管理骨架
| 项目 | 状态 | 文件 |
|------|------|------|
| 黄金备份 | ✅ | backups/GOLDEN_黄金备份_*/ |
| 自动备份工具 | ✅ | tools/auto_backup.py |
| 文件指纹库 | ✅ | backups/file_fingerprints.json |
| 文件唯一性保障规范 | ✅ | 布局规范/文件唯一性保障规范.md |
| 文件隔离区 | ✅ | _quarantine_待删除_20260909/ |

### 1.6 智能机器人骨架
| 项目 | 状态 | 文件 |
|------|------|------|
| 巡查机器人 | ✅ | tools/patrol_robot.py |
| 需求记录机器人 | ✅ | tools/requirement_recorder.py |

### 1.7 知识库骨架
| 项目 | 状态 | 文件 |
|------|------|------|
| 踩坑记录 | ✅ | docs/知识库/踩坑记录.md |
| 问题解决方案库 | ✅ | docs/知识库/问题解决方案库.md |
| 回归测试清单 | ✅ | docs/知识库/回归测试清单.md |
| 变更管理规范 | ✅ | docs/知识库/变更管理规范.md |
| 回滚预案模板 | ✅ | docs/知识库/回滚预案模板.md |

### 1.8 全生命周期架构骨架
| 项目 | 状态 | 文件 |
|------|------|------|
| 全生命周期统一调度看板 | ✅ | 布局规范/全生命周期统一调度看板.md |
| 系统血液循环架构图 | ✅ | 布局规范/系统血液循环架构图.md |
| 系统运行保障全体系 | ✅ | 布局规范/系统运行保障全体系.md |
| 总指挥总调度手册 | ✅ | 布局规范/总指挥总调度手册.md |

---

## 二、血肉阶段（分优先级填充）

### 阶段一：核心连通（P0 — 立即执行）
**目标：让骨架真正跑起来，模块间连通**

| 编号 | 任务 | 说明 | 预估 |
|------|------|------|------|
| F1.1 | 业务模块自动注册验证 | 刷新页面，F12查看SystemCenter.getStatus()，确认50+模块注册 | 5min |
| F1.2 | 监督机器人12项检查运行 | SystemSupervisor.runNow()，查看报告，修复critical项 | 10min |
| F1.3 | 布局类名映射验证 | LayoutClassMapper.validate()，确认130+映射 | 5min |
| F1.4 | 事件总线连通测试 | 模块间通过EventBus通信，不直接依赖 | 10min |
| F1.5 | 全局科目关联修复 | 登录选择→内容页科目显示（一造水利案例等简称） | 30min |

### 阶段二：布局落地（P1 — 本周完成）
**目标：V2布局标准真正应用到真实系统**

| 编号 | 任务 | 说明 | 预估 |
|------|------|------|------|
| F2.1 | 页面类型自动识别 | 自动检测当前页面类型（base/list/tabs/split/form/kanban/exam） | 30min |
| F2.2 | 59个页面逐个对照V2.0 | 登录/看板/题库/考试/闪卡/记忆/导图/视频/笔记/分析/设置 | 4h |
| F2.3 | 布局具体优化项修复 | 题库管理一行显示/导航栏与状态栏重合/视频6:4/表头等 | 2h |
| F2.4 | 布局规则写入HTML说明 | 导航栏与状态栏关系/配色/间距/3px规则等 | 1h |

### 阶段三：功能完善（P2 — 下周完成）
**目标：6大核心功能完善**

| 编号 | 任务 | 说明 | 预估 |
|------|------|------|------|
| F3.1 | 题库功能完善 | 题库管理/刷题/章节考试/答题卡 | 2h |
| F3.2 | 闪卡功能完善 | 闪卡管理/朗读记忆/今日复习/智能TTS | 2h |
| F3.3 | 思维导图完善 | 导图生成/编辑/导出 | 1h |
| F3.4 | 视频播放完善 | 视频缓存/讲义列表/视频列表/6:4比例 | 1h |
| F3.5 | 智能笔记完善 | 笔记编辑/AI总结 | 1h |
| F3.6 | 学习分析完善 | 学习数据/图表/AI学习建议（40天vs47天） | 1h |

### 阶段四：界面优化（P2 — 并行）
**目标：所有界面显示协调**

| 编号 | 任务 | 说明 | 预估 |
|------|------|------|------|
| F4.1 | 输入框显示不全修复 | 下拉框/搜索框提示文字 | 30min |
| F4.2 | 弹窗四挡后消失修复 | 弹窗内容显示不全 | 30min |
| F4.3 | 选中底色改淡色 | 选中的底色太深 | 15min |
| F4.4 | 模拟考试题与题间隔去除 | 题目卡片之间间隔缩小，去掉<符号 | 15min |
| F4.5 | AI学习功能修复 | 学习计划/建议天数/学习日历/今日目标 | 1h |

### 阶段五：代码治理（P3 — 持续）
**目标：代码整洁，防止混入**

| 编号 | 任务 | 说明 | 预估 |
|------|------|------|------|
| F5.1 | 代码防混入机制 | 检测新代码是否混入旧逻辑 | 1h |
| F5.2 | 内联代码约束规则 | 颜色/尺寸/布局规则集中管理 | 1h |
| F5.3 | 工具脚本统一入口 | 152个工具脚本→system_center.py命令 | 2h |
| F5.4 | 平板/手机代码剥离 | 与电脑端分离，互不干扰 | 2h |
| F5.5 | 数据库整理 | shuili_exam.db(207MB)/空数据库清理 | 1h |

### 阶段六：APK与移动端（P3 — 布局完成后）
**目标：手机/平板独立适配**

| 编号 | 任务 | 说明 | 预估 |
|------|------|------|------|
| F6.1 | APK白屏问题 | 安装后白板/正在聆听 | 2h |
| F6.2 | 朗读功能异常 | APK中朗读记忆专项无声音 | 1h |
| F6.3 | 离线模式完善 | 大专业设置/数据缓存/自动跳转 | 2h |
| F6.4 | 手机/平板布局独立 | 与电脑端代码分离 | 2h |
| F6.5 | 鸿蒙系统适配 | 卓易通解决方案 | 2h |
| F6.6 | Tailscale协同 | 自动调用/网络变化处理 | 1h |

### 阶段七：安全与性能（P4 — 长期）
**目标：系统稳定高效**

| 编号 | 任务 | 说明 | 预估 |
|------|------|------|------|
| F7.1 | 性能基线建立 | 首屏/API/内存基线 | 1h |
| F7.2 | 前端大文件优化 | 6个JS>500KB，共7.2MB | 2h |
| F7.3 | 操作审计 | 合规审计 | 1h |
| F7.4 | 灾备恢复预案 | RTO/RPO标准 | 1h |
| F7.5 | 备份条件标准 | 重大版本/大规模重构/考前稳定版判定 | 30min |

---

## 三、血肉填充选择策略

### 3.1 选择原则
1. **先连通后完善** — 先让骨架跑通（阶段一），再填内容
2. **先布局后功能** — 布局是用户最直观的感受，优先落地（阶段二）
3. **先核心后扩展** — 6大核心功能优先（阶段三），APK/安全靠后
4. **每阶段验证** — 完成一个阶段必须验证通过才进入下一阶段

### 3.2 验证标准
- 阶段一：F12控制台无critical错误，SystemCenter.getStatus()显示50+模块
- 阶段二：59个页面布局与效果图V2.0一致
- 阶段三：6大功能可正常使用，无404/空数据
- 阶段四：所有界面无显示不全/不协调
- 阶段五：代码防混入机制生效，工具脚本统一入口
- 阶段六：APK可正常安装使用，离线模式可用
- 阶段七：性能达标，安全审计通过

### 3.3 回滚保障
- 每阶段开始前自动备份（auto_backup.py）
- 每阶段完成后更新黄金备份
- 出现问题立即回滚到上一阶段备份

---

## 四、当前进度

| 阶段 | 状态 | 完成度 |
|------|------|--------|
| 骨架阶段 | ✅ 已完成 | 100% |
| 阶段一：核心连通 | 🔄 进行中 | 0% |
| 阶段二：布局落地 | ⏳ 待开始 | 0% |
| 阶段三：功能完善 | ⏳ 待开始 | 0% |
| 阶段四：界面优化 | ⏳ 待开始 | 0% |
| 阶段五：代码治理 | ⏳ 待开始 | 0% |
| 阶段六：APK与移动端 | ⏳ 待开始 | 0% |
| 阶段七：安全与性能 | ⏳ 待开始 | 0% |

---

## 五、全部框架建立完成（12个框架文件）

### 5.1 已建立的全部框架

| 序号 | 框架名称 | 文件 | 作用 | 状态 |
|------|----------|------|------|------|
| 1 | 统一入口 | system-center.js | 模块注册/事件总线/健康检查/定时调度 | ✅ |
| 2 | 系统总控 | system-controller.js | 模块管理/布局校验/事件总线 | ✅ |
| 3 | 监督机器人 | system-supervisor.js | 12项自动检查/告警/历史记录 | ✅ |
| 4 | 布局类名映射 | layout-class-mapper.js | V2类名→真实系统类名（130+映射） | ✅ |
| 5 | V2布局接入 | v2-layout-access.js | 智能布局生成器（6种页面类型） | ✅ |
| 6 | 全局科目管理 | global-subject-manager.js | 大专业→专业方向→科目三级选择/关联 | ✅ |
| 7 | 页面类型识别 | page-type-detector.js | 自动识别页面类型/应用对应布局 | ✅ |
| 8 | 6大功能模块 | feature-module-framework.js | 题库/闪卡/导图/视频/笔记/分析统一接口 | ✅ |
| 9 | 代码防混入 | code-anti-mixins.js | 重复函数/全局污染/内联样式检测 | ✅ |
| 10 | 内联代码约束 | inline-code-constraints.js | 颜色/尺寸/布局规则集中管理 | ✅ |
| 11 | 性能监控 | performance-monitor.js | 性能基线/实时监控/告警 | ✅ |
| 12 | 移动端适配 | mobile-adapter-framework.js | 电脑/平板/手机独立布局/离线模式 | ✅ |

### 5.2 框架文件位置
- 所有框架文件：`frontend/js/`（HTTP路径：`/static/js/`）
- 全部已引入 `frontend/index.html`
- 全部HTTP 200验证通过

### 5.3 框架间关系
```
SystemCenter（统一入口）
  ├── EventBus（事件总线）
  ├── SystemController（系统总控）
  ├── SystemSupervisor（监督机器人）
  ├── LayoutClassMapper（布局映射）
  ├── PageTypeDetector（页面识别）→ V2Layout（布局接入）
  ├── GlobalSubjectManager（全局科目）
  ├── FeatureModules（6大功能模块）
  ├── CodeAntiMixins（代码防混入）
  ├── InlineCodeConstraints（内联约束）
  ├── PerformanceMonitor（性能监控）
  └── MobileAdapter（移动端适配）
```

---

## 六、立即执行（阶段一：核心连通）

1. 刷新 http://localhost:8000/
2. F12控制台查看：
   - `[统一入口] 自动注册模块: XX/95`
   - `[监督机器人] 检查报告`
   - `[布局映射] 初始化完成，共 130+ 个V2类名`
   - `[全局科目] 管理器初始化完成`
   - `[页面识别] 框架已加载`
   - `[功能框架] 6大核心功能模块框架已加载`
   - `[防混入] 代码防混入检测器框架已加载`
   - `[内联约束] 内联代码约束规则框架已加载`
   - `[性能监控] 框架已加载`
   - `[移动适配] 移动端适配框架已加载`
3. 输入 `SystemCenter.getStatus()` 查看模块注册情况
4. 输入 `SystemSupervisor.runNow()` 执行检查
5. 输入 `LayoutClassMapper.validate()` 验证映射
6. 输入 `GlobalSubjectManager.help()` 查看科目管理
7. 输入 `FeatureModules.help()` 查看6大功能模块
8. 输入 `MobileAdapter.help()` 查看移动端适配


============================================================
# § 3. 【来源：模块化组件化架构设计_宪法级.md】
============================================================

# 水利智学系统 模块化组件化架构设计（宪法级）

## 一、核心思想：搭积木

```
┌─────────────────────────────────────────────────┐
│              主框架（壳子，不含业务）              │
│  ┌────────┬──────────────────────────────────┐  │
│  │ 顶部导航 │                                  │  │
│  ├────────┼──────────────────────────────────┤  │
│  │        │                                  │  │
│  │ 侧边栏  │        内容区（插槽）              │  │
│  │        │    ┌────────────────────────┐    │  │
│  │        │    │   模块A / 模块B / ...   │    │  │
│  │        │    │   像积木一样插入/拔出    │    │  │
│  │        │    └────────────────────────┘    │  │
│  ├────────┴──────────────────────────────────┤  │
│  │              状态栏                         │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
```

**铁律**：
- 主框架只负责布局容器（顶部/侧边/内容/状态栏），不含任何业务逻辑
- 每个功能模块是独立积木（HTML模板+CSS+JS），自包含
- 模块通过统一接口注册到主框架，不直接修改主框架
- 模块间通过事件总线通信，不直接调用对方函数
- 修改/替换一个模块，不影响其他模块

## 二、目录结构

```
frontend/
├── core/                          # 核心框架（不动）
│   ├── framework.js               # 主框架：布局容器+模块注册+事件总线
│   ├── module-loader.js           # 模块加载器
│   └── event-bus.js               # 事件总线
├── modules/                       # 功能模块（积木）
│   ├── layout/                    # 布局模块
│   │   ├── topbar.js              # 顶部导航
│   │   ├── sidebar.js             # 侧边栏
│   │   ├── statusbar.js           # 状态栏
│   │   └── layout.css
│   ├── dashboard/                 # 学习看板模块
│   │   ├── dashboard.js
│   │   ├── dashboard.html
│   │   └── dashboard.css
│   ├── question/                  # 题库模块
│   │   ├── question-list.js       # 题库列表
│   │   ├── question-practice.js   # 刷题
│   │   ├── question-exam.js       # 模拟考试
│   │   ├── question-manager.js    # 题库管理
│   │   └── question.css
│   ├── flashcard/                 # 闪卡模块
│   │   ├── flashcard.js
│   │   ├── flashcard.html
│   │   └── flashcard.css
│   ├── video/                     # 视频模块
│   │   ├── video-player.js
│   │   ├── video-list.js
│   │   └── video.css
│   ├── note/                      # 笔记模块
│   ├── mindmap/                   # 思维导图模块
│   ├── ai/                        # AI模块
│   ├── analytics/                 # 学习分析模块
│   ├── settings/                  # 设置模块
│   └── system-admin/              # 系统管理模块
├── shared/                        # 共享组件（被模块引用）
│   ├── components/                # UI组件
│   │   ├── card.js
│   │   ├── table.js
│   │   ├── modal.js
│   │   ├── tab.js
│   │   └── form.js
│   ├── utils/                     # 工具函数
│   │   ├── api.js                 # API封装
│   │   ├── storage.js             # 本地存储
│   │   └── format.js              # 格式化
│   └── styles/                    # 共享样式
│       ├── variables.css          # CSS变量
│       └── common.css             # 通用样式
└── index.html                     # 入口，只加载核心框架
```

## 三、模块规范

每个模块必须遵循以下接口：

```javascript
// 模块定义模板
const MyModule = {
  // 模块元信息
  name: 'question-list',           // 唯一标识
  version: '1.0.0',
  dependencies: ['api', 'storage'], // 依赖的共享模块
  
  // 模块状态（内部私有）
  state: {
    items: [],
    loading: false
  },
  
  // 初始化（模块被加载时调用）
  init(container, context) {
    this.container = container;     // 内容区DOM元素
    this.context = context;         // 框架上下文（API、事件总线等）
    this.render();
    this.bindEvents();
  },
  
  // 渲染（只操作自己的container）
  render() {
    this.container.innerHTML = this.template();
  },
  
  // HTML模板
  template() {
    return `<div class="question-list">...</div>`;
  },
  
  // 事件绑定（只绑定自己container内的事件）
  bindEvents() {
    this.container.querySelector('.btn').onclick = () => this.doSomething();
  },
  
  // 模块方法
  doSomething() {
    // 通过事件总线通知其他模块
    this.context.events.emit('question:selected', { id: 1 });
  },
  
  // 销毁（模块被卸载时调用，清理资源）
  destroy() {
    this.container.innerHTML = '';
    this.state = {};
  }
};

// 注册模块
Framework.register(MyModule);
```

## 四、主框架核心API

```javascript
// 框架全局对象
window.Framework = {
  // 模块注册
  register(module) { ... },
  
  // 模块加载（切换页面时调用）
  load(moduleName, params) { ... },
  
  // 模块卸载
  unload(moduleName) { ... },
  
  // 事件总线
  events: {
    on(event, callback) { ... },
    off(event, callback) { ... },
    emit(event, data) { ... }
  },
  
  // 共享服务
  services: {
    api: { ... },      // API封装
    storage: { ... },  // 本地存储
    auth: { ... },     // 认证
    subject: { ... }   // 全局科目
  },
  
  // 布局控制
  layout: {
    setTitle(title) { ... },
    setSidebar(items) { ... },
    setStatus(text) { ... },
    showLoading() { ... },
    hideLoading() { ... }
  }
};
```

## 五、事件总线通信规范

模块间**禁止直接调用**，必须通过事件总线：

```javascript
// 题库模块选中题目
Framework.events.emit('question:selected', { questionId: 123 });

// 笔记模块监听（自动关联笔记）
Framework.events.on('question:selected', (data) => {
  this.loadNotesForQuestion(data.questionId);
});

// 事件命名规范：模块名:动作名
// 例如：question:selected, flashcard:updated, video:play
```

## 六、迁移计划（四阶段，不影响现有运行）

### 阶段1：搭建框架（1-2天）
- 创建core/framework.js（布局容器+模块注册+事件总线）
- 创建shared/目录（API封装、工具函数）
- 现有系统继续运行，新框架并行

### 阶段2：布局模块迁移（2-3天）
- 提取顶部导航、侧边栏、状态栏为独立模块
- 主框架只保留布局容器
- 验证布局不变

### 阶段3：功能模块逐个迁移（按优先级）
1. 学习看板模块
2. 题库模块（列表/刷题/考试/管理）
3. 闪卡模块
4. 视频模块
5. 笔记模块
6. 思维导图模块
7. AI模块
8. 学习分析模块
9. 设置模块

**每个模块迁移后立即验证，不影响其他模块**

### 阶段4：清理旧代码
- 所有模块迁移完成后，删除app_v3.js
- 清理重复的CSS
- 性能优化

## 七、防混乱机制（写入宪法）

1. **模块隔离**：每个模块只能操作自己的container，禁止操作其他模块的DOM
2. **事件通信**：模块间只能通过事件总线通信，禁止直接调用
3. **样式隔离**：每个模块的CSS必须加模块名前缀，禁止全局样式
4. **版本管理**：每个模块有独立版本号，修改需更新版本
5. **注册校验**：框架启动时校验所有模块，缺少依赖或重复注册直接报错
6. **热插拔**：模块可以单独加载/卸载，不影响系统运行
7. **修改前检查**：修改模块前必须确认该模块的边界，禁止跨模块修改

## 八、与现有系统的兼容

- 现有app_v3.js继续运行，新模块逐步替换
- 新框架通过`window.Framework`全局对象暴露
- 旧代码可以通过`Framework.events`与新模块通信
- 迁移完成后，旧代码自然废弃


============================================================
# § 4. 【来源：内联样式迁移机制实施细则.md】
============================================================

# 内联样式迁移机制实施细则

> 版本：1.0
> 生效日期：2026-09-10
> 目标：将8698个内联样式逐步迁移到CSS组件化体系

---

## 一、现状分析

| 指标 | 数量 | 说明 |
|------|------|------|
| 内联style属性 | 8698个 | 分布在HTML和JS中 |
| 硬编码颜色值 | 3709个 | 应改用CSS变量 |
| 涉及文件 | 主要在app_v3_897262.js | 动态生成的HTML |

## 二、迁移原则

### 2.1 三不原则
1. **不一次性替换** — 分批迁移，每批验证
2. **不影响功能** — 迁移前后视觉效果必须一致
3. **不新增内联** — 新代码禁止使用内联样式

### 2.2 迁移优先级
| 优先级 | 类型 | 数量估计 | 说明 |
|--------|------|----------|------|
| P0 | 布局相关内联 | ~2000 | 影响布局一致性 |
| P1 | 颜色相关内联 | ~3000 | 改用CSS变量 |
| P2 | 尺寸/间距内联 | ~2000 | 改用spacing变量 |
| P3 | 其他样式 | ~1700 | 逐步清理 |

## 三、迁移方法

### 3.1 静态HTML中的内联样式
```html
<!-- 迁移前 -->
<div style="background: #e3f2fd; border-radius: 8px; padding: 8px;">

<!-- 迁移后 -->
<div class="icon-card">
```

### 3.2 JS动态生成的内联样式
```javascript
// 迁移前
element.style.background = '#e3f2fd';
element.style.borderRadius = '8px';
element.style.padding = '8px';

// 迁移后
element.classList.add('icon-card');
```

### 3.3 颜色硬编码迁移
```javascript
// 迁移前
element.style.color = '#3949ab';

// 迁移后（使用CSS变量）
element.style.color = 'var(--color-primary)';
// 或更好：添加class
element.classList.add('text-primary');
```

## 四、分批执行计划

### 第一批（布局相关）
- 目标：导航栏、状态栏、内容区布局样式
- 数量：约500处
- 验证：布局检查器通过

### 第二批（颜色相关）
- 目标：所有硬编码颜色改用CSS变量
- 数量：约3000处
- 验证：全局配色一致

### 第三批（组件相关）
- 目标：按钮、卡片、表格、表单
- 数量：约3000处
- 验证：组件化覆盖率>80%

### 第四批（剩余清理）
- 目标：剩余所有内联样式
- 数量：约2200处
- 验证：内联样式<500个

## 五、验证机制

### 5.1 每次迁移后必须验证
1. 布局检查器运行通过
2. 巡查机器人无新增问题
3. 核心页面视觉对比一致
4. 浏览器控制台无报错

### 5.2 迁移进度追踪
- 在系统管理中心显示迁移进度
- 每批迁移后更新统计数据
- 目标：内联样式从8698降至<500

## 六、防混入机制

### 6.1 新代码规范
- 所有新代码必须使用组件类名
- 禁止在JS中使用element.style.xxx
- 禁止在HTML中使用style属性
- 特殊情况必须标注 `// 临时内联样式，待迁移`

### 6.2 代码审查检查项
- [ ] 是否有新增内联样式
- [ ] 是否有新增硬编码颜色
- [ ] 是否使用了CSS变量
- [ ] 是否使用了组件类名

---

**本文件写入宪法实施细则，所有开发必须遵守。**


============================================================
# § 5. 【来源：全生命周期统一调度看板.md】
============================================================

# 水利智学系统 - 全生命周期统一调度看板

> 版本：V1.0  
> 一个入口管理：全阶段 + 全内容 + 全方面  
> 统一命令：`python tools/system_center.py <命令>`

---

## 一、全阶段管理

### 阶段定义与切换

| 阶段 | 标识 | 特征 | 准入条件 | 准出条件 |
|------|------|------|----------|----------|
| **开发期** | DEV | 功能开发、布局优化、代码迭代 | 需求明确 | P0问题清零，核心功能可用 |
| **测试期** | TEST | 全面测试、Bug修复、性能优化 | 开发期准出 | 测试用例通过率≥95% |
| **预发布期** | RC | 预发布验证、用户验收 | 测试期准出 | 用户验收通过 |
| **上线期** | RELEASE | 正式发布、版本冻结 | 预发布准出 | 稳定运行7天 |
| **运维期** | OPS | 日常运维、监控告警 | 上线期准出 | - |

### 当前阶段：🔴 开发期

**阶段目标**：布局V2.0全面落地 + 核心功能完善 + 代码治理

**阶段里程碑**：
- [x] 布局标准V2.0效果图锁死
- [x] V2布局接入层建立
- [x] 系统总控+监督机器人上线
- [x] 文件管理体系建立
- [x] 系统指挥中心建立
- [ ] P0问题清零（题库404/闪卡404/HTML结构）
- [ ] 布局全面对照V2.0执行
- [ ] 核心功能完善（题库/闪卡/思维导图/视频/笔记/分析）
- [ ] 代码治理完成
- [ ] 进入测试期

---

## 二、全内容管理（8大模块）

### 模块1：布局模块 🎨

| 项目 | 状态 | 说明 |
|------|------|------|
| 效果图V2.0 | 🔒 锁死 | 唯一标准，不允许改结构 |
| 布局接入层 | ✅ 已建立 | 智能生成器+校验器 |
| 布局CSS | ✅ 已引入 | V2布局规则_统一版.css |
| 布局宪法 | ✅ 已建立 | 最高准则 |
| 电脑端布局 | ⚠️ 待优化 | 需全面对照V2.0 |
| 平板端布局 | ⏸️ 暂停 | 电脑端完成后再做 |
| 手机端布局 | ⏸️ 暂停 | 电脑端完成后再做 |

**待办**：
- [ ] 修复效果图HTML结构（div 1106开/1105闭）
- [ ] 电脑端所有页面对照V2.0优化
- [ ] 布局合规检查自动化

### 模块2：功能模块 ⚙️

| 项目 | 状态 | 说明 |
|------|------|------|
| 题库管理 | ❌ 404 | questions.json缺失 |
| 闪卡管理 | ❌ 空 | 闪卡数据目录为空 |
| 思维导图 | ⚠️ 待完善 | 基础功能有，需优化 |
| 视频播放 | ⚠️ 待完善 | 6:4比例，去除章节 |
| 智能笔记 | ⚠️ 待完善 | 需测试 |
| 学习分析 | ⚠️ 待完善 | 需测试 |
| 朗读功能 | ❌ 异常 | 无声音/切换过快 |
| 离线模式 | ⚠️ 待完善 | APK端问题多 |

**待办**：
- [ ] 修复题库404
- [ ] 修复闪卡数据
- [ ] 修复朗读功能
- [ ] 完善6大核心功能

### 模块3：代码模块 💻

| 项目 | 状态 | 说明 |
|------|------|------|
| 前端JS | ⚠️ 53个文件 | 6个大文件(>500KB)需拆分 |
| 后端Python | ✅ 163个文件 | 结构完整 |
| 工具脚本 | ⚠️ 152个 | 过多，需统一入口 |
| 代码质量规范 | ✅ 已建立 | CODE_QUALITY_GUIDE.md |
| 代码安全规范 | ✅ 已建立 | CODE_SAFETY_RULES.md |
| 内联代码约束 | ⚠️ 待完善 | 需全面执行 |

**待办**：
- [ ] 工具脚本统一入口（system_center.py已建）
- [ ] 大JS文件拆分/懒加载
- [ ] 代码审查流程建立
- [ ] 内联代码约束全面执行

### 模块4：数据模块 📊

| 项目 | 状态 | 说明 |
|------|------|------|
| 题库数据 | ❌ 缺失 | questions.json 404 |
| 闪卡数据 | ❌ 为空 | flashcards目录无文件 |
| 视频数据 | ⚠️ 待检查 | 缓存机制需完善 |
| PDF数据 | ⚠️ 待检查 | 缓存机制需完善 |
| 考试配置 | ✅ 正常 | exam_config.json |
| 用户数据 | ⚠️ 待检查 | 本地存储机制 |

**待办**：
- [ ] 恢复题库数据
- [ ] 补全闪卡数据
- [ ] 视频/PDF缓存机制完善
- [ ] 数据字典文档

### 模块5：安全模块 🔒

| 项目 | 状态 | 说明 |
|------|------|------|
| XSS防护 | ⚠️ 待检查 | 需全面检查 |
| 输入验证 | ⚠️ 待完善 | 前后端校验 |
| 数据加密 | ⏸️ 计划中 | 敏感数据加密 |
| 权限控制 | ⚠️ 待完善 | 登录权限 |
| 代码安全规范 | ✅ 已建立 | CODE_SAFETY_RULES.md |

**待办**：
- [ ] XSS防护全面检查
- [ ] 统一错误处理
- [ ] 安全加密实现

### 模块6：性能模块 ⚡

| 项目 | 状态 | 说明 |
|------|------|------|
| 首屏加载 | ⚠️ 待优化 | 大JS文件影响 |
| JS体积 | ❌ 过大 | 6个文件>500KB，共7.2MB |
| 数据库索引 | ⚠️ 待优化 | 需检查慢查询 |
| 内存使用 | ⚠️ 待监控 | 监督机器人已监控 |
| APK体积 | ⚠️ 待优化 | 684MB过大 |

**待办**：
- [ ] JS拆分/懒加载
- [ ] 数据库索引优化
- [ ] APK体积优化
- [ ] 性能基线建立

### 模块7：文档模块 📚

| 项目 | 状态 | 说明 |
|------|------|------|
| 布局宪法 | ✅ 已建立 | 最高准则 |
| 总指挥手册 | ✅ 已建立 | 调度准则 |
| 文件管理体系 | ✅ 已建立 | 唯一性+备份 |
| 系统血液循环 | ✅ 已建立 | 七层架构 |
| 运行保障体系 | ✅ 已建立 | 七层保障 |
| 专家分析报告 | ✅ 已建立 | 68项缺失 |
| 文件总索引 | ✅ 已建立 | 本看板前身 |
| 本调度看板 | ✅ 已建立 | 全生命周期统一管理 |
| API文档 | ⏸️ 待建立 | 后端API文档 |
| 数据字典 | ⏸️ 待建立 | 数据结构说明 |
| 用户手册 | ⏸️ 待建立 | 操作指南 |

**待办**：
- [ ] 后端API文档
- [ ] 数据字典文档
- [ ] 用户操作手册

### 模块8：运维模块 🛠️

| 项目 | 状态 | 说明 |
|------|------|------|
| 系统总控 | ✅ 已运行 | system-controller.js |
| 监督机器人 | ✅ 已运行 | system-supervisor.js |
| 指挥中心 | ✅ 已建立 | system_center.py（14命令） |
| 自动备份 | ✅ 已建立 | auto_backup.py |
| 黄金备份 | ✅ 已建立 | 15个关键文件 |
| 归档清理 | ⚠️ 待执行 | 8个归档目录共1440个文件 |
| 日志轮转 | ⚠️ 待完善 | 日志管理机制 |
| 健康检查 | ✅ 已运行 | 总控每30秒+监督每60秒 |

**待办**：
- [ ] 归档文件清理（1440个文件）
- [ ] 日志轮转机制
- [ ] 巡查机器人脚本化
- [ ] 需求记录机器人脚本化

---

## 三、全方面管理（6大维度）

### 维度1：需求管理 📋

- 需求来源：用户对话 + 专家建议 + 问题反馈
- 需求记录：自动记录到需求池
- 需求优先级：P0(紧急)/P1(高)/P2(中)/P3(低)
- 需求追踪：从提出到完成全链路追踪
- **工具**：`python tools/system_center.py todo`

### 维度2：质量管理 ✅

- 质量门禁：每个阶段准出条件
- 代码审查：修改前分析+修改后验证
- 测试覆盖：核心功能测试用例
- 布局校验：V2.0合规自动检查
- **工具**：`python tools/system_center.py check` + `layout`

### 维度3：进度管理 📈

- 里程碑：每个阶段关键节点
- 任务看板：P0-P3优先级清单
- 进度追踪：完成一项勾选一项
- 风险预警：延期任务自动提醒
- **工具**：`python tools/system_center.py status` + `todo`

### 维度4：风险管理 ⚠️

- 风险识别：专家分析+自动检测
- 风险评估：影响范围+严重程度
- 风险应对：备份+回滚+降级
- 应急预案：应急处理手册
- **工具**：`python tools/system_center.py diagnose`

### 维度5：版本管理 🏷️

- 布局版本：V2.0（锁死）
- 接入层版本：V2.0.0
- 系统版本：语义化版本号
- 版本备份：黄金备份+修改前备份
- 版本对比：diff命令
- **工具**：`python tools/system_center.py diff` + `backup`

### 维度6：协同管理 👥

- 7专家组：布局/功能/代码/数据/安全/性能/运维
- 总指挥：统一调度
- 监督机器人：自动检查
- 专家协同：交叉审查
- **工具**：总指挥手册 + 监督机器人

---

## 四、统一命令入口（14+命令）

```
python tools/system_center.py <命令>

【状态类】
  status      - 系统状态总览（全模块状态一眼看清）
  todo        - 待办任务清单（P0-P3优先级）
  
【检查类】
  check       - 全面健康检查（6项）
  diagnose    - 快速诊断（8项+解决方案）
  layout      - 布局合规检查（10项）
  data        - 数据完整性检查
  
【操作类】
  start       - 快速启动系统
  backup      - 一键备份关键文件
  restore     - 列出可恢复备份
  diff        - 对比当前与黄金备份
  clean       - 清理临时文件
  
【检索类】
  search      - 智能检索所有文件
  logs        - 查看最近错误日志
  
【修复类】
  fix         - 自动修复常见问题
```

---

## 五、当前阶段重点任务（开发期）

### 🔴 P0 - 立即执行（3项）

1. **修复效果图HTML结构** - div 1106开/1105闭，差1个闭合标签
2. **修复题库数据404** - questions.json缺失
3. **补全闪卡数据** - flashcards目录为空

### 🟠 P1 - 本周执行（6项）

4. 布局全面对照V2.0优化
5. XSS防护全面检查
6. 统一错误处理
7. 统一UI组件（Loading/空状态）
8. 巡查机器人脚本化
9. 需求记录机器人脚本化

### 🟡 P2 - 下周执行（6项）

10. 前端JS拆分/懒加载
11. 数据库索引优化
12. 数据字典文档
13. 工具层统一入口
14. 归档文件清理（1440个文件）
15. 代码审查流程

### 🟢 P3 - 计划执行（6项）

16. APK体积优化
17. 多设备代码剥离
18. 安全加密实现
19. 自动化测试覆盖
20. 用户操作手册
21. 性能基线建立

---

## 六、质量门禁（阶段准出条件）

### 开发期 → 测试期
- [ ] P0问题全部清零
- [ ] 核心功能可用（题库/闪卡/视频/笔记/分析）
- [ ] 布局V2.0全面落地
- [ ] 无严重Bug
- [ ] 黄金备份已创建

### 测试期 → 预发布期
- [ ] 测试用例通过率≥95%
- [ ] 性能达标（首屏<3秒）
- [ ] 安全检查通过
- [ ] 用户验收通过

### 预发布期 → 上线期
- [ ] 预发布环境稳定运行7天
- [ ] 无P0/P1问题
- [ ] 文档齐全
- [ ] 回滚方案就绪

---

## 七、维护规则

1. **本看板是唯一调度入口** - 所有任务/进度/状态都在这里
2. **每周更新一次** - 每周一更新进度和待办
3. **完成任务必须勾选** - 在对应清单中勾选
4. **新增任务必须登记** - 加入对应模块和优先级
5. **阶段切换必须评审** - 满足准出条件才能切换阶段

---

**一个入口，全阶段管理，全内容覆盖，全方面把控！**


============================================================
# § 6. 【来源：水利智学系统布局宪法与实施细则.md】
============================================================

# 水利智学系统布局宪法与实施细则

> 版本：V2.0 最终版  
> 生效日期：2026-09-09  
> 地位：系统布局最高准则，所有页面必须严格遵守  
> 冲突解决：有冲突时按最新要求执行，本文件持续更新

---

## 第一部分 布局宪法（最高准则）

### 第一章 总纲

**第一条【唯一标准】**  
唯一布局标准V2.0_全品类效果图.html 是系统布局的唯一标准，所有页面必须严格对照执行。效果图HTML锁死，不允许修改布局结构。

**第二条【先效果图后代码】**  
任何布局调整必须先在效果图HTML中确认，再同步到真实系统代码。禁止直接改代码而不更新效果图。

**第三条【上传图片必看】**  
用户上传的所有图片必须查看，这是铁律。禁止在未查看图片的情况下进行布局修改。

**第四条【分析清楚再改】**  
修改前必须全面分析代码结构和影响范围，禁止来回试验打补丁。同一动作失败两次必须换方案。

**第五条【局部改动不影响全局】**  
所有局部修改必须通过override接口或CSS变量实现，禁止直接修改全局配置。

**第六条【锁死规则】**  
用户明确"锁死"的内容不允许再修改，除非有新的明确指令。

### 第二章 铁律（不可违反）

**第七条【结构完整铁律】**  
HTML结构必须完整，div开始标签和结束标签必须匹配。禁止出现section提前闭合、标签未闭合等问题。

**第八条【一页显示铁律】**  
所有页面必须一页显示，显示不下时只允许内容区出现竖向滚动条，**禁止出现横向滚动条**。

**第九条【导航栏与状态栏关系铁律】**  
竖向导航栏下边线必须与状态栏上边线完美重合，**不允许重叠**。状态栏是绝对定位，导航栏不延伸到状态栏下方。

**第十条【一行显示铁律】**  
Tab、筛选栏、题库管理等能一行显示的绝对不允许两行。一行显示时不得超出页面宽度。

**第十一条【3px间距铁律】**  
学习看板最后一行（今日待复习/AI学习建议/知识点掌握度）的底边线，距离右侧内容区容器（mock-kanban）底边线必须为3px。

**第十二条【代码防混入铁律】**  
新代码必须通过接入层引入，禁止直接混入核心代码。建立代码混入防止机制，后续有计划地逐步替换。

### 第三章 核心原则

**第十三条【真实还原原则】**  
效果图必须真实还原系统界面，图标数量、功能分区、配色方案必须与真实系统一致。

**第十四条【大众审美原则】**  
UI设计要有大众审美观，布局紧凑大方得体，图标不要忽大忽小，颜色协调统一。

**第十五条【内容增减自适应原则】**  
布局框不随内容增减而变化，内容增减时自动调整协调。

**第十六条【设备独立原则】**  
电脑、平板、手机的布局代码独立，不互相干扰。不同显示设备的规则分别写入宪法。

---

## 第二部分 布局实施细则

### 第四章 全局尺寸规范

| 元素 | 尺寸 | 说明 |
|------|------|------|
| 顶部导航栏高度 | 48px | 固定不动 |
| 底部状态栏高度 | 28px | 固定不动，绝对定位 |
| 左侧导航栏宽度 | 160px | 固定不动 |
| 内容区内边距 | 6px | |
| 卡片间距 | 6px | |
| 卡片内边距 | 8px | |
| 卡片圆角 | 8px | 微圆角 |
| 按钮圆角 | 4px | |
| 图标圆角 | 8px | 所有图标带圆角 |
| 图标尺寸 | 24px | |
| 基础字体 | 12px | |
| 小字体 | 10px | |
| 大字体 | 14px | |
| 最外圈大边框 | 2px solid #c5cae9 | 内容区大边框保留 |

### 第五章 全局配色规范

| 用途 | 颜色 | 说明 |
|------|------|------|
| 主色 | #3949ab | 使用频率最高(90次) |
| 主色亮 | #5c6bc0 | |
| 主色背景 | #e8eaf6 | |
| 主色边框 | #c5cae9 | 最外圈大边框 |
| 主要文字 | #333 | |
| 次要文字 | #666 | 使用频率高(82次) |
| 提示文字 | #999 | |
| 白色背景 | #fff | 卡片/顶部导航 |
| 左侧导航栏 | #fce4ec | 粉色 |
| 底部状态栏 | #e8f5e9 | 浅绿，边框#4caf50 |
| 学习看板背景 | #fff8e1 | 浅橙，独立风格 |
| 图标底色 | #e3f2fd | 淡蓝色 |
| 成功色 | #4caf50 | |
| 警告色 | #ff9800 | |
| 危险色 | #f44336 | |
| 分割线 | #ddd | |

**配色要求**：所有页面配色必须与效果图HTML一致，颜色统一写入接入层，禁止页面内硬编码不一致的颜色。

### 第六章 间距阶梯规范

| 名称 | 值 | 使用频率 |
|------|-----|----------|
| spacingLg | 12px | 最高(38次) |
| spacingMd | 6px | 高(28次) |
| spacingBase | 8px | 中(23次) |
| spacingXl | 20px | 中(19次) |
| spacingSl | 16px | 中(18次) |
| spacingSm | 10px | 中(18次) |
| spacingXs | 4px | 低(7次) |
| spacingMini | 2px | 低(10次) |
| spacingBottom | 3px | 底部专用 |

---

## 第三部分 各版块布局细则

### 第七章 登录界面（锁死）

**7.1 界面结构**
- 第一界面：真实系统登录界面（保留）
- 第二界面：科目选择界面（设计优化）

**7.2 选择逻辑（三级联动，每步必选）**
1. 第一步：选择大专业（一造/二造）
2. 第二步：选择专业方向（水利工程/交通工程等）
3. 第三步：选择学习科目（可多选）
- **跳过限制**：不选大专业不能选专业方向，不选专业方向不能选科目，跳过必须有提示
- **科目变化**：大专业选择后，专业课科目名称变化（如案例→一造水利案例），公共课不变
- **二造特殊**：二造只有两个科目，只显示两个框
- **默认显示**：默认显示四个框，选择后才发生变化

**7.3 下拉框规则**
- 下拉框显示层级在最上层，不允许被遮挡
- 大专业、专业方向均为下拉选择
- 专业方向选项：水利工程、交通工程等
- 服务器地址放在系统设置中

**7.4 全局关联**
- 登录界面选择的科目必须与内容页全局科目关联
- 内容页显示的科目名称必须与登录选择一致（如一造水利案例）

### 第八章 A类：标准列表页

**8.1 布局结构**
- 筛选栏：一行显示，不超页面宽度
- 表格：表头固定，列宽固定
- 分页：底部居中

**8.2 表格列宽**
| 列名 | 宽度 |
|------|------|
| 序号 | 50px |
| 题干 | auto |
| 题型 | 80px |
| 章节 | 100px |
| 答案 | 60px（ABCDE显示） |
| 年份 | 60px |
| 类型 | 80px |
| 操作 | 100px |

**8.3 规则**
- 表头固定（sticky）
- 按多选内容布置列宽，内容少时也保持一致
- 禁止横向滚动条
- 题库管理筛选简化，识别等功能去重

### 第九章 B类：Tab切换页

**9.1 布局结构**
- Tab栏：一行显示，不换行
- 内容区：无论内容多少，布局一致

**9.2 规则**
- Tab一行显示，white-space: nowrap
- 章节考试框与历史考试记录框布局一致
- 选中Tab底色为淡色，不要太深

### 第十章 C类：左右分栏页

**10.1 布局结构**
- 左侧：视频播放器（比例6）
- 右侧：视频列表+讲义列表（比例4）

**10.2 规则**
- 视频播放器6:4比例，布满左侧区域
- 去除视频章节
- 下方有讲义列表和视频列表，上下占满
- 视频播放器不允许只显示半截

### 第十一章 D类：表单页

**11.1 布局结构**
- 标签宽度：120px，右对齐
- 输入框：flex:1，显示完整

**11.2 规则**
- 输入框不允许显示不全
- 下拉框、搜索框提示文字显示完整
- 保存按钮位置合理

### 第十二章 E类：学习看板页（独立风格：浅橙背景）

**12.1 三行功能区结构**

**第一行：统计卡片区**
- 5列网格
- 内容：考试倒计时/答题数/正确率/错题数/连续天数

**第二行：功能区第一行（flex:1，拉伸填满）**
- 快捷入口(8图标) + 今日目标 + 学习日历
- 比例：**1.8 : 1.8 : 1.4**
- 快捷入口：4列2行 = 8图标
- 学习日历：7列显示

**第三行：功能区第二行（margin-top:auto，贴底）**
- 今日待复习 + AI学习建议 + 知识点掌握度
- 三等分（1:1:1）
- 底边线距mock-kanban底边线**3px**

**12.2 规则**
- 浅橙背景(#fff8e1)，橙色边框(#ffcc80)
- 第二行flex:1拉伸填满，减少与第三行的间隔
- 第三行margin-top:auto自动贴底
- mock-kanban的padding-bottom:3px
- 学习日历前面两个框宽度压缩，日历一到七显示一行
- 不要出现大量空白，布局协调
- 考试专项记忆训练适当变窄，九大记忆法和记忆工具图标适当变大

### 第十三章 F类：模拟考试进行中

**13.1 布局结构**
- 左侧：题目区（连续显示）
- 右侧：答题卡

**13.2 规则**
- 题目与题目卡片之间间隔为0，最好没有
- 题目之间不允许出现空白条或多余符号
- 答题卡支持题多和题少的显示
- 禁止横向滚动条
- 开始训练按钮按需求删除

### 第十四章 弹窗四档

**14.1 规则**
- 弹窗四档后面的内容必须全部显示
- 弹窗层级在最上层，不允许被遮挡
- 弹窗宽度：600px，圆角8px

### 第十五章 Token页面

**15.1 规则**
- 按效果图执行
- 与其他页面布局一致

### 第十六章 布局结构说明

**16.1 固定区域（不动）**
- 顶部导航栏：白色，48px高
- 左侧导航栏：粉色，160px宽
- 底部状态栏：浅绿，28px高

**16.2 功能区设计**
- 各区域背景色与功能分区颜色一致
- 布局结构说明的各区域背景色必须与实际功能区配色一致

**16.3 导航栏与状态栏关系**
- 竖向导航栏下边线 = 状态栏上边线
- 不是重叠关系
- 必须在HTML中说明清楚

---

## 第四部分 执行机制

### 第十七章 接入层机制

**17.1 文件位置**
`布局规范/V2布局接入层.js`

**17.2 核心功能**
- 核心布局锁死（只读）
- 智能布局生成器：`V2Layout.generate(pageType)`
- 局部改动：`V2Layout.override(pageType, overrides)`
- CSS变量注入：`--v2-color-*` / `--v2-size-*`

**17.3 使用方式**
```js
V2Layout.apply('E');           // 生成并注入E类布局
V2Layout.generate('A');        // 返回A类CSS字符串
V2Layout.override('E', {...}); // 局部改动，不影响全局
```

### 第十八章 布局校验机制

**18.1 校验器**
- `V2Layout.validate('E')` 检查布局是否符合规范
- 返回 `{ valid: boolean, issues: string[] }`

**18.2 校验项**
- 页面类型是否存在
- 看板是否为3行
- 三区域比例是否为1.8:1.8:1.4
- div标签是否匹配
- 是否有横向滚动条

### 第十九章 版本管理机制

**19.1 快照与回滚**
- `V2Layout.snapshot('修改前')` 创建快照
- `V2Layout.rollback(0)` 回滚到指定版本

**19.2 备份条件**
- 重大版本发布前
- 大规模重构前
- 考前稳定版
- 用户明确要求备份时

### 第二十章 巡查机器人机制

**20.1 巡查范围**
- 所有页面布局是否符合V2.0标准
- 宪法执行情况
- 代码混入检测
- 功能完整性检查

**20.2 巡查频率**
- 每次布局修改后自动巡查
- 定期全面巡查

### 第二十一章 需求记录机制

**21.1 需求记录机器人**
- 记录用户所有布局需求
- 跟踪需求执行状态
- 缺失项放入需求池

### 第二十二章 代码治理机制

**22.1 内联代码约束规则**
- 修改前必须全面分析相关内容
- 禁止逐项修改导致功能错乱
- 给出建议后统一修改
- 内联样式逐步迁移到CSS类

**22.2 代码清理计划**
- 先治理数据，再治理代码
- 布局搞清楚后，核心功能完善后，开始代码清理
- 平板、手机代码剥离到独立文件

---

## 第五部分 其他版块规范

### 第二十三章 离线模式

**23.1 功能要求**
- 离线模式具备视频和PDF缓存功能
- 用户可以选择缓存内容
- 智能TTS语音朗读（根据文字读取，非预生成MP3）
- 语音输入只在闪卡语音回答时启用，其他地方禁止

**23.2 网络协同**
- 与Tailscale协同工作
- 考虑网络变化问题
- 联网时增加提示

### 第二十四章 多设备适配

**24.1 设备独立**
- 电脑、平板、手机布局代码独立
- 不互相干扰
- 预留平板测试接口

**24.2 响应式断点**
- 桌面：≥1200px，左侧导航160px
- 平板：768-1199px，左侧导航120px
- 手机：<768px，左侧导航折叠

### 第二十五章 APK打包规范

**25.1 打包前检查**
- 全面虚拟测试20遍
- 模拟真实手机环境测试
- 功能完整性检查（朗读、视频缓存、闪卡等）
- 布局协调性检查（横屏竖屏）

**25.2 禁止问题**
- 白屏
- 正在聆听异常显示
- 功能阉割
- 布局混乱

---

### 第二十六章 组件化架构规范

**26.1 组件化目录结构（唯一标准）**
```
frontend/
├── css/
│   ├── layout/        # 布局组件（唯一布局来源）
│   │   ├── layout-base.css    # 基础布局（全局结构）
│   │   ├── layout-pages.css   # 各页面布局
│   │   ├── layout-v2.css      # V2.0主题引用
│   │   └── layout.css         # 统一入口
│   ├── components/    # UI组件（按钮/卡片/表格/弹窗）
│   ├── pages/         # 页面独有样式
│   └── themes/        # 主题（v2-theme.css等）
├── js/
│   ├── core/          # 核心工具（路由/状态/事件/防混入）
│   ├── components/    # UI组件逻辑
│   ├── pages/         # 页面模块
│   └── services/      # 数据服务（API/缓存/离线）
```

**26.2 命名空间规范（强制）**
- 布局类：`.l-xxx`（如 `.l-sidebar`, `.l-topbar`）
- 组件类：`.c-xxx`（如 `.c-btn`, `.c-card`）
- 页面类：`.p-xxx`（如 `.p-dashboard`）
- 主题类：`.t-xxx`（如 `.t-v2-card`）
- 工具类：`.u-xxx`（如 `.u-flex`, `.u-hidden`）
- **禁止**不同命名空间互相覆盖，只能同命名空间内覆盖

**26.3 属性隔离规则（强制）**
- `css/layout/` 只允许：position/display/width/height/margin/padding/flex/grid/overflow
- `css/components/` 只允许：color/font-size/background/border/animation
- `css/themes/` 只允许：颜色/边框/间距覆盖
- **禁止**在style.css/components.css中出现布局属性
- **禁止**在layout目录中出现功能属性（颜色/字体等）

**26.4 层叠顺序（强制）**
index.html中严格按此顺序引入，后面的覆盖前面的：
1. reset.css（重置）
2. layout/layout-base.css（基础布局）
3. layout/layout-pages.css（页面布局）
4. components/*.css（UI组件）
5. pages/*.css（页面样式）
6. themes/v2-theme.css（主题覆盖，最后生效）

**26.5 防混入机制**
- `js/core/code-anti-mixins.js` 自动检测代码混入
- 检测规则：CSS混写/命名空间合规/跨目录修改/文件职责单一/!important滥用
- 监督机器人 `system-supervisor.js` 每分钟检查组件化执行情况
- 违规修改必须回滚

**26.6 布局调整唯一入口**
- 所有布局调整只改 `css/layout/` 目录
- 禁止直接修改style.css/components.css中的布局属性
- 主题调整只改 `css/themes/` 目录
- 组件调整只改 `css/components/` 和 `js/components/`

---

## 第六部分 冲突解决与更新

### 第二十七条 冲突解决原则

1. **最新要求优先**：有冲突时按用户最新要求执行
2. **宪法高于细则**：宪法条款与细则冲突时，宪法优先
3. **效果图高于代码**：效果图与代码不一致时，以效果图为准
4. **全局高于局部**：全局规则与局部设置冲突时，全局优先（局部override除外）

### 第二十八条 更新机制

- 本文件持续更新，所有布局相关要求必须纳入
- 更新时标注版本号和生效日期
- 重大更新需用户确认

---

## 附录：关键文件清单

| 文件 | 用途 | 状态 |
|------|------|------|
| 唯一布局标准V2.0_全品类效果图.html | 布局唯一标准（效果图） | 🔒 锁死 |
| V2布局接入层.js | 布局接入层（生成器/插件/主题/校验） | ✅ 活跃 |
| 效果图HTML问题修复记录.md | 结构问题修复记录 | 📝 参考 |
| 水利智学系统布局宪法与实施细则.md | 本文件 | 📜 最高准则 |

---

**本宪法自发布之日起生效，所有专家必须严格遵守。**  
**违反宪法的修改必须回滚，并追究原因。**


============================================================
# § 7. 【来源：水利智学系统总指挥总调度手册.md】
============================================================

# 水利智学系统总指挥总调度手册

> 版本：V1.0  
> 生效日期：2026-09-09  
> 地位：系统开发最高调度准则，所有专家必须服从总指挥统一调度

---

## 第一部分 总指挥机制

### 第一章 总指挥定位

**第一条【总指挥职责】**  
总指挥是系统开发的最高调度者，负责：
1. 全局任务规划与优先级排序
2. 各专家小组的任务分配与协调
3. 跨模块依赖关系管理
4. 质量标准统一把控
5. 风险预警与应急决策
6. 用户需求的统一接收与分发

**第二条【总指挥权力】**
- 有权决定任务执行顺序
- 有权调配各专家资源
- 有权否决不符合规范的修改
- 有权启动紧急回滚机制
- 有权召开专家联席会议

**第三条【总指挥原则】**
- 不直接写代码，只做调度和决策
- 所有决策必须有依据（宪法/细则/用户要求）
- 重大决策需征求用户意见
- 决策后必须跟踪执行结果

---

## 第二部分 专家小组编制

### 第二章 专家组架构

```
总指挥
├── 布局专家组（UI/UX设计师）
│   ├── 效果图维护
│   ├── 布局校验
│   └── 响应式适配
├── 前端专家组（前端工程师）
│   ├── 接入层维护
│   ├── 页面开发
│   └── 性能优化
├── 功能专家组（业务工程师）
│   ├── 题库模块
│   ├── 闪卡模块
│   ├── 思维导图
│   ├── 视频播放
│   ├── 智能笔记
│   └── 学习分析
├── 数据专家组（数据工程师）
│   ├── 数据治理
│   ├── 数据备份
│   └── 数据迁移
├── 测试专家组（测试工程师）
│   ├── 功能测试
│   ├── 布局测试
│   ├── 兼容性测试
│   └── 自动化测试
├── 移动端专家组（移动工程师）
│   ├── APK打包
│   ├── 离线模式
│   ├── 鸿蒙适配
│   └── 平板适配
└── 质量保障组（QA）
    ├── 巡查机器人
    ├── 需求记录机器人
    ├── 代码审查
    └── 发布审核
```

### 第三章 各小组职责

**3.1 布局专家组**
- 维护唯一布局标准V2.0效果图HTML（锁死）
- 布局规则更新与版本管理
- 布局校验与巡查
- 响应式适配规范

**3.2 前端专家组**
- 维护V2布局接入层.js
- 智能布局生成器优化
- 页面布局应用
- 性能优化

**3.3 功能专家组**
- 各业务模块功能开发
- 模块间接口协调
- 功能完整性保障

**3.4 数据专家组**
- 数据结构治理
- 备份策略执行
- 数据迁移与合并

**3.5 测试专家组**
- 测试用例编写
- 功能/布局/兼容性测试
- 自动化测试脚本
- Bug跟踪与验证

**3.6 移动端专家组**
- APK打包与签名
- 离线模式实现
- 鸿蒙/安卓适配
- 平板/手机独立布局

**3.7 质量保障组**
- 巡查机器人运行
- 需求记录与跟踪
- 代码审查
- 发布前最终审核

---

## 第三部分 任务调度机制

### 第四章 任务优先级

**4.1 P0 - 紧急（立即执行）**
- 系统崩溃/白屏
- 数据丢失风险
- 核心功能完全不可用
- 用户明确要求立即处理

**4.2 P1 - 高优（当天完成）**
- 布局严重不符合V2.0
- 核心功能异常
- 安全漏洞
- 用户多次反馈的问题

**4.3 P2 - 中优（本周完成）**
- 布局细节优化
- 功能完善
- 性能优化
- 代码清理

**4.4 P3 - 低优（计划内完成）**
- 新功能开发
- 体验优化
- 文档完善
- 技术债务清理

### 第五章 任务流转流程

```
用户需求 → 总指挥接收 → 需求记录机器人登记
    ↓
总指挥分析 → 确定优先级 → 分配给对应专家组
    ↓
专家组执行 → 完成后提交测试组验证
    ↓
测试组验证 → 通过 → 质量保障组审核 → 发布
         ↓ 不通过
    退回专家组修改 → 重新测试
    ↓
巡查机器人定期复查 → 发现问题 → 上报总指挥
```

### 第六章 跨组协作机制

**6.1 依赖管理**
- 任务开始前必须确认依赖关系
- 上游任务未完成，下游任务不得开始
- 依赖变更必须通知总指挥

**6.2 接口约定**
- 模块间接口必须提前约定
- 接口变更必须通知所有相关组
- 接口文档必须同步更新

**6.3 信息同步**
- 每日站会：各小组汇报进度
- 重大变更：立即通知总指挥和相关组
- 每周总结：全面回顾与计划调整

---

## 第四部分 各方面要求串联

### 第七章 布局与功能串联

**7.1 布局先行原则**
- 任何新功能必须先确定布局方案
- 布局方案在效果图中确认后，再开发功能
- 功能开发不得破坏已有布局

**7.2 布局与功能对应关系**
| 页面类型 | 功能模块 | 布局规则 |
|----------|----------|----------|
| A类列表页 | 题库管理/闪卡管理 | 表头固定/一行筛选 |
| B类Tab页 | 章节考试/历史记录 | Tab一行/布局一致 |
| C类分栏页 | 视频播放 | 6:4/视频布满 |
| D类表单页 | 系统设置 | 标签120px/输入完整 |
| E类看板页 | 学习看板 | 3行/1.8:1.8:1.4 |
| F类考试页 | 模拟考试 | 题目无间隔/答题卡 |

### 第八章 代码治理与布局串联

**8.1 治理顺序**
1. 先恢复布局V2.0（从备份对比）
2. 完善核心功能（题库/闪卡/思维导图/视频/笔记/分析）
3. 代码迭代迁移
4. 最后布局手机和平板

**8.2 代码治理与布局的关系**
- 布局混乱往往是代码混乱导致
- 代码治理前必须先固定布局标准
- 治理过程中布局标准不得变更
- 治理完成后用布局校验器验证

### 第九章 离线模式与布局串联

**9.1 离线模式布局要求**
- 离线模式布局与在线模式一致
- 缓存提示不破坏原有布局
- 离线模式下功能不得阉割

**9.2 离线功能清单**
- 视频缓存（用户可选）
- PDF缓存（用户可选）
- 智能TTS朗读（根据文字实时生成）
- 闪卡语音输入（仅闪卡语音回答时）
- 学习数据本地存储

### 第十章 APK与布局串联

**10.1 APK打包前检查清单**
- [ ] 所有页面布局符合V2.0
- [ ] 核心功能完整可用
- [ ] 离线模式正常
- [ ] 朗读功能正常
- [ ] 视频缓存正常
- [ ] 横屏竖屏协调
- [ ] 无白屏/无异常显示
- [ ] 全面虚拟测试20遍通过

**10.2 APK与网页版关系**
- APK是网页版的封装，功能必须一致
- APK不得阉割网页版功能
- APK特有功能（缓存/离线）不影响网页版

---

## 第五部分 质量保障体系

### 第十一章 三道防线

**第一道防线：开发自检**
- 开发完成后必须自检
- 对照布局宪法逐条检查
- 运行布局校验器

**第二道防线：测试验证**
- 测试组全面测试
- 功能/布局/兼容性全覆盖
- 模拟真实环境测试

**第三道防线：巡查机器人**
- 定期自动巡查所有页面
- 检测布局偏离
- 检测代码混入
- 检测功能异常

### 第十二章 回滚机制

**12.1 回滚触发条件**
- 布局严重偏离V2.0
- 核心功能不可用
- 数据异常
- 用户明确要求回滚

**12.2 回滚流程**
1. 总指挥确认回滚必要性
2. 确定回滚目标版本
3. 执行回滚（V2Layout.rollback或文件恢复）
4. 验证回滚结果
5. 分析原因，防止再次发生

### 第十三章 备份机制

**13.1 备份触发条件**
- 重大版本发布前
- 大规模重构前
- 考前稳定版
- 用户明确要求
- 每日自动备份

**13.2 备份内容**
- 效果图HTML
- 接入层JS
- 布局宪法文档
- 核心功能代码
- 数据文件

**13.3 备份验证**
- 备份后必须验证可恢复性
- 定期测试备份恢复
- 备份文件命名规范：日期_版本_描述

---

## 第六部分 专家协同机制

### 第十四章 专家统一走偏防止机制

**14.1 问题现象**
- 多个专家同时修改同一模块
- 专家各自为政，标准不统一
- 修改互相覆盖或冲突

**14.2 防止机制**
- 总指挥统一分配任务，避免重复
- 同一模块同一时间只允许一个专家修改
- 修改前必须确认无其他专家在改
- 修改后立即通知总指挥和相关专家

### 第十五章 需求收集校核机制

**15.1 需求记录机器人**
- 自动记录用户所有需求
- 分类整理（布局/功能/优化/Bug）
- 标注优先级和状态
- 定期汇总给总指挥

**15.2 需求校核**
- 新需求必须与已有需求对比
- 发现冲突立即上报总指挥
- 冲突按最新要求解决
- 需求变更必须同步更新宪法

### 第十六章 专家联席会议

**16.1 召开时机**
- 重大架构决策前
- 跨模块复杂问题
- 多次修改未解决的问题
- 用户强烈不满时

**16.2 会议产出**
- 问题根因分析
- 解决方案共识
- 任务分配与时间表
- 风险评估与应对

---

## 第七部分 执行检查与彻底性保障

### 第十七章 执行检查清单

每次修改后必须检查：

**布局检查**
- [ ] 对照效果图V2.0
- [ ] 运行布局校验器
- [ ] 检查所有页面（不只是修改的页面）
- [ ] 检查横屏竖屏
- [ ] 检查不同设备

**功能检查**
- [ ] 修改的功能正常
- [ ] 相关功能未受影响
- [ ] 无控制台报错
- [ ] 数据正常

**代码检查**
- [ ] 无代码混入
- [ ] 通过接入层修改
- [ ] 注释完整
- [ ] 命名规范

### 第十八章 执行彻底性保障

**18.1 禁止半拉子工程**
- 任务必须完整完成，不允许留尾巴
- 发现的问题必须全部解决，不允许只解决部分
- 修改后必须全面验证，不允许只验证修改点

**18.2 重复问题防止**
- 同一问题出现两次必须分析根因
- 根因必须写入宪法或细则
- 建立预防机制，防止第三次发生

**18.3 用户确认机制**
- 重大修改必须用户确认效果
- 用户确认后才能标记完成
- 用户未确认的任务不得关闭

---

## 第八部分 总指挥决策流程

### 第十九章 决策流程

```
收到需求/问题
    ↓
总指挥分析
    ├─ 属于哪类问题？（布局/功能/代码/测试/移动端）
    ├─ 优先级？（P0/P1/P2/P3）
    ├─ 是否有依赖？
    └─ 是否需要专家联席会议？
    ↓
分配任务
    ├─ 指定负责专家组
    ├─ 明确完成标准
    ├─ 设定时间节点
    └─ 通知相关协作组
    ↓
跟踪执行
    ├─ 定期检查进度
    ├─ 协调解决阻塞
    └─ 质量中途检查
    ↓
验收发布
    ├─ 测试组验证
    ├─ 质量保障组审核
    ├─ 用户确认
    └─ 巡查机器人复查
    ↓
总结归档
    ├─ 更新需求状态
    ├─ 更新宪法/细则
    ├─ 记录经验教训
    └─ 备份当前版本
```

---

## 附录：总指挥常用工具

| 工具 | 用途 |
|------|------|
| V2Layout.validate() | 布局校验 |
| V2Layout.snapshot() | 版本快照 |
| V2Layout.rollback() | 版本回滚 |
| 巡查机器人 | 自动巡查 |
| 需求记录机器人 | 需求跟踪 |
| 布局宪法 | 最高准则 |
| 接入层JS | 布局生成与应用 |

---

**本手册自发布之日起生效，总指挥负责解释和修订。**  
**所有专家必须服从总指挥统一调度，确保系统循序渐进完善。**


============================================================
# § 8. 【来源：统一入口体系_骨架与血肉.md】
============================================================

# 统一入口体系 - 骨架与血肉

## 一、设计理念

> 一个入口管理全阶段、全内容、全方面
> 先丰满骨架，再逐步填充血肉

## 二、骨架结构（已完成）

### 2.1 前端统一入口 SystemCenter.js
```
SystemCenter
├── init(config)           # 唯一启动入口
├── register(name, module) # 模块注册
├── registerService(name)  # 服务注册
├── getModule(name)        # 获取模块
├── getStatus()            # 状态查询
├── check()                # 健康检查
├── help()                 # 帮助
└── events                 # 事件总线（统一通信）
```

### 2.2 后端统一入口 system_center.py
```
命令体系（14+1命令）
├── 状态类: status, todo, scheduler
├── 检查类: check, diagnose, layout, data, verify, fingerprint
├── 操作类: start, backup, restore, diff, clean
├── 检索类: search, logs
└── 修复类: fix
```

### 2.3 启动流程（统一）
```
页面加载
  ↓
SystemCenter.init()  ← 唯一入口
  ├── 初始化事件总线
  ├── 注册核心服务（布局/总控/监督）
  ├── 自动注册业务模块
  ├── 启动监督机器人
  ├── 应用V2布局
  └── 启动定时调度器
```

## 三、血肉填充计划（逐步进行）

### 阶段1：骨架完善（当前）
- [x] 前端统一入口 SystemCenter.js
- [x] 后端统一入口扩展（调度器）
- [x] index.html统一启动
- [ ] 模块自动注册机制完善
- [ ] 事件总线连接各模块

### 阶段2：业务模块接入
- [ ] 题库模块注册
- [ ] 闪卡模块注册
- [ ] 记忆训练模块注册
- [ ] 思维导图模块注册
- [ ] 视频模块注册
- [ ] 笔记模块注册
- [ ] 学习分析模块注册

### 阶段3：服务完善
- [ ] 布局服务：自动识别页面类型并应用
- [ ] 监督服务：12项检查全部实现
- [ ] 数据服务：统一数据访问接口
- [ ] 备份服务：修改前自动备份

### 阶段4：智能调度
- [ ] 巡查机器人定时自动运行
- [ ] 需求记录机器人自动记录
- [ ] 异常自动告警
- [ ] 性能自动优化

## 四、使用方法

### 前端
```javascript
// 启动（已在index.html中自动执行）
SystemCenter.init();

// 注册模块
SystemCenter.register('myModule', { ... });

// 获取模块
var qb = SystemCenter.getModule('qb');

// 查看状态
SystemCenter.getStatus();

// 事件通信
SystemCenter.events.on('question:answered', function(data) { ... });
SystemCenter.events.emit('question:answered', { id: 1 });
```

### 后端
```bash
# 查看状态
python tools/system_center.py status

# 启动定时调度
python tools/system_center.py scheduler start

# 健康检查
python tools/system_center.py check

# 巡查
python tools/patrol_robot.py
```

## 五、关键原则

1. **唯一入口**：所有组件通过SystemCenter管理，不允许分散启动
2. **骨架先行**：先搭框架，再填功能，避免混乱
3. **事件驱动**：模块间通过事件总线通信，不直接依赖
4. **自动注册**：业务模块自动扫描注册，无需手动
5. **统一调度**：定时任务、巡查、备份统一管理


============================================================
# § 9. 【来源：系统文件总索引与执行清单.md】
============================================================

# 水利智学系统文件总索引与执行清单

> 版本：V1.0  
> 用途：统一索引所有文件，明确执行优先级，防止遗漏  
> 使用方法：从上到下按优先级执行，完成一项勾选一项

---

## 一、文件分类总览

### 📌 第一类：必须执行（运行中）

| 序号 | 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|------|
| 1 | frontend/index.html | 运行文件 | ✅ 已运行 | 前端入口，已引入总控+监督+布局 |
| 2 | frontend/static/js/system-controller.js | 运行文件 | ✅ 已运行 | 系统总控中枢 |
| 3 | frontend/static/js/system-supervisor.js | 运行文件 | ✅ 已运行 | 总调度监督机器人 |
| 4 | frontend/static/js/v2-layout-access.js | 运行文件 | ✅ 已运行 | V2布局接入层 |
| 5 | backend/main.py | 运行文件 | ✅ 已运行 | 后端服务 |
| 6 | start.bat | 运行文件 | ✅ 已运行 | 启动入口 |

### 📜 第二类：准则规范（必须遵守）

| 序号 | 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|------|
| 7 | 布局规范/水利智学系统布局宪法与实施细则.md | 准则 | ✅ 已建立 | 📜 最高准则，所有布局必须遵守 |
| 8 | 布局规范/水利智学系统总指挥总调度手册.md | 准则 | ✅ 已建立 | 🎯 调度准则，7专家组分工 |
| 9 | 布局规范/文件管理体系_唯一性与备份机制.md | 准则 | ✅ 已建立 | 📁 文件管理，唯一性+备份 |
| 10 | CODE_SAFETY_RULES.md | 准则 | ✅ 已建立 | 🔒 代码安全规范 |
| 11 | CODE_QUALITY_GUIDE.md | 准则 | ✅ 已建立 | ✅ 代码质量规范 |

### 🔒 第三类：标准文件（锁死不动）

| 序号 | 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|------|
| 12 | 布局规范/唯一布局标准V2.0_全品类效果图.html | 标准 | 🔒 锁死 | 布局唯一标准，不允许修改结构 |
| 13 | 布局规范/V2布局接入层.js | 标准 | ✅ 已接入 | 智能布局生成器，核心锁死 |
| 14 | 布局规范/V2布局规则_统一版.css | 标准 | ✅ 已引入 | 统一布局CSS |

### 📊 第四类：分析报告（参考执行）

| 序号 | 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|------|
| 15 | 布局规范/系统血液循环架构图.md | 分析 | ✅ 已建立 | 七层架构+流动路径 |
| 16 | 布局规范/系统运行保障全体系.md | 分析 | ✅ 已建立 | 七层保障体系 |
| 17 | 布局规范/70名专家全面分析报告_缺失项与优化建议.md | 分析 | ✅ 已建立 | 68项缺失+P0-P3优先级 |
| 18 | 布局规范/效果图HTML问题修复记录.md | 分析 | ✅ 已建立 | 结构问题修复记录 |

### 🛠️ 第五类：工具脚本（按需使用）

| 序号 | 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|------|
| 19 | tools/auto_backup.py | 工具 | ✅ 已创建 | 修改前自动备份（**每次修改前必须用**） |
| 20 | tools/ (151个脚本) | 工具 | ⚠️ 待整理 | 批处理/导入导出，需统一入口 |

### 💾 第六类：备份文件（恢复用）

| 序号 | 文件/目录 | 类型 | 状态 | 说明 |
|------|-----------|------|------|------|
| 21 | backups/GOLDEN_黄金备份_*/ | 备份 | ✅ 已创建 | 15个关键文件黄金备份 |
| 22 | backups/pre_change/ | 备份 | ✅ 已建立 | 修改前自动备份（保留最近20个） |
| 23 | 布局规范/唯一布局标准V2.0 - 黄金备份.html | 备份 | ✅ 已更新 | 效果图同目录备份 |
| 24 | backups/backup_manifest.json | 备份 | ✅ 已建立 | 备份清单 |

### 📚 第七类：文档资料（参考阅读）

| 序号 | 文件 | 类型 | 状态 | 说明 |
|------|------|------|------|------|
| 25 | docs/质量保障体系.md | 文档 | ✅ 已有 | 质量保障 |
| 26 | docs/测试用例集_V1.0.md | 文档 | ✅ 已有 | 测试用例 |
| 27 | docs/部署指南.md | 文档 | ✅ 已有 | 部署指南 |
| 28 | docs/应急处理手册.md | 文档 | ✅ 已有 | 应急处理 |
| 29 | docs/设计规范_V2.0.md | 文档 | ✅ 已有 | 设计规范 |
| 30 | 规划细则分册/ | 文档 | ✅ 已有 | 专家建议/进度/审计 |

### 🗄️ 第八类：归档文件（不活跃）

| 序号 | 目录 | 类型 | 状态 | 说明 |
|------|------|------|------|------|
| 31 | _archive_*/ | 归档 | ⚠️ 待清理 | 历史脚本，移到backups/archive/ |
| 32 | watermark_test/ | 归档 | ⚠️ 待清理 | 556个测试脚本 |
| 33 | 待检查代码/ | 归档 | ⚠️ 待处理 | 检查后归位或删除 |
| 34 | 问题分析包_*/ | 归档 | ⚠️ 待整理 | 历史分析 |

---

## 二、执行优先级清单（按顺序执行）

### 🔴 P0 - 立即执行（影响系统运行）

- [ ] **1. 修复题库管理404** - questions.json数据不加载
- [ ] **2. 修复闪卡管理404** - 闪卡数据不加载
- [ ] **3. 修复朗读功能** - 无声音/切换过快
- [ ] **4. 修改前必须备份** - 执行 `python tools/auto_backup.py <文件>`
- [ ] **5. 巡查机器人脚本化** - 自动检测布局+功能

### 🟠 P1 - 本周执行（影响体验安全）

- [ ] **6. XSS防护全面检查**
- [ ] **7. 统一错误处理**
- [ ] **8. 统一UI组件（Loading/空状态）**
- [ ] **9. 需求记录机器人脚本化**
- [ ] **10. 后端API文档**
- [ ] **11. 日志轮转**

### 🟡 P2 - 下周执行（优化完善）

- [ ] **12. 前端JS拆分/懒加载**
- [ ] **13. 数据库索引优化**
- [ ] **14. 数据字典文档**
- [ ] **15. 工具层统一入口**
- [ ] **16. 归档文件清理**
- [ ] **17. 代码审查流程**

### 🟢 P3 - 计划执行（长期优化）

- [ ] **18. APK体积优化**
- [ ] **19. 多设备代码剥离**
- [ ] **20. 安全加密实现**
- [ ] **21. 自动化测试覆盖**
- [ ] **22. 用户操作手册**
- [ ] **23. 性能基线建立**

---

## 三、快速检索指南

### 我要改布局 → 看哪里？
1. 先看 `唯一布局标准V2.0_全品类效果图.html`（标准）
2. 再看 `布局宪法与实施细则.md`（规则）
3. 修改前执行 `python tools/auto_backup.py`（备份）
4. 修改后用 `V2Layout.validate()` 校验

### 我要改代码 → 看哪里？
1. 先看 `CODE_QUALITY_GUIDE.md` + `CODE_SAFETY_RULES.md`（规范）
2. 修改前执行 `python tools/auto_backup.py`（备份）
3. 修改后看 `系统总控` 控制台是否正常

### 系统出问题 → 看哪里？
1. F12控制台看 `系统总控` + `监督机器人` 报告
2. 看 `docs/应急处理手册.md`
3. 用 `python tools/auto_backup.py --list` 找备份恢复

### 不知道做什么 → 看哪里？
1. 看本文件第二部分「执行优先级清单」
2. 按P0→P1→P2→P3顺序执行
3. 完成一项勾选一项

---

## 四、文件数量统计

| 类别 | 数量 | 状态 |
|------|------|------|
| 必须执行（运行中） | 6个 | ✅ 全部运行 |
| 准则规范 | 5个 | ✅ 全部建立 |
| 标准文件 | 3个 | 🔒 锁死 |
| 分析报告 | 4个 | ✅ 全部建立 |
| 工具脚本 | 152个 | ⚠️ 1个就绪，151个待整理 |
| 备份文件 | 4类 | ✅ 全部建立 |
| 文档资料 | 6+ | ✅ 已有 |
| 归档文件 | 4类 | ⚠️ 待清理 |

---

## 五、维护规则

1. **新增文件必须登记** - 加入本索引，标注类别和优先级
2. **完成任务必须勾选** - 在执行清单中勾选
3. **文件废弃必须归档** - 移入归档目录，不删除
4. **定期更新本索引** - 每周更新一次状态
5. **本文件是唯一索引** - 其他地方不重复索引

---

**一个索引，全部可查；按序执行，不会遗漏！**


============================================================
# § 10. 【来源：系统血液循环架构图.md】
============================================================

# 水利智学系统血液循环架构图

> 版本：V1.0  
> 目标：让所有文件调动起来，打通关联，形成活的闭环系统

---

## 一、系统血液循环总图

```
                    ┌─────────────────────────────────────┐
                    │         【大脑】布局规范目录          │
                    │  宪法/细则/调度手册/效果图/接入层      │
                    └──────────────┬──────────────────────┘
                                   │ 读取/引用
                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                        【心脏】start.bat 启动入口                  │
│                    启动后端 + 启动前端静态服务                      │
└────────┬───────────────────────────────────┬────────────────────┘
         │                                   │
         ▼                                   ▼
┌──────────────────┐              ┌──────────────────────┐
│  【左心室】后端    │              │   【右心室】前端       │
│  backend/main.py │              │  frontend/index.html │
│  FastAPI服务     │              │  36个JS + 11个CSS    │
└────────┬─────────┘              └──────────┬───────────┘
         │                                    │
         │ API请求                            │ 页面渲染
         ▼                                    ▼
┌──────────────────┐              ┌──────────────────────┐
│  【肝脏】数据层    │              │   【脾脏】布局接入层   │
│  backend/data/   │              │  V2布局接入层.js      │
│  数据库/配置文件  │              │  智能生成器/校验器     │
└────────┬─────────┘              └──────────┬───────────┘
         │                                    │
         │ 数据读写                           │ 生成CSS
         ▼                                    ▼
┌──────────────────┐              ┌──────────────────────┐
│  【肾脏】工具层    │              │   【肺脏】功能模块     │
│  tools/ 151个脚本 │              │  qb/mt/mm/ai/sync... │
│  批处理/导入导出  │              │  题库/闪卡/思维导图   │
└────────┬─────────┘              └──────────┬───────────┘
         │                                    │
         │ 执行结果                           │ 用户操作
         ▼                                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                     【血液】数据流 + 事件总线                      │
│         EventBus / Store / API / Logger / Monitor                │
└─────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                     【免疫系统】质量保障层                         │
│         巡查机器人 / 需求记录 / 测试 / 备份 / 日志监控             │
└─────────────────────────────────────────────────────────────────┘
```

---

## 二、各器官功能与文件映射

### 【大脑】布局规范目录（神经中枢）

| 文件 | 功能 | 被谁调用 |
|------|------|----------|
| 布局宪法与实施细则.md | 最高准则 | 人工阅读+校验器读取 |
| 总指挥总调度手册.md | 调度准则 | 人工阅读 |
| 唯一布局标准V2.0效果图.html | 布局标准 | 接入层参考+人工对照 |
| V2布局接入层.js | 智能生成器 | **前端index.html引入** |
| V2布局规则_统一版.css | 布局CSS | 前端index.html引入 |

### 【心脏】启动入口

| 文件 | 功能 |
|------|------|
| start.bat | 系统启动总入口 |
| backend/main.py | 后端服务启动 |
| frontend/index.html | 前端页面入口 |

### 【左心室】后端系统

| 目录/文件 | 功能 |
|-----------|------|
| backend/main.py | FastAPI主服务 |
| backend/api/ | API接口 |
| backend/core/ | 核心配置 |
| backend/crud/ | 数据库操作 |
| backend/models/ | 数据模型 |
| backend/utils/ | 工具函数(51个) |
| backend/data/ | 数据文件 |

### 【右心室】前端系统

| 目录/文件 | 功能 |
|-----------|------|
| frontend/index.html | 页面入口 |
| frontend/js/core/ | 核心模块(7个) |
| frontend/js/modules/ | 业务模块(12个) |
| frontend/css/ | 样式文件(16个) |
| frontend/lib/ | 第三方库(11个) |

### 【肝脏】数据层

| 目录/文件 | 功能 |
|-----------|------|
| backend/data/ | 数据库和数据文件 |
| data/exam_config.json | 考试配置 |
| backend/uploads/ | 上传文件(42个) |

### 【脾脏】布局接入层

| 文件 | 功能 |
|------|------|
| V2布局接入层.js | 智能布局生成器 |
| V2布局规则_统一版.css | 统一布局CSS |
| V2兼容层_备用.css | 兼容层备用 |

### 【肺脏】功能模块

| 模块 | 文件 | 功能 |
|------|------|------|
| 题库 | qb.js | 题库管理/刷题 |
| 闪卡 | mt.js | 闪卡记忆 |
| 思维导图 | mm.js | 思维导图 |
| AI | ai.js/ai_brain.js | AI学习建议 |
| 同步 | sync.js | 数据同步 |
| 知识库 | knowledge_base.js | 知识库管理 |
| 文件库 | file_library.js | 文件管理 |

### 【肾脏】工具层

| 目录 | 数量 | 功能 |
|------|------|------|
| tools/ | 151个 | 批处理/导入导出/数据处理 |
| watermark_test/ | 556个 | PDF水印测试脚本 |
| _archive_*/ | 多个 | 归档脚本（待清理） |

### 【免疫系统】质量保障

| 目录/文件 | 功能 |
|-----------|------|
| backups/ | 备份管理 |
| docs/测试用例集 | 测试用例 |
| docs/质量保障体系 | 质量规范 |
| 规划细则分册/ | 需求/进度/审计 |
| logs/ | 运行日志 |

---

## 三、血液循环路径（数据流）

### 路径1：用户操作循环
```
用户点击 → 前端模块(qb.js等) → EventBus事件 → Store状态更新
    → API请求 → 后端main.py → CRUD操作 → 数据库
    → 返回数据 → 前端渲染 → 用户看到结果
```

### 路径2：布局应用循环
```
页面加载 → index.html引入V2布局接入层.js
    → V2Layout.generate(pageType) 生成CSS
    → 注入到页面 → 布局生效
    → V2Layout.validate() 校验布局
    → 不符合则上报巡查机器人
```

### 路径3：数据同步循环
```
前端操作 → sync-manager.js → 本地缓存(offline-data-cache.js)
    → 联网时同步到后端 → 后端写入数据库
    → 同步成功 → 更新本地状态
```

### 路径4：质量监控循环
```
monitor.js 监控运行 → 记录日志(logs/)
    → 发现异常 → error-boundary.js 捕获
    → 上报 → 巡查机器人检测
    → 通知总指挥 → 分配修复任务
```

### 路径5：备份恢复循环
```
修改前 → V2Layout.snapshot() 创建快照
    → 修改后 → 验证通过 → 保留
    → 验证失败 → V2Layout.rollback() 回滚
    → 定期 → backups/ 全量备份
```

---

## 四、当前堵塞点（需要打通）

| 堵塞点 | 现状 | 打通方案 |
|--------|------|----------|
| 接入层未引入 | V2布局接入层.js存在但index.html未引用 | 在index.html中引入 |
| 宪法未被读取 | 宪法是md文件，系统不读取 | 转为JSON配置，校验器读取 |
| 效果图未被引用 | 效果图是独立HTML，系统不引用 | 作为参考标准，接入层对照 |
| 巡查机器人未运行 | 机制有，无脚本 | 创建自动化巡查脚本 |
| 需求记录未运行 | 机制有，无脚本 | 创建需求记录脚本 |
| 工具层未串联 | 151个脚本独立运行 | 建立工具调用入口 |
| 归档文件混乱 | _archive_* 占大量空间 | 清理或移到备份目录 |
| 多设备代码未剥离 | tablet.css/mobile.css混在一起 | 独立目录管理 |

---

## 五、打通关联实施计划

### 第一步：接入层引入（立即）
- 在frontend/index.html中引入V2布局接入层.js
- 页面加载时自动调用V2Layout.apply()

### 第二步：配置化（本周）
- 将布局宪法关键规则转为JSON配置
- 创建system-config.json，所有模块读取统一配置

### 第三步：机器人运行（本周）
- 创建巡查机器人脚本，定期检查布局
- 创建需求记录脚本，自动记录用户需求

### 第四步：工具串联（下周）
- 创建tools/index.py统一入口
- 常用工具注册到总控

### 第五步：清理归档（下周）
- _archive_* 文件移到备份目录
- 清理无用脚本

---

## 六、系统健康指标

| 指标 | 目标 | 当前 |
|------|------|------|
| 布局符合率 | 100% | 待检测 |
| 功能可用率 | 100% | 待检测 |
| 代码重复率 | <10% | 待检测 |
| 归档文件占比 | <5% | 约30% |
| 自动化测试覆盖 | >80% | 待建立 |
| 巡查频率 | 每日 | 未运行 |

---

**目标：让每一个文件都有归属，每一次调用都有路径，每一个异常都有响应。**
**系统如人体，血液流动，生生不息。**


============================================================
# § 11. 【来源：系统运行保障全体系.md】
============================================================

# 水利智学系统运行保障全体系

> 版本：V1.0  
> 目标：代码、前后端、资料、安全、监控全部串联，保障系统稳定运行

---

## 一、系统全景架构（七层保障）

```
┌─────────────────────────────────────────────────────────────┐
│                    【第七层】用户交互层                        │
│              网页端 / APK / 平板 / 手机                       │
├─────────────────────────────────────────────────────────────┤
│                    【第六层】前端应用层                        │
│        index.html + 36个JS模块 + 16个CSS + 总控中枢           │
├─────────────────────────────────────────────────────────────┤
│                    【第五层】布局标准层                        │
│        效果图HTML(锁死) + 接入层JS + 宪法细则 + 调度手册       │
├─────────────────────────────────────────────────────────────┤
│                    【第四层】后端服务层                        │
│        FastAPI(main.py) + API + CRUD + 中间件 + 工具集        │
├─────────────────────────────────────────────────────────────┤
│                    【第三层】数据资料层                        │
│        数据库 + 配置文件 + 题库/闪卡/视频/PDF/语音包           │
├─────────────────────────────────────────────────────────────┤
│                    【第二层】安全防护层                        │
│        认证授权 + 输入校验 + 错误边界 + 数据加密 + 备份        │
├─────────────────────────────────────────────────────────────┤
│                    【第一层】监控运维层                        │
│        健康检查 + 日志监控 + 巡查机器人 + 需求记录 + 告警      │
└─────────────────────────────────────────────────────────────┘
```

---

## 二、各层详细保障

### 第一层：监控运维层（免疫系统）

| 机制 | 实现方式 | 状态 |
|------|----------|------|
| 系统总控 | system-controller.js | ✅ 已建立 |
| 健康检查 | 每30秒自动检测 | ✅ 已集成 |
| 日志监控 | monitor.js + logs/ | ✅ 已运行 |
| 错误捕获 | error-boundary.js | ✅ 已运行 |
| 巡查机器人 | 待脚本化 | ⚠️ 机制有 |
| 需求记录机器人 | 待脚本化 | ⚠️ 机制有 |
| 性能监控 | performance.memory | ✅ 已集成 |

**监控指标：**
- 模块加载状态
- 布局合规性
- 内存使用量
- 错误计数
- API响应时间
- 数据同步状态

### 第二层：安全防护层（安全系统）

| 安全项 | 实现方式 | 状态 |
|--------|----------|------|
| 登录认证 | 三级联动选择 | ✅ 已实现 |
| 输入校验 | 前端+后端双重校验 | ⚠️ 需加强 |
| SQL注入防护 | 参数化查询 | ✅ 后端已实现 |
| XSS防护 | 转义输出 | ⚠️ 需检查 |
| 数据加密 | 敏感数据加密存储 | ⚠️ 需实现 |
| 备份恢复 | backups/ + V2Layout快照 | ✅ 已建立 |
| 代码安全 | CODE_SAFETY_RULES.md | ✅ 已有规范 |

**安全规范文件：**
- `CODE_SAFETY_RULES.md` - 代码安全规则
- `docs/应急处理手册.md` - 应急处理

### 第三层：数据资料层（肝脏+脾脏）

| 数据类型 | 存储位置 | 数量 | 状态 |
|----------|----------|------|------|
| 题库数据 | backend/data/ | - | ✅ |
| 闪卡数据 | data/flashcards/ | - | ⚠️ 空目录 |
| 视频文件 | backend/uploads/ | 42个 | ✅ |
| PDF文件 | backend/uploads/ | - | ✅ |
| 语音包 | voice_samples/ | 57个 | ✅ |
| 配置文件 | data/exam_config.json | 1个 | ✅ |
| 知识库 | backend/data/ | - | ✅ |
| 用户上传 | uploads/ | - | ⚠️ 空目录 |

**资料管理：**
- 视频/PDF支持缓存（离线模式）
- 智能TTS语音朗读（实时生成）
- 资料分类管理（文件库模块）

### 第四层：后端服务层（左心室）

| 模块 | 文件 | 功能 |
|------|------|------|
| 主服务 | backend/main.py | FastAPI服务启动 |
| API接口 | backend/api/ | RESTful接口 |
| 核心配置 | backend/core/ | 配置管理 |
| 数据库操作 | backend/crud/ | CRUD操作 |
| 数据模型 | backend/models/ | ORM模型 |
| 数据校验 | backend/schemas/ | Pydantic校验 |
| 中间件 | backend/middleware/ | 请求处理 |
| 工具函数 | backend/utils/ | 51个工具 |
| 脚本工具 | backend/scripts/ | 批处理 |
| 测试 | backend/tests/ | 单元测试 |

**后端API体系：**
- 题库管理API
- 闪卡管理API
- 用户数据API
- 文件上传API
- AI接口
- 同步接口

### 第五层：布局标准层（神经中枢）

| 文件 | 功能 | 状态 |
|------|------|------|
| 唯一布局标准V2.0效果图.html | 布局唯一标准 | 🔒 锁死 |
| V2布局接入层.js | 智能生成器+校验+版本 | ✅ 已接入前端 |
| V2布局规则_统一版.css | 统一布局CSS | ✅ 已引入 |
| 布局宪法与实施细则.md | 最高准则 | ✅ 已建立 |
| 总指挥总调度手册.md | 调度准则 | ✅ 已建立 |
| 系统血液循环架构图.md | 架构说明 | ✅ 已建立 |
| 效果图HTML问题修复记录.md | 修复记录 | ✅ 已建立 |

### 第六层：前端应用层（右心室）

| 类别 | 模块 | 数量 |
|------|------|------|
| 核心模块 | console-interceptor/event-bus/constants/store/api/logger/monitor/error-boundary/pwa-installer | 9个 |
| 业务模块 | qb/mt/mm/ai/ai_brain/knowledge_graph/sync/knowledge_base/file_library/fl_bridge | 10个 |
| 公共模块 | common-utils/common-business/resource/music | 4个 |
| 布局模块 | v2-layout-access/system-controller | 2个 |
| 离线模块 | offline-data-cache/offline-init/offline-manager/offline-media-cache/sync-manager | 5个 |
| 第三方库 | mind-elixir/wangEditor/pdfjs/echarts/flv | 5个 |
| CSS样式 | tokens/components/style/V2布局/tablet/mobile | 6个 |

**前端总控：** SystemController.js 统一管理所有模块

### 第七层：用户交互层（脸面）

| 终端 | 状态 | 说明 |
|------|------|------|
| 电脑网页 | ✅ 正常 | localhost:8000 |
| 手机APK | ⚠️ 优化中 | 鸿蒙/安卓适配 |
| 平板网页 | ⚠️ 待优化 | 独立布局代码 |
| 离线模式 | ⚠️ 完善中 | 视频/PDF缓存 |

---

## 三、血液流动全路径

### 路径1：用户操作完整闭环
```
用户点击 → 前端模块 → EventBus事件 → Store状态更新
    → API请求 → 后端main.py → 中间件校验 → CRUD → 数据库
    → 返回数据 → 前端渲染 → 用户看到结果
    → monitor记录日志 → 健康检查更新
```

### 路径2：布局应用闭环
```
页面加载 → system-controller启动 → 注册V2布局模块
    → V2Layout.generate(pageType) → 生成CSS → 注入页面
    → V2Layout.validate() → 校验布局 → 结果上报总控
    → 健康检查(每30秒) → 发现偏离 → 告警
```

### 路径3：数据同步闭环
```
前端操作 → sync-manager → 本地缓存(offline-data-cache)
    → 联网检测 → 同步到后端 → 后端写入数据库
    → 同步成功 → 更新本地状态 → 通知用户
    → 同步失败 → 重试机制 → 记录日志
```

### 路径4：安全防护闭环
```
用户请求 → 前端输入校验 → 后端中间件校验
    → 认证授权检查 → SQL注入防护 → 业务处理
    → 输出转义(XSS防护) → 返回结果
    → 异常捕获(error-boundary) → 记录日志 → 告警
```

### 路径5：备份恢复闭环
```
修改前 → V2Layout.snapshot() → 创建快照
    → 修改后 → 验证通过 → 保留
    → 验证失败 → V2Layout.rollback() → 回滚
    → 定期 → backups/全量备份 → 验证可恢复性
```

### 路径6：资料管理闭环
```
用户上传 → 文件库模块 → 后端接收 → 存储到uploads/
    → 生成索引 → 知识库关联 → 用户可检索
    → 离线模式 → 用户选择缓存 → 本地存储
    → 清理机制 → 定期清理临时文件
```

---

## 四、系统健康指标看板

| 指标 | 目标值 | 检测方式 | 频率 |
|------|--------|----------|------|
| 前端模块加载率 | 100% | SystemController | 实时 |
| 布局符合率 | 100% | V2Layout.validate | 每30秒 |
| API响应时间 | <500ms | monitor.js | 每次请求 |
| 错误率 | <0.1% | error-boundary | 实时 |
| 内存使用 | <500MB | performance | 每30秒 |
| 数据同步延迟 | <10秒 | sync-manager | 实时 |
| 备份完整性 | 100% | 备份验证 | 每日 |
| 安全漏洞 | 0个 | 安全扫描 | 每周 |
| 资料完整率 | 100% | 文件校验 | 每日 |

---

## 五、待完善项（按优先级）

### P0 - 立即完善
1. 巡查机器人脚本化（自动检测布局+功能）
2. 需求记录机器人脚本化（自动记录用户需求）
3. 后端输入校验加强
4. XSS防护全面检查

### P1 - 本周完善
1. 宪法规则JSON化（机器可读取）
2. 工具层统一入口（151个脚本串联）
3. 归档文件清理（_archive_*移到备份）
4. 数据备份自动化

### P2 - 下周完善
1. 平板/手机代码独立剥离
2. 安全加密实现
3. 性能优化
4. 自动化测试覆盖

### P3 - 计划内
1. APK完善（鸿蒙/安卓）
2. 离线模式完善
3. 用户行为分析
4. AI功能增强

---

## 六、关键文件清单（全部串联）

| 层级 | 文件 | 关联 |
|------|------|------|
| 启动 | start.bat | 启动后端+前端 |
| 前端入口 | frontend/index.html | 引入所有JS/CSS |
| 前端总控 | frontend/static/js/system-controller.js | 串联所有前端模块 |
| 布局接入 | frontend/static/js/v2-layout-access.js | 智能布局生成 |
| 后端入口 | backend/main.py | FastAPI服务 |
| 数据库 | backend/data/ | 数据存储 |
| 布局标准 | 布局规范/唯一布局标准V2.0.html | 效果图(锁死) |
| 最高准则 | 布局规范/布局宪法与实施细则.md | 宪法 |
| 调度准则 | 布局规范/总指挥总调度手册.md | 调度 |
| 架构说明 | 布局规范/系统血液循环架构图.md | 架构 |
| 安全规范 | CODE_SAFETY_RULES.md | 安全 |
| 质量保障 | docs/质量保障体系.md | 质量 |
| 测试用例 | docs/测试用例集_V1.0.md | 测试 |
| 备份 | backups/ | 备份恢复 |

---

**七层保障，血液流动，系统生生不息！**
**代码、前后端、资料、安全、监控全部串联，保障系统稳定运行！**


============================================================
# § 12. 【来源：效果图HTML问题修复记录.md】
============================================================

# 效果图HTML问题修复记录

## 问题1：section-login提前闭合，A类之后页面不显示

### 根因分析
被合并的div导致渲染异常：
1. 登录界面：3个装饰圆div + 登录卡片div被合并成一个div（style属性包含多个position/background/width/height）
2. 科目选择界面：2个装饰圆div + 标题容器div被合并成一个div

### 错误的检测方法（导致误判）
- 使用 `content[i:i+5] == '<div '` 检测开始标签，漏掉了 `<div>`（无空格）的标签
- 导致深度跟踪显示"多次归零"、"最终深度-1"等错误结果
- 实际上原始结构是正确的（73开==73闭，最终深度0）

### 正确修复方法
1. 拆分第一个被合并的div → 3个装饰圆（自闭合）+ 1个登录卡片
2. 拆分第二个被合并的div → 2个装饰圆（自闭合）+ 1个标题容器
3. **不需要添加或删除任何</div>**，结构本身是正确的

### 验证方法（必须用精确正则）
```python
# 错误：漏掉<div>无空格标签
content[i:i+5] == '<div '

# 正确：匹配所有div开始标签
re.compile(r'<div[\s>]')

# 或用html.parser
from html.parser import HTMLParser
```

### 验证结果
- 全局div: 1105 == 1105 ✓
- section-login区域: 78开 == 78闭 ✓
- 深度归零次数: 1次（在科目选择后）✓
- 科目选择在section-login内: True ✓
- JS大括号: 115 == 115 ✓

### 预防措施
1. 修改HTML前必须用精确正则或html.parser验证结构
2. 禁止使用 `<div `（带空格）的检测方法
3. 被合并的div必须拆分，拆分后开始和结束标签净变化为0
4. 修改后必须验证：全局匹配 + 各section匹配 + 深度归零次数

---

## 问题2：JS中错误插入border-radius（已记录）

### 根因
全局替换border-radius时，替换了JS代码中的字符串，导致JS语法错误。

### 预防措施
1. 全局替换必须限定在CSS和HTML内联样式范围内
2. 替换前检查是否在`<script>`标签内
3. 修改后必须验证JS大括号匹配和function数量


============================================================
# § 追加. 【来源：通用布局规范V1.0.md】
============================================================

# 水利智学系统 通用布局规范 V1.0

> 适用范围：所有页面布局、表格、按钮、间距、颜色、字体
> 制定原则：全局统一 + 局部可覆盖 + 独立样式类隔离 + 禁止!important滥用

---

## 一、布局总原则

### 1.1 三层布局结构
所有页面统一采用三层结构：
```
┌─────────────────────────────────────────┐
│  content-header（标题+筛选栏，固定不滚动）│
├─────────────────────────────────────────┤
│  content-body（内容区，可滚动）          │
│  ┌─────────────────────────────────────┐│
│  │  表格/卡片/列表                      ││
│  └─────────────────────────────────────┘│
├─────────────────────────────────────────┤
│  分页栏（固定底部，不滚动）              │
└─────────────────────────────────────────┘
```

### 1.2 Flex布局铁律
- 外层容器：`display:flex;flex-direction:column;height:100%`
- header/footer：`flex-shrink:0`（不压缩）
- content-body：`flex:1;overflow-y:auto;min-height:0`（可滚动）

### 1.3 禁止事项
- ❌ 禁止用`position:sticky`在table的th上（浏览器兼容性差）
- ❌ 禁止把表头和内容分成两个table（列不对齐）
- ❌ 禁止用`!important`覆盖全局样式（除非是页面独立样式类）
- ❌ 禁止内联样式写死尺寸（统一用CSS变量或样式类）

---

## 二、表格规范

### 2.1 表格结构
所有数据表格必须是**单个table**，包含thead和tbody：
```html
<table class="data-table">
  <thead>
    <tr><th>列1</th><th>列2</th></tr>
  </thead>
  <tbody>
    <tr><td>数据1</td><td>数据2</td></tr>
  </tbody>
</table>
```

### 2.2 表头固定方案
**唯一标准方案**：表头放在content-header区域，与筛选栏同层，不随滚动：
```
content-header（标题+筛选+表头，固定）
content-body（只包含tbody，滚动）
```

**实现方式**：
- content-header中放表头table（只有thead）
- content-body中放内容table（只有tbody）
- 两个table用相同的`table-layout:fixed`和相同的列宽
- 用CSS变量统一列宽，确保对齐

### 2.3 列宽规范
| 列类型 | 推荐宽度 | 说明 |
|--------|----------|------|
| 序号 | 40px | 居中 |
| 单选/多选框 | 40px | 居中 |
| 题型 | 50px | 居中，标签形式 |
| 答案 | 45px | 居中，加粗 |
| 年份 | 45px | 居中 |
| 类型 | 55px | 居中，标签形式 |
| 操作 | 80px | 居中，按钮组 |
| 章节 | 120px | 居中，超长省略 |
| 题干/标题 | 自适应 | 左对齐，超长省略 |

### 2.4 单元格规范
- 所有单元格：`white-space:nowrap;overflow:hidden;text-overflow:ellipsis`
- 数字列：居中对齐
- 文本列：左对齐
- 操作列：居中对齐，按钮间距2px
- 行高：32px（padding:7px 6px）
- 斑马纹：偶数行`#f8fafc`，奇数行`#ffffff`
- 悬停：`#eff6ff`

### 2.5 表格边框
- 表头底部：`2px solid #e2e8f0`
- 行分隔：`1px solid #f1f5f9`
- 表格外边框：`1px solid #c5cae9`

---

## 三、页面独立样式类规范

### 3.1 命名规则
每个需要特殊布局的页面，必须定义独立样式类，格式：`页面名-page`
- 题库管理：`.qb-manager-page`
- 学习资料库：`.file-library-page`
- 闪卡管理：`.flashcard-manager-page`
- 思维导图：`.mindmap-page`

### 3.2 使用方式
```html
<div class="qb-manager-page">
  <!-- 页面内容 -->
</div>
```

```css
.qb-manager-page .content-body {
  padding: 0; /* 覆盖全局padding，不需要!important */
}
.qb-manager-page .data-table th {
  /* 表头样式 */
}
```

### 3.3 优先级规则
- 全局样式：通用默认值
- 页面样式类：覆盖全局，不需要!important
- 内联样式：仅用于动态计算值，不用于固定样式

---

## 四、按钮规范

### 4.1 按钮尺寸
| 尺寸 | padding | 字体大小 | 适用场景 |
|------|---------|----------|----------|
| 大 | 8px 16px | 14px | 主操作按钮 |
| 中 | 5px 10px | 13px | 普通按钮 |
| 小 | 2px 8px | 12px | 表格内操作按钮 |
| 超小 | 1px 4px | 10px | 表格内"删"等单字按钮 |

### 4.2 按钮类型
- 主按钮：`btn-primary`（蓝色背景）
- 次按钮：`btn-outline`（边框+透明背景）
- 危险按钮：`btn-danger`（红色背景）
- 成功按钮：`btn-success`（绿色背景）

### 4.3 按钮间距
- 同组按钮间距：4px
- 按钮与输入框间距：4px
- 按钮组与边缘间距：10px

---

## 五、间距规范

### 5.1 内边距
- 页面容器：`padding:10px 14px`
- 卡片/表格容器：`padding:0`（表格贴边）
- 筛选栏：`padding:6px 10px`
- 表头：`padding:8px 6px`
- 表格单元格：`padding:7px 6px`

### 5.2 外边距
- 模块间距：`10px`
- 元素间距：`6px`
- 紧凑间距：`4px`

### 5.3 圆角
- 卡片/容器：`2px`
- 按钮：`2px`
- 标签：`8px`
- 输入框：`2px`

---

## 六、颜色规范

### 6.1 主色调
- 主色：`#2563eb`（蓝色）
- 主色浅：`#dbeafe`
- 主色深：`#1e40af`

### 6.2 状态色
- 成功：`#16a34a`（绿色）
- 成功浅：`#dcfce7`
- 警告：`#d97706`（橙色）
- 警告浅：`#fef3c7`
- 危险：`#dc2626`（红色）
- 危险浅：`#fee2e2`

### 6.3 中性色
- 标题：`#1e293b`
- 正文：`#334155`
- 次要：`#64748b`
- 辅助：`#94a3b8`
- 边框：`#e2e8f0`
- 背景：`#f8fafc`
- 白色：`#ffffff`

### 6.4 题型标签色
- 单选题：`#dbeafe`背景，`#1e40af`文字
- 多选题：`#fef3c7`背景，`#92400e`文字
- 判断题：`#dcfce7`背景，`#166534`文字
- 案例题：`#fce7f3`背景，`#9d174d`文字

### 6.5 题目类型标签色
- 真题：`#dcfce7`背景，`#166534`文字
- 模拟题：`#fef3c7`背景，`#92400e`文字
- 练习题：`#f1f5f9`背景，`#475569`文字

---

## 七、字体规范

### 7.1 字体大小
| 级别 | 大小 | 适用场景 |
|------|------|----------|
| 大标题 | 18px | 页面标题 |
| 小标题 | 16px | 卡片标题 |
| 正文 | 14px | 普通文本 |
| 小字 | 13px | 表格内容 |
| 辅助 | 12px | 辅助信息 |
| 超小 | 10px | 标签、按钮 |

### 7.2 字重
- 标题：600
- 正文：400
- 强调：700
- 辅助：400

### 7.3 行高
- 标题：1.3
- 正文：1.5
- 表格：1.2

---

## 八、筛选栏规范

### 8.1 布局
- 标题+筛选栏同一行，flex布局
- 标题左对齐，筛选栏右对齐
- 筛选元素间距：4px
- 超出时横向滚动：`overflow-x:auto`

### 8.2 筛选元素
- 下拉框：高度26px，宽度70-120px
- 输入框：高度26px，宽度120-150px
- 按钮：高度26px，padding:2px 10px
- 所有元素：`flex-shrink:0`（不压缩）

### 8.3 筛选栏与表头
- 筛选栏和表头都在content-header中，固定不滚动
- 筛选栏在上，表头在下，无缝连接
- 表头与内容之间无空白条

---

## 九、分页栏规范

### 9.1 布局
- 固定在content-body下方，不随滚动
- 高度：36px
- 居中对齐
- 左侧显示总数，右侧显示页码

### 9.2 页码按钮
- 普通页码：`btn-outline`，小尺寸
- 当前页：`btn-primary`，小尺寸
- 禁用页：灰色，不可点击
- 页码间距：4px

---

## 十、响应式规范

### 10.1 断点
- 大屏（>1200px）：完整布局
- 中屏（768-1200px）：侧边栏可折叠
- 小屏（<768px）：表格横向滚动

### 10.2 表格响应式
- 小屏时表格容器：`overflow-x:auto`
- 列宽保持固定，不压缩
- 操作列固定在右侧（可选）

---

## 十一、实施检查清单

每个页面上线前必须检查：
- [ ] 页面是否有独立样式类（如`.qb-manager-page`）
- [ ] 表格是否是单个table（表头和内容不分离）
- [ ] 表头是否固定不滚动
- [ ] 表头与内容之间是否有空白条
- [ ] 列宽是否符合规范
- [ ] 单元格是否超长省略
- [ ] 斑马纹是否正确
- [ ] 悬停效果是否正常
- [ ] 按钮尺寸是否符合规范
- [ ] 颜色是否符合规范
- [ ] 字体大小是否符合规范
- [ ] 间距是否符合规范
- [ ] 筛选栏与标题是否同一行
- [ ] 分页栏是否固定底部
- [ ] 是否有未使用的`!important`

---

## 十二、违规处理

### 12.1 禁止行为
- ❌ 禁止把表头和内容分成两个table
- ❌ 禁止用`position:sticky`在th上
- ❌ 禁止用内联样式写死固定尺寸
- ❌ 禁止滥用`!important`
- ❌ 禁止修改全局CSS影响其他页面
- ❌ 禁止表头与内容之间有空白条

### 12.2 正确做法
- ✅ 用页面独立样式类覆盖全局样式
- ✅ 用CSS变量统一尺寸
- ✅ 表头放在content-header固定区域
- ✅ 单个table包含thead和tbody
- ✅ 修改后必须浏览器实测验证

---

**文档版本**：V1.0
**制定日期**：2026-09-07
**适用版本**：水利智学系统 V4.5+


============================================================
# § 追加. 【来源：多设备适配指南.md】
============================================================

# 水利智学系统 - 多设备适配指南

## 一、网络连接测试结果

### 1.1 服务状态
- ✅ 后端服务：正常运行（端口8000）
- ✅ 首页加载：正常（839KB）
- ✅ 静态资源：正常加载
- ✅ API接口：正常响应（需登录认证）

### 1.2 访问地址
- **本地访问**：http://localhost:8000
- **局域网访问**：http://192.168.0.203:8000（手机/平板同一WiFi访问）
- **默认账号**：admin / admin123

### 1.3 局域网访问配置
后端已绑定 `0.0.0.0`，支持局域网访问。确保：
1. 电脑和手机/平板连接同一WiFi
2. Windows防火墙允许8000端口入站
3. 使用电脑的局域网IP访问（如 http://192.168.0.203:8000）

---

## 二、多设备适配方案

### 2.1 响应式断点设计

| 设备类型 | 分辨率范围 | 适配策略 |
|---------|-----------|---------|
| 手机竖屏 | ≤480px | 单列布局，侧边栏60px，隐藏文字标签 |
| 手机横屏 | 481-768px | 双列网格，侧边栏72px |
| 平板竖屏 | 769-1024px | 标准布局，侧边栏90px |
| 平板横屏 | 1025-1440px | 紧凑布局，侧边栏84px |
| 笔记本 | 1366x768 | 标准布局，侧边栏84px |
| 显示器 | 1920x1080 | 舒适布局，侧边栏110px |
| 2K屏 | 2560x1440 | 流式缩放，侧边栏130px |
| 4K屏 | 3840x2160 | 流式缩放，最大宽度限制 |

### 2.2 流体排版（Clamp函数）
所有字体、间距、圆角使用 `clamp()` 函数实现平滑缩放：
- 基础字体：`clamp(14px, 1.5vw, 16px)`
- 标题字体：`clamp(20px, 2.5vw, 28px)`
- 间距：`clamp(12px, 1.5vw, 20px)`
- 侧边栏宽度：`clamp(80px, 10vw, 120px)`

### 2.3 平板专门优化

#### 平板竖屏（768-1024px）
- 侧边栏80px，导航文字11px
- 内容分割左侧180px
- 4列网格改为2列
- 视频播放器最大高度50vh

#### 平板横屏（1024-1366px）
- 侧边栏84px
- 内容分割左侧200px
- 视频播放器最大高度60vh
- 统计数字22px

---

## 三、触摸交互优化

### 3.1 触摸设备检测
系统自动检测触摸设备并添加CSS类：
- `.touch-device` - 触摸设备
- `.mobile-device` - 手机
- `.tablet-device` - 平板

### 3.2 更大点击区域
触摸设备自动增大点击区域：
- 按钮：最小40x40px
- 导航项：最小44px高度
- 输入框：最小36px高度，字体16px（避免iOS自动缩放）
- 浮动工具：48x48px

### 3.3 触摸滑动手势
已集成通用触摸手势引擎 `TouchGesture`，支持：
- `swipeLeft` - 左滑
- `swipeRight` - 右滑
- `swipeUp` - 上滑
- `swipeDown` - 下滑

**使用示例**（题目切换）：
```javascript
TouchGesture.on('swipeLeft', () => nextCard());
TouchGesture.on('swipeRight', () => prevCard());
```

### 3.4 触摸滚动优化
- `-webkit-overflow-scrolling: touch` - 惯性滚动
- `overscroll-behavior: contain` - 防止滚动穿透
- 禁止长按选中（按钮、导航、卡片）

---

## 四、横竖屏切换

### 4.1 自动适配
系统监听 `resize` 事件，自动检测横竖屏并调整布局：
- 侧边栏宽度自动调整
- 网格列数自动变化
- 视频播放器高度自适应
- 过渡动画0.3s平滑切换

### 4.2 安全区域适配
- `viewport-fit=cover` - 支持刘海屏
- 重要内容避开安全区域

---

## 五、高DPI屏幕优化

### 5.1 视网膜屏
- `@media(min-resolution:2dppx)` 媒体查询
- 阴影更细腻（0 1px 4px）
- 边框更细（0.5px）

### 5.2 图片清晰度
- 视频/图片保持比例，不溢出
- `max-width:100%; height:auto`
- Canvas图表实际分辨率翻倍

---

## 六、用户体验增强

### 6.1 可缩放性
- 移除 `user-scalable=no` 限制
- 允许用户缩放至300%（方便视力障碍用户）
- 输入框字体16px（避免iOS聚焦时自动缩放）

### 6.2 减少动画偏好
- 尊重系统 `prefers-reduced-motion` 设置
- 开启后所有动画/过渡立即完成
- 适合眩晕症用户和低性能设备

### 6.3 深色模式
- 支持系统深色模式自动切换
- `@media(prefers-color-scheme:dark)`
- 也可手动切换主题

---

## 七、不同设备使用指南

### 7.1 平板使用（推荐）
**最佳体验设备**：
- iPad（768x1024竖屏 / 1024x768横屏）
- Android平板（1200x800及以上）

**使用建议**：
1. 横屏模式适合视频学习和刷题
2. 竖屏模式适合阅读和笔记
3. 使用Safari/Chrome浏览器
4. 可添加到主屏幕作为PWA应用

### 7.2 手机使用
**适配范围**：
- iPhone SE（375x667）及以上
- Android手机（360x640及以上）

**使用建议**：
1. 侧边栏仅显示图标，点击展开
2. 内容单列布局，上下滚动
3. 表格支持横向滑动
4. 建议横屏观看视频

### 7.3 笔记本/台式机
**适配范围**：
- 14寸笔记本（1366x768）
- 24寸显示器（1920x1080）
- 27寸2K（2560x1440）
- 32寸4K（3840x2160）

**使用建议**：
1. 大屏多列布局，效率更高
2. 4K屏内容居中，不过宽
3. 支持窗口缩放自适应

---

## 八、PWA离线支持

### 8.1 功能
- Manifest配置，可添加到主屏幕
- Service Worker缓存静态资源
- 离线可访问已缓存页面

### 8.2 添加到主屏幕
1. 用Safari/Chrome打开系统
2. 点击"分享" → "添加到主屏幕"
3. 桌面出现应用图标，全屏体验

---

## 九、常见问题

### Q1: 平板访问显示不完整？
A: 确保使用最新版Chrome/Safari，清除浏览器缓存后刷新。

### Q2: 手机访问侧边栏太宽？
A: 手机端侧边栏自动缩为60px仅显示图标，点击导航项即可。

### Q3: 横竖屏切换布局错乱？
A: 刷新页面即可重新适配，或等待0.3s过渡动画完成。

### Q4: 局域网无法访问？
A: 检查：1)同一WiFi 2)Windows防火墙 3)使用正确的IP地址

### Q5: 触摸滑动不灵敏？
A: 最小滑动距离50px，确保滑动距离足够，且不在输入框内滑动。

---

## 十、版本信息

- **系统版本**：V4.5.15
- **适配版本**：20260823_2000
- **更新日期**：2026-08-23
- **适配设备**：手机/平板/笔记本/台式机/2K/4K

---

*本指南随系统更新持续完善*


============================================================
# § 追加. 【来源：功能清单与修改保障.md】
============================================================

# 水利智学系统 - 核心功能清单

> 本文档记录所有核心功能的位置，防止修改时误删。
> 每次修改代码后，必须对照本文档验证所有功能。

## 一、记忆闪卡模块

### 1.1 Tab结构
- 🔄 智能复习（review）
- 📐 公式填空（formula）
- 🗺️ 导图填空（mindmap）
- 📋 卡片管理（manage）

### 1.2 播报功能（第7872-7887行）
- 正面朗读：speakFlashcard('front')
- 背面朗读：speakFlashcard('back')
- 全部朗读：speakFlashcard('both')
- 自动播报：toggleAutoSpeak()
- 停止朗读：stopSpeak()
- 🎲 随机朗读：toggleRandomSpeak() ← 2026-08-30 添加

### 1.3 云南口音（第7882-7885行）
- 轻度：setYunnanAccent('light')
- 中度：setYunnanAccent('medium')
- 重度：setYunnanAccent('strong')

### 1.4 智能复习控制按钮（第8283-8295行）
- 🔊 正面、🔊 背面
- 💡 口诀、📖 教材、🤖 AI
- ← 上一张、✅ 记住了、❌ 没记住、下一张 →

### 1.5 核心函数
- speakFlashcard(part) - 闪卡朗读
- speakText(text, label) - 通用文本朗读（支持云南口音）
- speakTTS(text, options) - 后端TTS
- toggleAutoSpeak() - 自动播报开关
- toggleRandomSpeak() - 随机朗读开关 ← 2026-08-30 添加
- speakRandomFlashcard() - 随机朗读一张闪卡 ← 2026-08-30 添加
- setYunnanAccent(level) - 设置云南口音
- stopSpeak() - 停止朗读
- updateCard() - 更新闪卡显示
- prevCard() / nextCard() - 切换闪卡
- jumpCard(i) - 跳转到指定闪卡

## 二、记忆训练模块

### 2.1 专项训练列表（EXAM_MEMORY_TRAINING）
1. 💰 造价构成记忆（一造管理）
2. ⏰ 进度管理公式（一建管理）
3. ⚖️ 法规数字记忆（一建法规）
4. 🌊 水利技术要点（一建水利实务）
5. 📈 经济公式记忆（一建经济）
6. 🛡️ 安全管理考点（一建管理）
7. 📝 合同管理流程（一建管理）
8. 🔀 易混淆概念配对（通用）
9. 💡 口诀专项记忆（通用）← 2026-08-30 恢复
10. 🔊 朗读专项记忆（通用）← 2026-08-30 恢复

### 2.2 训练类型
- fill：填空题
- sequence：排序题
- match：配对题

### 2.3 核心函数
- speakTraining() - 朗读训练题目
- renderTrainingQuestion() - 渲染训练题目
- nextTrainingQuestion() - 下一题
- recordTrainingResult(isCorrect) - 记录结果

## 三、离线同步模块

### 3.1 系统设置 - 离线同步区域
- 离线缓存开关：offlineCacheToggle
- 离线数据同步开关：offlineSyncToggle
- 缓存状态：cacheStatusText
- 待同步操作：pendingOpsText
- 立即同步：syncNow()
- 清理缓存：clearOfflineCache()

### 3.2 核心函数
- toggleOfflineCache(checkbox) - 离线缓存开关
- toggleOfflineSync(checkbox) - 离线数据同步开关
- checkCacheStatus() - 检查缓存状态
- updatePendingOpsCount() - 更新待同步计数
- syncNow() - 立即同步
- clearOfflineCache() - 清理离线缓存

### 3.3 外部JS文件
- offline-init.js - SW注册+初始化
- offline-manager.js - 离线缓存管理
- offline-data-cache.js - 数据缓存
- sync-manager.js - 离线操作同步
- sw_v2.js - Service Worker

## 四、思维导图模块

### 4.1 Tab结构
- 新建导图
- 导图列表
- 导图合并

### 4.2 核心功能
- 展示视图：markmap
- 编辑视图：mind-map editor
- 一套数据源，两个视图

## 五、修改保障机制

### 5.1 修改前
- [ ] 确认修改范围，不涉及其他功能
- [ ] 备份当前代码（backups目录）

### 5.2 修改后
- [ ] 对照本文档验证所有核心功能
- [ ] JavaScript语法检查通过
- [ ] 页面可正常访问
- [ ] 新增功能记录到本文档

### 5.3 功能丢失排查
- 如果功能丢失，先查备份文件（backups目录）
- 对比当前代码与备份，找到被删除的代码
- 恢复被删除的代码

---

## 功能添加记录

| 日期 | 功能 | 位置 | 说明 |
|------|------|------|------|
| 2026-08-30 | 🎲 随机朗读 | 记忆闪卡播报工具栏 | 随机选择闪卡朗读，支持云南口音 |
| 2026-08-30 | 离线同步初始化 | renderSettings函数末尾 | 进入设置页面自动恢复开关状态、更新缓存状态 |
| 2026-08-30 | 开关CSS样式 | 全局CSS | 52x28px开关，开启蓝色/关闭灰色，平滑过渡 |
| 2026-08-30 | Watchdog v3 | backend/watchdog.py | 防误重启，只在进程完全不存在时重启 |




======================================================================
# 附录8 【来源：代码规范总集.md】
======================================================================

# 📦 代码规范总集.md
> 版本 V1.0 ｜ 2026-09-13 ｜ 合并自根目录散落文件，每份标来源，原文件已归档。

## 📑 目录
1. 【来源：CODE_QUALITY_GUIDE.md】
2. 【来源：CODE_SAFETY_RULES.md】
3. 【来源：代码治理清理计划_V1.0.md】

---



============================================================
# § 1. 【来源：CODE_QUALITY_GUIDE.md】
============================================================

# 水利智学系统 - 代码审查清单与开发规范

> 版本: v1.0 | 更新日期: 2026-09-03 | 适用范围: 全项目

---

## 一、代码审查清单（11项）

每次提交代码前，必须逐项检查：

### 1. 功能完整性
- [ ] 新增功能是否完整实现需求
- [ ] 边界条件是否处理（空值、最大值、异常输入）
- [ ] 错误提示是否友好（用户可理解，不暴露技术细节）
- [ ] 是否兼容旧数据（数据库迁移、字段兼容）

### 2. 异常处理
- [ ] 禁止裸 `except:`，必须 `except Exception as e:`
- [ ] 异常必须记录日志 `logger.error/debug/warning`
- [ ] 关键操作必须有 try-catch 保护
- [ ] 异步函数必须有异常处理
- [ ] 外部调用（API、数据库、文件）必须有超时和重试

### 3. 日志记录
- [ ] 禁止使用 `print()`，必须使用 `logger`
- [ ] 日志必须携带模块标识 `[模块名]`
- [ ] 错误日志必须包含异常信息 `str(e)`
- [ ] 关键操作必须记录（用户登录、数据修改、备份恢复）
- [ ] 日志级别正确（DEBUG/INFO/WARNING/ERROR/CRITICAL）

### 4. 性能考虑
- [ ] 数据库查询必须有索引（大表查询）
- [ ] 避免 N+1 查询（循环中查询数据库）
- [ ] 大文件处理必须流式读取，不一次性加载到内存
- [ ] 循环中避免重复计算（提前计算不变量）
- [ ] 前端避免频繁 DOM 操作（批量更新）

### 5. 安全考虑
- [ ] SQL 查询必须使用参数化，禁止字符串拼接
- [ ] 用户输入必须验证和转义
- [ ] 文件上传必须验证类型和大小
- [ ] 敏感信息（密码、密钥）不得硬编码
- [ ] CORS 配置不得使用 `*`（生产环境）
- [ ] 密码必须加密存储（bcrypt）

### 6. 可维护性
- [ ] 函数长度不超过 50 行（超过则拆分）
- [ ] 函数命名清晰（动词+名词，如 `getQuestionList`）
- [ ] 变量命名有意义（禁止 `a`, `b`, `tmp`）
- [ ] 复杂逻辑必须有注释
- [ ] 魔法数字必须定义为常量
- [ ] 代码重复超过 3 次必须提取为函数

### 7. 兼容性
- [ ] 数据库变更必须有迁移脚本
- [ ] API 变更必须保持向后兼容（或版本化）
- [ ] 前端 JS 变更必须测试旧页面
- [ ] 配置变更必须有默认值
- [ ] 多端兼容（PC/平板/手机）

### 8. 可测试性
- [ ] 核心算法必须可单元测试（纯函数，无副作用）
- [ ] 业务逻辑与 UI 分离
- [ ] 外部依赖可 Mock（数据库、API、文件）
- [ ] 测试用例覆盖正常和异常路径

### 9. 多端适配
- [ ] 响应式布局（PC/平板/手机）
- [ ] 触控优化（按钮最小 44x44px）
- [ ] 离线可用（PWA 缓存）
- [ ] 网络异常处理（断网提示、重试）

### 10. 离线兼容
- [ ] 核心功能离线可用（刷题、闪卡）
- [ ] 离线数据本地存储（IndexedDB）
- [ ] 上线后自动同步
- [ ] 冲突处理机制

### 11. 数据安全
- [ ] 修改前自动备份
- [ ] 删除前二次确认
- [ ] 软删除（is_deleted），保留 30 天可恢复
- [ ] 操作日志记录（谁、何时、做了什么）
- [ ] 恢复前安全网备份

---

## 二、开发规范

### 2.1 模块划分（7模块）

| 缩写 | 模块名 | 职责 | 蓝图前缀 |
|------|--------|------|----------|
| qb | 题库管理 | 题目识别、新增编辑、预览、批量导入 | /api/qb |
| mt | 记忆训练 | 艾宾浩斯复习、闪卡、口诀、关键词 | /api/mt |
| mm | 思维导图 | markmap展示、mind-map编辑、脑图解析 | /api/mm |
| ai | AI能力 | Ollama对接、多模态识别、置信度计算 | /api/ai |
| sync | 同步模块 | 多设备同步、数据去重、PWA离线缓存 | /api/sync |
| resource | 资源管理 | 教材、视频、讲义、文件管理 | /api/resource |
| common | 公共通用 | 工具函数、日志、数据库封装、弹窗 | /api/common |

**规则**:
- common 只放通用工具，严禁写业务逻辑
- A 模块禁止 import B 模块 service 业务代码
- 模块间通过事件通信（前端）或 API 调用（后端）
- 所有新增文件、蓝图、数据表、DOM-id、日志必须带模块缩写

### 2.2 后端规范

#### 文件结构
```
backend/
├── modules/                    # 业务模块（新增）
│   ├── qb/
│   │   ├── routes.py          # 路由（只做参数接收、响应返回）
│   │   └── service.py         # 业务逻辑（计算、数据库操作）
│   ├── mt/
│   ├── mm/
│   ├── ai/
│   ├── sync/
│   ├── resource/
│   └── common/
├── api/v1/                     # 旧路由（保留，逐步搬迁）
├── models/                      # 数据模型
├── utils/                       # 工具函数（逐步搬迁到 common）
└── main.py                      # 入口（只注册蓝图，不写业务逻辑）
```

#### 路由规范
```python
# routes.py - 只做参数接收和响应返回
from fastapi import APIRouter, Depends, HTTPException
from .service import QuestionService

router = APIRouter(prefix="/api/qb", tags=["题库管理"])
service = QuestionService()

@router.get("/questions")
async def get_questions(subject: str = None, page: int = 1, page_size: int = 20):
    """获取题目列表"""
    try:
        result = service.get_question_list(subject, page, page_size)
        return {"code": 200, "msg": "成功", "data": result}
    except Exception as e:
        logger.error(f"[qb] 获取题目列表失败: {str(e)}", exc_info=True)
        raise HTTPException(status_code=500, detail="获取题目列表失败")
```

#### 业务逻辑规范
```python
# service.py - 业务逻辑和数据库操作
import logging
from sqlalchemy.orm import Session
from models.models import Question

logger = logging.getLogger(__name__)

class QuestionService:
    def get_question_list(self, subject: str, page: int, page_size: int) -> dict:
        """获取题目列表"""
        query = self.db.query(Question)
        if subject:
            query = query.filter(Question.subject == subject)
        total = query.count()
        questions = query.offset((page-1)*page_size).limit(page_size).all()
        return {
            "total": total,
            "page": page,
            "page_size": page_size,
            "list": [self._to_dict(q) for q in questions]
        }
```

#### 日志规范
```python
import logging
logger = logging.getLogger(__name__)

# 正确示例
logger.info("[qb] 题目导入完成，共导入 100 道题")
logger.error("[qb] 题目导入失败: {str(e)}", exc_info=True)
logger.warning("[qb] 题目选项解析失败，使用默认值")

# 错误示例（禁止）
print("题目导入完成")  # 禁止使用 print
except: pass  # 禁止裸except
```

### 2.3 前端规范

#### 文件结构
```
frontend/js/
├── modules/                    # 业务模块（新增）
│   ├── qb.js                  # 题库管理
│   ├── mt.js                  # 记忆训练
│   ├── mm.js                  # 思维导图
│   ├── ai.js                  # AI功能
│   └── sync.js                # 同步和离线
├── core/                       # 核心层（新增）
│   ├── store.js               # 统一状态管理
│   ├── event-bus.js           # 事件总线
│   ├── component.js           # 组件基类
│   └── api.js                 # API封装
├── app.js                      # 旧代码（保留，逐步搬迁）
└── ...
```

#### 模块通信规范
```javascript
// 正确：通过事件总线通信
// qb.js 中
window.dispatchEvent(new CustomEvent('qb:question-answered', {
    detail: { questionId: 123, correct: true }
}));

// mt.js 中
window.addEventListener('qb:question-answered', (e) => {
    console.log('题目已回答:', e.detail);
});

// 错误：直接调用其他模块函数
// qb.js 中
mt.updateFlashcard(123);  // 禁止直接调用
```

#### DOM 命名规范
```html
<!-- 正确：带模块缩写前缀 -->
<div id="qb_question_modal">...</div>
<div id="mt_flashcard_container">...</div>
<div id="mm_mindmap_editor">...</div>

<!-- 旧组件：添加注释标记 -->
<!-- 水利智学旧组件：题库模块，后续迭代重构 -->
<div id="questionModal">...</div>
```

#### 状态管理规范
```javascript
// core/store.js - 统一状态管理
class Store {
    constructor() {
        this.state = {
            currentSubject: '',
            user: null,
            settings: {}
        };
        this.listeners = [];
    }

    getState() {
        return this.state;
    }

    setState(key, value) {
        this.state[key] = value;
        this.notify(key, value);
    }

    subscribe(key, callback) {
        this.listeners.push({ key, callback });
    }

    notify(key, value) {
        this.listeners
            .filter(l => l.key === key)
            .forEach(l => l.callback(value));
    }
}

window.store = new Store();
```

### 2.4 数据库规范

#### 表命名规范
- 旧表保留原名（不修改）
- 新表必须加模块缩写前缀：`qb_recognition_tasks`、`mm_pdf_parse_records`
- 字段命名：蛇形命名（snake_case），如 `created_at`、`question_id`

#### 迁移规范
```python
# backend/migrations/20260903_add_qb_recognition_tasks.py
"""
迁移：新增题库识别任务表
模块: qb
日期: 2026-09-03
"""

def upgrade(conn):
    """升级"""
    conn.execute("""
        CREATE TABLE IF NOT EXISTS qb_recognition_tasks (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            uuid TEXT UNIQUE,
            file_path TEXT,
            status TEXT DEFAULT 'pending',
            total_count INTEGER DEFAULT 0,
            success_count INTEGER DEFAULT 0,
            fail_count INTEGER DEFAULT 0,
            confidence_avg REAL DEFAULT 0,
            result_json TEXT,
            error_message TEXT,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
    """)
    conn.execute("CREATE INDEX IF NOT EXISTS idx_qb_recognition_status ON qb_recognition_tasks(status)")
    conn.commit()

def downgrade(conn):
    """降级"""
    conn.execute("DROP TABLE IF EXISTS qb_recognition_tasks")
    conn.commit()
```

### 2.5 Git 提交规范（如使用 Git）

```
<类型>(<模块>): <简短描述>

<详细描述>

<关联问题>
```

类型：
- feat: 新功能
- fix: 修复bug
- refactor: 重构（不改变功能）
- perf: 性能优化
- docs: 文档更新
- test: 测试相关
- chore: 构建/工具/依赖

示例：
```
feat(qb): 新增PDF题目识别功能

- 支持PDF页面图片快照
- 支持版面坐标切块
- 支持Ollama Qwen3-vl多模态识别
- 识别结果需人工确认后入库

关联: #123
```

---

## 三、性能监控阈值

| 指标 | 阈值 | 处理 |
|------|------|------|
| API 响应时间 | > 1s | 记录警告，分析优化 |
| 数据库查询 | > 500ms | 记录警告，检查索引 |
| 页面加载 | > 3s | 记录警告，优化资源 |
| AI 调用 | > 30s | 超时重试或降级 |
| 内存使用 | > 80% | 告警，清理缓存 |
| 磁盘使用 | > 80% | 告警，清理旧日志备份 |
| CPU 使用 | > 90% | 告警，检查进程 |

---

## 四、安全审计清单

- [ ] 密码加密存储（bcrypt）
- [ ] JWT Token 验证
- [ ] SQL 注入防护（参数化查询）
- [ ] XSS 防护（输入转义）
- [ ] CSRF 防护
- [ ] 文件上传验证（类型、大小）
- [ ] 敏感信息不硬编码
- [ ] CORS 配置限制
- [ ] 操作日志记录
- [ ] 错误信息不暴露技术细节
- [ ] 依赖库定期更新

---

## 五、测试用例清单（75项核心）

### 题库管理（15项）
1. 题目列表加载
2. 题目分页
3. 题目按科目筛选
4. 题目按章节筛选
5. 题目搜索
6. 单选题答题
7. 多选题答题
8. 题目解析显示
9. 错题自动记录
10. 错题本查看
11. 题目收藏
12. 题目新增
13. 题目编辑
14. 题目删除
15. 批量导入题目

### 记忆训练（15项）
16. 闪卡列表加载
17. 闪卡翻转
18. 闪卡记住/忘记
19. SM-2 间隔计算
20. 闪卡分类筛选
21. 闪卡搜索
22. 闪卡新增
23. 闪卡编辑
24. 闪卡删除
25. 口诀生成
26. 关键词提取
27. 学习计划生成
28. 今日复习
29. 学习进度统计
30. 记忆曲线展示

### 思维导图（10项）
31. 脑图列表加载
32. 脑图 markmap 展示
33. 脑图 mind-map 编辑
34. 脑图节点新增
35. 脑图节点编辑
36. 脑图节点删除
37. 脑图拖拽排序
38. 脑图导出
39. 脑图导入
40. PDF 脑图解析

### AI功能（10项）
41. AI 解题
42. AI 拍照解题
43. AI 知识点提取
44. AI 口诀生成
45. AI 学习计划
46. AI 薄弱点推荐
47. AI 错误分类
48. AI 置信度计算
49. AI 识别预览确认
50. AI 降级策略

### 同步离线（10项）
51. 数据同步上传
52. 数据同步下载
53. 冲突检测
54. 冲突解决
55. 离线刷题
56. 离线闪卡
57. 离线数据缓存
58. 上线自动同步
59. 同步状态显示
60. PWA 安装

### 系统设置（15项）
61. 用户登录
62. 用户注册
63. 密码修改
64. 科目切换
65. 专业方向选择
66. 备份管理
67. 数据恢复
68. 智能去重
69. 服务监控
70. 日志查看
71. 缓存清理
72. 主题切换
73. 字体大小调整
74. 通知设置
75. 关于系统

---

## 六、增量搬迁规范

### 原则
1. **新旧共存**：旧代码保留，新代码逐步添加
2. **增量搬迁**：每次只搬迁一个功能或一个模块
3. **测试验证**：搬迁后立即运行对应测试用例
4. **灰度发布**：新功能先在开发环境验证，再小范围试用
5. **可回滚**：保留旧代码至少2个版本周期，确认稳定后再删除

### 搬迁流程
```
1. 选择要搬迁的功能（如：题目列表）
2. 在新模块中创建对应函数
3. 将旧函数逻辑复制到新模块
4. 优化代码（添加日志、异常处理、类型注解）
5. 修改调用方，指向新模块函数
6. 运行测试用例验证
7. 确认稳定后，标记旧函数为 deprecated
8. 2个版本周期后，删除旧函数
```

### 搬迁优先级
1. **P0**：频繁修改的功能（容易引发bug）
2. **P1**：核心业务功能（题库、闪卡、思维导图）
3. **P2**：辅助功能（设置、统计、日志）
4. **P3**：临时脚本和工具函数

---

## 七、PDF-VL 识别规范

### 识别流程
```
PDF文件
  ↓
页面生成图片快照（200DPI）
  ↓
版面坐标切块（题目区域/脑图区域）
  ↓
Ollama Qwen3-vl:4b 多模态识别
  ↓
结构化 JSON 输出
  ↓
后处理（格式校验、内容校验、去重、跨页拼接）
  ↓
置信度计算（格式30% + 内容40% + 图像20% + 模型10%）
  ↓
预览弹窗（人工确认）
  ↓
写入数据库（仅确认后）
```

### 绝对禁止
- ❌ 仅传递 PDF 纯文本给 VL 模型（必须传截图+坐标）
- ❌ 识别结果自动直接入库（必须人工预览确认）
- ❌ 一次性全量重构旧识别代码（新旧并行，增量搬迁）

---

**文档结束**

> 本规范随项目迭代持续更新，如有疑问请参考代码实例或提交 Issue。


============================================================
# § 2. 【来源：CODE_SAFETY_RULES.md】
============================================================

# 代码安全约束与版本管理规范

## 一、代码删除约束（最高优先级）

### 1.1 禁止无确认大规模删除
- **绝对禁止**AI直接一次性删除大段业务代码（超过10行或包含核心逻辑）
- 删除操作必须**单独标注**，先输出待删除片段，用户确认后再执行
- 小范围删除（<5行且非核心逻辑）可直接执行，但必须在回复中明确说明

### 1.2 删除操作流程
1. **识别**：识别需要删除的代码片段
2. **标注**：在回复中明确标注"【待删除代码】"
3. **展示**：完整展示待删除的代码片段（包含行号和上下文）
4. **说明**：说明删除原因和影响范围
5. **等待确认**：等待用户明确确认（"确认删除"、"可以删"等）
6. **执行**：用户确认后才执行删除操作

### 1.3 禁止删除的内容
- 核心业务逻辑（如解析器、数据库操作、API接口）
- 用户已确认的功能模块
- 带有"锁死"标记的功能
- 备份文件和快照文件

---

## 二、源码存储约束

### 2.1 全部落地本地磁盘
- **禁止**依赖云端沙箱保存源码
- 所有代码修改必须直接写入本地磁盘文件
- 沙箱没有回滚、没有版本，不能作为唯一存储

### 2.2 关键文件清单
以下文件必须完整保存在本地：
- `frontend/index.html`（前端单文件应用）
- `backend/api/v1/*.py`（后端API接口）
- `backend/utils/*.py`（工具类）
- `backend/crud/*.py`（数据库操作）
- `backend/models/*.py`（数据模型）
- `backend/core/*.py`（核心配置）
- `backend/main.py`（后端入口）

---

## 三、代码快照机制

### 3.1 快照时机
- **每一轮迭代结束后**必须创建代码快照
- 重大修改前必须创建快照（如重构、删除大段代码）
- 用户明确要求时创建快照

### 3.2 快照工具
- 工具脚本：`snapshot.py`
- 用法：`python snapshot.py [轮次说明]`
- 快照位置：`code_snapshots/snapshot_YYYYMMDD_HHMMSS_[说明]/`
- 同时生成zip压缩包：`snapshot_YYYYMMDD_HHMMSS_[说明].zip`

### 3.3 快照内容
- 所有关键文件的完整副本
- 快照信息文件（时间、说明、文件清单）
- 可用于回滚到任意历史版本

---

## 四、Diff变更监听机制

### 4.1 监听时机
- **每次代码修改后**必须运行diff监听
- 记录本次修改了哪些文件、哪些行
- 出问题时可定位是哪一轮引入的bug

### 4.2 监听工具
- 工具脚本：`diff_logger.py`
- 用法：`python diff_logger.py [轮次说明]`
- 日志位置：`code_snapshots/diff_logs/diff_YYYYMMDD_HHMMSS_[说明].txt`

### 4.3 Diff日志内容
- 变更时间和说明
- 对比的快照版本
- 每个变更文件的统一diff（+新增/-删除/修改）
- 变更统计（文件数、文件清单）

---

## 五、迭代工作流（标准流程）

### 5.1 每轮迭代标准步骤
```
1. 接收用户需求
2. 分析需求，确定修改范围
3. 【如涉及删除】先输出待删除片段，等待确认
4. 执行代码修改（写入本地磁盘）
5. 验证语法（Python/JS语法检查）
6. 运行diff_logger.py记录本次变更
7. 运行snapshot.py创建代码快照
8. 回复用户修改结果（包含变更文件清单）
```

### 5.2 回滚流程
```
1. 发现问题
2. 查看diff_logs定位引入bug的轮次
3. 找到该轮次之前的快照
4. 从快照恢复关键文件
5. 验证恢复结果
6. 重新创建快照
```

---

## 六、锁死机制

### 6.1 锁死规则
- 用户说"锁死" = 该功能不可修改
- 用户说"其他锁死" = 除指定功能外，其他所有功能不可修改
- 锁死状态下不做任何更改，除非有新指令

### 6.2 锁死记录
- 每次用户说"锁死"时，必须在回复中明确记录锁死范围
- 后续修改前必须检查是否违反锁死规则
- 违反锁死规则的修改必须立即回滚

---

## 七、违规处理

### 7.1 违规行为
- 无确认删除大段代码
- 依赖云端沙箱保存源码
- 未创建代码快照
- 未记录diff变更
- 违反锁死规则

### 7.2 处理措施
- 立即停止当前操作
- 从最近快照回滚
- 向用户道歉并说明情况
- 重新执行正确流程

---

**本规范自创建之日起生效，所有代码修改必须严格遵循。**
**创建时间：2026-08-21**


============================================================
# § 3. 【来源：代码治理清理计划_V1.0.md】
============================================================

# 代码治理清理计划 V1.0

## 现状诊断

| 指标 | 数值 | 问题 |
|------|------|------|
| JS内联style | 3689个 | 布局混乱根源，CSS难以覆盖 |
| 含内联style的函数 | 247个 | 分散在各页面渲染函数 |
| style.css规则 | 1181条/101KB | 比黄金基线66KB多35KB冗余 |
| V2 CSS规则 | 57条/12KB | 唯一标准，但覆盖不全 |
| JS函数总数 | 1019个 | 代码量大，需分批治理 |

## 治理原则

1. **只改样式不改功能**：提取内联style为CSS类名，不改变渲染逻辑
2. **逐页验证**：每页清理后真实浏览器验证，不批量操作
3. **V2 CSS为唯一标准**：所有提取的样式写入V2 CSS，不新增style.css
4. **备份先行**：每阶段开始前自动创建L3快照
5. **可回滚**：每阶段完成后创建L2增量备份

## 阶段1：JS内联样式清理（最高优先级）

### 目标
将3689个内联style逐步提取为CSS类名，最终目标：内联style < 100个（仅保留动态计算样式）

### 分批策略（按页面重要性）

| 批次 | 页面/模块 | 预估内联style | 优先级 |
|------|-----------|---------------|--------|
| 1-1 | 学习看板(renderDashboard) | ~50 | P0 |
| 1-2 | 题库管理(renderQuestionList) | ~80 | P0 |
| 1-3 | 闪卡管理(renderFlashcard) | ~60 | P0 |
| 1-4 | 思维导图(renderMindmap) | ~70 | P0 |
| 1-5 | 视频播放(renderVideo) | ~50 | P1 |
| 1-6 | 智能笔记(renderNote) | ~40 | P1 |
| 1-7 | 学习分析(renderAnalysis) | ~60 | P1 |
| 1-8 | 登录界面(renderLogin) | ~40 | P1 |
| 1-9 | 系统设置(renderSettings) | ~50 | P2 |
| 1-10 | 其他页面 | ~3189 | P2 |

### 清理方法
1. 找到函数中的内联style
2. 分析样式内容，提取公共模式
3. 在V2 CSS中添加对应类名
4. 将JS中的`style="..."`替换为`class="xxx"`
5. 真实浏览器验证布局不变

### 验收标准
- 页面布局与清理前完全一致
- 内联style数量减少
- 无控制台报错

## 阶段2：style.css冗余清理

### 目标
style.css从101KB降至70KB以内，删除与V2 CSS重复的规则

### 方法
1. 对比黄金备份style.css（66KB），找出新增规则
2. 对比V2 CSS，删除重复规则
3. 保留基础重置样式和组件样式
4. 页面级样式迁移到V2 CSS

### 验收标准
- style.css < 70KB
- 所有页面布局正常
- V2 CSS成为页面级样式唯一来源

## 阶段3：CSS Token体系完善

### 目标
所有颜色、间距、字号、尺寸使用CSS变量，禁止硬编码

### Token清单
```css
:root {
  /* 颜色 */
  --v2-primary: #1976d2;
  --v2-success: #4caf50;
  --v2-warning: #ff9800;
  --v2-danger: #f44336;
  --v2-bg: #f5f5f5;
  --v2-card: #ffffff;
  --v2-border: #e0e0e0;
  --v2-text: #333333;
  --v2-text-secondary: #666666;
  
  /* 间距 */
  --v2-gap-xs: 2px;
  --v2-gap-sm: 4px;
  --v2-gap-md: 6px;
  --v2-gap-lg: 8px;
  --v2-gap-xl: 12px;
  
  /* 字号 */
  --v2-font-xs: 10px;
  --v2-font-sm: 11px;
  --v2-font-md: 12px;
  --v2-font-lg: 14px;
  --v2-font-xl: 16px;
  
  /* 尺寸 */
  --v2-nav-height: 48px;
  --v2-tab-height: 40px;
  --v2-header-height: 36px;
  --v2-row-height: 32px;
  --v2-status-height: 28px;
  --v2-sidebar-width: 180px;
  
  /* 圆角 */
  --v2-radius-sm: 3px;
  --v2-radius-md: 6px;
  --v2-radius-lg: 8px;
}
```

### 验收标准
- V2 CSS中无硬编码颜色/间距/字号
- 所有页面使用Token变量
- 修改Token可全局生效

## 阶段4：多端样式严格隔离

### 目标
电脑/手机/平板三端样式完全独立，互不干扰

### 隔离方案
- 电脑端：`style.css` + `V2布局规则_统一版.css`
- 手机端：`mobile.css`（独立，不引入电脑端样式）
- 平板端：`tablet.css`（独立，不引入电脑端样式）
- 共用：`tokens.css`（仅变量，无布局规则）

### 验收标准
- 修改电脑端样式不影响手机/平板
- 修改手机端样式不影响电脑/平板
- 三端各自独立验证

## 阶段5：代码混入检查机制

### 目标
防止新代码混入旧风格，建立自动化检查

### 检查项
1. 新增内联style > 5个 → 警告
2. 新增硬编码颜色 → 警告
3. 新增硬编码尺寸 → 警告
4. 修改style.css → 警告（应修改V2 CSS）
5. 跨端样式修改 → 警告

### 实施方式
- 提交前自动运行检查脚本
- 不符合规范的代码阻止提交
- 生成检查报告

## 时间估算

| 阶段 | 工作量 | 预计时间 |
|------|--------|----------|
| 阶段1：内联样式清理 | 3689个 | 分批进行，核心页面优先 |
| 阶段2：style.css清理 | 1181条规则 | 1-2天 |
| 阶段3：Token体系完善 | 全量替换 | 2-3天 |
| 阶段4：多端隔离 | 3端样式 | 1-2天 |
| 阶段5：检查机制 | 脚本开发 | 1天 |

## 责任专家

- 前端架构师：整体方案设计，V2 CSS维护
- 重构专家：内联样式提取，代码清理
- 验证专家：每页真实浏览器验证
- 质量管控：代码混入检查机制



======================================================================
# 附录9 【来源：README.md】
======================================================================

# 水利智学一体化题库系统 V4.0

水利工程考证（一造/一建/二建）智能刷题备考系统，支持题库管理、模拟考试、错题本、AI拍照解题、智能助手、视频课程、多端同步等功能。

## 交付版本说明

本系统提供三种交付形式，按需选择：

| 版本 | 文件名 | 适用场景 | 说明 |
|------|--------|----------|------|
| 可运行版 | shuili_zhixue_v4_full.zip | 直接测试使用 | 解压后双击 start.bat 即可运行，含完整依赖说明 |
| 源码版 | shuili_zhixue_v4_source.zip | 开发者二次开发 | 仅源代码，不含启动脚本和打包脚本，便于代码审查和修改 |
| EXE封装版 | shuili_zhixue_v4_exe_build.zip | 打包成桌面应用 | 含 launcher.py + build_exe.bat，在Windows上双击即可打包成单文件exe |

### EXE封装步骤（Windows）
1. 安装 Python 3.10+ 和 pip
2. 解压 EXE封装版，进入目录
3. 双击 `build_exe.bat`，自动安装依赖并打包
4. 打包完成后在 `dist/` 目录得到 `水利智学.exe`
5. 双击 exe 即可运行，自动打开浏览器，数据保存在 exe 同级目录

## AI解题 - 本地知识库优先策略

AI拍照解题和智能助手均采用「本地优先、AI其次」的检索策略：

1. **精确匹配**：题目图片识别后，先在本地题库中相似度匹配（阈值75%），匹配到原题直接返回答案和解析，无需调用AI
2. **本地上下文**：未精确匹配时，检索本地题库中相关题目、用户笔记、教材资料，组装成上下文
3. **AI增强**：将本地检索结果作为上下文传给大模型，生成更精准的解析
4. **纯AI兜底**：本地无相关内容时，直接调用大模型通用解答
5. **未配置AI**：返回本地检索结果汇总，引导用户配置API密钥

支持的AI提供商：通义千问、智谱AI、DeepSeek、豆包、OpenAI、自定义兼容OpenAI格式接口。
在「系统设置 - AI配置」中填写API密钥即可启用，所有数据本地闭环。


## 功能特性

- **题库刷题**：多科目、多章节、多难度筛选，支持单选/多选/判断
- **模拟考试**：按真实考试规则组卷，倒计时、答题卡、自动判分
- **错题本**：自动归集错题，艾宾浩斯复习提醒，举一反三推荐
- **收藏夹**：一键收藏重点题目
- **记忆闪卡**：正反面翻转复习，支持自定义卡片
- **学习笔记**：富文本笔记，支持标签分类
- **视频课程**：B站嵌入视频，考点绑定，播放进度同步
- **AI拍照解题**：拍照上传题目，AI自动识别并生成解析
- **智能助手**：错题答疑、自然语言检索、复习规划、学习进度问答
- **数据分析**：正确率统计、章节分析、薄弱点识别、学习趋势
- **多端同步**：IndexedDB离线缓存，局域网多设备数据同步
- **PWA支持**：Service Worker离线缓存，可安装到桌面
- **暗色模式**：支持明暗主题切换

## 快速开始

### 方式一：一键启动（Windows）

```bash
start.bat
```

### 方式二：手动启动

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 初始化数据库
cd backend
python scripts/init_db.py

# 3. 启动服务
python main.py
```

启动后访问：http://localhost:8000

### 默认账号

- 管理员：admin / admin123
- 测试用户：test / test123

## 项目结构

```
shuili_zhixue_v4/
├── backend/
│   ├── api/v1/          # API路由
│   │   ├── auth.py      # 认证
│   │   ├── question.py  # 题库
│   │   ├── exam.py      # 模拟考试
│   │   ├── wrong.py     # 错题
│   │   ├── ai_scan.py   # AI拍照解题
│   │   ├── flashcard.py # 闪卡
│   │   ├── note.py      # 笔记
│   │   ├── video.py     # 视频课程
│   │   ├── assistant.py # 智能助手
│   │   ├── sync.py      # 多端同步
│   │   ├── system.py    # 系统管理
│   │   └── analytics.py # 数据分析
│   ├── core/            # 核心配置
│   │   ├── config.py    # 配置（动态路径）
│   │   └── db.py        # 数据库
│   ├── models/          # 数据模型
│   ├── schemas/         # Pydantic校验
│   ├── crud/            # 数据操作
│   ├── utils/           # 工具函数
│   ├── scripts/         # 脚本
│   │   └── init_db.py   # 数据库初始化
│   └── main.py          # 入口
├── frontend/
│   ├── index.html       # 前端单页应用
│   ├── manifest.json    # PWA配置
│   └── sw.js            # Service Worker
├── data/                # 数据库文件
├── uploads/             # 上传文件
├── backups/             # 备份目录
├── logs/                # 日志
├── requirements.txt
├── start.bat            # Windows启动脚本
├── start.sh             # Linux/Mac启动脚本
├── launcher.py          # EXE封装启动器
├── build_exe.bat        # EXE打包脚本
├── setup_firewall.bat   # 防火墙放行脚本
├── .env                 # 环境变量
├── .gitignore
└── README.md
```

## API文档

启动后访问 http://localhost:8000/docs 查看完整API文档。

## 局域网访问

1. 运行 `setup_firewall.bat` 放行端口（Windows）
2. 查看本机IP：`ipconfig`
3. 手机/平板连同一WiFi，访问 `http://你的IP:8000`

## EXE封装

```bash
# 安装PyInstaller
pip install pyinstaller

# 打包
build_exe.bat
```

打包后在 `dist/` 目录生成单文件EXE。

## 技术栈

- 后端：FastAPI + SQLAlchemy + SQLite
- 前端：原生HTML/CSS/JS（无框架依赖）
- 认证：JWT
- 离线：PWA + IndexedDB
- 打包：PyInstaller

## 许可证

MIT



======================================================================
# 附录10 【来源：修改日志.md】
======================================================================

# 水利智学系统 - 修改日志

> 每次修改必须记录，确保可追溯、可回滚。

## 2026-08-30 修改记录

### 1. Watchdog v3 防误重启
- 文件：backend/watchdog.py
- 问题：v1使用wmic频繁超时误判，v2端口检测逻辑太激进
- 修改：移除端口检测重启，只在进程完全不存在时重启；内存阈值1200MB；启动宽限期90秒；检查间隔15秒
- 状态：✅ 已完成，稳定运行

### 2. 离线同步功能修复
- 文件：frontend/index.html
- 问题1：syncNow()函数重复定义（第2036行旧版本API路径错误）
- 修改1：删除旧版本，保留第17317行版本
- 问题2：同步无明显反馈
- 修改2：改进syncNow()，增加按钮状态、离线检查、待同步数量检查、结果显示
- 问题3：进入设置页面缓存状态一直显示"检测中..."
- 修改3：在renderSettings()末尾添加初始化代码，自动恢复开关状态、更新缓存状态和待同步计数
- 状态：✅ 已完成

### 3. 开关CSS样式优化
- 文件：frontend/index.html（第1456行style标签内）
- 问题：开关使用浏览器默认样式，不明显
- 修改：添加52x28px自定义开关，开启蓝色/关闭灰色，平滑过渡，悬停效果
- 状态：✅ 已完成

### 4. 记忆闪卡 - 随机朗读功能
- 文件：frontend/index.html
- 问题：用户反馈随机朗读功能丢失
- 修改：在播报工具栏添加"🎲 随机"按钮；添加toggleRandomSpeak()和speakRandomFlashcard()函数；支持云南口音；自动切换下一张随机闪卡
- 状态：✅ 已完成

### 5. 记忆训练 - 恢复两个专项训练
- 文件：frontend/index.html（EXAM_MEMORY_TRAINING数组）
- 问题：用户反馈口诀专项记忆和朗读专项记忆丢失
- 修改：添加第9个"💡 口诀专项记忆"（8题）；添加第10个"🔊 朗读专项记忆"（8题）
- 状态：✅ 已完成

### 6. 功能清单与修改保障文档
- 文件：功能清单与修改保障.md
- 内容：记录所有核心功能位置、修改保障机制、功能添加记录
- 状态：✅ 已创建

### 7. 本修改日志
- 文件：修改日志.md
- 内容：记录每次修改的详细内容
- 状态：✅ 已创建

### 8. 修复卡片管理-闪卡列表不显示（卡片库）
- 文件：frontend/index.html
- 问题：loadFcManage函数查找fcManageList元素，但卡片管理面板中只有flashcardList元素，导致闪卡列表不显示
- 根因：元素id不匹配，29号备份中也存在此问题
- 修改：
  1. 卡片管理面板：flashcardList → fcManageList（第7213行）
  2. 智能复习面板reviewArea中：添加flashcardList元素（第7265行）
- 状态：✅ 已修复，JavaScript语法验证通过

### 9. 完整备份当前版本
- 备份目录：backups/full_20260830_150430
- 备份大小：83.38MB
- 备份内容：frontend + backend（不含uploads/ollama_models）+ 根目录关键文件 + 布局规范
- 验证：所有核心文件大小验证通过
- 状态：✅ 备份完整

### 10. 创建自动备份脚本
- 文件：auto_backup.ps1（纯英文，避免编码问题）
- 功能：
  1. 备份前验证当前版本核心文件完整性
  2. 完整备份代码+日志+数据库（不含上传文件）
  3. 备份后自动验证完整性
  4. 验证失败自动删除不完整备份
- 使用：powershell -ExecutionPolicy Bypass -File auto_backup.ps1 -Reason "备份原因"
- 测试：backups/full_20260830_150713（83.27MB，验证通过）
- 状态：✅ 测试成功

### 11. 记忆闪卡-磨耳朵功能
- 文件：frontend/index.html
- 问题：用户反馈"磨耳朵"功能（连续播放所有闪卡增强记忆）不存在
- 修改：
  1. 播报工具栏添加"👂 磨耳朵"按钮（第7884行）
  2. 添加toggleEarTraining()函数（开启/关闭磨耳朵模式）
  3. 添加speakEarTrainingCard()函数（连续播放所有闪卡）
  4. 支持循环播放、云南口音、自动切换卡片、显示播放进度
- 状态：✅ 已实现，JavaScript语法验证通过

### 12. 模拟考试-多选题题型判断修复
- 文件：frontend/index.html
- 问题：用户反馈"多选题都是选择一个就直接跳答案了"，多选题题型判断函数isMultiQuestion只支持有限的题型值
- 修改：
  1. 扩展isMultiQuestion函数，支持更多题型值：multi_select、multiple_choice、多选、multi_answer、multiple_answer、不定项、不定项选择题
  2. 确保多选题正确调用toggleExamOption函数，支持多选
- 状态：✅ 已修复，JavaScript语法验证通过

### 13. 模拟考试布局全面对比检测
- 文件：frontend/index.html
- 问题：用户反馈"模拟考试也变成半个月以前的版本了"、"解析和答题左右布局也不在了"、"答题卡布局也变了"
- 检测结果：
  1. 答题卡布局：与29号备份完全一致（右侧280px宽度，sticky定位）
  2. 模拟考试结果页面：与29号备份完全一致（上下布局，分数圆圈+题型分布+答题详情）
  3. 刷题页面：与29号备份完全一致（上下布局，questionPracticeArea+questionList）
  4. 核心函数：全部存在，无缺失（renderExam、startExam、renderExamOngoing、renderExamResult、toggleExamOption、examAnswer等）
  5. JavaScript语法：验证通过
- 结论：代码层面未发现模拟考试功能倒退，布局与29号备份完全一致
- 状态：✅ 检测完成，未发现代码倒退

---

## 待确认功能

### 全局锁死/隔离功能
- 用户反馈："全局隔离也不在了"
- 当前状态：未找到独立的全局锁死/隔离功能
- 需要用户确认：
  1. 这个功能的具体位置（系统设置？还是每个模块？）
  2. 这个功能的作用（禁用所有操作？还是模块间隔离？）
  3. 这个功能的触发方式（按钮？还是开关？）

---

## 修改保障机制

1. 修改前：确认修改范围，备份当前代码
2. 修改中：只改被点名的范围，不涉及其他功能
3. 修改后：对照功能清单验证所有核心功能，JavaScript语法检查，页面可访问测试
4. 修改记录：记录到本日志和功能清单文档
5. 功能丢失：先查备份，对比恢复



======================================================================
# 附录11 【来源：版本回溯机制使用说明.md】
======================================================================

# 水利智学系统 - 版本回溯机制使用说明

## 概述

本系统提供完整的版本回溯机制，确保每次修改前都有备份，可随时恢复到任意历史版本。

## 文件结构

```
项目根目录/
├── version_control.py          # 版本管理主脚本
├── auto_backup_hook.py         # 自动备份钩子（修改前调用）
├── 备份.bat                     # 图形化备份工具（双击运行）
├── _version_backups/           # 自动备份目录
│   ├── index_20260821_153500.html
│   ├── index_20260821_164000.html
│   └── change_log.json         # 修改日志
└── _restore_points/            # 命名还原点目录
    ├── 2026-8-20 1800稳定版_xxx/
    │   ├── index.html
    │   └── meta.json
    └── 2026-8-21 1535 wangEditor5集成版_xxx/
        ├── index.html
        └── meta.json
```

## 快速使用（推荐）

### 方法一：双击 `备份.bat`（图形化菜单）

双击运行 `备份.bat`，选择操作：
1. 快速备份当前版本
2. 列出所有备份版本
3. 创建命名还原点
4. 列出所有还原点
5. 恢复到指定备份
6. 恢复到指定还原点
7. 对比两个版本差异
8. 清理旧备份

### 方法二：命令行

```bash
# 备份当前版本
python version_control.py backup "修改描述" "修改原因"

# 列出最近20个备份
python version_control.py list

# 列出最近50个备份
python version_control.py list 50

# 恢复到指定备份
python version_control.py restore index_20260821_153500.html

# 创建命名还原点
python version_control.py point "还原点名称" "还原点描述"

# 列出所有还原点
python version_control.py points

# 恢复到指定还原点（支持模糊匹配）
python version_control.py restore-point "18:00稳定版"

# 对比两个版本差异
python version_control.py compare 文件1路径 文件2路径
```

## 开发者使用（自动备份钩子）

在任何修改 `frontend/index.html` 的脚本开头，添加以下代码：

```python
from auto_backup_hook import auto_backup

# 在修改前自动备份
auto_backup("修改视频讲义布局", "准备调整播放器2/3+笔记1/3布局")

# 然后执行你的修改逻辑...
```

这样每次修改前都会自动备份，不会丢失任何版本。

## 现有还原点

| 还原点名称 | 创建时间 | 说明 |
|-----------|---------|------|
| 2026-8-20 18:00稳定版 | 2026-08-21 | 昨天布局稳定版本，wangEditor5未集成 |
| 2026-8-21 15:35 wangEditor5集成版 | 2026-08-21 | wangEditor5已集成到学习笔记，网站资源tab被误删 |

## 备份策略

- **自动备份**：每次修改前自动调用 `auto_backup()`
- **手动备份**：通过 `备份.bat` 或命令行手动备份
- **还原点**：重要节点创建命名还原点，方便快速恢复
- **清理策略**：默认保留最近30天或最近100个备份，可手动清理

## 恢复后操作

恢复版本后，请按 `Ctrl+F5` 强制刷新浏览器，清除缓存后查看效果。

## 注意事项

1. 恢复前会自动备份当前版本，不用担心恢复错误
2. 还原点名称支持模糊匹配，输入部分名称即可
3. 备份文件命名格式：`index_YYYYMMDD_HHMMSS.html`
4. 所有备份和还原点都在项目目录内，不涉及外部路径



======================================================================
# 附录12 【来源：规划细则分册\代码清理替换计划.md】
======================================================================

# 代码清理替换计划 V1.0

> 依据宪法第三十二章「代码质量与混入检测机制」制定
> 原则：新代码完全替换旧代码，禁止新旧逻辑混在一起；旧代码作为fallback必须明确标注

## 一、当前新旧代码共存点清单

### 1. 知识点掌握度（ECharts + 旧HTML进度条）
- **位置**：app.js 第3778-3870行
- **现状**：ECharts柱状图为主，旧HTML进度条作为fallback
- **替换计划**：确认ECharts稳定后，删除旧masteryHtml构建逻辑（第3809-3845行）
- **优先级**：中（不影响功能，仅代码冗余）
- **预计完成**：系统稳定1周后

### 2. API封装层（window.api + 原生fetch）
- **位置**：monitor.js 第202行、app.js 第445行
- **现状**：monitor.js拦截window.api，但部分代码仍直接调用fetch
- **替换计划**：逐步将所有原生fetch替换为window.api统一封装
- **优先级**：高（影响监控和错误处理一致性）
- **预计完成**：P0-06阶段4迁移时同步完成

### 3. 全局变量（window.xxx + window.store）
- **位置**：app.js多处
- **现状**：部分全局变量已迁移到window.store，部分仍在window上
- **替换计划**：P0-06阶段4完成全部迁移
- **优先级**：最高（P0核心任务）
- **预计完成**：持续推进中

### 4. 重复函数（多份实现）
- **位置**：待全面排查
- **现状**：995个函数无重复定义，但可能存在功能相似的函数
- **替换计划**：用code_quality_check.py定期检测，发现后合并
- **优先级**：中
- **预计完成**：每轮迭代清理一批

## 二、防止混入机制（每次修改必须执行）

### 修改前检查
1. ✅ 搜索目标函数/变量，确认只有一处定义
2. ✅ 检查所有调用点，确认修改范围
3. ✅ 用execution_guard.py备份
4. ✅ 用impact_analyzer.py分析影响范围

### 修改中规则
1. ✅ 精确替换，不扩展范围
2. ✅ 新代码完全替换旧代码，不保留旧逻辑（除非明确标注fallback）
3. ✅ 新增功能独立成函数，不混入现有函数体
4. ✅ 用Python脚本精确替换，禁止PowerShell -replace

### 修改后验证
1. ✅ 括号匹配验证（execution_guard自动）
2. ✅ 重复函数检测（code_quality_check.py）
3. ✅ 新增关键词出现次数检查（定义1次+调用N次）
4. ✅ app_v3同步
5. ✅ 冒烟测试
6. ✅ 浏览器实际效果验证（宪法23.4）
7. ✅ change_diff.py对比修改前后，确认无超范围修改

## 三、定期清理计划

| 频率 | 清理内容 | 工具 |
|------|----------|------|
| 每次修改后 | 重复函数、重复代码块、硬编码 | code_quality_check.py |
| 每周 | 全面代码质量检查、未使用代码清理 | code_quality_check.py + 人工审查 |
| 每版本发布前 | 全部检查项（代码+安全+性能+冒烟） | release_check.py |
| 系统稳定后 | 旧代码fallback清理、模块拆分 | 人工+工具 |

## 四、app.js体积优化计划

当前：1480KB，加载时间3秒
- **短期**：删除未使用代码、清理console.log、合并重复逻辑 → 目标1200KB
- **中期**：按模块拆分（题库/闪卡/导图/资料库），按需加载 → 目标首屏<500KB
- **长期**：引入构建工具（webpack/vite），代码压缩+Tree Shaking → 目标<300KB

## 五、执行记录

| 日期 | 清理内容 | 结果 |
|------|----------|------|
| 2026-09-07 | 创建防止混入机制，入宪第三十二章 | ✅ 完成 |
| 2026-09-07 | 创建code_quality_check.py工具 | ✅ 完成 |
| 2026-09-07 | 首次代码质量检查：14通过0失败 | ✅ 通过 |



======================================================================
# 附录13 【来源：规划细则分册\分阶段推进计划_V1.0.md】
======================================================================

# 分阶段推进计划 V1.0

> 原则：核心功能（刷题/闪卡/思维导图）持续保障正常使用，其他优化分阶段推进，不影响复习

---

## 核心功能保障（持续进行，不中断）

| 功能 | 保障措施 | 负责人 |
|------|----------|--------|
| 刷题 | 题库数据不丢失、刷题流程不中断、空白条等布局问题优先修复 | 测试+前端专家 |
| 闪卡 | 闪卡数据不丢失、复习算法正常运行、不重复生成低质量闪卡 | 造价+学习科学专家 |
| 思维导图 | 导图数据不丢失、节导图/章导图/科目导图正常显示、问题版/答案版切换正常 | AI+UI专家 |

**核心功能铁律**：
1. 任何修改不得影响核心功能正常使用
2. 核心功能出bug，优先于所有其他任务
3. 修改核心功能前必须备份，修改后必须验证

---

## 第一阶段：基础设施+布局收尾（1周）

**目标**：把当前布局问题彻底解决，建立基础工具链

| 任务 | 对应建议 | 优先级 | 预计时间 |
|------|----------|--------|----------|
| 题库刷题空白条彻底修复 | 已修复（.content-area padding） | 🔴 P0 | ✅ 已完成 |
| 设计Token系统（颜色/字号/间距/圆角变量化） | U1 | 🔴 P0 | 2天 |
| 核心流程冒烟测试（登录→选题→刷题→解析→错题本） | T1 | 🔴 P0 | 1天 |
| 数据质量巡检工具（重复题/空答案/章节错乱） | M3 | 🔴 P0 | 1天 |
| 一键部署脚本（备份→同步→重启→验证） | O4 | 🟡 P1 | 0.5天 |
| 健康检查端点 | O1 | 🟡 P1 | 0.5天 |

**交付物**：
- 布局V2.0全部页面验证通过
- 3个基础工具可运行
- 核心功能冒烟测试通过

---

## 第二阶段：数据治理（2周）

**目标**：以知识点为核心，打通题库→闪卡→思维导图的数据链路

| 任务 | 对应建议 | 优先级 | 预计时间 |
|------|----------|--------|----------|
| 知识点关联表（question_knowledge/flashcard_knowledge） | D2 | 🔴 P0 | 2天 |
| 闪卡去重（同一知识点合并，不是"空三个""空两个"算两张） | C+S专家 | 🔴 P0 | 1天 |
| 题库去重（相同题干合并，保留真题年份） | 数据分析师 | 🔴 P0 | 1天 |
| FTS5中文分词器（解决中文搜索返回0条） | D1 | 🟡 P1 | 1天 |
| 功能去重分析器（自动检测重复按钮/功能） | M8 | 🟡 P1 | 1天 |
| 数据血缘追踪器（题库→闪卡→知识点→导图关联图谱） | M9 | 🟡 P1 | 2天 |
| 教材版本管理（教材版本→知识点版本对应） | C2 | 🟡 P1 | 2天 |

**交付物**：
- 所有数据挂到知识点，无孤儿数据
- 闪卡数量从933张优化到高质量300-500张
- 中文搜索正常使用
- 数据血缘图谱可查看

---

## 第三阶段：AI赋能（2周）

**目标**：AI真正发挥作用，从"识别工具"升级为"学习助手"

| 任务 | 对应建议 | 优先级 | 预计时间 |
|------|----------|--------|----------|
| RAG本地知识库优先（AI答题先检索本地知识库） | A1 | 🔴 P0 | 2天 |
| AI质量审核闭环（OCR→AI审核→低分人工复核→入库） | A4 | 🔴 P0 | 3天 |
| 知识点实体关系抽取（AI自动构建知识图谱） | A3 | 🟡 P1 | 2天 |
| 多模态公式识别（LaTeX OCR+公式校验） | A2 | 🟡 P1 | 2天 |
| 案例题步骤分机制（分步作答+分步评分） | C1 | 🟡 P1 | 3天 |
| 题目质量评分（区分度算法，标记废题） | S3 | 🟢 P2 | 1天 |

**交付物**：
- AI识别准确率≥90%
- 知识图谱自动构建
- 案例题支持步骤分
- 废题自动标记

---

## 第四阶段：体验优化（持续）

**目标**：系统流畅、美观、易用

| 任务 | 对应建议 | 优先级 | 预计时间 |
|------|----------|--------|----------|
| 交互一致性（相同功能所有页面交互方式一致） | U2 | 🟡 P1 | 2天 |
| 虚拟列表（题库/闪卡长列表性能优化） | F1 | 🟡 P1 | 1天 |
| 模块懒加载（首屏加载时间从3秒→1秒） | F2 | 🟡 P1 | 1天 |
| 全局错误边界（JS错误不白屏） | F3 | 🟡 P1 | 0.5天 |
| 学习路径引擎（教材→知识点→刷题→错题→闪卡→真题→导图） | LS4 | 🟡 P1 | 3天 |
| 知识点掌握度算法（艾宾浩斯+答题置信度） | S1 | 🟢 P2 | 2天 |
| 空状态设计（无数据时显示引导操作） | U3 | 🟢 P2 | 1天 |
| 新手引导（首次打开3步引导） | P3 | 🟢 P2 | 1天 |

**交付物**：
- 首屏加载≤1秒
- 所有页面交互一致
- 学习路径自动规划
- 知识点掌握度实时显示

---

## 第五阶段：安全+运维（按需）

| 任务 | 对应建议 | 优先级 |
|------|----------|--------|
| SQL注入全扫描 | SEC1 | 🟡 P1 |
| XSS防护 | SEC2 | 🟡 P1 |
| 日志分级 | O2 | 🟢 P2 |
| 自动重启 | O3 | 🟢 P2 |
| 代码审查机器人 | M6 | 🟢 P2 |
| 文档自动同步 | - | 🟢 P2 |

---

## 进度跟踪

| 阶段 | 状态 | 完成时间 |
|------|------|----------|
| 核心功能保障 | 🔄 持续进行 | - |
| 第一阶段：基础设施+布局收尾 | ⏳ 待开始 | - |
| 第二阶段：数据治理 | ⏳ 待开始 | - |
| 第三阶段：AI赋能 | ⏳ 待开始 | - |
| 第四阶段：体验优化 | ⏳ 待开始 | - |
| 第五阶段：安全+运维 | ⏳ 待开始 | - |

---

## 风险控制

1. **每个阶段结束必须验证核心功能正常**：刷题、闪卡、思维导图可用
2. **每个任务修改前必须备份**：使用`safe_modify.py`
3. **每个任务修改后必须跑冒烟测试**：核心5步流程通过
4. **出问题立即回滚**：从备份恢复，不影响用户复习
5. **不并行做多个高风险任务**：一次只做一个，验证通过再做下一个

---

*本计划由70名专家联合制定，将根据实际进度动态调整*



======================================================================
# 附录14 【来源：规划细则分册\登录界面整改分册_V1.0.md】
======================================================================

# 登录界面整改分册 V1.0

> **生效日期**：2026-09-07
> **状态**：已完成并锁死
> **适用范围**：登录页面 + 科目选择页面

---

## 一、整改背景

### 1.1 原始问题

登录界面存在以下问题：
1. 布局与效果图不一致（旧版本为简单表单，无渐变背景、无卡片设计）
2. 科目选择界面为旧版弹窗设计，与全屏效果图不符
3. 登录后必须选择大专业才能进入系统，流程不合理
4. 全局科目下拉框与登录选择的科目无关联
5. 专业课命名不规范（显示"一造案例（水利）"而非"一造水利案例"）

### 1.2 整改目标

严格按照《唯一布局标准V2.0_全品类效果图.html》中的登录界面和科目选择界面布局，实现功能连接，不重新设计。

---

## 二、登录页面整改详情

### 2.1 布局规格（已锁死）

| 区域 | 规格 |
|------|------|
| 背景 | 全屏蓝色渐变 linear-gradient(135deg,#3949ab 0%,#5c6bc0 50%,#7986cb 100%) |
| 装饰圆 | 左上角200px、右下角300px半透明白色圆形 |
| 卡片 | 460px宽，白色背景，border-radius:16px，box-shadow:0 24px 64px rgba(0,0,0,0.25) |
| 卡片内边距 | padding:36px 40px 28px |
| 标题 | "水利智学 V4.5.15"，24px，font-weight:700，#3949ab，居中 |
| 副标题 | "一体化题库备考系统"，12px，#999，居中 |
| Tab栏 | 登录/注册，flex布局，border-bottom:2px solid #e0e0e0 |
| Tab选中态 | color:#3949ab，border-bottom:2px solid #3949ab，margin-bottom:-2px |
| 输入框 | 40px高，border:1px solid #e0e0e0，border-radius:6px，padding:0 12px |
| 用户名id | loginUser（必须与doLogin函数匹配） |
| 密码id | loginPass（必须与doLogin函数匹配） |
| 登录按钮 | 40px高，蓝色渐变，白色文字，font-weight:600，border-radius:6px |
| 默认提示 | "默认账号：admin / admin123"，12px，#999，居中 |
| 底部分割 | border-top:1px solid #e0e0e0，padding-top:12px |
| 网络模式 | 在线/离线单选（name=netMode），flex:1，在线默认选中，绿色边框 |
| 登录方案 | 手动/自动单选（name=loginMode），flex:1，手动默认选中，蓝色边框 |

### 2.2 函数清单

| 函数名 | 位置 | 功能 |
|--------|------|------|
| renderLogin() | app.js | 渲染登录页面 |
| switchLoginTab(tab) | app.js | 切换登录/注册Tab |
| doLogin() | app.js | 执行登录，成功后调用showFullSubjectSelectModal() |
| doRegister() | app.js | 执行注册 |

### 2.3 关键修复记录

| 问题 | 原因 | 修复 |
|------|------|------|
| 点击登录无反应 | 输入框id为loginUsername/loginPassword，doLogin用loginUser/loginPass | 修改id为loginUser/loginPass |
| 登录被阻止 | doLogin要求_tempSelectedMajors.length>0，但新登录页无大专业选择 | 移除该校验 |
| 登录后无科目选择 | showFullSubjectSelectModal被旧版本覆盖 | 删除旧版本，恢复全屏版本 |

---

## 三、科目选择页面整改详情

### 3.1 布局规格（已锁死）

| 区域 | 规格 |
|------|------|
| 容器 | id=subjectSelectModal，position:fixed，全屏，z-index:9999，display:flex |
| 背景 | 同登录页蓝色渐变 |
| 欢迎语 | "欢迎回来，管理员 👋"，32px，白色，font-weight:700 |
| 副标题 | "请选择要学习的科目"，15px，rgba(255,255,255,0.8) |
| 下拉容器 | flex布局，gap:16px，居中 |
| 大专业下拉 | id=majorDropdownBtn，240px宽，40px高，半透明白色背景 |
| 大专业下拉列表 | id=majorDropdownList，position:absolute，白色背景，z-index:9999 |
| 专业方向下拉 | id=subjectDropdownBtn，240px宽，40px高，半透明白色背景 |
| 专业方向下拉列表 | id=subjectDropdownList，position:absolute，白色背景，z-index:9999 |
| 科目卡片容器 | id=subjectSelectCards，grid 4列，gap:20px，max-width:1000px |
| 科目卡片 | 220px宽，170px高，白色背景，border-radius:14px，flex居中 |
| 卡片选中态 | border:3px solid #ff9800，右上角"✓ 已选"徽章 |
| 卡片禁用态 | 显示"请先选方向"，灰色 |
| 底部按钮 | "切换账号"（半透明）+ "进入系统 →"（橙色渐变 #ff9800→#ffb74d） |

### 3.2 大专业配置（5个）

| 大专业 | id | 科目数 | 公共课 | 专业课 |
|--------|-----|--------|--------|--------|
| 一级造价工程师 | 一造 | 4 | 管理、计价 | 计量、案例 |
| 二级造价工程师 | 二造 | 2 | 基础 | 实务 |
| 一级建造师 | 一建 | 4 | 经济、法规、管理 | 实务 |
| 二级建造师 | 二建 | 3 | 管理、法规 | 实务 |
| 监理工程师 | 监理 | 4 | 合同、目标、理论 | 案例 |

### 3.3 专业方向配置（4个）

| 方向 | 简称 | 适用大专业 |
|------|------|-----------|
| 水利工程 | 水利 | 一造、二造、一建、二建、监理 |
| 交通工程 | 交通 | 一造、二造、一建、二建 |
| 土木工程 | 土建 | 一造、二造、一建、二建 |
| 安装工程 | 安装 | 一造、二造、一建、二建 |

### 3.4 命名规则（造价专家确认）

**公共课不带专业方向，专业课带专业方向**：
- 一造管理（公共课）→ 一造管理
- 一造计价（公共课）→ 一造计价
- 一造计量（专业课）→ 一造水利计量
- 一造案例（专业课）→ 一造水利案例

命名公式：`大专业简称 + 方向简称 + 科目后缀`
- 一造 + 水利 + 案例 = 一造水利案例

### 3.5 三级选择限制

1. **第一步**：必须选择大专业，否则不能打开专业方向下拉（提示"请先选择大专业"）
2. **第二步**：必须选择专业方向，否则科目卡片为禁用态（显示"请先选方向"）
3. **第三步**：必须选择至少一个科目，否则不能进入系统（提示"请至少选择一个学习科目"）

### 3.6 函数清单

| 函数名 | 功能 |
|--------|------|
| showFullSubjectSelectModal() | 显示科目选择弹窗，重置所有选择 |
| toggleMajorDropdown() | 切换大专业下拉列表显示 |
| toggleSubjectDropdown() | 切换专业方向下拉列表显示（未选大专业时提示） |
| selectMajor(majorName) | 选择大专业，更新按钮文字，重置方向和科目 |
| selectSubjectDirection(name) | 选择专业方向，更新按钮文字，激活科目卡片 |
| clickSubjectCard(num) | 点击科目卡片，切换选中状态（未选方向时提示） |
| updateSubjectCards(majorName, direction) | 更新科目卡片显示 |
| updateStepIndicator() | 更新步骤指示器 |
| enterSystemWithSubject() | 进入系统，设置Store属性，过滤全局科目 |
| getSubjectsByMajorAndDirection(majorName, direction) | 获取大专业+方向下的科目列表 |

### 3.7 关键修复记录

| 问题 | 原因 | 修复 |
|------|------|------|
| 下拉菜单点击无反应 | 函数用id=subjectMajorDropdown，HTML用id=majorDropdownList | 统一为majorDropdownList/subjectDropdownList |
| 按钮文字不更新 | 函数用id=subjectMajorBtn，HTML用id=majorDropdownBtn | 统一为majorDropdownBtn/subjectDropdownBtn |
| index.html有两套代码 | 旧版本未删除，覆盖新版本 | 删除第468-504行旧版本代码 |
| 进入系统后弹窗不消失 | enterSystemWithSubject缺少隐藏弹窗和render() | 添加modal.style.display='none'和render() |
| 全局科目下拉框为空 | exam_config.json不存在，loadSubjects走else分支用全称id | 创建backend/data/exam_config.json |
| Store属性未设置 | enterSystemWithSubject未设置currentMajor/currentDirectionName | 添加设置代码 |
| 专业课命名错误 | 显示"一造案例（水利）" | 修改为"一造水利案例"格式 |

---

## 四、全局关联机制

### 4.1 关联流程

```
用户选择科目 → enterSystemWithSubject()
    ↓
设置 Store.selectedSubjects = [简称数组]
设置 Store.currentMajor = 大专业id（如"一造"）
设置 Store.currentDirectionName = 方向名（如"水利工程"）
    ↓
selectGlobalSubject(第一个科目)
    ↓
render() → loadExamConfig() → loadSubjects()
    ↓
loadSubjects()根据Store.currentMajor和Store.selectedSubjects过滤SUBJECTS
    ↓
全局科目下拉框只显示选择的科目
```

### 4.2 数据文件

**文件路径**：`backend/data/exam_config.json`

**结构**：
```json
{
  "majors": [
    {
      "id": "一造",
      "name": "一级造价工程师",
      "shortName": "一造",
      "icon": "📐",
      "subjects": [
        {"id": "建设工程造价管理", "name": "...", "shortName": "一造管理", "icon": "📊"},
        {"id": "建设工程技术与计量", "name": "...", "shortName": "一造计量", "icon": "📐", "directions": ["水利工程", ...]}
      ]
    }
  ]
}
```

**注意**：
- 公共课无directions字段
- 专业课有directions字段（数组）
- id为全称，shortName为简称
- loadSubjects()用shortName与Store.selectedSubjects匹配

---

## 五、验证清单

### 5.1 登录页面验证

- [x] 页面加载显示登录界面（白色卡片+蓝色渐变背景）
- [x] 标题显示"水利智学 V4.5.15"
- [x] 用户名默认admin，密码默认admin123
- [x] 登录/注册Tab可切换
- [x] 网络模式在线/离线单选可切换
- [x] 登录方案手动/自动单选可切换
- [x] 点击登录按钮进入科目选择界面

### 5.2 科目选择页面验证

- [x] 登录成功后显示全屏科目选择界面
- [x] 欢迎语显示"欢迎回来，管理员 👋"
- [x] 大专业下拉显示5个选项
- [x] 未选大专业时，专业方向下拉提示"请先选大专业"
- [x] 选择大专业后，按钮文字更新为"大专业：一级造价工程师"
- [x] 专业方向下拉显示4个选项
- [x] 选择方向后，按钮文字更新为"专业方向：水利工程"
- [x] 未选方向时，科目卡片显示"请先选方向"（禁用）
- [x] 选择方向后，科目卡片激活
- [x] 公共课显示"一造管理"（不带方向）
- [x] 专业课显示"一造水利案例"（带方向）
- [x] 科目卡片可多选（显示"✓ 已选"）
- [x] 未选科目时点击进入系统提示"请至少选择一个学习科目"
- [x] 选择科目后点击进入系统，弹窗消失，进入系统

### 5.3 全局关联验证

- [x] 进入系统后，全局科目下拉框显示选择的第一个科目
- [x] 全局科目下拉框只显示选择的科目（不显示未选择的科目）
- [x] 切换全局科目后，页面内容相应变化

---

## 六、文件清单

| 文件 | 修改内容 |
|------|----------|
| frontend/js/app.js | renderLogin重写、showFullSubjectSelectModal及相关函数、enterSystemWithSubject修复 |
| frontend/index.html | subjectSelectModal改为全屏设计，删除旧版本重复代码 |
| backend/data/exam_config.json | 新建，大专业/科目/方向配置 |
| 系统设计宪法.md | 新增第二十二章：登录界面锁死规则 |

---

## 七、锁死声明

**本登录界面和科目选择界面已全部锁死，不再修改。**

任何后续修改必须经用户明确授权，违反者按宪法第二十二章处理。

> **分册版本**：V1.0
> **完成日期**：2026-09-07
> **验证状态**：全部通过
> **锁死状态**：已锁死



---

# 🖥️ 附录B区：服务器配置与启动脚本（py/bat，2026-09-13）
> 文件管理器管控资产清单。以下为入口与配置文件全文，按序号排列。




======================================================================
# 附录15 【来源：start.bat】
======================================================================

@echo off
chcp 65001 >nul 2>&1
title ShuiLi ZhiXue System V4.0

REM ============================================
REM 优先启动Ollama AI服务（确保AI功能可用）
REM ============================================
echo [0/4] Starting Ollama AI service...
set "BASE_DIR=%~dp0"
tasklist /FI "IMAGENAME eq ollama.exe" 2>nul | findstr /i "ollama.exe" >nul
if not errorlevel 1 goto ollama_running
if not exist "%BASE_DIR%backend\ollama\ollama.exe" goto ollama_notfound
set OLLAMA_IGPU_ENABLE=1
set OLLAMA_MODELS=%BASE_DIR%backend\ollama_models
set OLLAMA_HOST=0.0.0.0:11434
set OLLAMA_HF_MIRROR=https://modelscope.cn
start "" /min "%BASE_DIR%backend\ollama\ollama.exe" serve
echo   Ollama launched (hidden window).
goto ollama_done
:ollama_running
echo   Ollama already running, skipped.
goto ollama_done
:ollama_notfound
echo   [INFO] Ollama not found, skipped.
:ollama_done
echo.


REM ============================================
REM 快速检查：如果后端已运行，直接打开浏览器
REM ============================================
netstat -ano | findstr ":8000" | findstr "LISTENING" >nul
if not errorlevel 1 (
    echo [INFO] Backend already running on port 8000.
    echo Opening browser...
    start "" http://localhost:8000
    echo.
    echo System is running. Close this window anytime.
    pause
    exit /b 0
)

REM ============================================
REM 动态查找Python 3.11（优先项目内，其次D:\Python311，最后系统PATH）
REM 系统默认python是3.13，有内存泄漏会导致后端频繁崩溃
REM ============================================
set PYTHON=
set PYTHONW=
REM 优先使用项目内便携Python
if exist "%~dp0python\python.exe" (
    set PYTHON=%~dp0python\python.exe
    set PYTHONW=%~dp0python\pythonw.exe
    goto :python_found
)
REM 其次使用D:\Python311
if exist "D:\Python311\python.exe" (
    set PYTHON=D:\Python311\python.exe
    set PYTHONW=D:\Python311\pythonw.exe
    goto :python_found
)
REM 最后查找系统PATH中的python
for /f "delims=" %%i in ('where python 2^>nul') do (
    set PYTHON=%%i
    goto :check_python_version
)
:check_python_version
if not defined PYTHON (
    echo [ERROR] Python not found. Please install Python 3.11.x.
    pause
    exit /b 1
)
REM 校验Python版本是否为3.11
for /f "tokens=2 delims= " %%v in ('"%PYTHON%" --version 2^>^&1') do set PYVER=%%v
echo %PYVER% | findstr /b "3.11" >nul
if errorlevel 1 (
    echo [WARNING] Python %PYVER% detected, recommend 3.11.x for stability.
)
REM 查找pythonw.exe
for /f "delims=" %%i in ('where pythonw 2^>nul') do (
    set PYTHONW=%%i
    goto :python_found
)
if not defined PYTHONW set PYTHONW=%PYTHON:python.exe=pythonw.exe%
:python_found

echo ========================================
echo   ShuiLi ZhiXue Quiz System V4.0
echo   Python: %PYTHON%
echo ========================================
echo.

cd /d "%~dp0"

REM Check Python
"%PYTHON%" --version >nul 2>&1
if errorlevel 1 (
    echo [ERROR] Python 3.11 not found at %PYTHON%
    echo Please install Python 3.11.x and add it to system PATH.
    pause
    exit /b 1
)

REM Install dependencies (show progress, not silent)
echo [1/4] Checking and installing dependencies...
"%PYTHON%" -m pip install -r requirements.txt
if errorlevel 1 (
    echo [ERROR] Failed to install dependencies. Please check your network.
    pause
    exit /b 1
)

REM Initialize database
echo.
echo [2/4] Initializing database...
cd backend
"%PYTHON%" scripts/init_db.py
if errorlevel 1 (
    echo [ERROR] Database initialization failed.
    pause
    exit /b 1
)
cd ..

REM Start service
echo.
echo [3/4] Starting service...
echo.

REM Detect LAN IP
for /f "tokens=2 delims=:" %%a in ('ipconfig ^| findstr /i "IPv4"') do (
    set LAN_IP=%%a
    goto :found_ip
)
:found_ip
set LAN_IP=%LAN_IP: =%

echo ========================================
echo   Service started!
echo   Local:    http://localhost:8000
if defined LAN_IP echo   LAN:      http://%LAN_IP%:8000  (手机/平板同一WiFi访问)
echo   Default account: admin / admin123
echo ========================================
echo.

REM 待办事项自动提醒（防止遗忘迁移计划）
echo [待办提醒] 检查系统待办事项...
"%PYTHON%" "%~dp0todo_reminder.py"
echo.

REM Start VS Code file watcher (debug port 5678) - only if not already running, hidden window
echo [3.5/4] Starting VS Code file watcher (debug port 5678)...
tasklist /FI "IMAGENAME eq pythonw.exe" /V 2>nul | findstr /i "watch.py" >nul
if errorlevel 1 (
    if exist "%~dp0watch\watch.py" (
        start "" /min "%PYTHONW%" "%~dp0watch\watch.py"
        echo   Watcher launched (hidden window).
    ) else (
        echo   [INFO] watch.py not found, skipped.
    )
) else (
    echo   Watcher already running, skipped.
)
echo.

REM Start auto backup script (every 1 hour) - only if not already running, hidden window
echo [3.6/4] Starting auto backup script (every 1 hour)...
tasklist /FI "IMAGENAME eq pythonw.exe" /V 2>nul | findstr /i "auto_backup.py" >nul
if errorlevel 1 (
    if exist "%~dp0auto_backup.py" (
        start "" /min "%PYTHONW%" "%~dp0auto_backup.py"
        echo   Auto backup launched (hidden window, every 1 hour).
    ) else (
        echo   [INFO] auto_backup.py not found, skipped.
    )
) else (
    echo   Auto backup already running, skipped.
)
echo.

REM Open VS Code (if installed)
echo Opening VS Code...
where code >nul 2>&1
if errorlevel 1 (
    echo   [INFO] VS Code not found in PATH, skipped.
) else (
    start "" code .
)

REM Start backend first via WMI (non-blocking, survives window close)
echo Starting backend via WMI...
powershell -Command "Invoke-WmiMethod -Class Win32_Process -Name Create -ArgumentList '\"%PYTHON%\" \"%~dp0backend\main.py\"', '%~dp0backend' | Out-Null"
echo   Backend launched.
timeout /t 3 /nobreak >nul

REM Auto open browser (after backend is ready)
echo Opening browser...
start "" http://localhost:8000

echo.
echo ========================================
echo   All launched! Watchdog running below.
echo   Watchdog monitors: process alive + memory ^<600MB + port 8000
echo   Backend launched via WMI (survives window close)
echo   Close this window to stop watchdog only.
echo ========================================
echo.

cd backend
echo [4/4] Starting watchdog (auto-recovery on crash/memory leak)...
echo.
REM Check if watchdog already running
tasklist /FI "IMAGENAME eq python.exe" /V 2>nul | findstr /i "watchdog" >nul
if errorlevel 1 (
    "%PYTHON%" watchdog.py
) else (
    echo   Watchdog already running, skipped.
    echo.
    echo   System is running. Close this window anytime.
    pause
)
echo.
echo [%date% %time%] Watchdog exited. Backend may still be running via WMI.
echo To stop backend: taskkill /F /IM python.exe
pause



======================================================================
# 附录16 【来源：start_backend.bat】
======================================================================

@echo off
chcp 65001 >nul
title 水利智学系统 - 后端启动器

echo ========================================
echo   水利智学系统 - 后端启动器
echo ========================================
echo.

:: 查找并杀掉占用8000端口的旧进程
echo [1/3] 检查端口8000占用...
for /f "tokens=5" %%a in ('netstat -ano ^| findstr ":8000" ^| findstr "LISTENING"') do (
    echo   发现旧进程 PID: %%a
    taskkill /F /PID %%a >nul 2>&1
    if %errorlevel% equ 0 (
        echo   已杀掉旧进程
    ) else (
        echo   [警告] 权限不够，无法杀掉旧进程，请手动在任务管理器结束python.exe
    )
)

echo.
echo [2/3] 进入backend目录...
cd /d "F:\水利智学系统\可运行版（解压即用，双击start.bat）\backend"

echo.
echo [3/3] 启动后端服务...
echo ========================================
echo.

D:\Python311\python.exe main.py

pause



======================================================================
# 附录17 【来源：start_simple.bat】
======================================================================

@echo off
chcp 65001 >nul
title 水利智学系统 - 直接启动
cd /d "%~dp0backend"
python main.py
pause



======================================================================
# 附录18 【来源：一键启动.bat】
======================================================================

@echo off
chcp 65001 >nul
title 水利智学系统一键启动

echo ======================================
echo   水利智学系统 - 一键启动
echo ======================================
echo.

set "PROJECT_ROOT=F:\水利智学系统\可运行版（解压即用，双击start.bat）"
cd /d "%PROJECT_ROOT%"

echo [1/4] 检查后端服务 (端口8000)...
netstat -ano | findstr ":8000 " | findstr "LISTENING" >nul
if %errorlevel% equ 0 (
    echo   ✅ 后端已在运行
) else (
    echo   🚀 启动后端服务...
    start "后端服务" cmd /k "cd /d %PROJECT_ROOT%\backend && D:\Python311\python.exe main.py"
    echo   等待后端启动...
    timeout /t 8 /nobreak >nul
)

echo.
echo [2/4] 检查Ollama服务 (端口11434)...
netstat -ano | findstr ":11434 " | findstr "LISTENING" >nul
if %errorlevel% equ 0 (
    echo   ✅ Ollama已在运行
) else (
    echo   🚀 启动Ollama...
    start "Ollama服务" cmd /k "cd /d C:\Users\37704\AppData\Local\Programs\Ollama && set OLLAMA_MODELS=D:\AI\ollama_models && set OLLAMA_HOST=0.0.0.0:11434 && ollama.exe serve"
    timeout /t 5 /nobreak >nul
)

echo.
echo [3/4] 启动本地AI分析（后台运行）...
tasklist | findstr /i "python.exe" | findstr "analyzer" >nul
if %errorlevel% equ 0 (
    echo   ✅ 本地AI分析已在运行
) else (
    if exist "%PROJECT_ROOT%\run_analyzer_guardian.bat" (
        start /min "本地AI分析" "%PROJECT_ROOT%\run_analyzer_guardian.bat"
        echo   ✅ 本地AI分析已在后台启动
    ) else (
        echo   ⚠️ 未找到本地AI分析脚本
    )
)

echo.
echo [4/4] 验证服务状态...
timeout /t 2 /nobreak >nul
netstat -ano | findstr ":8000 " | findstr "LISTENING" >nul
if %errorlevel% equ 0 (
    echo   ✅ 后端就绪
) else (
    echo   ⚠️ 后端还在启动中，稍等几秒
)
netstat -ano | findstr ":11434 " | findstr "LISTENING" >nul
if %errorlevel% equ 0 (
    echo   ✅ Ollama就绪
) else (
    echo   ⚠️ Ollama还在启动中
)

echo.
echo ======================================
echo   启动完成！
echo   访问地址: http://localhost:8000
echo ======================================
echo.
timeout /t 5 /nobreak >nul



======================================================================
# 附录19 【来源：build_exe.bat】
======================================================================

@echo off
chcp 65001 >nul 2>&1
title ShuiLi ZhiXue - EXE Builder

echo ========================================
echo   ShuiLi ZhiXue System - EXE Builder
echo ========================================
echo.

cd /d "%~dp0"

REM Check Python
python --version >nul 2>&1
if errorlevel 1 (
    echo [ERROR] Python not found. Please install Python 3.9+ first.
    echo Download: https://www.python.org/downloads/
    pause
    exit /b 1
)

REM Install project dependencies first
echo [0/3] Installing project dependencies...
python -m pip install -r requirements.txt
if errorlevel 1 (
    echo [ERROR] Failed to install project dependencies.
    pause
    exit /b 1
)

REM Check and install PyInstaller
python -m pip show pyinstaller >nul 2>&1
if errorlevel 1 (
    echo [1/3] Installing PyInstaller...
    python -m pip install pyinstaller
    if errorlevel 1 (
        echo [ERROR] Failed to install PyInstaller.
        pause
        exit /b 1
    )
) else (
    echo [1/3] PyInstaller already installed.
)

REM Clean old build files
echo.
echo [2/3] Cleaning old build files...
if exist build rmdir /s /q build
if exist dist rmdir /s /q dist
if exist "shuili_zhixue.spec" del /q "shuili_zhixue.spec"

REM Build EXE
echo.
echo [3/3] Building EXE (this may take 2-5 minutes)...
echo.

python -m PyInstaller --onefile --name "shuili_zhixue" --noconsole ^
  --add-data "backend;backend" ^
  --add-data "frontend;frontend" ^
  --hidden-import uvicorn.logging ^
  --hidden-import uvicorn.loops ^
  --hidden-import uvicorn.loops.auto ^
  --hidden-import uvicorn.protocols ^
  --hidden-import uvicorn.protocols.http ^
  --hidden-import uvicorn.protocols.http.auto ^
  --hidden-import uvicorn.lifespan ^
  --hidden-import uvicorn.lifespan.on ^
  --collect-all fastapi ^
  --collect-all sqlalchemy ^
  --collect-all bcrypt ^
  launcher.py

if errorlevel 1 (
    echo.
    echo [ERROR] Build failed!
    pause
    exit /b 1
)

echo.
echo ========================================
echo   Build SUCCESS!
echo   Output: dist\shuili_zhixue.exe
echo ========================================
echo.
echo Note: The exe will create data/, uploads/, backups/, logs/ folders
echo       in the same directory when first run.
echo       Default account: admin / admin123
echo.
pause



======================================================================
# 附录20 【来源：rollback_to_stable.bat】
======================================================================

@echo off
chcp 65001 >nul
title 一键回滚到稳定快照

echo ========================================
echo   水利智学系统 - 一键回滚工具
echo ========================================
echo.

set BACKUP_DIR=backups\stable_snapshot_20260831_全局优化前
set TARGET_DIR=%~dp0

if not exist "%BACKUP_DIR%" (
    echo [错误] 稳定快照不存在: %BACKUP_DIR%
    echo 请检查backups目录下是否有稳定快照
    pause
    exit /b 1
)

echo [信息] 稳定快照位置: %BACKUP_DIR%
echo [信息] 当前目录: %TARGET_DIR%
echo.
echo [警告] 回滚将覆盖当前代码和数据库！
echo.
set /p CONFIRM=确认回滚？(输入Y继续): 
if /i not "%CONFIRM%"=="Y" (
    echo 已取消回滚
    pause
    exit /b 0
)

echo.
echo [1/4] 停止服务...
taskkill /f /im python.exe >nul 2>&1
timeout /t 2 /nobreak >nul

echo [2/4] 备份当前版本...
set SAFETY_DIR=backups\rollback_safety_%date:~0,4%%date:~5,2%%date:~8,2%_%time:~0,2%%time:~3,2%
mkdir "%SAFETY_DIR%" >nul 2>&1
xcopy "backend" "%SAFETY_DIR%\backend\" /E /I /Y >nul 2>&1
xcopy "frontend" "%SAFETY_DIR%\frontend\" /E /I /Y >nul 2>&1
echo  当前版本已备份到: %SAFETY_DIR%

echo [3/4] 恢复稳定快照...
xcopy "%BACKUP_DIR%\backend" "%TARGET_DIR%backend\" /E /I /Y >nul
xcopy "%BACKUP_DIR%\frontend" "%TARGET_DIR%frontend\" /E /I /Y >nul
if exist "%BACKUP_DIR%\config.ini" copy "%BACKUP_DIR%\config.ini" "%TARGET_DIR%config.ini" /Y >nul

echo [4/4] 验证恢复...
if exist "backend\main.py" (
    echo  [OK] 后端代码恢复成功
) else (
    echo  [FAIL] 后端代码恢复失败
)
if exist "frontend\index.html" (
    echo  [OK] 前端代码恢复成功
) else (
    echo  [FAIL] 前端代码恢复失败
)

echo.
echo ========================================
echo   回滚完成！
echo ========================================
echo.
echo 安全网备份位置: %SAFETY_DIR%
echo 如需恢复回滚前的版本，请使用上述安全网备份
echo.
pause



======================================================================
# 附录21 【来源：run_tests.bat】
======================================================================

@echo off
chcp 65001 >nul
echo ========================================
echo   水利智学系统 - 自动化测试
echo ========================================
echo.

cd /d "%~dp0backend"

echo [1/3] 检查后端服务...
curl -s -o nul -w "后端状态: %%{http_code}\n" http://localhost:8000/api/health
if errorlevel 1 (
    echo [警告] 后端服务未启动，将只运行单元测试
    echo.
)

echo.
echo [2/3] 运行API测试...
D:\Python311\python.exe -m pytest tests/test_api.py -v --tb=short --timeout=30 2>&1

echo.
echo [3/3] 生成测试报告...
D:\Python311\python.exe -m pytest tests/test_api.py --tb=short --junitxml=test_report.xml 2>&1

echo.
echo ========================================
echo   测试完成！报告已保存至 test_report.xml
echo ========================================
pause



======================================================================
# 附录22 【来源：备份.bat】
======================================================================

@echo off
chcp 65001 >nul
title 水利智学系统 - 版本回溯工具

:menu
cls
echo ========================================
echo    水利智学系统 - 版本回溯工具
echo ========================================
echo.
echo   1. 快速备份当前版本
echo   2. 列出所有备份版本
echo   3. 创建命名还原点
echo   4. 列出所有还原点
echo   5. 恢复到指定备份
echo   6. 恢复到指定还原点
echo   7. 对比两个版本差异
echo   8. 清理旧备份（保留30天）
echo   0. 退出
echo.
set /p choice=请选择操作 (0-8): 

if "%choice%"=="1" goto backup
if "%choice%"=="2" goto list
if "%choice%"=="3" goto point
if "%choice%"=="4" goto points
if "%choice%"=="5" goto restore
if "%choice%"=="6" goto restore_point
if "%choice%"=="7" goto compare
if "%choice%"=="8" goto cleanup
if "%choice%"=="0" goto end
echo 无效选择，请重试
pause
goto menu

:backup
cls
echo ========================================
echo    快速备份当前版本
echo ========================================
echo.
set /p desc=请输入备份描述（如：修改视频布局前）: 
python version_control.py backup "%desc%" "用户手动备份"
echo.
pause
goto menu

:list
cls
echo ========================================
echo    备份版本列表
echo ========================================
echo.
python version_control.py list 30
echo.
pause
goto menu

:point
cls
echo ========================================
echo    创建命名还原点
echo ========================================
echo.
set /p name=请输入还原点名称（如：2026-8-21稳定版）: 
set /p desc=请输入还原点描述（可选）: 
python version_control.py point "%name%" "%desc%"
echo.
pause
goto menu

:points
cls
echo ========================================
echo    还原点列表
echo ========================================
echo.
python version_control.py points
echo.
pause
goto menu

:restore
cls
echo ========================================
echo    恢复到指定备份
echo ========================================
echo.
echo 最近的备份版本：
python version_control.py list 10
echo.
set /p filename=请输入要恢复的备份文件名（如 index_20260821_153500.html）: 
python version_control.py restore "%filename%"
echo.
echo 请按 Ctrl+F5 强制刷新浏览器查看效果
pause
goto menu

:restore_point
cls
echo ========================================
echo    恢复到指定还原点
echo ========================================
echo.
echo 所有还原点：
python version_control.py points
echo.
set /p name=请输入要恢复的还原点名称（支持模糊匹配）: 
python version_control.py restore-point "%name%"
echo.
echo 请按 Ctrl+F5 强制刷新浏览器查看效果
pause
goto menu

:compare
cls
echo ========================================
echo    对比两个版本差异
echo ========================================
echo.
echo 备份文件都在 _version_backups 目录下
echo.
set /p file1=请输入第一个文件路径: 
set /p file2=请输入第二个文件路径: 
python version_control.py compare "%file1%" "%file2%"
echo.
pause
goto menu

:cleanup
cls
echo ========================================
echo    清理旧备份
echo ========================================
echo.
python -c "from auto_backup_hook import cleanup_old_backups; cleanup_old_backups()"
echo.
pause
goto menu

:end
echo.
echo 感谢使用！
timeout /t 2 >nul



======================================================================
# 附录23 【来源：run_analyzer_guardian.bat】
======================================================================

@echo off
chcp 65001 >nul
title 代码分析器守护进程

echo ============================================================
echo 🛡️ 代码分析器守护进程
echo ============================================================
echo.
echo 守护规则：
echo   - 主脚本断了，3秒后自动重启
echo   - 断点续跑，不用从头开始
echo   - Ctrl+C 停止守护
echo.
echo ============================================================
echo.

:loop
echo [%date% %time%] 启动分析器...
D:\Python311\python.exe system_brain_analyzer_v2.py

echo.
echo [%date% %time%] 主脚本退出，3秒后重启...
echo （按 Ctrl+C 停止）
timeout /t 3 /nobreak >nul
goto loop



======================================================================
# 附录24 【来源：run_analyzer_silent.ps1】
======================================================================

# Silent analyzer guardian - PowerShell version
# Runs completely in background, no windows pop up

$workingDir = "F:\水利智学系统\可运行版（解压即用，双击start.bat）"
$pywExe = "D:\Python311\pythonw.exe"
$script = "system_brain_analyzer_v2.py"

Set-Location $workingDir

while ($true) {
    $proc = Start-Process -FilePath $pywExe -ArgumentList $script -WorkingDirectory $workingDir -PassThru -WindowStyle Hidden
    $proc.WaitForExit()
    Start-Sleep -Seconds 3
}



======================================================================
# 附录25 【来源：run_analyzer_silent.vbs】
======================================================================

' 代码分析器静默守护进程
' 完全后台运行，不弹出任何CMD窗口

Set WshShell = CreateObject("WScript.Shell")
strWorkingDir = "F:\水利智学系统\可运行版（解压即用，双击start.bat）"
strPythonW = "D:\Python311\pythonw.exe"
strScript = "system_brain_analyzer_v2.py"

' 切换到工作目录
WshShell.CurrentDirectory = strWorkingDir

' 构建命令行
strCmd = strPythonW & " " & strScript

' 循环守护
Do While True
    ' 静默启动Python分析器（无窗口，0=隐藏）
    WshShell.Run strCmd, 0, True
    
    ' 主脚本退出，等待3秒后重启
    WScript.Sleep 3000
Loop



======================================================================
# 附录26 【来源：backend\main.py】
======================================================================

import os
import sys
import logging
from logging.handlers import RotatingFileHandler
from pathlib import Path
from fastapi import FastAPI, Request, UploadFile, File
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.staticfiles import StaticFiles
from fastapi.responses import FileResponse, JSONResponse, Response
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException
from core.config import get_base_dir, get_resource_dir, BASE_DIR, DATA_DIR, UPLOAD_DIR, CORS_ORIGINS, ENABLE_FILE_HASH_HEADER
from core.db import engine, Base
from api.v1 import auth, question, question_file, exam, ai_unified, ai_scan, flashcard, note, video, sync_unified, system, analytics, material, mindmap, sprint, syllabus, lecture, music, tts, backup, subject_switch, knowledge_graph, exam_analysis, formula_trainer, monitor, deduplication, combined_analysis, data_check, rag_knowledge, preprocess_config, relation, wrong_analysis, ai_brain
from utils.audit_logger import setup_sqlalchemy_audit_listener, audit_log

# 公共工具层导入
from modules.common.response import register_exception_handlers
from modules.common.data_routes import router as data_security_router
from modules.common.monitor_routes import router as monitor_router
from modules.common.shutdown_routes import router as shutdown_router
from modules.common.file_library_model import FileLibrary  # 学习资料库模型（确保表创建）
from modules.common.file_library_routes import router as file_library_router  # 学习资料库路由
from modules.common.fl_bridge_routes import router as fl_bridge_router  # 文件库衔接路由

# 先定义logger（新模块导入异常处理需要）
logger = logging.getLogger("shuili_exam")

# ========== 新架构模块（增量搬迁，新旧共存）==========
# 模块划分：qb(题库) mt(记忆) mm(思维导图) ai(AI能力) sync(同步) resource(资源) common(公共)
# 规则：A模块禁止import B模块service，模块间通过API或事件通信
try:
    from modules.qb.routes import router as qb_router
    from modules.qb.quality_routes import router as qb_quality_router
    from modules.mt.routes import router as mt_router
    from modules.mt.category_routes import router as mt_category_router
    from modules.mm.routes import router as mm_router
    from modules.ai.routes import router as ai_module_router
    from modules.ai.manager_routes import router as ai_manager_router
    from modules.ai.evaluation_routes import router as ai_evaluation_router
    from modules.ai.stream_routes import router as ai_stream_router
    from modules.sync.routes import router as sync_module_router
    from modules.resource.routes import router as resource_router
    from modules.common.routes import router as common_router
    MODULES_AVAILABLE = True
except ImportError as e:
    MODULES_AVAILABLE = False
    logger.info(f"[架构] 新模块加载失败（不影响旧功能）: {str(e)}")
# ========== 日志配置 ==========
LOG_DIR = os.path.join(DATA_DIR, "logs")
os.makedirs(LOG_DIR, exist_ok=True)
_log_handlers = [RotatingFileHandler(os.path.join(LOG_DIR, "app.log"), maxBytes=10*1024*1024, backupCount=7, encoding="utf-8")]
# 安全检查：sys.stdout为None时（如后台运行）不添加StreamHandler，避免isatty错误
if sys.stdout is not None:
    try:
        _log_handlers.append(logging.StreamHandler(sys.stdout))
    except Exception as e:
        logging.error(f'异常: {e}', exc_info=True)
        pass

# P5-03 日志过期自动清理：后台线程每天清理30天前的旧日志
def _cleanup_old_logs():
    import time as _time
    while True:
        try:
            cutoff = _time.time() - 30 * 86400  # 30天
            cleaned = 0
            for fname in os.listdir(LOG_DIR):
                fpath = os.path.join(LOG_DIR, fname)
                if os.path.isfile(fpath) and os.path.getmtime(fpath) < cutoff:
                    try:
                        os.remove(fpath)
                        cleaned += 1
                    except Exception:
                        pass
            if cleaned > 0:
                logging.info(f'[P5-03] 清理过期日志: {cleaned}个文件')
        except Exception:
            pass
        _time.sleep(86400)  # 每天检查一次

import threading as _threading
_log_cleanup_thread = _threading.Thread(target=_cleanup_old_logs, daemon=True, name='log-cleanup')
_log_cleanup_thread.start()
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    handlers=_log_handlers,
    force=True  # 强制覆盖已有配置，避免与uvicorn冲突
)
logger = logging.getLogger("shuili_exam")

# 服务监控已迁移至 modules/common/service_monitor.py，在下方启动

app = FastAPI(title="水利智学一体化题库系统 V4.5.15", version="4.5.15")

# P4-02 全局中间件：过滤客户端提交的系统字段，防止篡改
_SYSTEM_FIELDS = {'id', 'create_time', 'update_time', 'content_hash', 'is_deleted', 'user_id', 'created_at', 'updated_at'}

@app.middleware("http")
async def filter_system_fields(request: Request, call_next):
    """过滤POST/PUT/PATCH请求体中的系统字段"""
    if request.method in ('POST', 'PUT', 'PATCH') and request.url.path not in ('/api/auth/login', '/api/auth/register'):
        try:
            body = await request.body()
            if body:
                import json as _json
                data = _json.loads(body.decode('utf-8'))
                if isinstance(data, dict):
                    removed = [k for k in data if k in _SYSTEM_FIELDS]
                    for k in removed:
                        del data[k]
                    if removed:
                        logging.info(f'[P4-02] 过滤系统字段: {removed} path={request.url.path}')
                    body = _json.dumps(data, ensure_ascii=False).encode('utf-8')
                    async def _receive():
                        return {"type": "http.request", "body": body, "more_body": False}
                    request = Request(request.scope, _receive)
        except Exception:
            pass
    response = await call_next(request)
    return response

# P1-18 全局异常脱敏：不返回原始异常信息，避免泄露路径/数据库细节
from fastapi.responses import JSONResponse
from fastapi import Request
import traceback as _tb

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    logger.error("[全局异常] %s %s -> %s\n%s" % (
        request.method, request.url.path, str(exc), _tb.format_exc()))
    return JSONResponse(
        status_code=500,
        content={"error": "服务器内部错误，请稍后重试", "detail": "已记录日志"}
    )


# 注册统一异常处理器
register_exception_handlers(app)
app.include_router(data_security_router)
app.include_router(monitor_router)
app.include_router(shutdown_router)  # /api/common/shutdown 优雅退出
app.include_router(file_library_router, prefix="/api/v1")  # /api/v1/fl 学习资料库
app.include_router(fl_bridge_router, prefix="/api/v1")  # /api/v1/fl_bridge 文件库衔接

# ========== Gzip压缩（加速页面加载，排除视频文件） ==========
from starlette.middleware.gzip import GZipMiddleware as _GZipMiddleware
class SmartGZipMiddleware(_GZipMiddleware):
    """智能Gzip中间件：排除视频/音频等已压缩文件，避免flv.js无法解析"""
    EXCLUDED_EXTENSIONS = ('.flv', '.mp4', '.m4v', '.mov', '.webm', '.ogg', '.mp3', '.wav', '.aac', '.zip', '.gz', '.rar', '.7z')
    async def __call__(self, scope, receive, send):
        if scope['type'] == 'http':
            path = scope.get('path', '').lower()
            if any(path.endswith(ext) for ext in self.EXCLUDED_EXTENSIONS):
                # 视频/音频/压缩文件不做gzip
                await self.app(scope, receive, send)
                return
        await super().__call__(scope, receive, send)
app.add_middleware(SmartGZipMiddleware, minimum_size=1000)

# ========== 【测试模式】强制不缓存中间件（解决PWA缓存顽固问题） ==========
from starlette.middleware.base import BaseHTTPMiddleware
# P1-14 缓存中间件已合并到下方cache_control_middleware，避免两套逻辑冲突

# ========== 【测试模式】返回自毁SW，主动取消注册并清除所有缓存 ==========
_self_destruct_sw = """
self.addEventListener('install', function(e) {
  self.skipWaiting();
});
self.addEventListener('activate', function(e) {
  e.waitUntil(
    caches.keys().then(function(names) {
      return Promise.all(names.map(function(n) { return caches.delete(n); }));
    }).then(function() {
      return self.registration.unregister();
    }).then(function() {
      return self.clients.matchAll();
    }).then(function(clients) {
      clients.forEach(function(client) {
        client.postMessage({type: 'SW_CLEARED', message: '缓存已清除，SW已注销'});
      });
    })
  );
});
self.addEventListener('fetch', function(e) { e.respondWith(fetch(e.request)); });
"""
@app.get('/sw.js')
@app.get('/sw_v2.js')
async def self_destruct_service_worker(request: Request):
    return Response(content=_self_destruct_sw, media_type='application/javascript')
logger.info('[测试模式] 自毁SW已启用（主动取消注册并清除所有缓存）')

# ========== 强制更新入口：清除所有缓存+SW后跳转首页 ==========
_force_update_html = """<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>强制更新中...</title>
<style>body{font-family:sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#f0f9ff;color:#0c4a6e}
.box{text-align:center;padding:40px;border-radius:12px;background:#fff;box-shadow:0 4px 20px rgba(0,0,0,0.1)}
.spinner{width:40px;height:40px;border:4px solid #bae6fd;border-top-color:#0284c7;border-radius:50%;animation:spin 1s linear infinite;margin:0 auto 20px}
@keyframes spin{to{transform:rotate(360deg)}}</style></head>
<body><div class="box"><div class="spinner"></div><div id="msg">正在清除缓存...</div></div>
<script>
(async function(){
  const msg = document.getElementById('msg');
  try {
    msg.textContent = '正在注销Service Worker...';
    if ('serviceWorker' in navigator) {
      const regs = await navigator.serviceWorker.getRegistrations();
      for (const reg of regs) await reg.unregister();
    }
    msg.textContent = '正在清除缓存...';
    if ('caches' in window) {
      const keys = await caches.keys();
      for (const key of keys) await caches.delete(key);
    }
    msg.textContent = '正在清除IndexedDB...';
    if ('indexedDB' in window) {
      const dbs = await indexedDB.databases();
      for (const db of dbs) indexedDB.deleteDatabase(db.name);
    }
    msg.textContent = '清除完成，正在跳转...';
    setTimeout(function(){ location.href = '/'; }, 800);
  } catch(e) {
    msg.textContent = '错误: ' + e.message + '，3秒后跳转';
    setTimeout(function(){ location.href = '/'; }, 3000);
  }
})();
</script></body></html>"""
@app.get('/force_update')
async def force_update(request: Request):
    return Response(content=_force_update_html, media_type='text/html', headers={
        'Cache-Control': 'no-cache, no-store, must-revalidate',
        'Pragma': 'no-cache',
        'Expires': '0'
    })
logger.info('[强制更新] /force_update 端点已启用')

# ========== Range请求支持（用于视频seek跳转） ==========
from fastapi import Request, Response
from fastapi.responses import FileResponse
import mimetypes

@app.api_route("/uploads/videos/{filename:path}", methods=["GET", "HEAD"])
async def serve_video_with_range(request: Request, filename: str):
    """视频文件服务，支持Range请求（用于FLV/MP4 seek跳转）"""
    file_path = os.path.join(UPLOAD_DIR, "videos", filename)
    if not os.path.exists(file_path) or not os.path.isfile(file_path):
        return Response(status_code=404)
    
    file_size = os.path.getsize(file_path)
    content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
    
    # 处理Range请求
    range_header = request.headers.get("range")
    if range_header:
        try:
            # 解析 Range: bytes=start-end
            range_value = range_header.replace("bytes=", "").strip()
            if "-" in range_value:
                start_str, end_str = range_value.split("-", 1)
                start = int(start_str) if start_str else 0
                end = int(end_str) if end_str else file_size - 1
            else:
                start = 0
                end = file_size - 1
            
            # 边界检查
            start = max(0, min(start, file_size - 1))
            end = max(start, min(end, file_size - 1))
            content_length = end - start + 1
            
            # 读取指定范围的数据
            with open(file_path, "rb") as f:
                f.seek(start)
                data = f.read(content_length)
            
            headers = {
                "Content-Range": f"bytes {start}-{end}/{file_size}",
                "Accept-Ranges": "bytes",
                "Content-Length": str(content_length),
                "Content-Type": content_type,
                "Cache-Control": "public, max-age=3600",
            }
            return Response(content=data, status_code=206, headers=headers)
        except Exception as e:
            logger.info(f"Range请求解析失败: {e}")
    # 非Range请求，返回完整文件
    headers = {
        "Accept-Ranges": "bytes",
        "Content-Length": str(file_size),
        "Content-Type": content_type,
        "Cache-Control": "public, max-age=3600",
    }
    return FileResponse(file_path, headers=headers)

logger.info("[后端] 视频Range请求支持已添加")
# 启用SQLAlchemy全局审计监听：所有INSERT/UPDATE/DELETE自动记录日志
setup_sqlalchemy_audit_listener(engine)
logger.info("SQLAlchemy审计监听器已启用，系统所有数据变更将自动记录")

# P4-05 后端接口限流：上传/AI识别接口限制QPS
import time as _rate_time
from collections import defaultdict as _defaultdict
_rate_limits = _defaultdict(list)
RATE_LIMIT_QPS = 10
RATE_LIMIT_PATHS = ('/api/v1/fl/', '/api/ai/', '/api/v1/file', '/upload')

@app.middleware("http")
async def rate_limit_middleware(request: Request, call_next):
    path = request.url.path
    if any(path.startswith(p) for p in RATE_LIMIT_PATHS):
        client_ip = request.client.host if request.client else 'unknown'
        now = _rate_time.time()
        _rate_limits[client_ip] = [t for t in _rate_limits[client_ip] if now - t < 1.0]
        if len(_rate_limits[client_ip]) >= RATE_LIMIT_QPS:
            from fastapi.responses import JSONResponse
            return JSONResponse(status_code=429, content={"code": 429, "msg": "请求过于频繁，请稍后再试"})
        _rate_limits[client_ip].append(now)
    return await call_next(request)

# P3-07 批量接口幂等key：防止网络抖动重复提交
import hashlib as _idemp_hash
_idempotency_cache = {}  # {key: timestamp}
IDEMPOTENCY_TTL = 300  # 5分钟内重复请求视为重复

@app.middleware("http")
async def idempotency_middleware(request: Request, call_next):
    """对批量操作接口进行幂等控制"""
    path = request.url.path
    idempotent_paths = ('/batch_import', '/batch_delete', '/recognize/confirm', '/fl_bridge/recognize')
    if request.method == 'POST' and any(p in path for p in idempotent_paths):
        try:
            body = await request.body()
            if body:
                import json as _ijson
                data = _ijson.loads(body.decode('utf-8'))
                # 优先使用客户端传入的idempotency_key，否则用请求体哈希
                idem_key = data.get('idempotency_key') if isinstance(data, dict) else None
                if not idem_key:
                    idem_key = _idemp_hash.md5(body).hexdigest()
                # 检查是否重复
                import time as _itime
                now = _itime.time()
                # 清理过期记录
                expired = [k for k, v in _idempotency_cache.items() if now - v > IDEMPOTENCY_TTL]
                for k in expired:
                    del _idempotency_cache[k]
                if idem_key in _idempotency_cache:
                    from fastapi.responses import JSONResponse
                    return JSONResponse(
                        status_code=409,
                        content={"code": 409, "msg": "重复请求，操作已在处理中或已完成", "idempotency_key": idem_key}
                    )
                _idempotency_cache[idem_key] = now
                # 重建request
                async def _receive():
                    return {"type": "http.request", "body": body, "more_body": False}
                request = Request(request.scope, _receive)
        except Exception:
            pass  # 非JSON请求不处理
    return await call_next(request)

app.add_middleware(
    CORSMiddleware,
    allow_origins=CORS_ORIGINS,
    allow_credentials=False,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 文件哈希中间件（用于内容哈希去重，默认关闭）
if ENABLE_FILE_HASH_HEADER:
    try:
        from middleware.file_hash_middleware import FileHashMiddleware
        app.add_middleware(FileHashMiddleware)
        logger.info("文件哈希中间件已启用（X-File-Hash响应头）")
    except Exception as e:
        logger.warning(f"文件哈希中间件加载失败: {e}")

# ========== 请求ID追踪中间件（便于日志追踪和问题定位）==========
try:
    from middleware.request_id_middleware import RequestIdMiddleware
    app.add_middleware(RequestIdMiddleware)
    logger.info("请求ID追踪中间件已启用（X-Request-ID / X-Response-Time响应头）")
except Exception as e:
    logger.warning(f"请求ID追踪中间件加载失败: {e}")

# ========== API限流中间件（防止滥用和恶意攻击）==========
try:
    from middleware.rate_limit_middleware import RateLimitMiddleware
    app.add_middleware(RateLimitMiddleware, max_requests=120, window_seconds=60)
    logger.info("API限流中间件已启用（每分钟120次请求）")
except Exception as e:
    logger.warning(f"API限流中间件加载失败: {e}")

# ========== 全局异常处理器 ==========
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    logger.warning(f"HTTP {exc.status_code} {request.method} {request.url.path}: {exc.detail}")
    return JSONResponse(
        status_code=exc.status_code,
        content={"code": exc.status_code, "msg": str(exc.detail), "data": None}
    )

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    def _safe(obj):
        if isinstance(obj, bytes):
            try: return obj.decode("utf-8")
            except Exception as e:
                logging.error(f"bytes解码失败: {e}", exc_info=True)
                return str(obj)
        if isinstance(obj, dict): return {k: _safe(v) for k, v in obj.items()}
        if isinstance(obj, list): return [_safe(i) for i in obj]
        return obj
    safe_errors = _safe(exc.errors())
    logger.warning(f"参数校验失败 {request.method} {request.url.path}: {safe_errors}")
    return JSONResponse(
        status_code=422,
        content={"code": 422, "msg": "请求参数校验失败", "errors": safe_errors, "data": None}
    )

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    logger.error(f"未捕获异常 {request.method} {request.url.path}: {exc}", exc_info=True)
    return JSONResponse(
        status_code=500,
        content={"code": 500, "msg": f"服务器内部错误: {str(exc)}", "data": None}
    )

# ========== 请求日志中间件 ==========
@app.middleware("http")
async def log_requests(request: Request, call_next):
    logger.info(f"请求开始: {request.method} {request.url.path}")
    try:
        response = await call_next(request)
        logger.info(f"请求完成: {request.method} {request.url.path} -> {response.status_code}")
        return response
    except Exception as e:
        logger.error(f"请求异常: {request.method} {request.url.path} -> {e}", exc_info=True)
        raise

# 注册路由
app.include_router(auth.router, prefix="/api/v1")
app.include_router(question.router, prefix="/api/v1")
app.include_router(question_file.router, prefix="/api/v1")
app.include_router(exam.router, prefix="/api/v1")
app.include_router(ai_unified.router, prefix="/api/v1")
app.include_router(ai_brain.router, prefix="/api/v1")  # AI智能大脑
app.include_router(ai_scan.router, prefix="/api/v1", tags=["AI拍照解题"])
app.include_router(flashcard.router, prefix="/api/v1")
app.include_router(relation.router, prefix="/api/v1")
app.include_router(wrong_analysis.router, prefix="/api/v1")
app.include_router(note.router, prefix="/api/v1")
app.include_router(video.router, prefix="/api/v1")
app.include_router(sync_unified.router, prefix="/api/v1")
app.include_router(sync_unified.offline_router, prefix="/api/v1")
app.include_router(system.router, prefix="/api/v1")
app.include_router(analytics.router, prefix="/api/v1")
app.include_router(material.router, prefix="/api/v1")
app.include_router(mindmap.router, prefix="/api/v1")
app.include_router(lecture.router, prefix="/api/v1")
app.include_router(sprint.router, prefix="/api/v1")
app.include_router(syllabus.router, prefix="/api/v1")
app.include_router(music.router, prefix="/api/v1")
app.include_router(tts.router, prefix="/api/v1")
app.include_router(backup.router, prefix="/api/v1")
app.include_router(ai_unified.assistant_router, prefix="/api/v1")
app.include_router(subject_switch.router, prefix="/api/v1")
app.include_router(knowledge_graph.router, prefix="/api/v1")
app.include_router(exam_analysis.router, prefix="/api/v1")
app.include_router(formula_trainer.router, prefix="/api/v1")
app.include_router(deduplication.router, prefix="/api/v1")
app.include_router(combined_analysis.router, prefix="/api/v1")
app.include_router(data_check.router, prefix="/api/v1")
app.include_router(rag_knowledge.router, prefix="/api/v1")
app.include_router(preprocess_config.router, prefix="/api/v1")  # 预处理标准配置
app.include_router(monitor.router, prefix="/api/v1")

# ========== 新架构模块蓝图注册（增量搬迁，新旧共存）==========
if MODULES_AVAILABLE:
    app.include_router(qb_router)          # /api/qb 题库管理
    app.include_router(qb_quality_router)  # /api/qb/quality 题库质量分级
    app.include_router(mt_router)          # /api/mt 记忆训练
    app.include_router(mt_category_router)  # /api/mt/categories 闪卡六类
    app.include_router(mm_router)          # /api/mm 思维导图
    app.include_router(ai_module_router)
    app.include_router(ai_manager_router)   # /api/ai AI能力
    app.include_router(ai_evaluation_router)  # /api/ai/evaluation AI效果评估
    app.include_router(ai_stream_router)  # /api/ai/stream AI流式输出
    app.include_router(sync_module_router) # /api/sync 同步模块
    app.include_router(resource_router)    # /api/resource 资源管理
    app.include_router(common_router)
    logger.info("[架构] 新模块蓝图注册成功: qb, mt, mm, ai, sync, resource, common")

# 系统监督管理API
from api.supervisor_api import register_supervisor_api
register_supervisor_api(app)
# ========== PDF去水印API（已迁移到ai模块，业务逻辑下沉） ==========
@app.post("/api/watermark/remove")
async def remove_watermark(file: UploadFile = File(...)):
    """频域滤波去除PDF水印 - 业务逻辑已迁移到ai模块AiService.remove_watermark"""
    from modules.ai.service import AiService
    contents = await file.read()
    ai_service = AiService()
    result_pdf = ai_service.remove_watermark(contents)
    if result_pdf:
        return Response(content=result_pdf, media_type="application/pdf", headers={
            "Content-Disposition": "attachment; filename=watermark_removed.pdf"
        })
    return JSONResponse(status_code=500, content={"error": "PDF去水印失败，请检查依赖（cv2/numpy/PIL/pymupdf）"})

# 静态文件挂载
os.makedirs(UPLOAD_DIR, exist_ok=True)

# 手动文件服务路由（确保PDF等文件可访问）
@app.api_route("/uploads/{filename:path}", methods=["GET", "HEAD"])
async def serve_upload_file(request: Request, filename: str):
    """手动服务uploads目录下的文件"""
    import logging
    logger = logging.getLogger("shuili_exam")
    file_path = os.path.join(UPLOAD_DIR, filename)
    logger.info(f"[文件服务] 请求文件: {filename}, 完整路径: {file_path}, 存在: {os.path.exists(file_path)}")
    if os.path.exists(file_path) and os.path.isfile(file_path):
        return FileResponse(file_path)
    logger.warning(f"[文件服务] 文件未找到: {file_path}")
    return JSONResponse(status_code=404, content={"error": "文件未找到", "path": filename, "full_path": file_path})

app.mount("/uploads", StaticFiles(directory=UPLOAD_DIR), name="uploads")

frontend_dir = os.path.join(get_resource_dir(), "frontend")

# P5-05: 静态资源内容哈希（暂不启用，待系统稳定后开启）
_STATIC_MANIFEST = {}
_STATIC_REVERSE = {}

if os.path.exists(frontend_dir):
    app.mount("/static", StaticFiles(directory=frontend_dir), name="static")
    # P1静态资源路径规范化（2026-09-11）：前端已统一使用 /static/data/offline/ 绝对路径
    # /static 已挂载到 frontend_dir，自动覆盖 frontend/data/ 目录，无需独立挂载 /data
    # data_dir = os.path.join(frontend_dir, "data")
    # if os.path.exists(data_dir):
    #     app.mount("/data", StaticFiles(directory=data_dir), name="data")


# 全局版本号：后端启动时间戳，每次重启自动更新，强制浏览器重新下载所有JS/CSS
import time as _time
APP_VERSION_TS = str(int(_time.time()))

@app.get("/")
async def root():
    index_path = os.path.join(frontend_dir, "index.html")
    if os.path.exists(index_path):
        # 读取index.html，动态注入版本号（每次后端重启版本号自动更新）
        with open(index_path, 'r', encoding='utf-8') as f:
            html = f.read()
        import re
        # P0-01修复：只替换HTML标签的src/href属性中的.js/.css，不误伤JS字符串内部内容
        def _version_replacer(m):
            prefix = m.group(1)  # src=" 或 href="
            url = m.group(2)     # 完整文件路径（含扩展名）
            quote = m.group(3)   # 结束引号
            return prefix + url + '?v=' + APP_VERSION_TS + quote
        html = re.sub(r'((?:src|href)=")([^"\']+?\.(?:js|css))(?:\?v=[^"\']*)?(")', _version_replacer, html)
        return Response(content=html, media_type='text/html', headers={
            "Cache-Control": "no-cache, no-store, must-revalidate, max-age=0",
            "Pragma": "no-cache",
            "Expires": "0"
        })
    return {"message": "水利智学 V4.5.15 API", "docs": "/docs"}





@app.get("/offline.html")
async def offline_page():
    """完全自包含的离线页面（不依赖Service Worker，华为手机兼容）"""
    from fastapi.responses import HTMLResponse
    offline_path = os.path.join(frontend_dir, "offline.html")
    if os.path.exists(offline_path):
        with open(offline_path, "r", encoding="utf-8") as f:
            return HTMLResponse(content=f.read())
    return HTMLResponse(content="<h1>离线页面未找到</h1>", status_code=404)

# P0-04: 已删除重复SW路由，统一使用自毁SW

@app.get("/api/health")
async def health():
    """P5-04 深度健康探针：检查数据库、磁盘、Ollama等组件状态"""
    import shutil as _shutil
    import sqlite3 as _sqlite3
    report = {"status": "ok", "version": "v4.5.15", "components": {}}
    # 1. 数据库连通性
    try:
        db_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'data', 'shuili_exam.db')
        conn = _sqlite3.connect(db_path, timeout=3)
        cursor = conn.cursor()
        cursor.execute("SELECT COUNT(*) FROM sqlite_master WHERE type='table'")
        table_count = cursor.fetchone()[0]
        conn.close()
        report["components"]["database"] = {"status": "ok", "tables": table_count}
    except Exception as e:
        report["components"]["database"] = {"status": "error", "error": str(e)[:100]}
        report["status"] = "degraded"
    # 2. 磁盘剩余空间
    try:
        usage = _shutil.disk_usage(os.path.dirname(os.path.abspath(__file__)))
        free_gb = round(usage.free / (1024**3), 1)
        report["components"]["disk"] = {"status": "ok" if free_gb > 1 else "warning", "free_gb": free_gb, "total_gb": round(usage.total/(1024**3),1)}
        if free_gb < 1:
            report["status"] = "degraded"
    except Exception as e:
        report["components"]["disk"] = {"status": "error", "error": str(e)[:100]}
    # 3. Ollama状态（不阻塞，超时2秒）
    try:
        import urllib.request as _ur
        req = _ur.Request('http://localhost:11434/api/tags', method='GET')
        with _ur.urlopen(req, timeout=2) as resp:
            ollama_data = json.loads(resp.read().decode('utf-8'))
            report["components"]["ollama"] = {"status": "ok", "models": len(ollama_data.get('models', []))}
    except Exception:
        report["components"]["ollama"] = {"status": "offline", "note": "Ollama未运行，AI功能不可用"}
    return report


# P3-03 服务器时间接口：业务时间戳以服务器为准，防止客户端篡改
@app.get("/api/server/time")
async def get_server_time():
    """返回服务器当前时间，前端业务时间应以此为准"""
    from datetime import datetime, timezone, timedelta
    now = datetime.now(timezone(timedelta(hours=8)))
    return {
        "code": 200,
        "data": {
            "timestamp": int(now.timestamp()),
            "datetime": now.strftime("%Y-%m-%d %H:%M:%S"),
            "date": now.strftime("%Y-%m-%d"),
            "timezone": "Asia/Shanghai (UTC+8)"
        }
    }


@app.get("/data/exam_config.json")
async def get_exam_config():
    """提供考试专业配置文件 - 业务逻辑已迁移到common模块CommonService.get_exam_config"""
    from modules.common.service import CommonService
    common_service = CommonService()
    result = common_service.get_exam_config(DATA_DIR)
    if result['success']:
        return Response(content=result['content'], media_type="application/json; charset=utf-8", headers={
            "Cache-Control": "no-cache"
        })
    return JSONResponse(status_code=404, content={"error": result['error']})


@app.get("/favicon.ico")
async def favicon():
    """返回空favicon，避免浏览器自动请求导致404错误"""
    return Response(status_code=204)


def init_db():
    Base.metadata.create_all(bind=engine)
    _run_migrations()
    from scripts.init_db import init as seed_init
    seed_init()

def _run_migrations():
    """P1-15 数据库自动迁移加固：版本记录+事务包裹+失败告警"""
    from sqlalchemy import text
    with engine.connect() as conn:
        trans = conn.begin()  # P1-15 事务包裹
        try:
            # P1-15 创建迁移版本记录表
            conn.execute(text("""
                CREATE TABLE IF NOT EXISTS schema_migrations (
                    version VARCHAR(128) PRIMARY KEY,
                    description VARCHAR(256),
                    executed_at DATETIME DEFAULT CURRENT_TIMESTAMP
                )
            """))
            # 获取已执行的迁移版本
            executed = set(r[0] for r in conn.execute(text("SELECT version FROM schema_migrations")).fetchall())

            migrations = [
                ("m001_users_reset_token", "users", "reset_token", "VARCHAR(128) DEFAULT ''"),
                ("m002_users_reset_expire", "users", "reset_expire", "DATETIME"),
                ("m003_exam_records_switch", "exam_records", "switch_count", "INTEGER DEFAULT 0"),
                ("m004_exam_records_cheating", "exam_records", "is_cheating", "BOOLEAN DEFAULT 0"),
                ("m005_course_materials_user", "course_materials", "user_id", "INTEGER DEFAULT 0"),
                ("m006_data_versions_check", "data_versions", "check_status", "VARCHAR(16) DEFAULT 'unknown'"),
                ("m007_data_versions_time", "data_versions", "last_check_time", "DATETIME"),
                ("m008_answer_logs_time", "question_answer_logs", "time_spent", "FLOAT DEFAULT 0"),
            ]
            for version, table, col, col_def in migrations:
                if version in executed:
                    continue
                cols = conn.execute(text(f"PRAGMA table_info({table})")).fetchall()
                col_names = [c[1] for c in cols]
                if col not in col_names:
                    conn.execute(text(f"ALTER TABLE {table} ADD COLUMN {col} {col_def}"))
                    logger.info(f"[Migration] 已为 {table} 添加字段 {col}")
                # 记录迁移版本
                conn.execute(text("INSERT OR IGNORE INTO schema_migrations (version, description) VALUES (:v, :d)"),
                             {"v": version, "d": f"{table}.{col}"})

            # 创建data_check_records表
            conn.execute(text("""
                CREATE TABLE IF NOT EXISTS data_check_records (
                    id INTEGER PRIMARY KEY AUTOINCREMENT,
                    check_type VARCHAR(64) DEFAULT 'full',
                    total_records INTEGER DEFAULT 0,
                    error_count INTEGER DEFAULT 0,
                    fixed_count INTEGER DEFAULT 0,
                    detail_json TEXT DEFAULT '',
                    status VARCHAR(16) DEFAULT 'completed',
                    create_time DATETIME DEFAULT CURRENT_TIMESTAMP
                )
            """))
            trans.commit()  # P1-15 事务提交
            logger.info("[P1-15] 数据库迁移完成（事务已提交）")
        except Exception as e:
            trans.rollback()  # P1-15 失败回滚
            logger.error(f"[P1-15] 数据库迁移失败，已回滚: {e}", exc_info=True)
            # 本地工具不阻止启动，但记录严重错误
            logger.warning("[P1-15] 警告：迁移失败可能导致部分功能异常，建议检查数据库完整性")



# ========== P1-14 统一缓存中间件（合并原NoCacheMiddleware）==========
@app.middleware("http")
async def cache_control_middleware(request: Request, call_next):
    response = await call_next(request)
    path = request.url.path.lower()
    # HTML/JS/CSS/JSON/根路径：不缓存，删除etag避免304旧缓存
    if path.endswith(('.html', '.js', '.css', '.json')) or path == '/' or path.endswith('/'):
        response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate, max-age=0"
        response.headers["Pragma"] = "no-cache"
        response.headers["Expires"] = "0"
        if 'etag' in response.headers:
            del response.headers['etag']
        if 'last-modified' in response.headers:
            del response.headers['last-modified']
    # 静态资源：图片、字体、视频 缓存1小时
    elif path.startswith("/static/") or path.startswith("/uploads/"):
        response.headers["Cache-Control"] = "public, max-age=3600"
    return response

logger.info("[P1-14] 统一缓存中间件已启用：HTML/JS/CSS/JSON不缓存，静态资源缓存1小时")
if __name__ == "__main__":
    import uvicorn
    import time
    import gc
    init_db()
    port = int(os.environ.get("PORT", 8000))

    def _kill_port_occupant(target_port):
        """检测并杀掉占用指定端口的旧进程，避免Errno 10048"""
        try:
            import subprocess
            result = subprocess.run(
                ['netstat', '-ano'], capture_output=True, text=True, timeout=5
            )
            for line in result.stdout.split('\n'):
                if f':{target_port}' in line and 'LISTENING' in line:
                    parts = line.split()
                    pid = parts[-1] if parts else ''
                    if pid and pid.isdigit() and int(pid) != os.getpid():
                        try:
                            subprocess.run(['taskkill', '/F', '/PID', pid],
                                         capture_output=True, timeout=5)
                            logger.info(f"已清理占用端口{target_port}的旧进程 PID={pid}")
                        except Exception:
                            logging.error(f'异常: {e}', exc_info=True)
                            pass
        except Exception:
            logging.error(f'异常: {e}', exc_info=True)
            pass

    def _force_gc():
        """强制垃圾回收，释放内存"""
        try:
            gc.collect()
            logger.debug("已执行垃圾回收")
        except Exception:
            logging.error(f'异常: {e}', exc_info=True)
            pass

    # 崩溃自动重启：uvicorn偶发退出时5秒后自动恢复
    # 注意：外部看门狗也会监控，这里是双重保险
    restart_count = 0

    # 启动服务监控
    from modules.common.service_monitor import get_service_monitor
    _service_monitor = get_service_monitor()
    _service_monitor.register_service("backend", os.getpid())
    _service_monitor.start()

    # P1-19 优雅关闭：收到SIGTERM/SIGINT时停止新请求，等待现有请求完成
    import signal as _signal
    _shutdown_flag = [False]  # 用列表实现可变闭包
    def _handle_shutdown(signum, frame):
        _shutdown_flag[0] = True
        logger.info(f"[P1-19] 收到关闭信号({signum})，等待现有请求完成后退出...")
    try:
        _signal.signal(_signal.SIGINT, _handle_shutdown)
        _signal.signal(_signal.SIGTERM, _handle_shutdown)
    except Exception:
        pass  # Windows下某些信号不可用

    while True:
        if _shutdown_flag[0]:
            logger.info("[P1-19] 优雅关闭中，不再重启")
            break
        try:
            # 启动前清理占用端口的旧进程
            if restart_count > 0:
                _kill_port_occupant(port)
                _force_gc()
                time.sleep(2)
            logger.info(f"启动后端服务 (端口 {port})，重启次数: {restart_count}")
            # P1-19: timeout_graceful_shutdown=30 给现有请求30秒完成时间
            uvicorn.run(app, host="0.0.0.0", port=port, log_level="info",
                       log_config=None, workers=1, loop="asyncio",
                       timeout_keep_alive=30, limit_concurrency=50,
                       timeout_graceful_shutdown=30)
            logger.info("uvicorn 正常退出，5秒后重启...")
        except Exception as e:
            restart_count += 1
            logger.error(f"后端崩溃 (第{restart_count}次): {e}", exc_info=True)
            logger.info("5秒后自动重启...")
            _force_gc()
        if _shutdown_flag[0]:
            logger.info("[P1-19] 关闭信号已触发，退出重启循环")
            break
        time.sleep(5)




---

# 📋 附录C：动态文件清单（由脚本生成，可刷新）
> 代码本体在原地，此处仅索引。改代码后重新运行生成脚本刷新本附录。


### 📁 .vscode（4个）

- extensions.json  (13行)
- launch.json  (31行)
- settings.json  (42行)
- tasks.json  (42行)

### 📁 _temp_integration（10个）

- 01_question_importer.py  (212行)
- 02_flashcard_generator.py  (275行)
- 03_video_mapper.py  (254行)
- 04_rag_indexer.py  (179行)
- 05_resource_importer.py  (215行)
- api_client.py  (192行)
- config.py  (85行)
- quick_test_yizao.py  (335行)
- README.md  (120行)
- run_all.py  (216行)

### 📁 _temp_integration\checkpoints（1个）

- token.json  (5行)

### 📁 _temp_scripts（42个）

- add_compat_routes.py  (69行)
- audit_migration.py  (157行)
- batch_replace_urls.py  (99行)
- build_mapping.py  (159行)
- check_500_errors.py  (28行)
- check_all_issues.py  (85行)
- check_answer_format.py  (29行)
- check_answer_samples.py  (22行)
- check_db.py  (37行)
- check_key_db.py  (45行)
- cleanup_duplicate_routes.py  (69行)
- compare_endpoints.py  (51行)
- create_missing_tables.py  (118行)
- debug_qb.py  (38行)
- find_all_500.py  (66行)
- find_mock_endpoints.py  (72行)
- fix_ai_history.py  (23行)
- fix_ai_indent.py  (14行)
- fix_all_500.py  (100行)
- fix_case_name.py  (25行)
- fix_column_names.py  (44行)
- fix_data_service.py  (50行)
- fix_exam_records.py  (43行)
- fix_materials_query.py  (16行)
- fix_multi_button.py  (17行)
- fix_multi_render.py  (27行)
- fix_remaining_500.py  (34行)
- fix_resource.py  (190行)
- fix_resource_materials.py  (29行)
- fix_resource_tables.py  (28行)
- fix_route_order.py  (38行)
- fix_single_show_result.py  (42行)
- fix_syllabi.py  (24行)
- fix_syntax_errors.py  (21行)
- merge_weighted_random.py  (144行)
- optimize_indexes.py  (76行)
- remove_dup2.py  (37行)
- remove_duplicate_bind.py  (37行)
- scan_schema_issues.py  (104行)
- test_all_endpoints.py  (95行)
- unify_subject_names.py  (77行)
- unify_subject_short.py  (52行)

### 📁 backend（4个）

- _duplicate_pdfs.json  (3955行)
- main.py  (839行)
- system_monitor.ps1  (66行)
- watchdog.py  (226行)

### 📁 backend\.pytest_cache（1个）

- README.md  (8行)

### 📁 backend\api（2个）

- __init__.py  (0行)
- supervisor_api.py  (277行)

### 📁 backend\api\v1（34个）

- __init__.py  (0行)
- ai_brain.py  (339行)
- ai_scan.py  (140行)
- ai_unified.py  (28行)
- analytics.py  (408行)
- assistant.py  (730行)
- auth.py  (137行)
- combined_analysis.py  (340行)
- data_check.py  (454行)
- deduplication.py  (358行)
- exam.py  (432行)
- exam_analysis.py  (290行)
- flashcard.py  (349行)
- formula_trainer.py  (203行)
- knowledge_graph.py  (799行)
- lecture.py  (278行)
- material.py  (1063行)
- mindmap.py  (1194行)
- monitor.py  (82行)
- music.py  (78行)
- note.py  (61行)
- preprocess_config.py  (281行)
- question.py  (1447行)
- question_file.py  (71行)
- rag_knowledge.py  (356行)
- relation.py  (131行)
- sprint.py  (166行)
- subject_switch.py  (251行)
- syllabus.py  (524行)
- sync_unified.py  (593行)
- system.py  (399行)
- tts.py  (156行)
- video.py  (584行)
- wrong_analysis.py  (130行)

### 📁 backend\core（11个）

- __init__.py  (0行)
- ai_controller.py  (624行)
- ai_dev_workflow.py  (347行)
- code_cleanup_planner.py  (410行)
- code_review.py  (585行)
- commander_center.py  (295行)
- config.py  (191行)
- db.py  (32行)
- layout_checker.py  (468行)
- requirement_tracker.py  (318行)
- system_supervisor.py  (642行)

### 📁 backend\crud（2个）

- __init__.py  (0行)
- crud.py  (964行)

### 📁 backend\data（4个）

- exam_config.json  (84行)
- pdf_ai_config.json  (22行)
- remote_config.json  (14行)
- requirements.json  (353行)

### 📁 backend\data\exports（1个）

- mindmap_116_测试脑图_带JSON_修复版.md  (2行)

### 📁 backend\data\offline（4个）

- flashcards.json  (1行)
- mindmaps.json  (1行)
- questions.json  (1行)
- README.md  (21行)

### 📁 backend\data\offline\config（1个）

- offline_config.json  (7行)

### 📁 backend\data\pdf_cache（1个）

- cache_meta.json  (9行)

### 📁 backend\data\pdf_cache\49（1个）

- 4966d6b9abbb94e7b53d8f4db83d9bc7.json  (18行)

### 📁 backend\middleware（4个）

- __init__.py  (1行)
- file_hash_middleware.py  (86行)
- rate_limit_middleware.py  (126行)
- request_id_middleware.py  (51行)

### 📁 backend\modules（1个）

- __init__.py  (5行)

### 📁 backend\modules\ai（11个）

- __init__.py  (0行)
- ai_manager.py  (413行)
- case_grader.py  (136行)
- effect_evaluator.py  (214行)
- evaluation_routes.py  (106行)
- manager_routes.py  (207行)
- pdf_vl_recognizer.py  (975行)
- routes.py  (1056行)
- service.py  (1272行)
- stream_routes.py  (136行)
- stream_service.py  (277行)

### 📁 backend\modules\common（17个）

- __init__.py  (0行)
- data_routes.py  (103行)
- data_security.py  (238行)
- file_library_model.py  (26行)
- file_library_routes.py  (418行)
- file_library_service.py  (391行)
- fl_bridge_routes.py  (1097行)
- graceful_shutdown.py  (171行)
- logger.py  (165行)
- monitor_routes.py  (173行)
- preprocess_service.py  (302行)
- question_importer.py  (295行)
- response.py  (268行)
- routes.py  (1362行)
- service.py  (55行)
- service_monitor.py  (330行)
- shutdown_routes.py  (54行)

### 📁 backend\modules\mm（3个）

- __init__.py  (0行)
- routes.py  (759行)
- service.py  (1129行)

### 📁 backend\modules\mt（9个）

- __init__.py  (0行)
- ability_radar.py  (658行)
- bkt_algorithm.py  (249行)
- category_manager.py  (302行)
- category_routes.py  (138行)
- fsrs_algorithm.py  (300行)
- learning_path_planner.py  (439行)
- routes.py  (635行)
- service.py  (626行)

### 📁 backend\modules\qb（6个）

- __init__.py  (0行)
- irt_algorithm.py  (362行)
- quality_manager.py  (290行)
- quality_routes.py  (120行)
- routes.py  (1277行)
- service.py  (776行)

### 📁 backend\modules\resource（4个）

- __init__.py  (0行)
- pdf_parse_cache.py  (370行)
- routes.py  (1243行)
- service.py  (648行)

### 📁 backend\modules\sync（3个）

- __init__.py  (0行)
- routes.py  (515行)
- service.py  (747行)

### 📁 backend\ollama（1个）

- 启动ollama.bat  (8行)

### 📁 backend\schemas（2个）

- __init__.py  (0行)
- schemas.py  (210行)

### 📁 backend\scripts（2个）

- __init__.py  (0行)
- init_db.py  (232行)

### 📁 backend\tests（4个）

- conftest.py  (120行)
- test_all_modules.py  (272行)
- test_api.py  (163行)
- test_core.py  (177行)

### 📁 backend\uploads\cache\split（931个）

- 006b218a47c669bb2d13ac6d40d47a24.json  (1行)
- 0145a885fc080abfce283343b95264c8.json  (1行)
- 01a70c87fef7710f65496602d2c92049.json  (1行)
- 02fd5dd8f5b116fd462ccea28235b0f0.json  (1行)
- 030c5e0c5c2a431f7af27287b0aadd4a.json  (1行)
- 03fa425f4c49c34b065d4686aeb7b9ad.json  (1行)
- 04185737a028bd52621b5372979964e6.json  (1行)
- 0497a208d62b4e0f7e4472c9187d72d3.json  (1行)
- 04eb342ebf7bc91ac81f23b1fe7d38fc.json  (1行)
- 053186996ede9cf4c6f0eeb765bdf284.json  (1行)
- 053df4a005f589f2d31628e3814ac4e5.json  (1行)
- 0589fdf20616c16241548e211ca1abcc.json  (1行)
- 05c1addb0a8597aed7e0762f4d43553f.json  (1行)
- 05c273f63d5836087f55b02628d80b57.json  (1行)
- 06798ddc5830b7561d95fe5ba6ca489f.json  (1行)
- 06c11b920d7424f46d0608354843d14b.json  (1行)
- 06e462f71dba31faabebd805002bcd5d.json  (1行)
- 07477053f78db3c77b446e6b786ad820.json  (1行)
- 074a953ccb85fadf4c9f1b3b12bd7c0f.json  (1行)
- 076863193be1b208ce35149783cb1aa2.json  (1行)
- 076d3426f45cb83624b942395b8641ee.json  (1行)
- 07820259074f5901b073451a13a25dac.json  (1行)
- 079f47c9ada2ab89b2127143d2020e3a.json  (1行)
- 07d1dc82baeec4ecc8696f7888600ef3.json  (1行)
- 0887e72cb60b7c6fec12b0dcd8e69647.json  (1行)
- 092cf5dc49482ecd0f6caedd5173856d.json  (1行)
- 09517a985412deec466ab4dac313808d.json  (1行)
- 0957ae04154c19d3fce2ceb115873dc7.json  (1行)
- 0968a3919513e424c2cb2374cbc47442.json  (1行)
- 09c2a4abd8cfbaca5bdd18c5abb62b59.json  (1行)
- 0a067ff46803183ee422462f7f28fab2.json  (1行)
- 0a4e82ae972426e0ab017d99d79489e8.json  (1行)
- 0ab44cb492fa41a9190180075e8522c8.json  (1行)
- 0adbc28369f253d4ffc8066cafa58674.json  (1行)
- 0af9cf02b8d498d17ba97cd2d409f05a.json  (1行)
- 0afb27dee9660e4467d9493b1dc0eb8b.json  (1行)
- 0b87bf67f9f228d66bdc8f468964d9b0.json  (1行)
- 0b8c9214164be37b1ed21b0ebac23786.json  (1行)
- 0c18b359d520b44b0ea6e117cca22dc8.json  (1行)
- 0c312e2bfe045fd1349a3d624f242fda.json  (1行)
- 0c874a0e646dff4d576a2ad3108ff788.json  (1行)
- 0ca14ccf0808eedb4069855f4a62f9dd.json  (1行)
- 0cf3679bec1147777810dc0e36f6646c.json  (1行)
- 0d9098a3471035e88e12a690f0e4c916.json  (1行)
- 0db48c8d7c10472513cbcddd68c0d7c3.json  (1行)
- 0e0d3e618671c44b5b256b81247b8fa1.json  (1行)
- 0ee18a9dca4d362dbd55db267670d50f.json  (1行)
- 105e572f8d1fdba9590c7bd4c51ffdb9.json  (1行)
- 1074127934fc2be6ca5e9c4e7289ca87.json  (1行)
- 1089620d9f5638f291fa3d6b9a2a856c.json  (1行)
- 10d4327f2e5b14add56751e1d64ac17c.json  (1行)
- 10d95c316b3e04b654f4f75563f9b86f.json  (1行)
- 112300eb4784146ec181547121c21033.json  (1行)
- 11e9488f80bdda6ac03b2ebbf2085f68.json  (1行)
- 11f813774dc1286660907e827490949d.json  (1行)
- 1229b393e150b18ff30e771a61322e62.json  (1行)
- 1248d6416f9444d1bbcce547b8bfe634.json  (1行)
- 127872f8abfb6a2dd3c6cd3a9b7b9256.json  (1行)
- 12bbf59d05b274d04447dbb39a78d9be.json  (1行)
- 12fbe65a63bbc3ca5dee556f4246446c.json  (1行)
- 13188c6f550c679d53d2b9ad6c7bbb1e.json  (1行)
- 131c0ce03de18a655588dc3aa2039d88.json  (1行)
- 131fead5ef2afa74bb4ec8b7736c7e77.json  (1行)
- 135102596989d22335ad2ddf8ee699db.json  (1行)
- 135307bb847785de4daeb547cd0ea690.json  (1行)
- 136f5ed67c5d4f516481472be1ba9d4e.json  (1行)
- 136fcdd16df218db32c9027474c865c4.json  (1行)
- 13ebe467d1d538de696b1fe8f9750749.json  (1行)
- 14ac46abf3e330e98afa6cf449936e84.json  (1行)
- 14d9d146dba11493b24e53ed08f94227.json  (1行)
- 153f03dcd871eab578b5bd5b1d41387b.json  (1行)
- 15675de1b5dbf4475ec321ca3af8d597.json  (1行)
- 159f590c7d3423c32caffd91f45476e9.json  (1行)
- 16d38abb7c512a2410576118c007216f.json  (1行)
- 178814572c3e8bf1e918946ca71d8198.json  (1行)
- 178fd38f41417875c154d3f59bbe11a9.json  (1行)
- 17a7b816282b6e260dbe6c96e77cb663.json  (1行)
- 186d6d843bcb6023429737b6046ad6ac.json  (1行)
- 1888d9f9777fe3546ad09f9b74aeafa6.json  (1行)
- 1915e0577a8c0dc8db50051161fa8e2f.json  (1行)
- 19b7e8aba943e065e1de3f43dafc76e9.json  (1行)
- 19edc8df2a2df6e569e5d63131677ebd.json  (1行)
- 1ad5ede62445468c6506a2909822e0cc.json  (1行)
- 1add0fff791c69cadcfb7d73722fc56b.json  (1行)
- 1ae91403c480eaf1cdc4d048173fbc6b.json  (1行)
- 1afcb625337a4716bd1371b140d1d63e.json  (1行)
- 1b8bd17cd8a6cba7fed08cb46f60d785.json  (1行)
- 1c6913cbd871a6459078f4ef6fb897cf.json  (1行)
- 1e0fb17714df68415bcff160e390bbb0.json  (1行)
- 1e1f5a91b4af316ab7a44d3757ae47d4.json  (1行)
- 1f033a6d414fd015c8758656e67d0006.json  (1行)
- 1f1a7bc5cf7610fdf46c311356f1d4a1.json  (1行)
- 1f606a7716ae5560513411e1279ecec8.json  (1行)
- 1f6295103e732b6be02cfdf36f881652.json  (1行)
- 20fa7e3eae74855d8e1f091b51bcc7f8.json  (1行)
- 20ff7cc1ca90a6dca9a5cc09fe4e2c2f.json  (1行)
- 21137b01f4876fa143866558cad08b0e.json  (1行)
- 2115fd29612ff3b2eb5f77e99ff3efb5.json  (1行)
- 219c489341824bcbff1c3ef3073dc9f7.json  (1行)
- 21bb8f9aede3566614529e919252c6a1.json  (1行)
- 2260a9ff083a8b75a07243f019f4f1d7.json  (1行)
- 233398d6aa622bc4f9ffef186a0a3a72.json  (1行)
- 234c73b9473164ec064830614689137a.json  (1行)
- 23dfcc11a3dc2d10099082a911e0da91.json  (1行)
- 23e5029a6919d9a721fb98492a2052fe.json  (1行)
- 23ed8553b4883a9a56a405e0672f737a.json  (1行)
- 24317f8acc9b1b617da5035faf9c6d22.json  (1行)
- 24fc5267faf7561f58cdecf3d9389143.json  (1行)
- 25de8f6c253e72f1629b4e079a768a86.json  (1行)
- 261efc4ba5dae62e117d5c02c248694c.json  (1行)
- 2676da792ca362562ba0d5d7a99673d5.json  (1行)
- 27043c4f38a673ce3be250d10000752f.json  (1行)
- 273c4a5854f3aad5c1465844adb87845.json  (1行)
- 27a2c4238f50d4a4662798167400d1a6.json  (1行)
- 27c2fa0e0fe4b4c9c4efbf7f715a975b.json  (1行)
- 288571e84eb31a9e46c386403449a616.json  (1行)
- 289add36ee7319df0e234f6f9dc24e32.json  (1行)
- 28bb4339c8f4ac16b6df0f7c93c3df59.json  (1行)
- 28c4a77e77c729f9b8358f054f539952.json  (1行)
- 28e228d547431d7c6e59168c619706ac.json  (1行)
- 291c63dae04801c6c36e03f578931d80.json  (1行)
- 299233cdc66e74990dc41728029095f9.json  (1行)
- 29ffac7d3c19e738ea8befd3a8123827.json  (1行)
- 2a06b3fe36b32dfc404998dc93992a1e.json  (1行)
- 2a5e1dcd545b904f2d9463e7abc893a7.json  (1行)
- 2a5fca1df8ddaab92ab44523aaa3db35.json  (1行)
- 2ab7470d0c0c5843004a545850798718.json  (1行)
- 2ab888107977f3bc202217c22df76d5d.json  (1行)
- 2b1638e0620c740b29bde686b1cc62cb.json  (1行)
- 2b3e2e5ec8623572000075e3837094fa.json  (1行)
- 2b4924713b983a6c57ac85bfe96b63a7.json  (1行)
- 2baac5d8db239ab8c2429d357f5cef94.json  (1行)
- 2bde71ec3f57e2c004b5efbcc3b2593f.json  (1行)
- 2be5f40d3c0d06457ede48d876166f00.json  (1行)
- 2bf1ac64a19465d7893f50e05c8e3c7d.json  (1行)
- 2c492488de5f8e9950df82dee1ed3294.json  (1行)
- 2c8025e225054fd8fa621412f5e5b965.json  (1行)
- 2d308eb7900553358d24c6c61d4fadd1.json  (1行)
- 2d39db39ffd44c41955b47500c64a65a.json  (1行)
- 2d7615404b1c0033d9da6a6bb173e7ba.json  (1行)
- 2d9d5ca1a15c06fda1122d1ad1b842d0.json  (1行)
- 2dc73abf390315a586694d753f585ebd.json  (1行)
- 2e0a35061928f1e369060fecb12f7557.json  (1行)
- 2e28f8131819ec741cd201677bc2e58c.json  (1行)
- 2f6fdf25ffe03d14219d04e051790241.json  (1行)
- 2ff52cc46b95f421b633d13e8431df18.json  (1行)
- 3077b53e8e10f83b058db5921bc679fc.json  (1行)
- 30910a4cc022ab07a0036bd2d4f8c8f9.json  (1行)
- 30f8b75f2ae25c9795ac547c2e8e1450.json  (1行)
- 3131d68e11dc7f2299fa59b089d3c6dd.json  (1行)
- 3149e8983002ef54c9cba546412fce84.json  (1行)
- 31875b1f6c9c4c9cd53de95cf01fe5fd.json  (1行)
- 3208a88d67ad6570ae3820958966231c.json  (1行)
- 327e59a31095cf9ec33be599c4b80388.json  (1行)
- 32ac3dbbc72bd488a544cf3bf75d4f70.json  (1行)
- 32d1a37809a24af8a008cbb93014a335.json  (1行)
- 330063d2a6d160ee509743a177f40a75.json  (1行)
- 3315e6c1e0f8ca05667911d6478ae9d0.json  (1行)
- 336e719f3bfdfa3dfad33e99af6e96bd.json  (1行)
- 336f5441cab03214c1b2429d05ef843a.json  (1行)
- 33800ccd0cef3590a4f63051d09ddfd3.json  (1行)
- 33a82e80c62905e86774043f1f675049.json  (1行)
- 33e0ac41d3b46eb1396ce3356b967438.json  (1行)
- 348133467decfe69809072f5e8f11d16.json  (1行)
- 34ae60a1b5a76a4fb5ade8321cb8813a.json  (1行)
- 34bdff011dc0a4c17408ab684acf22b6.json  (1行)
- 34f8ec2e0b6fb57f66062645c54f69bc.json  (1行)
- 355e2218f238423954a81b6e7513169b.json  (1行)
- 359f9cb1c7005931b0846c6e782ebfe9.json  (1行)
- 35aba211858550e8ef5a1deb15d12f18.json  (1行)
- 35efc92c4eb92dc8c5d5ab140d32b965.json  (1行)
- 35f463089f1bfc1fe822f0e6c0126bad.json  (1行)
- 362f0690765311a339e413bf48c65f3b.json  (1行)
- 362f78697efd26e4138ef2b3ab467fbb.json  (1行)
- 36908e8fa798e2e3387aac901c1a278a.json  (1行)
- 377008af31d267bf8710c2841796b27e.json  (1行)
- 3779858b9ff2098ad7cb0e6bd3716913.json  (1行)
- 379634121c893c65efd7c84e01e8c87b.json  (1行)
- 37b07bf3fd17a8eed221d83e5c5bb41e.json  (1行)
- 382f8d9a469d61853fa93c7ba5d1c106.json  (1行)
- 38d35a17b919a628a0375d3cd0dc2bbd.json  (1行)
- 392bdf7c4300b267168b3483aabc1f4a.json  (1行)
- 396acc414c0f7e51524dc889c2aba760.json  (1行)
- 39d27a99eac67176e9621402c6c68986.json  (1行)
- 3a190c66dac22571f6d71c1b463efdb2.json  (1行)
- 3a3465861336d8d3699c91a018acb246.json  (1行)
- 3a54b070c2425bdebb4f191c0199495b.json  (1行)
- 3a6f9b94b92c1d7c662145688ee9378e.json  (1行)
- 3a840117e4774355cbef4bc3765ab913.json  (1行)
- 3ab6716bcec82340763d22a05e8950b6.json  (1行)
- 3ac16282692616972d942e741b05a0e1.json  (1行)
- 3b21c225d67f4a20ed1bc44b5e3ae54c.json  (1行)
- 3b86ac9c15423fed95d0147d07e948e5.json  (1行)
- 3b8893d9b440dcad20664e0837f04b76.json  (1行)
- 3c03299ea1e7651b1d18ab16f1e5095f.json  (1行)
- 3c2a464423104c5da68a9ca83d15ad48.json  (1行)
- 3c4d4462fa2a38e444f56d5125b3963c.json  (1行)
- 3ccd873146cfe8afa604dbbf14970af4.json  (1行)
- 3cddd79f4403a682ba550886f3a68f68.json  (1行)
- 3ce3b08cb7117de8947727695ae5ad58.json  (1行)
- 3dd8972fac2bc290e57c5d968f48aa3b.json  (1行)
- 3e0129fc62d7d3e6e9937f23ed0f10d5.json  (1行)
- 3e0be80a9d1409362f63d90dc12f7ed4.json  (1行)
- 3e2202ee7401164275cbfe32a7c50c11.json  (1行)
- 3e42d081e0eae57b184199752bb7db07.json  (1行)
- 3e609b2527aa00211564907c10ebca56.json  (1行)
- 3e772f8294c55606662d7afd03badd25.json  (1行)
- 3f2598090b52462ff6c49a7b769f7ff8.json  (1行)
- 3f2b666165466a333c4611cf5107d8f2.json  (1行)
- 3f5d02ebcac09fcba09ef28750af4750.json  (1行)
- 3f966175100b9573ff63cb6b3457fb9d.json  (1行)
- 3fa92d18a737b9cf55bd0b7b6fbf6cf9.json  (1行)
- 3fc06fd91f580780472229d11dcd9a62.json  (1行)
- 3ff6ad8c552c847b82c802025fddab49.json  (1行)
- 401c774b973a964f460d121aee0ca8de.json  (1行)
- 406a23f6334b438b7e1ca6521076f039.json  (1行)
- 40816a5795e5595a31e03c5f02102416.json  (1行)
- 40a8487e20e976339636f918a630549c.json  (1行)
- 40b32596f7243590b964ab794065e8b1.json  (1行)
- 40f64246f15cf8b316af88302dc897b5.json  (1行)
- 41f340f60f535d63529589d01e4f7fa5.json  (1行)
- 426674a64b3794d03a51ca5100e7d225.json  (1行)
- 426dd5a3d1169aa79da8b60687c79e1f.json  (1行)
- 426e2df8d57be29ec9e9f7a367de0e35.json  (1行)
- 435ec7834dc68870779ccd88850614b9.json  (1行)
- 43cf1d3929a5b0a10b30d29a2f744636.json  (1行)
- 43f7c3df9ed3fa1994e5de9f6ebef1cd.json  (1行)
- 445042d9ca3bffae84821f1968a49fd2.json  (1行)
- 44cc5ab00e8e5c8e064765b4c1d8915c.json  (1行)
- 453e079a5cbd9205798ef1e1c2393496.json  (1行)
- 4541da8a65f604403005e67d24e38fa1.json  (1行)
- 4543238daa3b305b440ccfbb7c92549f.json  (1行)
- 45e3be05b950c372c5aa830bdf658ceb.json  (1行)
- 465ab1b25b9761b784350986867cb1ec.json  (1行)
- 46646582c65bed674738654826498764.json  (1行)
- 46914b93b2f268bccc4918d589987898.json  (1行)
- 46b2a93e6437b98df08e71c1980cf7e9.json  (1行)
- 46cd97aa4808a6a3a702c8a276d74e93.json  (1行)
- 4793e79fcbc971b954ba1552f64c7112.json  (1行)
- 47c740f7bae0fa505c1c8b81dd7aa5af.json  (1行)
- 47e182c01c392478dd85e16e3993db98.json  (1行)
- 481e2733284d08be88b41224146ddc35.json  (1行)
- 484d7d8aadbac70bb767835af4094b5f.json  (1行)
- 488cd4ce29549c3199c706ed96145d53.json  (1行)
- 48915a7942a7d1dcbdd3700c38387de5.json  (1行)
- 48930e81e033d959dbb42779301791f6.json  (1行)
- 48b2696364ae770c3982c759a59c2b85.json  (1行)
- 48cbea18cf8ab10ab88442b0acb02610.json  (1行)
- 48d4aed8e6a247f46293eb2a998d5165.json  (1行)
- 4900910f041d1759cd022d367aaba6b8.json  (1行)
- 49043e4b2e226cfb0b316fd032055247.json  (1行)
- 494916a6cf54a8d6f633af5201b46e16.json  (1行)
- 49cb003a2fe230f8f5700a0d221fa95b.json  (1行)
- 4a63bdffff65faa13f9984f687ad79c6.json  (1行)
- 4a8cb352c11f010c2d5a50dd414722d4.json  (1行)
- 4a955b041bf11af4f2e815c6d5655acc.json  (1行)
- 4ab16df3e9523aa12e79320e32848c76.json  (1行)
- 4c2ed820eada3e2a75aa4c89734b67bb.json  (1行)
- 4c5cec56a5d8fc932447afcd94f10ad2.json  (1行)
- 4ce9b9f6f5eb2b63726c3c1d8676a791.json  (1行)
- 4d12c103a7251206e3b2b647cc896e72.json  (1行)
- 4d13e3f1b2981f9639ba67d5e5fff961.json  (1行)
- 4dd36c0b7bfd8372bc146b3eea27d4d1.json  (1行)
- 4e1313a9511103fa980cddd3baac9d5c.json  (1行)
- 4f37ea209ae3b5ad6a3382141d1c6dd2.json  (1行)
- 4fe574b940915ae0869db89efacd71ee.json  (1行)
- 5002bcadbb9abb90bfa2c4b08452f97c.json  (1行)
- 50ee3336b410861fbea24bc1f08b23fa.json  (1行)
- 5109a220e719702cdf8fbe32ac391fd6.json  (1行)
- 515cd9b64846835018f1f70358f83c89.json  (1行)
- 52214382aca0464bcc1a9b41339c525e.json  (1行)
- 527ebb38921ebfc709560180b58da082.json  (1行)
- 528b64d09ba5a6c808c28e470d1776b1.json  (1行)
- 5305ceca0709f592454fc60ab8dad8d5.json  (1行)
- 53278fe1e845a65b163333931fe9d01a.json  (1行)
- 533a66cfe15670de21adff3184b40ecf.json  (1行)
- 5355ec5d10e10b7ee51ad5f9aa00b5f6.json  (1行)
- 53bc29eff62ad52cf00109479fe17eb9.json  (1行)
- 53cd5d788722323b26a21a394d413592.json  (1行)
- 53e038af2f84f5dbdfe622373754a669.json  (1行)
- 53f4de6c475791c44c9fb6054708b678.json  (1行)
- 5423f0085b9e9c65d02049bb00464707.json  (1行)
- 5440d863fcc738a1d9a9fd4ab9858624.json  (1行)
- 545ef614f534fa7e6f5d320d15e9e15e.json  (1行)
- 55137359237d76772e6b10fb1e560191.json  (1行)
- 55149b24d95c47b4297f9910b9cdb414.json  (1行)
- 553bbed614e367ea9abf43ca7bddf1de.json  (1行)
- 553e64bbe7e90d3800ade54a526fabef.json  (1行)
- 55586751fd8d55d5e0bbf409b4f4dd84.json  (1行)
- 55bf9e60d7c7c50e2291690353e13ce9.json  (1行)
- 55eb0175a4ce485acc0d6df6b64e35ee.json  (1行)
- 562fd073046b747d1c6b6cad10642de9.json  (1行)
- 56fa73e5c65691360a89a692430e1c33.json  (1行)
- 5703ece96e89f8c0b64ba4dfc1e7e617.json  (1行)
- 57523b00252eb94beb2272bdfe630c8e.json  (1行)
- 585589f043e4bcb2b2f879efe3bb05d4.json  (1行)
- 594102a3a1ee73b8386ba0e93d466af5.json  (1行)
- 596d142add307363ae1f750d701b8390.json  (1行)
- 5a2784cc12138cdaf74facfbe6166d06.json  (1行)
- 5a55e92a76360500bc9c4493cd27eb7a.json  (1行)
- 5a6fe70635c10b61806ee92c5e90a0f2.json  (1行)
- 5ade176c15e85426284265078e24478d.json  (1行)
- 5ae2bbb3de0c02d299a39e75766f3c34.json  (1行)
- 5b061f245b9293361c6098f88484c134.json  (1行)
- 5b1d7c549e9a1ed6e74e89284cfd4784.json  (1行)
- 5b3c10d88662cb61aea11195ae411752.json  (1行)
- 5b4c8094a44e8566705ff1188be24e72.json  (1行)
- 5bbde28324514a324b6c0ac09d220463.json  (1行)
- 5bda08419d0e0ad5731f48b640264200.json  (1行)
- 5bdc204fdc81616499e05ebfcac40c81.json  (1行)
- 5c29d1cf66b317eb228c773ee82cbf49.json  (1行)
- 5c4ddefac397a3c109ace3b44f1d4822.json  (1行)
- 5cc7e2e2c9fbf5cbfeba51de9e4d4d37.json  (1行)
- 5d1560289b0d46726394b9a07b14e2c7.json  (1行)
- 5d27b3e1fbd0053de982fae6c77a4b4f.json  (1行)
- 5d5978a7a32a89c06abb7d07e56ac142.json  (1行)
- 5dab58f0705e255249ea7537ea4e8a28.json  (1行)
- 5e110e42197819e72e3bff63f775fec3.json  (1行)
- 5e33caf5aedd3fea85ecfbf4db28991d.json  (1行)
- 5f140a6356a1b659823d1e3c90d756cf.json  (1行)
- 5f35d87c10853cfad708b90b6dd42f1c.json  (1行)
- 5f74255e8865a7443b86081d41b2a654.json  (1行)
- 5faf86411d55f0e17f4bec9b76c0a2a3.json  (1行)
- 6030b632cbfb4a547a93162266bfa712.json  (1行)
- 6036effd1f60980143892f9dd1e25f6f.json  (1行)
- 6064e262f866593e379b74f9bebd2ebe.json  (1行)
- 60654c2be25dfb41ab33d545755416f5.json  (1行)
- 60e885c01bc170cb1cf74f8adcaefc28.json  (1行)
- 60e9721962897bc2885db3b099bfc678.json  (1行)
- 612406b2a1f7c1839a8b5ab43f01db74.json  (1行)
- 61259e10549210655173f8cbd4f4d0a7.json  (1行)
- 613750cec4946cde5c0b062358d27621.json  (1行)
- 616c64a825e4dc28a1df72a140cf1174.json  (1行)
- 616d24798766e7af76f32da81273b8f5.json  (1行)
- 618788450aa93836a56ce7f6328be430.json  (1行)
- 627ea1c4f85b0fae7b568dff696f81f5.json  (1行)
- 63381dd590fbb50a898d1cee60f24788.json  (1行)
- 638028c73600e4e69b42a2a914ecf899.json  (1行)
- 6380620ae937aba8561edfcfc768014f.json  (1行)
- 63a0d841d0ca08bac23fb3cc2d1343ab.json  (1行)
- 645f62a962051768834c5bc2305e1ade.json  (1行)
- 6472e2237949d463db2f69426347bd62.json  (1行)
- 64b5d273b13125c29d60469d68d3d653.json  (1行)
- 6529aa016f459ea421668d54d53c04c7.json  (1行)
- 653d2a00e5eca296bdeda10af3b1eea2.json  (1行)
- 6550be5d12525c2806340fc11d72dea3.json  (1行)
- 65614ba259c53f810d2e51dd82e04453.json  (1行)
- 65b3d1859cf4ad26afe7d80b31861a34.json  (1行)
- 65d79c0e94a6d971107576474a35de92.json  (1行)
- 663ff6c0b28b6601dd118116aaa67126.json  (1行)
- 666143110c39093cbda4628dcd3712e6.json  (1行)
- 667ea163be637fb1860c6c931837781f.json  (1行)
- 66a545932a1846a2e10ebda923d42e07.json  (1行)
- 676105421170e1e748864f8558bfd660.json  (1行)
- 6777fce8e0ba52b67e0f14bfa368cee3.json  (1行)
- 67dc7f45b9b258a3c242aded5e31fca3.json  (1行)
- 68258f4d2f79d69dd303c5c481adac75.json  (1行)
- 687b35a1790ac2cd4c86e71e8309f341.json  (1行)
- 68be9d4ea54991ddc8d7c25c9f5736f3.json  (1行)
- 699b91d7966a5d1fe96296ba06b8e4d6.json  (1行)
- 69a0a5a1c3a196249aca0979e10ad0a9.json  (1行)
- 6aa315d4327813a0bdc6faa7537ac71a.json  (1行)
- 6ab58291381e9c6175921c83bd254441.json  (1行)
- 6afd4f2f5b74353a71131f49fde34020.json  (1行)
- 6b187bf0a6558e3d7b0a2a23337f3c21.json  (1行)
- 6b195bcad5fcffb15c9107a98aa5beaf.json  (1行)
- 6b5265cd77fa5e9b875bb2d161bff8c1.json  (1行)
- 6b582e2aa140085eda97cce62dceceae.json  (1行)
- 6b8828d9b182cd35de52cfb443632635.json  (1行)
- 6b8f9994a4b54c0982649b6b5b904dd6.json  (1行)
- 6bb5c696687babd07393c69565f904da.json  (1行)
- 6c1b75cb9ad8b3172068a5f4f4a34da1.json  (1行)
- 6c2103558c58591f91e49dced4fb55f4.json  (1行)
- 6c45a7bbf81e329103f6a55c3af1c6b2.json  (1行)
- 6c6bdc9013eba62bdfaf164435c4c094.json  (1行)
- 6c7e121d382a358776234b4d90950ae9.json  (1行)
- 6c860314b1e9ed29cdb6dc11c145b0af.json  (1行)
- 6cadec72b907b0cd377472149fea1813.json  (1行)
- 6cb8158ff8d15b6c5ace9f96a7af75fb.json  (1行)
- 6d5589a0863a4190c611acac61b64ffa.json  (1行)
- 6df526ca3ca48d068d5d5cc8e756f0a7.json  (1行)
- 6e2b85d8d8ce125e7dce82ea38f59fd4.json  (1行)
- 6e31f782d62a509b4b5e900791573fac.json  (1行)
- 6ef0d947b16e3c0257463242bebcfe08.json  (1行)
- 6f059df6513387df273b65fa47cad203.json  (1行)
- 6f16d4721671f5f2cfce2b8aef2cd0ef.json  (1行)
- 6f526a0b3cddd6ca5a99e89d6fd2093f.json  (1行)
- 6f68c86026f99c37043d49429df96805.json  (1行)
- 6fcbe8644ad61edc3d1af89e707aa722.json  (1行)
- 6fd9783d6420e98e9101c46701eafbbb.json  (1行)
- 6fded7f23114e93da1ff7998b89baff4.json  (1行)
- 702a51af87ffff7fca71a33d6ec856ee.json  (1行)
- 708574d202c277fcfe3b83c02e9c1838.json  (1行)
- 708ea5d74fc92deae53866c9292b0e98.json  (1行)
- 71113ab1ed48a13593d46b49bc178a8a.json  (1行)
- 718cd759c9111b80a045c667d655952a.json  (1行)
- 719c4040df70200861f804c18c619f76.json  (1行)
- 71b6b185a09010460e5a6bf845b0351d.json  (1行)
- 71cde3e5542aa4b1fba9407eb4eea399.json  (1行)
- 71d5f1a1b33246035efd7de172e32278.json  (1行)
- 7257c3626063686f145ad7208b32bc9e.json  (1行)
- 72aedf17e3caf90ae7182c6fe0ed328c.json  (1行)
- 72c7a0a0096c548085a2d6e9997899c4.json  (1行)
- 72d6c93fc1538dae054411f0ade7942d.json  (1行)
- 731018668d72946023ab0fae9086a77a.json  (1行)
- 732900f494722db631f07097b5155460.json  (1行)
- 7335d7217e46e97bd604d1637e5e3704.json  (1行)
- 737af39aa42183e28ba8777af39b68a1.json  (1行)
- 73d34c93fd389308a96e0ee1d8d32776.json  (1行)
- 7421068910201f0e3cca7263dfa46b5b.json  (1行)
- 742e24811a558c858a4eccc271d039fe.json  (1行)
- 7451ece36fe9b58c65dcc9c575889616.json  (1行)
- 7488ab207c246398b4292036c5466bf7.json  (1行)
- 749930d4229e0e3424126796d65f0d2e.json  (1行)
- 75024d661befc21cb65f6776b27dea15.json  (1行)
- 7512979cbeea590f3acf6f6e3e135928.json  (1行)
- 75460df43c673f36770e423c59b4b89d.json  (1行)
- 75915bba61a03fbd83f140684c575f96.json  (1行)
- 7599390bcb45f58c863a36e15940260b.json  (1行)
- 75e67085c6f5433c8487cec0092d37d4.json  (1行)
- 7625ffe711e5f175b413c2861ce49356.json  (1行)
- 7630371f3e724d391639186e783cdd98.json  (1行)
- 763bf27c175423c08a8c8d1b5f5dd95f.json  (1行)
- 7738a7d6e4c7b49eaf5757e31fafe673.json  (1行)
- 779e6f8fc65b69811c8b4ecb4cf47112.json  (1行)
- 77d38b568870725a937067e270c32e2c.json  (1行)
- 77e3894f3558aefbd32db0888c834e2a.json  (1行)
- 78178121e4d6f8a24533b2ce306024b2.json  (1行)
- 7838ed46ee54f9b2b0b98f2b5111682b.json  (1行)
- 78fe004217e5c56a782bd287b8c43a7d.json  (1行)
- 799d4c8a61e065be58ca5bc732718212.json  (1行)
- 79b88cf03280cb89d1df69fc227d2e2d.json  (1行)
- 79c1e9f4f17d89097492169957cfa708.json  (1行)
- 7a3d9efbaaef18ab299050822b5f6842.json  (1行)
- 7a862297e14bb4499b9e9092a4837c1a.json  (1行)
- 7b35a644451d003f8839ff5bd33fb9b9.json  (1行)
- 7b4ad71085f25d3d6105e180a8a7fc51.json  (1行)
- 7bb11dcd7c6e58e7bc7702c12eda99f4.json  (1行)
- 7bef70c1cdd6d6c4234c11f65473cbae.json  (1行)
- 7c332fb96f7bac884133c92cbbad69c6.json  (1行)
- 7c99bcfb8b024a2a0d7a559af2844b7d.json  (1行)
- 7ca12a8b5d312ae284a485fc9d109277.json  (1行)
- 7cd8d4b8c9c365fe7e643ca76dec9b78.json  (1行)
- 7d0e7fa06b06457813e1a765873debd9.json  (1行)
- 7d5f01f5097544bfcc1c2484b2cf0a79.json  (1行)
- 7d78c7aba9b62929823a48f5331ac9a1.json  (1行)
- 7d88b2a788c24e5ba5077706f5d3ce30.json  (1行)
- 7dce971110ecb73ecbd696f566dd5bfa.json  (1行)
- 7e1686597925939c386691ffd3adc474.json  (1行)
- 7e2b1940fed11087fc29763733b8087d.json  (1行)
- 7f01ef6f9ad9d0ee10648c6d6b9830c2.json  (1行)
- 7f3d491baf191495f358615e92b4e024.json  (1行)
- 7faca8d33bdfa8636feddaa35020c427.json  (1行)
- 8020e1625bad2ab95b1af399c9b06625.json  (1行)
- 809443fb8621474f8702c60631c637c5.json  (1行)
- 8124e7fdf7adb04617a1e639d44c5a5c.json  (1行)
- 818a4049e777d51df2e0abfda5d74df9.json  (1行)
- 81a5035d2bf952bad7cfc7c890390f93.json  (1行)
- 82f6cfeb9a72e82438417ff49b61d28b.json  (1行)
- 835ba1efacd2fd41889e7f3f4638b62d.json  (1行)
- 839bfff48a367e512d74a7b1368d7209.json  (1行)
- 83b399e9e72938f43089a48db481ef8a.json  (1行)
- 842d3346aec52930777f1401dfb48f87.json  (1行)
- 8468ec2d43e54654347ecd33b3c0d834.json  (1行)
- 8495adfcb92e5a421495386e50a894e8.json  (1行)
- 8516aef5df54ffe26a5835c12e6bdf34.json  (1行)
- 853c8a889dcc6a0413eb327b5224384b.json  (1行)
- 8555993cfb0af3a53cef5b62a5132a2f.json  (1行)
- 857e204f22b6ee59393b93d3cf8824f7.json  (1行)
- 85ce8147f64012a49c818a6c872895ff.json  (1行)
- 8660742530b08b890737f7a264209a2c.json  (1行)
- 86790f37d8a3e393b36b6e9419a9a7e6.json  (1行)
- 86b09e265dbf4656f9d1208152b1938f.json  (1行)
- 87197f2e36f5a5dd46a52461d966427f.json  (1行)
- 87482544181a030aa31f286ecf386898.json  (1行)
- 8770706d095676232c72fe3d9113d916.json  (1行)
- 87912232dc6570d586ab4f59c604b3b4.json  (1行)
- 8791f8a1bc6001a3d350fa6256a1eacd.json  (1行)
- 880a2b44f744025fe85261919ba406b2.json  (1行)
- 883c81e5e54135d12c34628597a82390.json  (1行)
- 88b57b26ea273de0285e8547c24abc8e.json  (1行)
- 88bcc5940f7253013e0e76f0f06d75cb.json  (1行)
- 88d7671cd477e4e8f7517a3ff422b728.json  (1行)
- 892aef076470267d42f8688faa1e9001.json  (1行)
- 896235d56718271ce777370e8731c236.json  (1行)
- 89f9be5cdb3275246c2c5f76518af4fe.json  (1行)
- 8a320c00a1a62c874ef7e3dd22135e67.json  (1行)
- 8a808bf7316c8cb58d8822c67b63f902.json  (1行)
- 8a87dc1513eb138a59d730fa01c75c7f.json  (1行)
- 8a985179d38a04369920a9d8a4d0fc62.json  (1行)
- 8b316c794377590aeab7013739037327.json  (1行)
- 8b6bdd6e00411b26f67dd9639feb13b1.json  (1行)
- 8ba191ea4c7f08b331a627190be7235d.json  (1行)
- 8ba95844948760ed0f5bb91904235c8d.json  (1行)
- 8bacd1ca71fe991463491c751fecbc8b.json  (1行)
- 8c1f416c197642b1820db628ea67ea0b.json  (1行)
- 8c3c82a435e4778a5c343dafb42ecc67.json  (1行)
- 8c8a1512250cce7ed8edfa0010be7be0.json  (1行)
- 8c9a7ffc3996b2f4de6cbe1a26cc8a0a.json  (1行)
- 8ce8b7bdd1624d486ed5c386dfdc2051.json  (1行)
- 8d18704d354b78b30fc7bfb2f7c81dd4.json  (1行)
- 8da919f28569151664e6a48bc52a673c.json  (1行)
- 8e13ae476ca2b162b57b6428e393e5e9.json  (1行)
- 8e97ec50ffc776be124dab920f410e05.json  (1行)
- 8eaaf455df5ccec816f7c7d2b3cc3677.json  (1行)
- 8ee8d9792742f3bae30579ab47a1720e.json  (1行)
- 8ef7b6a604f1e180a56b908a07801b78.json  (1行)
- 8f029556736fb6d86338b8e87b34430b.json  (1行)
- 8f7251eb8e5b92500aa7abc86171266a.json  (1行)
- 8f8793d9368372d94c39a68a1d9134bc.json  (1行)
- 8fb1448e73c0a51068827165f19a630d.json  (1行)
- 8fb764bfdcdd62932aa555e1982fcac5.json  (1行)
- 8fe1bca6fcf5ca504740b3c4f3cccf00.json  (1行)
- 9006cb9716875e9573fa6df376edd552.json  (1行)
- 915332b58991c250bbcb1b4597a4327b.json  (1行)
- 9155c39f2a9815eb9224680e7d0afeac.json  (1行)
- 915978b06bf5e93036d3d5562945c31b.json  (1行)
- 915bdf74131fcb9583cc96283be35bd6.json  (1行)
- 916fedb3deea4de50cb3e105159e8f67.json  (1行)
- 918ab57a964d6ba63ed61b76c38d7774.json  (1行)
- 91a0b7c11d59500beac06c4e1414135d.json  (1行)
- 928435000b487c2f6f1e9ff67edee681.json  (1行)
- 928bbd738a02f56e5bb1d2f9397194dd.json  (1行)
- 92a07895713a9b7597b32f06188f3613.json  (1行)
- 9317e449534abfe379437d77a3659ba5.json  (1行)
- 93ace54319a344a643c7bdadfbd149dd.json  (1行)
- 93adf7a626683254d338c61d065aaa18.json  (1行)
- 9404477fc5f7f46e67a0a9bc76330c1f.json  (1行)
- 94101919c2e2f904a8784e7a513fbfa7.json  (1行)
- 9494169abcbb4a59e0b7750b55897d79.json  (1行)
- 94d5e9a9569fa279b2890fb1ade6c5c3.json  (1行)
- 94d6ad81738b1aae81f34c77e5c004c1.json  (1行)
- 951a285878ee7f59942761e6541fab70.json  (1行)
- 95485ec3fb1e2bbe023db8aa057c2bd1.json  (1行)
- 9558f3d9a746c8b6f5014ae4d5a71cc1.json  (1行)
- 95b204f1bb91778d8d16d60fe06df24d.json  (1行)
- 95d74956b22b09896b24ed3b643a039e.json  (1行)
- 95dfb73f4800154a7f2ddfecf1e55192.json  (1行)
- 9672bbbf4ad09abb9f915df6d7d4efc8.json  (1行)
- 96aaf42ef4e3c8c5b654b3e2964d71f4.json  (1行)
- 96e224e0828f281c3885620964a3e9d0.json  (1行)
- 970c08dde2ed3f51459c3d6cd7260149.json  (1行)
- 970dbb2b3c093744602c9d9e9b20445c.json  (1行)
- 97e94d7d7a0ed8c0b60f85fd4d0b2c68.json  (1行)
- 9830398c76d02a357924637b4e1e8c62.json  (1行)
- 9908e3392461d4027fd422f77653f723.json  (1行)
- 99281fbd549242120ae807be0bf6c882.json  (1行)
- 999c00d8b920b7d0c331cf57a9e3cc0e.json  (1行)
- 99bd31c2167c0eec62483020990f1d94.json  (1行)
- 99be801677de2b4fc9e399aab83d81fa.json  (1行)
- 9a264cd7d0a2c8dc0cd7f9899e1f9e67.json  (1行)
- 9b01c31892d1103e3bf15375331b4353.json  (1行)
- 9b2833927ea88ff17fa7e7149fe90348.json  (1行)
- 9b951e24c3e46308f6e5eb169e85dd1a.json  (1行)
- 9bbf3c772e10165da06ffa2a0b441c22.json  (1行)
- 9bd85e69ee77d1a9bd40e9a96888691f.json  (1行)
- 9bdba2a32e094e2914411cfe745d9f85.json  (1行)
- 9bf8f46562fab70318b9734767162ec0.json  (1行)
- 9c4bcb292edf9eb17ee812071d6c18fa.json  (1行)
- 9c79d46fab0bbdb4937c2c50884b3856.json  (1行)
- 9cb5530168098bbd3d60d9a2369161ed.json  (1行)
- 9d2f74f619b27e2111777b1aea2504e4.json  (1行)
- 9d3907d5d60b8ce0a3dc18d398c7c2c2.json  (1行)
- 9edbde930e94a1ecab870f5981fe60b6.json  (1行)
- 9efd58d5c652711d83ef96eb3af8340d.json  (1行)
- 9f4a4173ecfa427a5bc255eb9529472e.json  (1行)
- 9f559d61eb0d5b03998fb8bbb0d2dc5a.json  (1行)
- 9ff66f8fcd31677394af689e50eefc7b.json  (1行)
- 9ffe6931cefc2612a044199cf4e0e3a8.json  (1行)
- a0368f16d23ff65c871767b7736f0108.json  (1行)
- a0402e13aa09d29b7edfcb492b317280.json  (1行)
- a06cd361f7b4390d777ae84d4ae1cf34.json  (1行)
- a07c4a00ff93af71b1b2b2902f09380a.json  (1行)
- a0e266f2d13af1d143d0b53506e5973e.json  (1行)
- a1413e6b2a0b349733a2053e481ee59c.json  (1行)
- a168f37bf9f237c2be46a275bfa6db8a.json  (1行)
- a1af828b4e13d6513f1cf700166f0407.json  (1行)
- a1f3a8bcbb60b66fdd2179f81940e095.json  (1行)
- a2165080ae5eb5856347df6b81eec604.json  (1行)
- a231855cdc1ffdd82aeaef2dcc5037e9.json  (1行)
- a246f38b4c6eca42bdc71cf80f851410.json  (1行)
- a27d9151466b2cc75fc7b80c7e8e2846.json  (1行)
- a2b644aaee423794290113ada6fd6480.json  (1行)
- a304798e3d30b26be465b7a4d5911e25.json  (1行)
- a3138e80bb75f6339b8607ece09668a3.json  (1行)
- a37d3ecf8d5530cdc930ab41cf7409d4.json  (1行)
- a3d1005c11af98cddcdbbbfbf18b30dc.json  (1行)
- a3d4b6bd0a2c978e3706b799f5f06f08.json  (1行)
- a3ffa4c346226333361a3b23657f7359.json  (1行)
- a4d5dfeac38f909a697fdb75d21b081a.json  (1行)
- a4fa878e23b3b07bd1f94dc5ee7feca2.json  (1行)
- a5225303626dcb9741366c7e7ec4ff6c.json  (1行)
- a5343cf435db159e0735fcf06eb90a88.json  (1行)
- a54f1a9976940a6d83ed499621dceecf.json  (1行)
- a5944a1b141fcc0fb80ceee46fd2105f.json  (1行)
- a631c010f89e9b0c82e1d2281843b93c.json  (1行)
- a6402d364894401b659e9622470b17dc.json  (1行)
- a684082723987d975cf537f92742c605.json  (1行)
- a6dcd0049ac0a23e12bb3406018e2ba0.json  (1行)
- a7108cb7eca11ef7defdbf24dae6743b.json  (1行)
- a746419c623f47360d6c978a3aaa0580.json  (1行)
- a79f1ae05f5b98f70cdf0a61d2cc414f.json  (1行)
- a7b8333aeba91d319e65130a69e9df14.json  (1行)
- a87f279873b1aa12cc59f5613db18b72.json  (1行)
- a88e2018940a528c63d07a6884a44b09.json  (1行)
- a8c8747efe155659f8c191704a085c3b.json  (1行)
- a8c97a5d75e907822f1b34ddf2f65d16.json  (1行)
- a8e601a500271e893cc298a5cbcf2612.json  (1行)
- a90ab9532e21bc0feb188dc18e35e161.json  (1行)
- a92eee5e78e6e595224d66b31904f8a2.json  (1行)
- a9889b269891c40ebdaf1f23a925f979.json  (1行)
- a9d2141d8c6c790bce2ddd9c84158f47.json  (1行)
- aa243985b570e8fe197f782143e28c63.json  (1行)
- aa57f15acc2a86cdcf776563293f9e5d.json  (1行)
- aa6d5166cc4d85707f70e2d0f57e6990.json  (1行)
- aa7defd2ab9c087914b653810147f027.json  (1行)
- aa97ed5133142e95bb40a0caca20539c.json  (1行)
- aade644332a58d2aa0ca2c6df5d8a242.json  (1行)
- aaee451f461af7a7ebec70c2498b6737.json  (1行)
- ac9cd7a7c9f5ced620d061b18f1553ba.json  (1行)
- acad4abc40d9bf372c744abc5f2d4989.json  (1行)
- acfcc2a0e4668351d05d4375f1c2bb0c.json  (1行)
- ad17abb4b1ccf29d601d34f4c976dd83.json  (1行)
- ad20312bdd6d0618b81ba56b9ca8a876.json  (1行)
- ad7b7d37cbbaf734d6561856a58f260e.json  (1行)
- ada9174326ad8dd0fd0e7101fb898fd4.json  (1行)
- ade9c42e2a0434b60edd70d3d4286a76.json  (1行)
- ae0ea274eb3a890d3c99d6f681e56e89.json  (1行)
- ae1fca41e8ae36f25e1fb9985dc99579.json  (1行)
- ae4aea067aaafc0762cb1c866feb68da.json  (1行)
- ae59b6fc4d978ce85d6417807c5697a6.json  (1行)
- af80c43f524fb9cdd079f4e02c17e902.json  (1行)
- afbce3db89b08310eb42ddf176d14d7c.json  (1行)
- afd213846f5f6b628d228de7277744dc.json  (1行)
- b0c12d3cb6192dafccea7d7b94930f2a.json  (1行)
- b0f188e68d413940e14b59d6c2cdcedd.json  (1行)
- b15487fc081548cf80126573a030f3d3.json  (1行)
- b17ecb044bf1f043e0418a8fef53a5c0.json  (1行)
- b2b5f69589042d11c62777866a22759a.json  (1行)
- b340f9443ac43287f4cdcdbd6e0d3517.json  (1行)
- b3933b9b656fa0080e9079a501c7c764.json  (1行)
- b406077bc8452ab0d6c45e7d49cf6838.json  (1行)
- b41398d609a96da0b2f8d13302b93fea.json  (1行)
- b50ffbfd06c6f475dbbf0509ac247f9a.json  (1行)
- b52243a52035a1b6396c3f777de634bb.json  (1行)
- b52d40a120c24489724955bfead639d4.json  (1行)
- b535c2ee3bc295086fa84fd6fec879b4.json  (1行)
- b55ed2451061e0830589c1d5b03f694b.json  (1行)
- b5b1c7827246dee6fd9fea9ba9bb205e.json  (1行)
- b5c4e44c56a5fdfe87369dffe34daaa5.json  (1行)
- b5d8123d16246f9669991a45f95ce1f0.json  (1行)
- b5def55d3b19cb125d858fc390eb04f0.json  (1行)
- b68b3f44193d9320068a4548da2877c7.json  (1行)
- b692b5e708a6beea047fc6a71738b073.json  (1行)
- b6e0da29c931c6ff64287e5d69ae4316.json  (1行)
- b7b763999355400e890e74e5da83db48.json  (1行)
- b7fcc00c556b372532f80cef455c57c7.json  (1行)
- b849d590aa1a96c937d91c18fff0ddda.json  (1行)
- b8a9eaa00dfb6f142e63e9f448c216d3.json  (1行)
- b8fe1afc7fd82182d76136bce38abb80.json  (1行)
- b94b6894e6f8e5d6df9914cc39f7bb76.json  (1行)
- b962aa93617d4a71a738ab4f5703c655.json  (1行)
- b97cfd7661a6027602809da38044710e.json  (1行)
- ba69afec145aa812337df4b6ecf5666a.json  (1行)
- ba9b63529eaeff2b7e81e4cca2306a20.json  (1行)
- bae854e686b4ae70d67214ba59c5fc91.json  (1行)
- bb00402f20c54055ddc511bf04d6f061.json  (1行)
- bc1da3b01f6574eff15619d7aa830666.json  (1行)
- bc7502c88228d5d8a47e913bd38bb7d6.json  (1行)
- bc862553fce5aea8415b7ea06b98d667.json  (1行)
- bd536eb18424d625c8622712a206e8f1.json  (1行)
- bda75dea674fd5cf822680b2513e55fe.json  (1行)
- bdb2baf2a2eeae1d0032aa770ac9d4ba.json  (1行)
- bddfd3e645bcf8887e6bffde0ffe4c8c.json  (1行)
- be63181249be6ec72f6795463b8bd3ed.json  (1行)
- be8083a77847d1ed5abf3d2af878845e.json  (1行)
- be84a7a5412bb0f0b3db93313ff2a3c8.json  (1行)
- befb69f695dc84dd781265853d5405b4.json  (1行)
- bf35704e9ca100ad1eb180736d034182.json  (1行)
- bf543c08e9daddab2970dc0803910361.json  (1行)
- bff2823def620819663556b62611265b.json  (1行)
- c002f47ce062ef8aa3dce5894dd33c83.json  (1行)
- c01a1fc3a94397e05bf47cf134da8c8d.json  (1行)
- c0c2814fdda4c865c5eebd0d80988659.json  (1行)
- c10250efbf95230cb770b569075977a1.json  (1行)
- c1b60db1add39c73b9e416a956a708dd.json  (1行)
- c1dcfb421f21961d5d7ff887222b094a.json  (1行)
- c2b86a565883cf88188fd30309b7a034.json  (1行)
- c2c467a9812f596e654fc131451febca.json  (1行)
- c2cf647f705d9629c57cb4e9f2082e24.json  (1行)
- c39f7e5c16119014c37e95546858ec6a.json  (1行)
- c3b8ad18fe8f31f7e9648530c7a5e577.json  (1行)
- c3b9b9ceefee45129d132ab91a69164c.json  (1行)
- c3daedfc6623504605e1d648e1410632.json  (1行)
- c47845d9e9e263979cb7c9eb4357fdc3.json  (1行)
- c4ffa78c810439ba88546eb3e3e6a02d.json  (1行)
- c59ea67f0b6d7795a668f31ec362c30b.json  (1行)
- c5e1f7e2490c52a02a99e27b137a5017.json  (1行)
- c6135cbaeb57616ecea2457020b95cdb.json  (1行)
- c64a772cc1f776bd9fb8a212ef810cb5.json  (1行)
- c6ed293401ceff1e4d2f04fb9302783f.json  (1行)
- c7117ccb99be9e7dd08eeb7a799fb9f3.json  (1行)
- c73de43e5e0bda52d3c1153180bb876d.json  (1行)
- c7879da01a07a3cfb7878ea22dbc103d.json  (1行)
- c78ac036d42c0181f4b82835c675ed5e.json  (1行)
- c7b71cce8b92318ae7fb12d15256711b.json  (1行)
- c899692e5915601d9be90fa047767efa.json  (1行)
- c8ab4d59791c0cdf01f5ad0f207b92d0.json  (1行)
- c8bcffaa9e4e3baa86905d6c97359ef2.json  (1行)
- c8bf801566171256d63466c46f289666.json  (1行)
- c90de6625c4b582ece96eb28e6f482b8.json  (1行)
- c91eb38e3fbc40c2fe6b80abfea4bd7b.json  (1行)
- c97a8ebd75ac1cb64a084aa25fc79735.json  (1行)
- ca39edf7eab17c8051335775b7890a79.json  (1行)
- caa11230a3a17479f9383991dcb9412a.json  (1行)
- cb1e4fb96de397db879da366eb9a1023.json  (1行)
- cb451fdf23284fd030c9da6ce3737611.json  (1行)
- cb80204ddbdb6d45d7d11967d20bec90.json  (1行)
- cb925ed2947a4fc2810f9e3923d8bed6.json  (1行)
- cbc210d06633d2fe2a0f29eb868f5160.json  (1行)
- cbc6ff3e681058b626fe990dfc425295.json  (1行)
- cbf45deeb87009edcea38fc843ace12e.json  (1行)
- cc36c0bd125001bc4420301378d49d6d.json  (1行)
- cc46408098280ccd6cebd7e6368267ca.json  (1行)
- cc4df295bc101556afa47cc92f29a236.json  (1行)
- ccb8d73f1be5355ae6183ab502cd3e45.json  (1行)
- ccd8fee257c76ca93fda7740be969a41.json  (1行)
- cce1adbeb101e3350c98b3bbeac1ca14.json  (1行)
- ccfd9be90b155a3abd9c64c72d6556ee.json  (1行)
- cd545590f471a1d45f468841e57984ad.json  (1行)
- ce1a56e7e2c9862fedce7f02783564fc.json  (1行)
- ce78cb16158aef081a3e34fb96c4b212.json  (1行)
- ceae1f8998f8be0276a824655d6dc70e.json  (1行)
- ceb12c3df188e64be621d619b5519de9.json  (1行)
- cf4135b0619bc0003c63c1b2f1d189b1.json  (1行)
- cf9c321e28cecce45b9321f2e574a530.json  (1行)
- cfe742a52b24a86aefebd1ca133dd407.json  (1行)
- cff119f3ddc3926948e541c3e6b72e74.json  (1行)
- d04d398e2bd11ceacb1f2a948d03ff0d.json  (1行)
- d05250f3cb66047f0c0aeb2624e7fbc8.json  (1行)
- d06fd5b637459702b8e399bf03214456.json  (1行)
- d092a98000994bbed1dc381ae69b094a.json  (1行)
- d0b14b348d91932bc343ca37f33669b2.json  (1行)
- d0d5877a22ad900f8d3a9690fb57c349.json  (1行)
- d0ee774b0be2f3ed71f1cb849b3cb5ef.json  (1行)
- d134b75388da33a60cf31363cd290f55.json  (1行)
- d14d363167fc33c3658f90d09be36e0e.json  (1行)
- d19c5543e75e0890cadbce108ad495a9.json  (1行)
- d1a9fce10fea4b59fd0ef973572589fa.json  (1行)
- d1e278d3d3bb91b10c2d6b4f369a0174.json  (1行)
- d297d1b05cf0eefe7792bec6fff08cd6.json  (1行)
- d2a3e1dbf8fd65b0a0df9f3d4301a3a8.json  (1行)
- d2d586803786740bccb460aa0087a09e.json  (1行)
- d333f94893f4662bcbd3498760ab753e.json  (1行)
- d3ef05e33d3f8c6227059f62cc513c19.json  (1行)
- d464c7c28dcc97cf5c1371d96ff462d5.json  (1行)
- d472e38c5708fea196c0710151380e1c.json  (1行)
- d48c357bec8ce33917c947d98b67d7ff.json  (1行)
- d4b42a3cf846aace680648b9e9c12d17.json  (1行)
- d500dc6f206f7f919047e9d5e6c08b1a.json  (1行)
- d5fee50a0e7d676348eab95ac860df1a.json  (1行)
- d64516f812ad1a1d17e4465c90e2c8a7.json  (1行)
- d64ef2dfe47715b75df21fd3dc41d216.json  (1行)
- d65b40216d9fac1e06bfd2a4544b5423.json  (1行)
- d67b7a1d62abbf4ab085e79938781ae9.json  (1行)
- d69e09ead09b240f94067f7614ded587.json  (1行)
- d6db783f5631d5127b6be04fb7a94454.json  (1行)
- d6fee08e9d67b8aced4f8bf774e4c546.json  (1行)
- d77bb10c635025b6e8d5e45b0e43267e.json  (1行)
- d77f38c40e721bc63164992264418495.json  (1行)
- d78a78add60e27202c48d16a3d4164a5.json  (1行)
- d861c67b9d386ad599547ea1e1cb97ce.json  (1行)
- d865b68b6d0d28c549a5cb0660160e7c.json  (1行)
- d935951dc28d235dd9afaa2c7d5d3fdf.json  (1行)
- d97fd207d62975b5449c1317a3acedab.json  (1行)
- da16cc1b0aaa689a071637e3c864849b.json  (1行)
- da18b056da08014132d9b9c32263f79a.json  (1行)
- da6487fb5c244beb657fb4a992fe4326.json  (1行)
- da9032cbc3b67bf16e5fa1dd8dd884b3.json  (1行)
- daa75fba5f532e303961b07c987e7198.json  (1行)
- dabbae1b3a46239410b9f978bb73b5cf.json  (1行)
- db0f1551ad05131236518c2bf7cfc3a9.json  (1行)
- db21793abd32f982fe01d6790d6fa2fc.json  (1行)
- dbd0e51243d6f9352a90fe6e7e70c0a0.json  (1行)
- dc2c5472d173d7bc92f8180eed7346da.json  (1行)
- dc7f19c5b7370aae4d2aaeaaa867145b.json  (1行)
- dc970a6bed18c2a54a352832816c42f6.json  (1行)
- dcffc37b0ce9d020fa8ca700493dfe14.json  (1行)
- dda76c64f1362190ec2b0a516238c196.json  (1行)
- ddbabf46ce157fda59e39a6cf19fa2b4.json  (1行)
- dde63c542427158dbea33336879a0af6.json  (1行)
- de43fe5883e0e97866092aabf39dc160.json  (1行)
- dea3977521fa9133508df36f5095f346.json  (1行)
- dec8bf600849456047ccbfa5a431f0ca.json  (1行)
- ded9a1aebddd6cb632dca0e34a8b3db6.json  (1行)
- df2758630c4cdbfcc9395dd9ecefaca8.json  (1行)
- df89d5a0cd8933f9b099cb92e6ea26b9.json  (1行)
- dfcb7e730f6b466ef3d6a03cff5c3d52.json  (1行)
- e02e7917bcdd4f2856edfe37599d91d0.json  (1行)
- e03b46a67424f9748d986a65ce7d16c7.json  (1行)
- e096624e658818c05d9e0637487bf4aa.json  (1行)
- e0d02919de787a6aaab56ddbfe954473.json  (1行)
- e17a0c381825593ba38beca52a0e4033.json  (1行)
- e1af564c67efe11fe4308f2fb888ad91.json  (1行)
- e2a5ad25e55f21d6fd7dea855282181e.json  (1行)
- e2b09f46dfe9f167ec386907991e721e.json  (1行)
- e2b770465b91a60ed0c4e384b16ad624.json  (1行)
- e357236edccc643472e59f766c2fcd10.json  (1行)
- e3633f4b5409a4b9c1c20b905f9f7662.json  (1行)
- e394fc21301b9be1e26fd4c3ec5bc614.json  (1行)
- e3983b0ba9884cea778ee95a067e2719.json  (1行)
- e3a78b37f36a7177a87a819029ad7e90.json  (1行)
- e4b0a6708efb1529bbd3728e222e4454.json  (1行)
- e4f8b6bb5f2056786f1112b7fd2f176c.json  (1行)
- e5bd7dd100391ca3cd0f29b2359c8bdf.json  (1行)
- e5bf0332a496ce70d45fc36837cf57f2.json  (1行)
- e670fea7d01bf76f09faa4bf9b282c94.json  (1行)
- e69307fa047b0cd3734da62640810f6f.json  (1行)
- e7d779b1477ceba0ca9ad42baabc7e91.json  (1行)
- e7d902649eb6b2b1cc4b91787937bf41.json  (1行)
- e7f8914769546a12571385e614644644.json  (1行)
- e830babfef04f24530d41885905ba70a.json  (1行)
- e8b2aa6cd71369716728531bd2e80b4d.json  (1行)
- e8c5c8393f530e7ede179bd56dce7e18.json  (1行)
- e8e9690f4690b2884b7fae0e51088fb0.json  (1行)
- e90c2d5a9f5ad9788c42158d8cb765ef.json  (1行)
- e91809fd63023a46b763adfd20451fe6.json  (1行)
- e91a797fcaf8c647337f07de02ceec38.json  (1行)
- e91fd4b240e29d2397a6ca45233bca4c.json  (1行)
- e94331bbb3426d649ce613476910bde1.json  (1行)
- e991f087b36f2a8f91b53cb32852f802.json  (1行)
- ea1b4bf03d0f60e0820f5cfbf17fd9c7.json  (1行)
- ea8e2e7aa800685d245baa2fdade365b.json  (1行)
- ea92d02488c7f2802bf672f8753235a4.json  (1行)
- ea9b1de23d2114699259784351cc296b.json  (1行)
- eaacff740b95888afb4ab55e0f7726db.json  (1行)
- eab05169c5973150f5553be41840c570.json  (1行)
- eabc10685b398884b0aee100c2ce3e1c.json  (1行)
- eb67d66d4ec4269d6d4eb5842a43166d.json  (1行)
- eb67db1426be506bfd0665af9dcdbbeb.json  (1行)
- eb9df5e6563c252749be9b630561759c.json  (1行)
- eba747112d5776e1ca6f13cfbfd50caf.json  (1行)
- ebeab2b73f801c95f8c760c1183cea6d.json  (1行)
- ebf84eafc022accf6f5783354857b4b1.json  (1行)
- ec02433ac89549a80a67c29c573beb7a.json  (1行)
- ec0971e7827e8cd12c9888453d78ac7a.json  (1行)
- ec14a77c1bce2d006529a85fece004da.json  (1行)
- ec30e6654b60945a4ba770c037589c90.json  (1行)
- ec90594d05c5735e6e001f689f54f046.json  (1行)
- ec974afd26b577aaba2220f20a37b1a6.json  (1行)
- ecba54b65efd05f93f94291dc45ae7ed.json  (1行)
- ecc2fdb643cfa22f59a09f9ceed642d1.json  (1行)
- ed108626d248a59cdda37d684e665d8f.json  (1行)
- ed5e422c277ed98ab5a4087093959210.json  (1行)
- edc1a244e6135cb73d211bdf7c34c4cf.json  (1行)
- edcf9d7ac7ce4e762f2fb47458e77460.json  (1行)
- ee5f2062ed6bffca36ab847d5fcd787a.json  (1行)
- eeb340d882f9bdfbfb87c88284100a86.json  (1行)
- eec777f6c24acee017a6f0d5a043e5a4.json  (1行)
- eed2fe8685b23d2ed3679ff19f22f5d8.json  (1行)
- eee5a9371cc5af69f1d9faf50f47b2da.json  (1行)
- ef4a074c1c1afcccdd1befa14e213a35.json  (1行)
- ef6ad4cf1301490d33a2aaa11d9dc5ed.json  (1行)
- ef8fdfe3eeedd7aa9e36dcf616e4cc2e.json  (1行)
- efcd667a0150f8d993cc9c14f1740a31.json  (1行)
- f02380c30f58d7b868a22488ad9b03ec.json  (1行)
- f03954fcfdc28c27d99a89b25ae0450a.json  (1行)
- f0ea085f03bfe9dcdd82ba0cd7dea1b7.json  (1行)
- f0ff420ae82a9144eb269e69a481ff53.json  (1行)
- f10d2e47e6dda9d666c9cf208213af16.json  (1行)
- f1742a431023caf6cb773f63f68934fd.json  (1行)
- f1a0e2e1e86d9f5f619514352ddafbe9.json  (1行)
- f1aade2318932215be4507ece022cd51.json  (1行)
- f1ad0e9f942002828c1fffa0f7ac6680.json  (1行)
- f1ded55a7568e99b65b0addf808e9919.json  (1行)
- f1e4f31c59b63020864e5b46d52769d5.json  (1行)
- f25faa4fd7ec0a1a94f3a7afcf08ec7f.json  (1行)
- f272690c836ef818c7089415a91ecfd1.json  (1行)
- f286fbb2c4fc038a8140f45cbb931876.json  (1行)
- f35b875d217fa01ab501ab26226a20d0.json  (1行)
- f39488e2c9f96540a819d0e10162d9bc.json  (1行)
- f42ada75795873838d501a1b36bc9952.json  (1行)
- f466e979fa2abd9148a54416b79ae383.json  (1行)
- f49af7c314be9ebdf098e40ad3175a82.json  (1行)
- f4ceff6283dcc33b01d17daad3fc4be2.json  (1行)
- f4fa70a5ead0111f7086e9cf73344c81.json  (1行)
- f51c5ad7cb4c6ee8822f01a733514ba6.json  (1行)
- f58b2ff20b93c0aab9556987e7b73881.json  (1行)
- f5be4e3172ac973feac417ca1399981d.json  (1行)
- f5c9cdccce78985b28d9c5e9ff1d8d74.json  (1行)
- f661ec3e00aefdcc0914bd116736977a.json  (1行)
- f6efc395e06ee387de0c59298879fac8.json  (1行)
- f70b87c91138f87a281b501bdd358024.json  (1行)
- f71a1acdf6d724ea1f17f880472528bf.json  (1行)
- f72bbfaeccc43ec435fc477043f83deb.json  (1行)
- f72cfbfd211a9ec36c4f89fce58256e5.json  (1行)
- f797ec28fa10e0abae558b7fe4175f38.json  (1行)
- f86c37ff3f16080f0fb44b607c4736fa.json  (1行)
- f8d1008f93652e352e5ee35f250cd59e.json  (1行)
- f90d771e1e010f1c6c43d33cba2e3825.json  (1行)
- f9ad4427f3d356fa18616e6202cf16bf.json  (1行)
- f9b038e69a4258660a1f2af3cc30dd40.json  (1行)
- fab027f2a02aefb91babaa3d07c9872c.json  (1行)
- fab9a570a18fb7dbb5f5b0852f1e3dca.json  (1行)
- faf9ed750b62f88dbbce65808c4f570d.json  (1行)
- fb03b3d5f9e48750b27fc2d688922182.json  (1行)
- fb05d13b46875cdc751e71e251cbe667.json  (1行)
- fb146e59b3181619090a8b48961adaa9.json  (1行)
- fb4bbd20979b9729464b2af7c0c35885.json  (1行)
- fb609f8905481d39952dd5eb7e2dcd52.json  (1行)
- fb64ba03ef1b9a11d3f13005aece12bd.json  (1行)
- fbf6f8fc61e479d44e22cbf0381518c2.json  (1行)
- fc04f513d0e81ad0107d7b0599926c81.json  (1行)
- fc055293084005d2ce32ae92aa75b706.json  (1行)
- fc0d23e13d54f079456adcbab165542d.json  (1行)
- fc1cbcd29862a22068a7b0ba537e85f6.json  (1行)
- fc2733d88b9f527810bcc0f3215120d4.json  (1行)
- fc4d72adf677b81edffc3cac7d6eb686.json  (1行)
- fcc4bfefbada641151643ca7059c5a78.json  (1行)
- fd2392b83c8d1ac36975f0ed1fd6b262.json  (1行)
- fd60a642a01d14910745e5e9502a3fc9.json  (1行)
- fe274fe58cea8aaa483f52a8a6979a9b.json  (1行)
- fe705f67ab904950e34ab42c307bc052.json  (1行)
- fe844fba8659989933e751817eec2fef.json  (1行)
- fecb69420a31b0ee96ba3ed629912fab.json  (1行)
- fee4a084ee860d8ef497b694ae3a7e6e.json  (1行)
- ff30fd45765d431f33bf1fd780e5eaa5.json  (1行)
- ff64bdeffba18c936b62b403e756d12e.json  (1行)
- ff7108025b4cc5881519b443c87a8224.json  (1行)
- fff6cb0bf51f2903949f76c92619c634.json  (1行)
- fffcdf2a51fd4703bd5899d4720a58ff.json  (1行)

### 📁 backend\uploads\lectures\02.知识点精讲\cache\preprocess（1个）

- 8b5fd05119882e674b1ff39676a31b14.json  (1行)

### 📁 backend\utils（53个）

- __init__.py  (0行)
- ai_brain.py  (1235行)
- ai_brain_hub.py  (1015行)
- ai_config.py  (91行)
- ai_solve.py  (646行)
- ai_vision_parser.py  (354行)
- audit_logger.py  (216行)
- constants.py  (103行)
- data_quality_pipeline.py  (299行)
- db_migration.py  (306行)
- deduplication.py  (596行)
- deps.py  (29行)
- enhanced_ocr_store.py  (712行)
- error_classifier.py  (224行)
- error_handler.py  (67行)
- exam_analyzer.py  (341行)
- expert_personas.py  (166行)
- famous_teacher_mnemonics.py  (365行)
- file_hash_utils.py  (122行)
- file_validator.py  (95行)
- flashcard_generator.py  (570行)
- flashcard_quality_manager.py  (483行)
- formula_trainer.py  (411行)
- knowledge_base_answer.py  (201行)
- knowledge_graph.py  (344行)
- local_search.py  (254行)
- mindmap_recognizer.py  (554行)
- mindmap_recognizer_v2.py  (316行)
- mindmap_standardizer.py  (277行)
- mindmap_verifier.py  (272行)
- mm_parser.py  (294行)
- pdf_ai.py  (973行)
- pdf_base_processor.py  (2066行)
- pdf_parser.py  (2198行)
- pdf_question_extractor.py  (308行)
- pdf_splitter.py  (2883行)
- pdf_toolkit.py  (794行)
- premium_mnemonics_v2.py  (167行)
- quality_gate_framework.py  (276行)
- question_recognizer.py  (573行)
- question_serializer.py  (104行)
- scan_preprocessor.py  (501行)
- section_matcher.py  (207行)
- security.py  (26行)
- service_monitor.py  (276行)
- sm2_engine.py  (296行)
- smart_toc_extractor.py  (1476行)
- start_ollama.bat  (7行)
- static_hasher.py  (39行)
- study_planner.py  (635行)
- syllabus_tree_generator.py  (557行)
- video_mnemonic_extractor.py  (223行)
- water_case_mnemonics.py  (120行)

### 📁 data（4个）

- exam_config.json  (120行)
- folder_batch_missing_analysis.json  (229行)
- missing_functions_analysis.json  (1071行)
- requirements.json  (151行)

### 📁 data\ai\evaluations（1个）

- 268a97a786b4.json  (29行)

### 📁 data\health_reports（1个）

- 20260911_102633_health_report.json  (107行)

### 📁 data\offline（6个）

- exam_config.json  (260行)
- flashcards.json  (58151行)
- manifest.json  (17行)
- mindmaps.json  (4967行)
- notes.json  (331行)
- questions.json  (227573行)

### 📁 data\quality_reports（1个）

- data_quality_report.json  (627行)

### 📁 data\search_index（2个）

- main_py.idx.json  (1行)
- 系统设计宪法_md.idx.json  (1行)

### 📁 data\static_check_reports（2个）

- 20260911_101831_static_check.json  (48038行)
- 20260911_102633_static_check.json  (47798行)

### 📁 data\问题知识库（1个）

- issue_knowledge_base.json  (67行)

### 📁 docs（4个）

- 32专家全面检测报告_V2.2.json  (105行)
- 功能迁移检查报告.json  (266行)
- 全面功能迁移检查报告.json  (763行)
- 需求管理清单.json  (249行)

### 📁 docs\ai_analysis（5个）

- 00_综合优化计划.md  (152行)
- 01_架构分析.md  (33行)
- 02_数据质量分析.md  (40行)
- 03_前端代码分析.md  (93行)
- 03_前端代码全面分析_含文件管理.md  (82行)

### 📁 docs\迁移冲突清单（5个）

- 01_重复函数清单.md  (461行)
- 02_冲突全局变量清单.md  (100行)
- 03_函数分类清单.md  (496行)
- 04_通用工具函数清单.md  (23行)
- 05_函数分类清单V2.md  (499行)

### 📁 docs\知识库（5个）

- README.md  (25行)
- 变更管理规范.md  (118行)
- 踩坑记录.md  (106行)
- 回归测试清单.md  (88行)
- 问题解决方案库.md  (96行)

### 📁 frontend（19个）

- ARCHITECTURE.md  (28行)
- check_html.js  (12行)
- check_js.js  (5538行)
- exam_analysis.html  (253行)
- index.html  (109行)
- index-modular.html  (95行)
- layout-demo.html  (346行)
- manifest.json  (108行)
- module-demo.html  (199行)
- offline.html  (50104行)
- offline-data-cache.js  (641行)
- offline-init.js  (384行)
- offline-manager.js  (520行)
- offline-media-cache.js  (438行)
- sw.js  (106行)
- sw_v2_root_已废弃_请勿修改.js  (286行)
- sw_v2_已废弃_请勿修改.js  (667行)
- sync-manager.js  (730行)
- system-admin.html  (378行)

### 📁 frontend\core（8个）

- api.js  (81行)
- common-utils.js  (202行)
- config.js  (64行)
- data-service.js  (222行)
- event-bus.js  (108行)
- framework.js  (262行)
- module-base.js  (131行)
- storage.js  (196行)

### 📁 frontend\css（8个）

- components.css  (1行)
- mobile.css  (842行)
- mobile-tablet.css  (405行)
- style.css  (1896行)
- style.min.css  (1896行)
- tablet.css  (302行)
- tokens.css  (150行)
- V2布局规则_统一版.css  (457行)

### 📁 frontend\css\components（6个）

- _buttons.css  (81行)
- _cards.css  (73行)
- _forms.css  (125行)
- _tables.css  (124行)
- _variables.css  (79行)
- index.css  (28行)

### 📁 frontend\css\layout（5个）

- _layout.css  (134行)
- layout.css  (4行)
- layout-base.css  (1行)
- layout-pages.css  (1行)
- layout-v2.css  (2行)

### 📁 frontend\css\themes（1个）

- v2-theme.css  (1010行)

### 📁 frontend\data（5个）

- AI分析报告.json  (34行)
- exam_config.json  (67行)
- 数据库状态.json  (465行)
- 需求管理清单.json  (247行)
- 优化建议.json  (82行)

### 📁 frontend\data\offline（12个）

- exam_config.json  (260行)
- exam_history.json  (1108行)
- flashcards.json  (58151行)
- lectures.json  (12720行)
- manifest.json  (57行)
- materials.json  (1448行)
- mindmaps.json  (4967行)
- notes.json  (331行)
- questions.json  (227573行)
- syllabus.json  (5762行)
- videos.json  (14798行)
- wrong_questions.json  (31568行)

### 📁 frontend\js（11个）

- app_v3_897262.js  (34848行)
- feature-module-framework.js  (117行)
- global-subject-manager.js  (186行)
- mobile-adapter-framework.js  (180行)
- music.js  (244行)
- performance-monitor.js  (141行)
- resource.js  (11591行)
- system-center.js  (279行)
- system-controller.js  (312行)
- system-supervisor.js  (412行)
- tts-service.js  (256行)

### 📁 frontend\js\core（14个）

- api.js  (148行)
- code-anti-mixins.js  (170行)
- console-interceptor.js  (88行)
- constants.js  (94行)
- error-boundary.js  (291行)
- event-bus.js  (152行)
- inline-code-constraints.js  (148行)
- layout-class-mapper.js  (288行)
- logger.js  (228行)
- monitor.js  (480行)
- page-type-detector.js  (193行)
- pwa-installer.js  (558行)
- store.js  (151行)
- v2-layout-access.js  (347行)

### 📁 frontend\js\modules（14个）

- ai.js  (507行)
- ai_brain.js  (606行)
- common.js  (2276行)
- common-business.js  (1431行)
- common-utils.js  (1445行)
- file_library.js  (1313行)
- fl_bridge.js  (176行)
- knowledge_base.js  (479行)
- knowledge_graph_view.js  (602行)
- mm.js  (276行)
- mt.js  (397行)
- preprocess_config_view.js  (543行)
- qb.js  (404行)
- sync.js  (332行)

### 📁 frontend\lib（11个）

- d3.min.js  (2行)
- echarts.min.js  (45行)
- flv.min.js  (10行)
- markmap-lib.js  (11329行)
- markmap-view.js  (1670行)
- MindElixir.min.js  (8行)
- mind-elixir-adapter.js  (29行)
- mind-elixir-style.css  (1行)
- mindmap-dual-adapter.js  (176行)
- wangEditor.css  (27行)
- wangEditor.min.js  (24129行)

### 📁 frontend\lib\pdfjs（2个）

- pdf.min.js  (22行)
- pdf.worker.min.js  (22行)

### 📁 frontend\modules（1个）

- hello-demo.js  (125行)

### 📁 frontend\modules\admin（1个）

- system-admin.js  (499行)

### 📁 frontend\modules\ai（1个）

- ai-brain.js  (148行)

### 📁 frontend\modules\analytics（1个）

- analytics.js  (537行)

### 📁 frontend\modules\collect（1个）

- collect.js  (506行)

### 📁 frontend\modules\dashboard（1个）

- dashboard.js  (411行)

### 📁 frontend\modules\exam（1个）

- mock-exam.js  (851行)

### 📁 frontend\modules\flashcard（1个）

- flashcard.js  (1212行)

### 📁 frontend\modules\knowledge（1个）

- knowledge.js  (522行)

### 📁 frontend\modules\layout（4个）

- module-nav.js  (114行)
- sidebar.js  (225行)
- statusbar.js  (108行)
- topbar.js  (378行)

### 📁 frontend\modules\library（1个）

- file-library.js  (2007行)

### 📁 frontend\modules\manager（1个）

- question-manager.js  (244行)

### 📁 frontend\modules\material（1个）

- material.js  (334行)

### 📁 frontend\modules\memory（1个）

- memory.js  (528行)

### 📁 frontend\modules\mindmap（1个）

- mindmap.js  (530行)

### 📁 frontend\modules\note（1个）

- note.js  (442行)

### 📁 frontend\modules\photo（1个）

- photo-solve.js  (405行)

### 📁 frontend\modules\question（1个）

- question-practice.js  (1444行)

### 📁 frontend\modules\settings（1个）

- settings.js  (646行)

### 📁 frontend\modules\sprint（1个）

- sprint.js  (373行)

### 📁 frontend\modules\video（1个）

- video.js  (1510行)

### 📁 frontend\modules\wrong（1个）

- wrong-book.js  (461行)

### 📁 frontend\static（1个）

- manifest.json  (22行)

### 📁 frontend\static\core（7个）

- common-utils.js  (1行)
- config.js  (1行)
- data-service.js  (197行)
- event-bus.js  (1行)
- framework.js  (1行)
- module-base.js  (1行)
- storage.js  (1行)

### 📁 frontend\static\css（1个）

- common.css  (242行)

### 📁 frontend\static\css\modules（1个）

- system-admin.css  (159行)

### 📁 frontend\static\js（5个）

- layout-class-mapper.js  (244行)
- system-center.js  (279行)
- system-controller.js  (312行)
- system-supervisor.js  (359行)
- v2-layout-access.js  (294行)

### 📁 frontend\static\lib（3个）

- d3.min.js  (2行)
- markmap-lib.js  (11329行)
- markmap-view.js  (1670行)

### 📁 frontend\static\modules\admin（1个）

- system-admin.js  (1行)

### 📁 frontend\static\modules\analytics（1个）

- analytics.js  (1行)

### 📁 frontend\static\modules\collect（1个）

- collect.js  (1行)

### 📁 frontend\static\modules\dashboard（1个）

- dashboard.js  (1行)

### 📁 frontend\static\modules\exam（1个）

- mock-exam.js  (1行)

### 📁 frontend\static\modules\flashcard（1个）

- flashcard.js  (1行)

### 📁 frontend\static\modules\knowledge（1个）

- knowledge.js  (1行)

### 📁 frontend\static\modules\layout（4个）

- module-nav.js  (1行)
- sidebar.js  (1行)
- statusbar.js  (1行)
- topbar.js  (1行)

### 📁 frontend\static\modules\library（1个）

- file-library.js  (1行)

### 📁 frontend\static\modules\manager（1个）

- question-manager.js  (1行)

### 📁 frontend\static\modules\material（1个）

- material.js  (1行)

### 📁 frontend\static\modules\memory（1个）

- memory.js  (1行)

### 📁 frontend\static\modules\mindmap（1个）

- mindmap.js  (1行)

### 📁 frontend\static\modules\note（1个）

- note.js  (1行)

### 📁 frontend\static\modules\photo（1个）

- photo-solve.js  (1行)

### 📁 frontend\static\modules\question（1个）

- question-practice.js  (292行)

### 📁 frontend\static\modules\settings（1个）

- settings.js  (1行)

### 📁 frontend\static\modules\sprint（1个）

- sprint.js  (1行)

### 📁 frontend\static\modules\video（1个）

- video.js  (1行)

### 📁 frontend\static\modules\wrong（1个）

- wrong-book.js  (1行)

### 📁 tools（333个）

- __init__.py  (1行)
- _add_accent_ui.py  (61行)
- _add_ai_brain_status.py  (91行)
- _add_ai_explain.py  (90行)
- _add_ai_reports_to_admin.py  (116行)
- _add_analytics_chart.py  (51行)
- _add_analytics_charts.py  (73行)
- _add_answer_sheet.py  (223行)
- _add_batch_tag.py  (52行)
- _add_case_frontend.py  (136行)
- _add_case_template.py  (119行)
- _add_collect_batch.py  (128行)
- _add_collect_export.py  (71行)
- _add_dashboard_trend.py  (45行)
- _add_db_status_complete.py  (110行)
- _add_db_status_to_admin.py  (98行)
- _add_debug.py  (26行)
- _add_dq_dashboard.py  (52行)
- _add_draft_feature.py  (209行)
- _add_evaluate_endpoint.py  (55行)
- _add_filelib_core.py  (89行)
- _add_flashcard_ai.py  (71行)
- _add_flashcard_events.py  (91行)
- _add_flashcard_nav.py  (34行)
- _add_flashcard_speak.py  (25行)
- _add_getcurrentcard.py  (23行)
- _add_keyboard.py  (66行)
- _add_knowledge_crud.py  (199行)
- _add_knowledge_graph.py  (80行)
- _add_leaderboard.py  (52行)
- _add_library_move.py  (118行)
- _add_mastered_feature.py  (88行)
- _add_material_reader.py  (50行)
- _add_material_search.py  (26行)
- _add_memory_methods.py  (149行)
- _add_memory_train.py  (71行)
- _add_mindmap_ai.py  (103行)
- _add_multi_submit.py  (63行)
- _add_note_crud.py  (172行)
- _add_note_features.py  (75行)
- _add_note_link.py  (80行)
- _add_notification.py  (84行)
- _add_optimizations_to_admin.py  (81行)
- _add_pwa.py  (24行)
- _add_read_tts.py  (189行)
- _add_special_practice.py  (87行)
- _add_sprint_ai_plan.py  (88行)
- _add_sprint_plan.py  (45行)
- _add_tts_script.py  (18行)
- _add_tts_settings.py  (104行)
- _add_video_core.py  (64行)
- _add_video_fav.py  (42行)
- _add_video_folder.py  (71行)
- _add_video_search.py  (34行)
- _add_voice_settings.py  (47行)
- _add_wrong_actions.py  (124行)
- _add_wrong_chapter_filter.py  (112行)
- _add_wrong_core.py  (76行)
- _add_wrong_export.py  (48行)
- _add_wrong_features.py  (91行)
- _add_yunnan_accent.py  (91行)
- _analyze_missing_options.py  (48行)
- _analyze_options_missing.py  (60行)
- _check_answer_match.py  (53行)
- _check_api_health.py  (57行)
- _check_api_v2.py  (73行)
- _check_coverage.py  (14行)
- _check_duplicates.py  (43行)
- _check_endpoints.py  (28行)
- _check_error_handling.py  (30行)
- _check_module_features.py  (173行)
- _check_ollama.py  (8行)
- _check_option_fields.py  (67行)
- _check_q.py  (13行)
- _check_quality.py  (34行)
- _check_router_prefix.py  (12行)
- _clean_analysis_ads.py  (58行)
- _clean_console_logs.py  (21行)
- _clean_dashboard.py  (55行)
- _clean_question_ads.py  (90行)
- _compare_code.py  (54行)
- _compare_features.py  (81行)
- _compare_modules.py  (71行)
- _compare_old_new.py  (100行)
- _db_cleanup_execute.py  (66行)
- _db_cleanup_plan.py  (154行)
- _db_status.py  (25行)
- _debug_answer_display.py  (66行)
- _debug_multi.py  (40行)
- _deep_code_audit.py  (126行)
- _diagnose_all_modules.py  (79行)
- _enhance_ai_brain.py  (84行)
- _enhance_exam_result.py  (116行)
- _enhance_flv_error.py  (17行)
- _extract_all_features.py  (95行)
- _feature_audit.py  (167行)
- _fix_analysis_display.py  (66行)
- _fix_answer_display.py  (58行)
- _fix_audit_issues.py  (114行)
- _fix_db_status_json.py  (26行)
- _fix_duplicate.py  (13行)
- _fix_duplicate_tag.py  (18行)
- _fix_eventbus.py  (12行)
- _fix_fetch_intercept.py  (34行)
- _fix_fl_api_path.py  (19行)
- _fix_flashcard_read.py  (59行)
- _fix_flv_config.py  (45行)
- _fix_flv_loader.py  (53行)
- _fix_flv_warning.py  (39行)
- _fix_format_detect.py  (27行)
- _fix_format_detect2.py  (38行)
- _fix_init_controls.py  (21行)
- _fix_missing_1.py  (59行)
- _fix_missing_2.py  (86行)
- _fix_missing_3.py  (47行)
- _fix_multi_select.py  (150行)
- _fix_multi_submit.py  (62行)
- _fix_multi_type.py  (13行)
- _fix_options_parse.py  (38行)
- _fix_play_logic.py  (98行)
- _fix_practice.py  (30行)
- _fix_question_types.py  (42行)
- _fix_read_residual.py  (26行)
- _fix_seektype.py  (19行)
- _fix_tab_css.py  (29行)
- _fix_tts_onend.py  (178行)
- _fix_video_play.py  (23行)
- _fix_video_src.py  (38行)
- _force_native_play.py  (29行)
- _full_audit.py  (72行)
- _full_audit_v2.py  (121行)
- _full_compare.py  (52行)
- _full_feature_audit.py  (126行)
- _gen_ai_reports_json.py  (45行)
- _gen_db_status_json.py  (42行)
- _gen_enhanced_db_status.py  (80行)
- _gen_optimization_report.py  (145行)
- _insert_opt_method.py  (47行)
- _integrate_trend_to_calendar.py  (43行)
- _list_missing_q.py  (62行)
- _mark_duplicates.py  (37行)
- _mark_low_quality.py  (30行)
- _mark_missing_options.py  (52行)
- _migrate_mnemonic_logic.py  (185行)
- _multimode_player.py  (112行)
- _organize_tools.py  (108行)
- _page_audit.py  (86行)
- _read_migration_report.py  (29行)
- _rebuild_options.py  (81行)
- _register_ai_brain.py  (20行)
- _replace_read_html.py  (101行)
- _restore_eventbus.py  (13行)
- _revert_trend_layout.py  (41行)
- _rewrite_question_logic.py  (107行)
- _system_audit.py  (132行)
- _test_ai_brain.py  (54行)
- _test_api.py  (20行)
- _test_endpoints.py  (35行)
- _test_endpoints2.py  (33行)
- _test_range.py  (14行)
- _update_flashcard_tts.py  (82行)
- _verify_analysis_quality.py  (52行)
- _verify_features.py  (101行)
- _verify_features2.py  (47行)
- add_chapter25.py  (41行)
- add_chapter26.py  (49行)
- add_chapter27.py  (50行)
- add_chapter28.py  (60行)
- add_chapter29.py  (57行)
- add_chapter30.py  (55行)
- add_chapter31.py  (41行)
- add_chapter32.py  (44行)
- add_chapter33.py  (72行)
- add_chapter34.py  (53行)
- add_data_viz.py  (142行)
- add_deviation_chapter.py  (32行)
- add_difficulty_tag.py  (32行)
- add_dropdown_funcs.py  (60行)
- add_full_subject_select.py  (205行)
- add_keyboard_shortcuts.py  (103行)
- add_sprint_mode.py  (76行)
- add_step_indicator.py  (44行)
- add_step_update.py  (113行)
- add_weekly_report.py  (61行)
- add_wrong_analysis.py  (118行)
- ai_analyzer_step.py  (258行)
- ai_frontend_full_analysis.py  (141行)
- ai_system_analyzer.py  (307行)
- amend_constitution_css.py  (35行)
- analyze_offline.py  (128行)
- apply_effect_layout.py  (185行)
- auto_difficulty.py  (59行)
- batch_fix_scan.py  (45行)
- batch_migrate.py  (116行)
- batch_migrate_v2.py  (79行)
- batch_optimize_borders.py  (51行)
- change_diff.py  (144行)
- check_api_consistency.py  (182行)
- check_dates.py  (20行)
- check_db.py  (15行)
- check_difficulty.py  (9行)
- check_schema.py  (11行)
- check_wrong_data.py  (19行)
- classify_functions.py  (99行)
- classify_functions_v2.py  (103行)
- cleanup_old_subject.py  (55行)
- code_quality_check.py  (161行)
- constitution_audit.py  (205行)
- css_conflict_detector.py  (118行)
- css_merger.py  (85行)
- daily_health_report.py  (177行)
- data_lineage.py  (124行)
- data_migration.py  (251行)
- data_quality_guard.py  (401行)
- data_quality_inspector.py  (212行)
- dedup_analyzer.py  (115行)
- deploy.py  (83行)
- deviation_guard.py  (118行)
- diff_vs_golden.py  (77行)
- execution_guard.py  (286行)
- export_offline_data.py  (114行)
- fast_search.py  (334行)
- feature_checklist.py  (147行)
- feature_migration_check.py  (163行)
- feature_migration_checker.py  (152行)
- final_fix_all.py  (136行)
- find_hardcoded_dates.py  (8行)
- fix_backend_dates.py  (48行)
- fix_blank_space_real_root.py  (29行)
- fix_blank_space_root.py  (47行)
- fix_border_radius.py  (8行)
- fix_bottom_spacing.py  (44行)
- fix_btn_ids.py  (19行)
- fix_default_short.py  (15行)
- fix_default_subjects.py  (38行)
- fix_direction_name.py  (26行)
- fix_dropdown_ids.py  (19行)
- fix_duplicate_and_steps.py  (116行)
- fix_dynamic_year.py  (43行)
- fix_enter_system.py  (38行)
- fix_exam_date.py  (92行)
- fix_exam_stage_config.py  (64行)
- fix_filter_bar.py  (57行)
- fix_full_modal.py  (53行)
- fix_func_names.py  (44行)
- fix_global_lock_rule.py  (80行)
- fix_global_subject.py  (40行)
- fix_id_to_short.py  (26行)
- fix_input_ids.py  (10行)
- fix_link_and_skip.py  (81行)
- fix_link_subjects.py  (49行)
- fix_login_call.py  (19行)
- fix_multi_select.py  (108行)
- fix_offline_401.py  (48行)
- fix_offline_api.py  (52行)
- fix_offline_login.py  (50行)
- fix_offline_login2.py  (62行)
- fix_offline_static.py  (115行)
- fix_offline_statusbar.py  (60行)
- fix_public_subject.py  (36行)
- fix_qb_layout.py  (71行)
- fix_qb_single_line.py  (66行)
- fix_question_page.py  (50行)
- fix_remaining_radius.py  (47行)
- fix_render_login.py  (115行)
- fix_settings_subjects.py  (46行)
- fix_sidebar_bottom.py  (58行)
- fix_step_limit.py  (73行)
- fix_store_props.py  (52行)
- fix_subject_ids.py  (53行)
- fix_subject_name.py  (32行)
- fix_subject_structure.py  (140行)
- fix_update_cards.py  (96行)
- full_feature_migration_check.py  (321行)
- full_inspector_v2.py  (192行)
- full_inspector_v3.py  (263行)
- full_scan_v2.py  (56行)
- generate_conflict_list.py  (111行)
- impact_analyzer.py  (95行)
- layout_guard.py  (113行)
- layout_inspector_v1.py  (131行)
- link_subjects_safe.py  (42行)
- list_tables.py  (12行)
- login_final_complete.py  (409行)
- login_final_v2.py  (387行)
- maintenance_tools.py  (254行)
- optimize_dashboard_v2.py  (150行)
- optimize_question_manager_v2.py  (120行)
- optimize_video_v2.py  (45行)
- optimize_wrong_v2.py  (21行)
- orchestrator.py  (145行)
- p006_extend_proxy.py  (36行)
- p006_stage4_pilot.py  (56行)
- patrol_robot.py  (156行)
- performance_monitor.py  (113行)
- question_explanation_batch.py  (175行)
- question_explanation_filler.py  (186行)
- README.md  (53行)
- release_check.py  (168行)
- remove_duplicate_modal.py  (37行)
- remove_major_check.py  (21行)
- replace_index_modal.py  (87行)
- replace_login_ui.py  (98行)
- replace_subject_js.py  (243行)
- replace_subject_modal.py  (72行)
- req_tracker.py  (116行)
- requirement.py  (185行)
- requirement_bot.py  (181行)
- requirement_checker.py  (306行)
- requirement_recorder.py  (98行)
- restore_original_login.py  (67行)
- rollback_link.py  (48行)
- rollback_to_golden.py  (63行)
- safe_modify.py  (94行)
- security_check.py  (138行)
- semantic_dedup.py  (149行)
- simplify_question_manager.py  (61行)
- smoke_test.py  (162行)
- static_check.py  (236行)
- system_center.py  (900行)
- system_tools.py  (259行)
- update_chapter34.py  (56行)
- user_behavior_analysis.py  (144行)
- v2_batch_optimize.py  (36行)
- v2_final_check.py  (78行)
- v2_fix_wrap.py  (64行)
- v2_global_css.py  (122行)
- v2_overflow_fix.py  (112行)
- verify_features.py  (26行)
- verify_offline.py  (38行)
- version_manager.py  (201行)
- write_constitution_and_booklet.py  (307行)
- write_execution_rule.py  (82行)

### 📁 tools\archive（1个）

- README.md  (160行)

### 📁 tools\archive\布局调整（8个）

- _add_layout_locks.py  (45行)
- _adjust_layout.py  (41行)
- _adjust_layout2.py  (33行)
- _fix_css.py  (148行)
- _fix_layout_after_merge.py  (33行)
- _fix_migration_check.py  (54行)
- _update_design_record_ratio.py  (28行)
- _vertical_layout.py  (179行)

### 📁 tools\archive\检查诊断（9个）

- _check_deleted_files.py  (35行)
- _check_file_count_detail.py  (45行)
- _check_file_distribution.py  (40行)
- _check_manage_files.py  (26行)
- _check_modules_api.py  (80行)
- _check_optimization_items.py  (80行)
- _check_remaining.py  (40行)
- _check_tables.py  (18行)
- _check_total_files.py  (43行)

### 📁 tools\archive\其他（11个）

- _add_api_js.py  (17行)
- _add_batch_ops.py  (131行)
- _add_xhr_interceptor.py  (56行)
- _fix_flashcard_api_path.py  (17行)
- _fix_gzip_middleware.py  (34行)
- _fix_knowledge_error_handling.py  (229行)
- _replace_with_fetch_interceptor.py  (62行)
- _restart_backend.py  (42行)
- _update_admin_requirements.py  (155行)
- _update_design_record_6_4.py  (28行)
- _update_req_status.py  (54行)

### 📁 tools\archive\事件绑定（4个）

- _check_all_bindevents.py  (69行)
- _check_all_events.py  (43行)
- _fix_collect_sprint_events.py  (268行)
- _fix_memory_events.py  (133行)

### 📁 tools\archive\视频讲义（31个）

- _add_flv_init.py  (55行)
- _add_video_controls.py  (158行)
- _add_video_controls_events.py  (122行)
- _add_video_download_recent.py  (69行)
- _add_video_note_logic.py  (143行)
- _add_video_progress_save.py  (53行)
- _adjust_video_player_height.py  (41行)
- _adjust_video_ratio_v2.py  (71行)
- _check_video_count.py  (37行)
- _check_video_data.py  (30行)
- _check_video_subject.py  (29行)
- _fix_ai_note_real_api.py  (82行)
- _fix_flv_config.py  (66行)
- _fix_flv_init_timing.py  (51行)
- _fix_flv_init_v2.py  (47行)
- _fix_flv_player.py  (80行)
- _fix_play_layout_css.py  (39行)
- _fix_video_layout_complete.py  (109行)
- _fix_video_layout_v2.py  (264行)
- _fix_video_player_layout.py  (47行)
- _merge_videos.py  (92行)
- _migrate_player_controls.py  (174行)
- _migrate_video_controls.py  (251行)
- _remove_old_video_styles.py  (37行)
- _remove_video_manage_tab.py  (64行)
- _restore_player_css.py  (59行)
- _restore_video_original_layout.py  (462行)
- _restore_web_resources.py  (246行)
- _set_player_note_ratio_6_4.py  (69行)
- _set_video_ratio_60_40.py  (43行)
- _update_design_record_video.py  (51行)

### 📁 tools\archive\数据质量（2个）

- _auto_fix_enhanced.py  (178行)
- _auto_fix_round2.py  (123行)

### 📁 tools\archive\题库（18个）

- _add_data_quality_v2.py  (81行)
- _add_question_features.py  (155行)
- _add_question_features_v2.py  (101行)
- _add_question_features_v3.py  (89行)
- _auto_fill_analysis.py  (93行)
- _check_analysis_coverage.py  (55行)
- _check_duplicate_analysis.py  (88行)
- _check_missing_analysis.py  (93行)
- _check_options_storage.py  (58行)
- _check_question_quality.py  (56行)
- _check_question_quality_v2.py  (61行)
- _clean_analysis_ads.py  (61行)
- _fix_case_questions.py  (83行)
- _fix_options_loading.py  (50行)
- _fix_question_quality.py  (80行)
- _fix_question_ui.py  (134行)
- _integrate_all_quality_gates.py  (109行)
- _integrate_quality_pipeline.py  (124行)

### 📁 tools\archive\宪法修改（13个）

- _add_analyst_roles.py  (95行)
- _add_constitution_rule.py  (26行)
- _add_css_merger_constitution.py  (33行)
- _add_data_quality_constitution.py  (84行)
- _add_design_decision_constitution.py  (41行)
- _add_layout_guard_constitution.py  (75行)
- _add_layout_report_rule.py  (26行)
- _add_migration_responsibility.py  (108行)
- _add_modular_first_principle.py  (44行)
- _expand_migration_constitution.py  (292行)
- _fix_constitution_chapters.py  (34行)
- _update_constitution_fullscope.py  (66行)
- _update_constitution_source.py  (56行)

### 📁 tools\archive\学习资料库（14个）

- _add_normalize_fl.py  (62行)
- _add_tag_colors.py  (77行)
- _expand_tags.py  (66行)
- _fix_all_doc_filters.py  (79行)
- _fix_delete_preview.py  (116行)
- _fix_doc_filter.py  (29行)
- _fix_filelibrary_p0.py  (164行)
- _fix_fl_api.py  (91行)
- _fix_formdata.py  (40行)
- _fix_subject_filter.py  (59行)
- _migrate_batch_tag_modal.py  (174行)
- _remove_single_file_ops.py  (131行)
- _save_folder_tags.py  (76行)
- _save_tags_api.py  (78行)

### 📁 watch（1个）

- watch.py  (468行)

### 📁 本地AI分析结果（123个）

- 代码分析报告_20260913_074120.md  (102行)
- 代码分析报告_20260913_075121.md  (147行)
- 代码分析报告_20260913_080121.md  (192行)
- 代码分析报告_20260913_081105.md  (280行)
- 代码分析报告_20260913_082055.md  (370行)
- 代码分析报告_20260913_083055.md  (415行)
- 代码分析报告_20260913_084055.md  (460行)
- 代码分析报告_20260913_084906.md  (236行)
- 代码分析报告_20260913_085006.md  (534行)
- 代码分析报告_20260913_090007.md  (579行)
- 代码分析报告_20260913_090646.md  (464行)
- 代码分析报告_20260913_090929.md  (665行)
- 代码分析报告_20260913_091929.md  (710行)
- 代码分析报告_20260913_092702.md  (740行)
- 代码分析报告_20260913_092930.md  (755行)
- 代码分析报告_20260913_093930.md  (800行)
- 代码分析报告_20260913_094544.md  (985行)
- 代码分析报告_20260913_094930.md  (845行)
- 代码分析报告_20260913_095930.md  (890行)
- 代码分析报告_20260913_100854.md  (1267行)
- 代码分析报告_20260913_100930.md  (935行)
- 代码分析报告_20260913_101930.md  (980行)
- 代码分析报告_20260913_102931.md  (1025行)
- 代码分析报告_20260913_103931.md  (1070行)
- 代码分析报告_20260913_104924.md  (1154行)
- 代码分析报告_20260913_105512.md  (1758行)
- 代码分析报告_20260913_112223.md  (2163行)
- 代码分析报告_20260913_113147.md  (2368行)
- 代码分析报告_20260913_115020.md  (2746行)
- 代码分析报告_20260913_120805.md  (3089行)
- 代码分析报告_20260913_121330.md  (3263行)
- 代码分析报告_20260913_122206.md  (3442行)
- 代码分析报告_20260913_161822.md  (126行)
- 代码分析报告_20260913_163121.md  (286行)
- 代码分析报告_20260913_163330.md  (349行)
- 代码分析报告_20260913_170305.md  (206行)
- 代码分析报告_20260913_172646.md  (567行)
- 代码分析报告_20260913_173029.md  (649行)
- 代码分析报告_20260913_173335.md  (728行)
- 代码分析报告_20260913_174024.md  (847行)
- 代码分析报告_20260913_180102.md  (1143行)
- 代码分析报告_20260913_180359.md  (1222行)
- 代码分析报告_20260913_181052.md  (1338行)
- 代码分析报告_20260913_181446.md  (1433行)
- 代码分析报告_20260913_183123.md  (1668行)
- 代码分析报告_20260913_183444.md  (1763行)
- 代码分析报告_20260913_184219.md  (1882行)
- 代码分析报告_20260913_185538.md  (2094行)
- 代码分析报告_20260913_190255.md  (2262行)
- 代码分析报告_20260913_190717.md  (2356行)
- 代码分析报告_20260913_191741.md  (2525行)
- 代码分析报告_20260913_192938.md  (2734行)
- 代码分析报告_20260913_193254.md  (2824行)
- 代码分析报告_20260913_193647.md  (2902行)
- 代码分析报告_20260913_200047.md  (3234行)
- 代码分析报告_20260913_200432.md  (3335行)
- 代码分析报告_20260913_202153.md  (3606行)
- 代码分析报告_20260913_202727.md  (3696行)
- 代码分析报告_20260913_203545.md  (3835行)
- 代码分析报告_20260913_204526.md  (4007行)
- 代码分析报告_20260913_205644.md  (4205行)
- 代码分析结果_20260913_074120.json  (32行)
- 代码分析结果_20260913_075121.json  (62行)
- 代码分析结果_20260913_080121.json  (92行)
- 代码分析结果_20260913_081105.json  (122行)
- 代码分析结果_20260913_082055.json  (152行)
- 代码分析结果_20260913_083055.json  (182行)
- 代码分析结果_20260913_084055.json  (212行)
- 代码分析结果_20260913_084906.json  (23行)
- 代码分析结果_20260913_085006.json  (242行)
- 代码分析结果_20260913_090007.json  (272行)
- 代码分析结果_20260913_090646.json  (44行)
- 代码分析结果_20260913_090929.json  (302行)
- 代码分析结果_20260913_091929.json  (332行)
- 代码分析结果_20260913_092702.json  (65行)
- 代码分析结果_20260913_092930.json  (362行)
- 代码分析结果_20260913_093930.json  (392行)
- 代码分析结果_20260913_094544.json  (86行)
- 代码分析结果_20260913_094930.json  (422行)
- 代码分析结果_20260913_095930.json  (452行)
- 代码分析结果_20260913_100854.json  (107行)
- 代码分析结果_20260913_100930.json  (482行)
- 代码分析结果_20260913_101930.json  (512行)
- 代码分析结果_20260913_102931.json  (542行)
- 代码分析结果_20260913_103931.json  (572行)
- 代码分析结果_20260913_104924.json  (602行)
- 代码分析结果_20260913_105512.json  (128行)
- 代码分析结果_20260913_112223.json  (149行)
- 代码分析结果_20260913_113147.json  (170行)
- 代码分析结果_20260913_115020.json  (191行)
- 代码分析结果_20260913_120805.json  (212行)
- 代码分析结果_20260913_121330.json  (233行)
- 代码分析结果_20260913_122206.json  (254行)
- 代码分析结果_20260913_161822.json  (16行)
- 代码分析结果_20260913_163121.json  (30行)
- 代码分析结果_20260913_163330.json  (44行)
- 代码分析结果_20260913_170305.json  (16行)
- 代码分析结果_20260913_172646.json  (30行)
- 代码分析结果_20260913_173029.json  (44行)
- 代码分析结果_20260913_173335.json  (58行)
- 代码分析结果_20260913_174024.json  (72行)
- 代码分析结果_20260913_180102.json  (86行)
- 代码分析结果_20260913_180359.json  (100行)
- 代码分析结果_20260913_181052.json  (114行)
- 代码分析结果_20260913_181446.json  (128行)
- 代码分析结果_20260913_183123.json  (142行)
- 代码分析结果_20260913_183444.json  (156行)
- 代码分析结果_20260913_184219.json  (170行)
- 代码分析结果_20260913_185538.json  (184行)
- 代码分析结果_20260913_190255.json  (198行)
- 代码分析结果_20260913_190717.json  (212行)
- 代码分析结果_20260913_191741.json  (226行)
- 代码分析结果_20260913_192938.json  (240行)
- 代码分析结果_20260913_193254.json  (254行)
- 代码分析结果_20260913_193647.json  (268行)
- 代码分析结果_20260913_200047.json  (282行)
- 代码分析结果_20260913_200432.json  (296行)
- 代码分析结果_20260913_202153.json  (310行)
- 代码分析结果_20260913_202727.json  (324行)
- 代码分析结果_20260913_203545.json  (338行)
- 代码分析结果_20260913_204526.json  (352行)
- 代码分析结果_20260913_205644.json  (366行)
- 文件结构分析报告.md  (561行)

### 📁 布局规范（7个）

- V2布局规则_统一版.css  (403行)
- V2布局接入层.js  (294行)
- V2兼容层_备用.css  (27行)
- 开发期待优化项扫描结果.json  (40行)
- 全任务清单_顶层设计.json  (525行)
- 全任务清单_全面梳理版.json  (1058行)
- 唯一布局标准V2.0_全品类效果图.html  (2093行)

### 📁 布局规范\历史版本备份（2个）

- 唯一布局标准V2.0_全品类效果图 - 备份 .html  (2093行)
- 唯一布局标准V2.0_全品类效果图 - 黄金备份.html  (2093行)

### 📁 规划细则分册（3个）

- 需求管理清单.json  (233行)
- 执行进度.json  (53行)
- 专家走偏记录.json  (11行)

### 📁 规划细则分册\安全检查报告（5个）

- 20260907_212055_安全检查.json  (33行)
- 20260907_212318_安全检查.json  (33行)
- 20260907_212754_安全检查.json  (33行)
- 20260907_213047_安全检查.json  (33行)
- 20260907_214200_安全检查.json  (33行)

### 📁 规划细则分册\代码质量报告（9个）

- 20260907_211842_代码质量.json  (38行)
- 20260907_211903_代码质量.json  (43行)
- 20260907_211936_代码质量.json  (38行)
- 20260907_211944_代码质量.json  (38行)
- 20260907_212008_代码质量.json  (38行)
- 20260907_212318_代码质量.json  (38行)
- 20260907_212754_代码质量.json  (38行)
- 20260907_213047_代码质量.json  (38行)
- 20260907_214200_代码质量.json  (38行)

### 📁 规划细则分册\发布检查报告（2个）

- 20260907_211223_发布检查.json  (0行)
- 20260907_211300_发布检查.json  (139行)

### 📁 规划细则分册\宪法执行审计（1个）

- 20260907_204259_宪法执行审计.json  (74行)

### 📁 规划细则分册\协同执行报告（4个）

- 20260907_212319_post.json  (37行)
- 20260907_212754_post.json  (37行)
- 20260907_213048_post.json  (37行)
- 20260907_214200_post.json  (37行)

### 📁 规划细则分册\性能监控报告（1个）

- 20260907_211648_性能监控.json  (48行)

### 📁 规划细则分册\巡查报告（4个）

- 20260907_215058_V3巡查.json  (7行)
- 20260907_215240_V3巡查.json  (7行)
- 20260907_223011_V3巡查.json  (7行)
- 20260907_223434_V3巡查.json  (7行)

### 📁 规划细则分册\用户行为分析报告（1个）

- 20260907_212422_行为分析.json  (13行)

### 📁 系统大脑（1个）

- 系统知识图谱.json  (1085行)




---

# 📋 附录C区：动态文件索引（2026-09-13 自动生成）
> 本索引由 tools/gen_file_index.ps1 生成，代码变更后重跑该脚本刷新。排除：备份/隔离/归档/node_modules/__pycache__。


## C.1 后端 Python（backend/，176个）
| 文件 | 行数 |
|---|---|
| backend\api\__init__.py | 0 |
| backend\api\supervisor_api.py | 277 |
| backend\api\v1\__init__.py | 0 |
| backend\api\v1\ai_brain.py | 339 |
| backend\api\v1\ai_scan.py | 140 |
| backend\api\v1\ai_unified.py | 28 |
| backend\api\v1\analytics.py | 408 |
| backend\api\v1\assistant.py | 730 |
| backend\api\v1\auth.py | 137 |
| backend\api\v1\backup.py | 90 |
| backend\api\v1\combined_analysis.py | 340 |
| backend\api\v1\data_check.py | 454 |
| backend\api\v1\deduplication.py | 358 |
| backend\api\v1\exam.py | 432 |
| backend\api\v1\exam_analysis.py | 290 |
| backend\api\v1\flashcard.py | 349 |
| backend\api\v1\formula_trainer.py | 203 |
| backend\api\v1\knowledge_graph.py | 799 |
| backend\api\v1\lecture.py | 278 |
| backend\api\v1\material.py | 1063 |
| backend\api\v1\mindmap.py | 1194 |
| backend\api\v1\monitor.py | 82 |
| backend\api\v1\music.py | 78 |
| backend\api\v1\note.py | 61 |
| backend\api\v1\preprocess_config.py | 281 |
| backend\api\v1\question.py | 1447 |
| backend\api\v1\question_file.py | 71 |
| backend\api\v1\rag_knowledge.py | 356 |
| backend\api\v1\relation.py | 131 |
| backend\api\v1\sprint.py | 166 |
| backend\api\v1\subject_switch.py | 251 |
| backend\api\v1\syllabus.py | 524 |
| backend\api\v1\sync_unified.py | 593 |
| backend\api\v1\system.py | 399 |
| backend\api\v1\tts.py | 156 |
| backend\api\v1\video.py | 584 |
| backend\api\v1\wrong_analysis.py | 130 |
| backend\core\__init__.py | 0 |
| backend\core\ai_controller.py | 624 |
| backend\core\ai_dev_workflow.py | 347 |
| backend\core\code_cleanup_planner.py | 410 |
| backend\core\code_review.py | 585 |
| backend\core\commander_center.py | 295 |
| backend\core\config.py | 191 |
| backend\core\db.py | 32 |
| backend\core\layout_checker.py | 468 |
| backend\core\requirement_tracker.py | 318 |
| backend\core\system_supervisor.py | 642 |
| backend\crud\__init__.py | 0 |
| backend\crud\crud.py | 964 |
| backend\main.py | 839 |
| backend\middleware\__init__.py | 1 |
| backend\middleware\file_hash_middleware.py | 86 |
| backend\middleware\rate_limit_middleware.py | 126 |
| backend\middleware\request_id_middleware.py | 51 |
| backend\models\__init__.py | 0 |
| backend\models\models.py | 567 |
| backend\modules\__init__.py | 5 |
| backend\modules\ai\__init__.py | 0 |
| backend\modules\ai\ai_manager.py | 413 |
| backend\modules\ai\case_grader.py | 136 |
| backend\modules\ai\effect_evaluator.py | 214 |
| backend\modules\ai\evaluation_routes.py | 106 |
| backend\modules\ai\manager_routes.py | 207 |
| backend\modules\ai\pdf_vl_recognizer.py | 975 |
| backend\modules\ai\routes.py | 1056 |
| backend\modules\ai\service.py | 1272 |
| backend\modules\ai\stream_routes.py | 136 |
| backend\modules\ai\stream_service.py | 277 |
| backend\modules\common\__init__.py | 0 |
| backend\modules\common\data_routes.py | 103 |
| backend\modules\common\data_security.py | 238 |
| backend\modules\common\file_library_model.py | 26 |
| backend\modules\common\file_library_routes.py | 418 |
| backend\modules\common\file_library_service.py | 391 |
| backend\modules\common\fl_bridge_routes.py | 1097 |
| backend\modules\common\graceful_shutdown.py | 171 |
| backend\modules\common\logger.py | 165 |
| backend\modules\common\monitor_routes.py | 173 |
| backend\modules\common\preprocess_service.py | 302 |
| backend\modules\common\question_importer.py | 295 |
| backend\modules\common\response.py | 268 |
| backend\modules\common\routes.py | 1362 |
| backend\modules\common\service.py | 55 |
| backend\modules\common\service_monitor.py | 330 |
| backend\modules\common\shutdown_routes.py | 54 |
| backend\modules\mm\__init__.py | 0 |
| backend\modules\mm\routes.py | 759 |
| backend\modules\mm\service.py | 1129 |
| backend\modules\mt\__init__.py | 0 |
| backend\modules\mt\ability_radar.py | 658 |
| backend\modules\mt\bkt_algorithm.py | 249 |
| backend\modules\mt\category_manager.py | 302 |
| backend\modules\mt\category_routes.py | 138 |
| backend\modules\mt\fsrs_algorithm.py | 300 |
| backend\modules\mt\learning_path_planner.py | 439 |
| backend\modules\mt\routes.py | 635 |
| backend\modules\mt\service.py | 626 |
| backend\modules\qb\__init__.py | 0 |
| backend\modules\qb\irt_algorithm.py | 362 |
| backend\modules\qb\quality_manager.py | 290 |
| backend\modules\qb\quality_routes.py | 120 |
| backend\modules\qb\routes.py | 1277 |
| backend\modules\qb\service.py | 776 |
| backend\modules\resource\__init__.py | 0 |
| backend\modules\resource\pdf_parse_cache.py | 370 |
| backend\modules\resource\routes.py | 1243 |
| backend\modules\resource\service.py | 648 |
| backend\modules\sync\__init__.py | 0 |
| backend\modules\sync\routes.py | 515 |
| backend\modules\sync\service.py | 747 |
| backend\schemas\__init__.py | 0 |
| backend\schemas\schemas.py | 210 |
| backend\scripts\__init__.py | 0 |
| backend\scripts\init_db.py | 232 |
| backend\tests\backups\snapshot_20260831_233856_测试1\test_core.py | 177 |
| backend\tests\backups\snapshot_20260831_233856_测试2\test_core.py | 177 |
| backend\tests\backups\snapshot_20260831_233856_测试备份\test_core.py | 177 |
| backend\tests\conftest.py | 120 |
| backend\tests\test_all_modules.py | 272 |
| backend\tests\test_api.py | 163 |
| backend\tests\test_core.py | 177 |
| backend\utils\__init__.py | 0 |
| backend\utils\ai_brain.py | 1235 |
| backend\utils\ai_brain_hub.py | 1015 |
| backend\utils\ai_config.py | 91 |
| backend\utils\ai_solve.py | 646 |
| backend\utils\ai_vision_parser.py | 354 |
| backend\utils\audit_logger.py | 216 |
| backend\utils\backup_manager.py | 327 |
| backend\utils\constants.py | 103 |
| backend\utils\data_quality_pipeline.py | 299 |
| backend\utils\db_migration.py | 306 |
| backend\utils\deduplication.py | 596 |
| backend\utils\deps.py | 29 |
| backend\utils\enhanced_ocr_store.py | 712 |
| backend\utils\error_classifier.py | 224 |
| backend\utils\error_handler.py | 67 |
| backend\utils\exam_analyzer.py | 341 |
| backend\utils\expert_personas.py | 166 |
| backend\utils\famous_teacher_mnemonics.py | 365 |
| backend\utils\file_hash_utils.py | 122 |
| backend\utils\file_validator.py | 95 |
| backend\utils\flashcard_generator.py | 570 |
| backend\utils\flashcard_quality_manager.py | 483 |
| backend\utils\formula_trainer.py | 411 |
| backend\utils\knowledge_base_answer.py | 201 |
| backend\utils\knowledge_graph.py | 344 |
| backend\utils\local_search.py | 254 |
| backend\utils\mindmap_recognizer.py | 554 |
| backend\utils\mindmap_recognizer_v2.py | 316 |
| backend\utils\mindmap_standardizer.py | 277 |
| backend\utils\mindmap_verifier.py | 272 |
| backend\utils\mm_parser.py | 294 |
| backend\utils\pdf_ai.py | 973 |
| backend\utils\pdf_base_processor.py | 2066 |
| backend\utils\pdf_parser.py | 2198 |
| backend\utils\pdf_question_extractor.py | 308 |
| backend\utils\pdf_splitter.py | 2883 |
| backend\utils\pdf_toolkit.py | 794 |
| backend\utils\premium_mnemonics_v2.py | 167 |
| backend\utils\quality_gate_framework.py | 276 |
| backend\utils\question_recognizer.py | 573 |
| backend\utils\question_serializer.py | 104 |
| backend\utils\scan_preprocessor.py | 501 |
| backend\utils\section_matcher.py | 207 |
| backend\utils\security.py | 26 |
| backend\utils\service_monitor.py | 276 |
| backend\utils\sm2_engine.py | 296 |
| backend\utils\smart_toc_extractor.py | 1476 |
| backend\utils\static_hasher.py | 39 |
| backend\utils\study_planner.py | 635 |
| backend\utils\syllabus_tree_generator.py | 557 |
| backend\utils\video_mnemonic_extractor.py | 223 |
| backend\utils\water_case_mnemonics.py | 120 |
| backend\watchdog.py | 226 |

## C.2 前端文件（frontend/，162个）
| 文件 | 行数 |
|---|---|
| frontend\check_html.js | 12 |
| frontend\check_js.js | 5538 |
| frontend\core\api.js | 81 |
| frontend\core\common-utils.js | 202 |
| frontend\core\config.js | 64 |
| frontend\core\data-service.js | 222 |
| frontend\core\event-bus.js | 108 |
| frontend\core\framework.js | 262 |
| frontend\core\module-base.js | 131 |
| frontend\core\storage.js | 196 |
| frontend\css\components.css | 1 |
| frontend\css\components\_buttons.css | 81 |
| frontend\css\components\_cards.css | 73 |
| frontend\css\components\_forms.css | 125 |
| frontend\css\components\_tables.css | 124 |
| frontend\css\components\_variables.css | 79 |
| frontend\css\components\index.css | 28 |
| frontend\css\layout\_layout.css | 134 |
| frontend\css\layout\layout.css | 4 |
| frontend\css\layout\layout-base.css | 1 |
| frontend\css\layout\layout-pages.css | 1 |
| frontend\css\layout\layout-v2.css | 2 |
| frontend\css\mobile.css | 842 |
| frontend\css\mobile-tablet.css | 405 |
| frontend\css\style.css | 1896 |
| frontend\css\style.min.css | 1896 |
| frontend\css\tablet.css | 302 |
| frontend\css\themes\v2-theme.css | 1010 |
| frontend\css\tokens.css | 150 |
| frontend\css\V2布局规则_统一版.css | 457 |
| frontend\exam_analysis.html | 253 |
| frontend\index.html | 109 |
| frontend\index-modular.html | 95 |
| frontend\js\app_v3_897262.js | 34848 |
| frontend\js\core\api.js | 148 |
| frontend\js\core\code-anti-mixins.js | 170 |
| frontend\js\core\console-interceptor.js | 88 |
| frontend\js\core\constants.js | 94 |
| frontend\js\core\error-boundary.js | 291 |
| frontend\js\core\event-bus.js | 152 |
| frontend\js\core\inline-code-constraints.js | 148 |
| frontend\js\core\layout-class-mapper.js | 288 |
| frontend\js\core\logger.js | 228 |
| frontend\js\core\monitor.js | 480 |
| frontend\js\core\page-type-detector.js | 193 |
| frontend\js\core\pwa-installer.js | 558 |
| frontend\js\core\store.js | 151 |
| frontend\js\core\v2-layout-access.js | 347 |
| frontend\js\feature-module-framework.js | 117 |
| frontend\js\global-subject-manager.js | 186 |
| frontend\js\mobile-adapter-framework.js | 180 |
| frontend\js\modules\ai.js | 507 |
| frontend\js\modules\ai_brain.js | 606 |
| frontend\js\modules\common.js | 2276 |
| frontend\js\modules\common-business.js | 1431 |
| frontend\js\modules\common-utils.js | 1445 |
| frontend\js\modules\file_library.js | 1313 |
| frontend\js\modules\fl_bridge.js | 176 |
| frontend\js\modules\knowledge_base.js | 479 |
| frontend\js\modules\knowledge_graph_view.js | 602 |
| frontend\js\modules\mm.js | 276 |
| frontend\js\modules\mt.js | 397 |
| frontend\js\modules\preprocess_config_view.js | 543 |
| frontend\js\modules\qb.js | 404 |
| frontend\js\modules\sync.js | 332 |
| frontend\js\music.js | 244 |
| frontend\js\performance-monitor.js | 141 |
| frontend\js\resource.js | 11591 |
| frontend\js\system-center.js | 279 |
| frontend\js\system-controller.js | 312 |
| frontend\js\system-supervisor.js | 412 |
| frontend\js\tts-service.js | 256 |
| frontend\layout-demo.html | 346 |
| frontend\lib\d3.min.js | 2 |
| frontend\lib\echarts.min.js | 45 |
| frontend\lib\flv.min.js | 10 |
| frontend\lib\markmap-lib.js | 11329 |
| frontend\lib\markmap-view.js | 1670 |
| frontend\lib\MindElixir.min.js | 8 |
| frontend\lib\mind-elixir-adapter.js | 29 |
| frontend\lib\mind-elixir-style.css | 1 |
| frontend\lib\mindmap-dual-adapter.js | 176 |
| frontend\lib\pdfjs\pdf.min.js | 22 |
| frontend\lib\pdfjs\pdf.worker.min.js | 22 |
| frontend\lib\wangEditor.css | 27 |
| frontend\lib\wangEditor.min.js | 24129 |
| frontend\module-demo.html | 199 |
| frontend\modules\admin\system-admin.js | 499 |
| frontend\modules\ai\ai-brain.js | 148 |
| frontend\modules\analytics\analytics.js | 537 |
| frontend\modules\collect\collect.js | 506 |
| frontend\modules\dashboard\dashboard.js | 411 |
| frontend\modules\exam\mock-exam.js | 851 |
| frontend\modules\flashcard\flashcard.js | 1212 |
| frontend\modules\hello-demo.js | 125 |
| frontend\modules\knowledge\knowledge.js | 522 |
| frontend\modules\layout\module-nav.js | 114 |
| frontend\modules\layout\sidebar.js | 225 |
| frontend\modules\layout\statusbar.js | 108 |
| frontend\modules\layout\topbar.js | 378 |
| frontend\modules\library\file-library.js | 2007 |
| frontend\modules\manager\question-manager.js | 244 |
| frontend\modules\material\material.js | 334 |
| frontend\modules\memory\memory.js | 528 |
| frontend\modules\mindmap\mindmap.js | 530 |
| frontend\modules\note\note.js | 442 |
| frontend\modules\photo\photo-solve.js | 405 |
| frontend\modules\question\question-practice.js | 1444 |
| frontend\modules\settings\settings.js | 646 |
| frontend\modules\sprint\sprint.js | 373 |
| frontend\modules\video\video.js | 1510 |
| frontend\modules\wrong\wrong-book.js | 461 |
| frontend\offline.html | 50104 |
| frontend\offline-data-cache.js | 641 |
| frontend\offline-init.js | 384 |
| frontend\offline-manager.js | 520 |
| frontend\offline-media-cache.js | 438 |
| frontend\static\core\common-utils.js | 1 |
| frontend\static\core\config.js | 1 |
| frontend\static\core\data-service.js | 197 |
| frontend\static\core\event-bus.js | 1 |
| frontend\static\core\framework.js | 1 |
| frontend\static\core\module-base.js | 1 |
| frontend\static\core\storage.js | 1 |
| frontend\static\css\common.css | 242 |
| frontend\static\css\modules\system-admin.css | 159 |
| frontend\static\js\layout-class-mapper.js | 244 |
| frontend\static\js\system-center.js | 279 |
| frontend\static\js\system-controller.js | 312 |
| frontend\static\js\system-supervisor.js | 359 |
| frontend\static\js\v2-layout-access.js | 294 |
| frontend\static\lib\d3.min.js | 2 |
| frontend\static\lib\markmap-lib.js | 11329 |
| frontend\static\lib\markmap-view.js | 1670 |
| frontend\static\modules\admin\system-admin.js | 1 |
| frontend\static\modules\analytics\analytics.js | 1 |
| frontend\static\modules\collect\collect.js | 1 |
| frontend\static\modules\dashboard\dashboard.js | 1 |
| frontend\static\modules\exam\mock-exam.js | 1 |
| frontend\static\modules\flashcard\flashcard.js | 1 |
| frontend\static\modules\knowledge\knowledge.js | 1 |
| frontend\static\modules\layout\module-nav.js | 1 |
| frontend\static\modules\layout\sidebar.js | 1 |
| frontend\static\modules\layout\statusbar.js | 1 |
| frontend\static\modules\layout\topbar.js | 1 |
| frontend\static\modules\library\file-library.js | 1 |
| frontend\static\modules\manager\question-manager.js | 1 |
| frontend\static\modules\material\material.js | 1 |
| frontend\static\modules\memory\memory.js | 1 |
| frontend\static\modules\mindmap\mindmap.js | 1 |
| frontend\static\modules\note\note.js | 1 |
| frontend\static\modules\photo\photo-solve.js | 1 |
| frontend\static\modules\question\question-practice.js | 292 |
| frontend\static\modules\settings\settings.js | 1 |
| frontend\static\modules\sprint\sprint.js | 1 |
| frontend\static\modules\video\video.js | 1 |
| frontend\static\modules\wrong\wrong-book.js | 1 |
| frontend\sw.js | 106 |
| frontend\sw_v2_root_已废弃_请勿修改.js | 286 |
| frontend\sw_v2_已废弃_请勿修改.js | 667 |
| frontend\sync-manager.js | 730 |
| frontend\system-admin.html | 378 |


## C.3 工具脚本（tools/）
| 子目录 | 脚本数 | 说明 |
|---|---|---|
| tools/根目录 | 339 | 顶层脚本 |

## C.4 数据/题库文件（按目录统计）
| 目录 | 文件数 | 类型 |
|---|---|---|
| 本地AI分析结果/ | 123 | 数据/资源 |
| data/ | 22 | 数据/资源 |
| docs/ | 20 | 数据/资源 |


---

# 🔍 附录D区：文件索引与跨平台检索
> 三层串联：总控md（人读全文） ↔ tools/file_index.json（机器索引，889条） ↔ tools/search.py（跨平台检索）

## 怎么用
1. **按功能找文件**：任意机器有Python就跑 python tools/search.py 闪卡 → 秒出相关文件路径+行数+功能
2. **按类型筛**：python tools/search.py --ext py 列所有后端
3. **代码改完刷新索引**：Windows跑 powershell -File tools/gen_file_index.ps1；其他平台跑 python tools/search.py --refresh`n4. **索引结构**：每条 = 路径 | 大小KB | 行数 | 扩展名 | 一句话功能（func字段待逐步补充）

## 换平台也能用
search.py 是纯Python，Mac/Linux/Windows/装了Python的手机都能跑；file_index.json 是纯文本JSON，任何工具可读。



## 2026-09-14 思维导图模块需求更新

### 自动加载模板
- **需求**：进入思维导图模块时，自动加载第一个思维导图，无需手动点击"加载模板"按钮
- **实现**：
  1. init() → render() → _updatePreview() → _loadRealMindmaps()
  2. _loadRealMindmaps() 加载完后端数据后，自动选择第一个思维导图
  3. 自动设置 markdown 内容（优先从 localStorage 读取，否则用后端数据）
  4. 再次调用 render() 和 _updatePreview() 显示内容
- **状态**：✅ 已实现

### 实时预览
- **需求**：编辑 Markdown 时，右侧实时预览同步更新
- **实现**：编辑器 oninput 事件触发 _updatePreview()
- **状态**：✅ 已实现


---

## 变更记录：2026-09-14 23:18

### 修复：路由系统完全重写

**问题描述：**
- URL是#/question，但页面显示的是学习看板
- bu.click_xy点击侧边栏菜单没反应，页面不切换
- 启动时硬编码加载dashboard，没有从URL hash读取初始页面
- 没有监听hashchange事件，URL变了但页面不切换

**根本原因：**
- index.html第225行：renderPage('dashboard') 硬编码加载学习看板
- 没有监听hashchange事件，hash路由完全失效
- 侧边栏导航只触发Framework.events，不同步URL hash

**修复方案：**
1. 启动时从URL hash读取初始页面（getPageFromHash函数）
2. 监听hashchange事件，自动切换页面
3. 侧边栏导航时，同步更新window.location.hash

**修改文件：**
- frontend/index.html 第224-244行（路由系统完全重写）

**验证结果：**
- ✅ 访问 http://localhost:8000/#/question 正确加载题库刷题模块
- ✅ URL变化触发页面切换
- ✅ 侧边栏菜单点击后同步更新URL hash

---


---

## 变更记录：2026-09-14 23:45

### 修复1：路由系统完全重写

**问题：**
- URL是#/question但页面显示学习看板
- URL变了但页面不切换

**修复：**
1. 启动时从URL hash读取初始页面（getPageFromHash函数）
2. 监听hashchange事件，自动切换页面
3. 侧边栏导航时，同步更新window.location.hash

**文件：** frontend/index.html 第224-244行

---

### 修复2：题库刷题API路径修正

**问题：**
- 每日一练API返回404
- 前端调用/api/v1/questions/random（复数）
- 后端实际路由是/api/v1/question/random_real（单数）

**修复：**
- 第203行：把/api/v1/questions/random?count=10改成/api/v1/question/random_real?count=10

**文件：** frontend/modules/question/question-practice.js 第203行

---


---

## 变更记录：2026-09-15 00:10

### 修复：专项练习功能补全

**问题：**
- 点击专项练习卡片后，只是showToast提示，没有真正开始练习
- _startPractice方法没有接收topic参数，无法按知识点筛选题目

**修复：**
1. _startPractice方法加topic参数（source = 'chapter', topic = null）
2. 获取题目后，根据topic筛选题目（标题或解析包含topic关键词）
3. 如果筛选后没有题目，就返回随机练习20题
4. 点击专项练习卡片时，把topic传进去（this._startPractice('special', topic)）

**文件：** frontend/modules/question/question-practice.js

---


---

## 变更记录：2026-09-15 00:15

### 修复：思维导图预览功能缩进错误

**问题：**
- _loadRealMindmaps方法里，this.render()和this._updatePreview()缩进不对
- 导致else if块闭合后才调用render和updatePreview
- 预览区域不显示内容

**修复：**
- 第818行：this.render()缩进改成和this.state.markdown一样
- 第819行：this._updatePreview()缩进改成和this.state.markdown一样

**文件：** frontend/modules/mindmap/mindmap.js

---


---

## 变更记录：2026-09-15 00:25

### 修复：专项练习tab内容不显示

**问题：**
- 点击"专项练习"tab后，tab视觉效果变了（蓝色下划线），但内容区域没有变化
- 原因：bottomHtml变量只赋值了，但第282行的innerHTML只包含了contentHtml，没有包含bottomHtml
- 原因：bottomHtml变量没有定义（let bottomHtml = ''）

**修复：**
1. 第229行：加上let bottomHtml = '';
2. 第283行：innerHTML改成包含contentHtml和bottomHtml

**文件：** frontend/modules/question/question-practice.js

---

## 2026-09-15 功能测试与Bug修复

### 错题本模块测试
- **标记掌握功能**：✅ 验证通过，点击后状态切换，统计更新（已掌握0→1，未掌握80→7）
- **删除功能**：✅ 验证通过，弹出确认对话框，确认后删除，统计更新（总题数80→7）

### 笔记模块测试
- **新建笔记功能**：✅ 验证通过，弹出对话框→输入内容→保存→列表更新
- **Bug修复**：noteModule全局变量未定义
  - 问题：保存按钮用内联onclick引用noteModule，但它不是全局变量
  - 修复：在note.js末尾添加window.noteModule = noteInstance
  - 文件：frontend/modules/note/note.js 第560-564行

### 测试方法说明
- 使用bu.js()直接执行JS代码测试功能（bu.click_xy坐标不准）
- 用JS点击按钮、输入内容、验证数据变化
- 这种方法比坐标点击更准确

### 模块注册状态检查
- **检查方法**：用JS检查Framework._modules里注册了哪些模块
- **结果**：所有19个业务模块都已注册
- **已注册模块清单**：
  - ✅ dashboard（学习看板）
  - ✅ question（题库刷题）
  - ✅ mock-exam（模拟考试）
  - ✅ photo-solve（AI拍照解题）
  - ✅ wrong-book（错题本）
  - ✅ question-manager（题库管理）
  - ✅ file-library（文件资料库）
  - ✅ note（学习笔记）
  - ✅ flashcard（记忆闪卡）
  - ✅ collect（我的收藏）
  - ✅ video（视频讲义）
  - ✅ material（课程教材）
  - ✅ mindmap（思维导图）
  - ✅ knowledge（知识库）
  - ✅ analytics（智能分析）
  - ✅ memory（记忆训练）
  - ✅ sprint（冲刺中心）
  - ✅ settings（系统设置）
  - ✅ system-admin（系统管理中心）
- **结论**：没有"模块迁移中"的未实现模块，所有模块都已加载
- **注意**：批量导航时每个模块需要等5秒才能加载完，导航太快会显示"模块迁移中"

### HTTP 429限流问题修复
- **问题**：批量生成导图时大量文件返回HTTP 429错误
- **原因**：不是后端代码限流，是Ollama模型本身限流
  - Ollama同时只能处理一个请求
  - 批量处理时请求太快，前一个还没处理完，后一个又来了
- **修复**：在fl_bridge.js的batchExecute函数里加2秒延迟
  - 文件：frontend/js/modules/fl_bridge.js 第81-84行
  - 每个文件之间等2秒，让Ollama有时间处理完
- **效果**：批量处理不会再出现HTTP 429错误

## 错误预防机制（2026-09-15新增）

### 三道防线
1. **第一道**：修改代码后 → 运行 
ode verify.cjs <文件> 检查语法
2. **第二道**：验证通过后 → 运行 
ode sync.cjs <模块名> 同步到static
3. **第三道**：同步完成后 → 刷新浏览器测试

### 调试经验库
所有犯过的错误都记录在 调试经验库.md，下次不再犯

### 工具脚本
- erify.cjs：语法检查 + 错误模式检测
- sync.cjs：modules/ → static/ 同步
- 调试经验库.md：错误知识库




---

## 2026-09-19 错题本（wrong-book）数据层根治 + 前后端API审计

### 根因（此前"加入复习报错/统计假数据"的真正原因）
1. **假数据**：`_loadRealWrongQuestions` 在本地无缓存时不调错题API，而是 `DataService.getQuestions('一造管理')` 后用 `Math.random()` 随机抽50道普通题伪造错题（随机 userAnswer/wrongCount/status/日期），违反真实数据铁律；state 初始硬编码 total:80 与5个假薄弱知识点。
2. **错误路径**：前端原调 `/api/v1/wrong/list` 是404；正确为 `/api/qb/wrong/list`（MODULE_PREFIXES `/qb`→`/api/qb`）。
3. **按钮不调后端**：掌握/删除/复习只改本地 state + StorageService，刷新即失效。
4. **复习落地无效**：`_reviewQuestion` 存 sessionStorage('reviewQuestion') 后跳 `#/question`，但 question-practice.js 根本不读 reviewQuestion（只读 todayReview）。
5. **代码腐烂**：查看解析/加入复习/移除错题的事件绑定块在 bindEvents/_exportWrong/_showStats/aiAnalyzeWrong 等处重复粘贴7处，部分夹在 fetch 与 await res.json() 之间。

### 修复（wrong-book.js 798→683行，frontend/modules 与 frontend/static/modules 双写一致）
- 新增 `_mapWrong`（后端DTO→卡片模型：options 优先数组否则 option_a~e 组装；答案/用户答案字母A-E同时转数字索引供高亮、保留 answerLetter 供文字；映射 wrongId/status/wrongCount/lastWrongTime/knowledgePoint/chapter 等）。
- `_loadRealWrongQuestions` 分页（pageSize=100 while 拉到 total）调 `/api/qb/wrong/list`，失败才降级 localStorage；**每个 render() 后必须跟 bindEvents()**（含 catch 兜底分支）。
- `_refreshStats` 由真实错题聚合 total/mastered/unmastered 与未掌握题薄弱知识点 TOP8（按章节）。
- bindEvents 按每张 `.wrong-question-card` 内按钮顺序绑定：标记掌握→POST `/api/qb/wrong/{wrongId}/mastered`；取消掌握→PUT `/api/qb/wrong/{wrongId}` body `{is_mastered:0}`（后端 mastered 接口只单向置1，取消走 PUT 白名单字段，已验证两接口均200翻转）；移除→DELETE；加入复习→POST `/review`。
- question-practice.js 新增 init 读 sessionStorage('reviewQuestion') + `_startSingleReview`（消费一次性数据，置 practiceQuestions=[q]/total=1 后 render+bindEvents）。
- 修复0值falsy bug：`q.userAnswer || q.myAnswer` 在答案为A（索引0）时显示"你的答案: -"，改为显式 null/undefined 判断。

### 关键机制经验（新增调试经验）
- **模块生命周期**（static/core/module-base.js:14-22）：init 同步执行 beforeRender→render→afterRender(**async，不被await**)→bindEvents。故任何"异步加载数据后再 render"的模块，数据回调里 render() 后**必须自己再调 bindEvents()**，否则动态生成的卡片按钮无事件；不要依赖框架补绑。
- **冷加载等待**：错题/列表类首次冷加载可能 >4 秒（后端关联查询/初始化阻塞）。浏览器测试必须轮询等待卡片出现且 stats.total>0 再点击，否则点在空状态上误判"按钮失效"。
- **缓存破坏**：index.html 每个 `<script>` 用独立 `?v=`，改 JS 后必须 bump 对应模块版本号，否则浏览器持续用缓存旧版（表现为代码已新、页面仍旧）。bu.hotkey 硬刷新在本环境报 focus 错误不可用，靠版本号 + 导航带时间戳。
- 模块实例即 `Framework._modules[name]`（无 .instance 包裹）；container 是 `.content-scroll`。

### 前后端API审计（audit_api.cjs，可复用 node audit_api.cjs）
- 读 openapi.json（698路由）扫描前端 api()/fetch()，按 MODULE_PREFIXES 还原并参数化归一。80调用/46匹配/19未匹配；甄别后**真实缺失仅3个**：
  1. POST `/api/v1/fl/files/batch-tag`（file-library.js 批量打标签，后端无，对应用户49项之17）；
  2. `/api/ai/generate-questions`（sprint.js 假fetch+toast，后端无此名）；
  3. `/api/v1/videos/{id}/smart-note`（video.js 智能笔记，后端无）。
  - 其余16个为误报（模块内 fetch('/api/v1'+path) 封装、ID在引号外拼接只截到前缀、离线兜底 /static/data/offline 非API）。

### 浏览器实测（bu平面，通过）
- 错题本真实46条；统计"共46道/已掌握/未掌握"随真实 is_mastered 变化；薄弱知识点真实聚合（如"2相关法律法规(7)、第3章第3节 工程项目计划与控制(4)"）。
- 加入复习→POST /review 200→跳 #/question→刷题页 1/1 单题、题干选项A-D正确、UI完整。
- POST /mastered 与 PUT {is_mastered:0} 端到端均200且状态翻转；DELETE 路由存在（routes.py:483）。
- index.html 版本号：wrong-book ?v=20260919wb8put、question-practice ?v=20260919qb9review。
- 测试后已恢复数据（仅 wrong_id=540 保持掌握，总46条）。


---

## 2026-09-19 学习看板(dashboard)三问题闭环 + Service Worker 缓存机制根治

### 修复（dashboard.js，frontend/modules 与 frontend/static/modules 双写一致，语法OK）
**问题1 快捷入口**：经浏览器实测，8个 quick-item 均已绑定 setPage(action)，index.html moduleMap 映射完整，真实点击"错题本"→#/wrong(wrong-book)、"模拟考试"→#/exam(mock-exam) 正常（此前疑"没挂"实为缓存旧版）。
**问题3 今日待复习（真实数据+可点击）**：
- 根因：列表只从本地 StorageService.wrongQuestions 取（本地为空→0条），虽 L167 已 fetch `/api/v1/question/wrong/today`（实测返回 total:45）却只取计数、丢弃 list。
- 修复：保存 wrongTodayList，todayReview 优先取后端到期列表前5（映射 wrongId=记录id、questionId）；模板去内联 onclick 改 data-wid/data-qid；bindEvents 绑 `.review-item`；新增 `_startReviewFromDashboard(qid,wid)`：POST `/api/qb/wrong/{wid}/review` 重置SM-2 → GET `/api/qb/questions/{qid}` 拉完整题 → 存 sessionStorage('reviewQuestion') → Framework.navigate('question')，question-practice `_startSingleReview` 消费，进入 1/1 单题复习。
- 浏览器实测：真实5道（wid450/qid3481 等），点击首项→#/question 单题、题干"总成本费用2500万…"正确、UI完整。
**问题2 学习日历（真实学习日）**：
- 根因：`d.toISOString().split('T')[0]` 用 UTC，UTC+8 下本地日期错位一天，study_trend 返回的 `2026-09-18`(26条) 匹配到 09-17，故全周灰色。
- 修复：改本地日期格式化 `getFullYear()-pad(month+1)-pad(date)`。实测 9/18 周五 study=true，今天19日 isToday 正确。
**去假数据（铁律②）**：state 初始写死的4道 todayReview（民法典2023/材料采购2017/银行保函800万/总成本2000万）与写死 weekDays 全部清空，todayReview=[] 并加 reviewLoaded 标志，加载前显示"正在加载今日复习…"，加载后0道显示"暂无到期复习"；calendar 初始 weekDays=[] 由 afterRender 同步生成当前周并立即 render。
**重复加载**：init 与 afterRender 各调一次 _loadRealData（同错题本曾犯问题），删除 init 中重复调用，仅 afterRender 一处；冷加载 4.5s→2.4s。

### ★ Service Worker 缓存机制根治（解决长期"改代码不生效、反复 bump ?v="）
- 根因：`frontend/sw.js` 对 `/static/` 资源用 **stale-while-revalidate + `caches.match(request,{ignoreSearch:true})`**，缓存键用无 query 的 pathname，故无论 index.html 里 `?v=` 改成什么，SW 都 ignoreSearch 命中并立即返回旧缓存，后台才 revalidate——表现为"服务器脚本已新、浏览器页面仍旧"，且必须再刷新一次。
- 修复：静态资源策略改为 **network-first**（在线 `fetch({cache:'no-store'})` 永远拿最新并回写缓存，仅离线/网络失败回退缓存）；CACHE_NAME 升级 `shuili-exam-v3-20260919i`→`shuili-exam-v4-20260919-netfirst`，activate 清理全部旧缓存。本地 localhost 学习系统网络优先零代价，PWA 离线能力保留（API GET 仍网络优先+运行时缓存、导航网络优先离线回退、媒体 Range 206 不变）。
- 已在浏览器注销旧 SW、删除 v3/data/videos 三个缓存后重载验证：改 JS 后普通刷新即生效，**今后无需再手动 bump 模块 ?v= 版本号**（保留 bump 也无害）。

### 实测结论
- dashboard：初始无假题（"正在加载"）→约2.4s 显示真实5道待复习；9/18 学习日高亮；快捷入口跳转正确；点击待复习端到端进单题复习。
- 产物脚本：fix_dashboard_review.py / fix_dashboard_fakedata.py / fix_calendar_tz.py / fix_sw_networkfirst.py（项目根，可复用/复跑）。


---

## 2026-09-19 ★静态服务目录真相澄清 + data-service配额崩溃根治 + 旧单体selectedSubjects修复

### ★★★ 最高优先级机制发现：`/static/*` 映射到 `frontend/*` 根，`frontend/static/` 是不被服务的影子副本
- 后端 `backend/main.py` L592/L599：`frontend_dir = get_resource_dir()/frontend`（开发态=项目根/frontend），`app.mount("/static", StaticFiles(directory=frontend_dir))`。
- 因此 URL→磁盘真实映射为：
  - `/static/modules/xxx/x.js` → **`frontend/modules/xxx/x.js`**
  - `/static/core/x.js`       → **`frontend/core/x.js`**
  - `/static/js/x.js`         → **`frontend/js/x.js`**
  - `/static/css/x.css`       → **`frontend/css/x.css`**
- **`frontend/static/` 整个目录不被任何路由服务**（全后端仅 /uploads、/static 两个 mount），是历史遗留影子副本。铁证：`frontend/static/js/layout-class-mapper.js` 磁盘存在，但 HTTP `/static/js/layout-class-mapper.js` 返回 404；HTTP `/static/js/app_v3_897262.js` 返回字节数= `frontend/js/` 那份而非 `frontend/static/js/` 那份。
- **纠正旧铁律**：此前"frontend/modules 与 frontend/static/modules 必须双写"的认知是错的——真正生效的只有 `frontend/` 根目录。双写无害但浪费，且曾导致"改了 frontend/static/js/app_v3 却不生效"的假象。
- **新铁律（替代旧双写说法）**：①所有前端改动一律以 `frontend/` 根目录（modules/core/js/css）为权威；②改完必须用 PowerShell `Invoke-WebRequest`（绕过SW/浏览器）或浏览器 `fetch(url?cb=时间戳,{cache:'no-store'})` 以 **HTTP 返回内容**为准确认生效，不能只看磁盘文件；③frontend/static/ 可同步作备份但不作为验证依据。
- 版本号机制（main.py L607-629）：后端每次请求 `/`(index.html) 实时生成时间戳，正则把所有 .js/.css 的 src 注入 `?v=时间戳`，且中间件对 .js/.css 设 no-store——配合 SW network-first，**改前端后普通刷新即生效，无需手动 bump、通常无需重启后端**。

### data-service 配额崩溃根治 + 全量接口归位（问题44"运行一段时间崩溃"元凶之一）
- 根因1（配额）：`_setLocalCache` 仅单文件 5MB 阈值，无法防止 flashcards/notes/mindmaps/questions 多缓存累积撑爆 localStorage 总配额（约5MB），mindmaps.json 持续 `QuotaExceededError`。
- 修复：改为**配额感知 LRU**——单文件阈值 1.2MB（超过只留内存）；总阈值 4.2MB；写入捕获配额异常后，遍历本前缀(`zhixue_data_cache_`)缓存按 timestamp 升序清理最旧项直到腾出空间，再重试一次，仍失败则仅内存。
- 根因2（双写不一致）：`frontend/core/data-service.js`(249行，getQuestions 用正确全量接口 `/api/qb/all`、getFlashcards 用 `/api/v1/flashcard/list`) 比服务实际加载的旧版(224行)新；旧版误用 /random（只认 count 默认10，会导致全模块只有10题）且有 `result is not defined`。已以 frontend/core 新版为基础打配额补丁（frontend/core 为权威服务文件，frontend/static/core 同步）。
- 实测：`/api/qb/all?subject=一造管理` 返回 1043 题、`/api/v1/flashcard/list` total=483；浏览器清旧缓存重载后 DataService.getQuestions 返回 1043 题、配额错误 0。

### 旧单体 app_v3 selectedSubjects.includes TypeError 修复
- 现象：控制台 `TypeError: selectedSubjects.includes is not a function`（启动多次）。根因：`Store.selectedSubjects` 默认是对象 `{majorId:[shortName...]}`（L170 `JSON.parse(...||'{}')`），但 loadSubjects 内 major 过滤与全局 #globalSubject 过滤两处直接 `Store.selectedSubjects||[]` 后调 `.includes`，对象 truthy 致 `||[]` 不生效、对象无 .includes。
- 修复（权威文件 **frontend/js/app_v3_897262.js**，最初误改 frontend/static/js 影子副本不生效，已据上述目录真相改对）：两处做形态归一——数组直用；对象则 major 内取 `[Store.currentMajor]`、全局取 `Object.values().flat()`；字符串包成单元素数组。L21929 `_isSubjectSelected` 本已有 Array.isArray 保护，无需改。
- 实测：HTTP 返回含 `_ssRaw` 修复；浏览器重载后 selectedSubjects 错误 0、配额错误 0、dashboard 页原生 JS 错误 0。

### 产物脚本（项目根，可复跑）
- fix_data_service.py（配额LRU+以core新版同步static）、fix_selected_subjects_real.py（改权威 frontend/js）、fix_selected_subjects.py（影子副本，留档）。


---

## 2026-09-19 学习笔记模块 note 功能补全 + 全模块功能真实状态盘点（专家会诊）

### 一、关键认知纠正：渲染扫描会误判，功能判定以「源码静态分析 + API连通性 + 最底层点击」为准
- 早期仅在浏览器渲染后数 `button/.btn/[onclick]`，把用 `div.tab/div.card` 实现交互的模块误判为「0按钮空壳」。
- 改用源码静态分析（fetch调用数 / addEventListener·onclick绑定数 / API URL / 占位词）+ PowerShell实测API + 浏览器最底层点击后，确认以下模块**功能实际完整，并非缺失**：
  - **analytics 智能分析**（约718行，4Tab：数据分析/考点图谱/真题分析/大纲分析），依赖9个API全部200（overview/study_trend/weak_points/knowledge-graph三件套/sprint heatmap/exam_analysis overview+constant_points）。
  - **memory 记忆训练**（973行，5 fetch/36绑定，flashcard list+review_today+assistant/ask）。
  - **mindmap 思维导图**（823行，7 fetch/21绑定，mindmap/save等）。
  - **video 视频讲义**（1685行，4 fetch/34绑定，真实上传/删除/进度API）。
  - **collect 我的收藏**（490行，11绑定，collect/list真实API；表0行时空状态本身正确）。
- 结论：今后判定模块是否空壳，**禁止只数button**；必须用 analyze_weak_modules.cjs 式静态分析 + openapi/实测API + setPage 真实路径点到底层。

### 二、API连通性实测（PowerShell，均真实返回数据）
- analytics 9个API全200：overview(total_answered614/accuracy41.9%/total_wrong536)、study_trend、weak_points、knowledge-graph overview(total_chapters99/total_questions1080)、key-points(86点/45关键)、weak-points、sprint/heatmap、exam_analysis overview(1043题/183考点/28恒重)+constant_points(20恒重)。
- sprint：heatmap/weak_points/exam/stats 均200；brain/plan-learning(POST)200；rag/chat(POST)200；collect/list 200（空）；flashcard/review_today 200（270KB）；storage_info 200。
- rag/search 用POST（GET返回405=路由存在）。
- **确认缺失后端接口：POST /api/ai/generate-questions → 404**（sprint「生成题目」按钮依赖；问题45人工复核流程也依赖）。另两个此前audit确认缺失：POST /api/v1/fl/files/batch-tag（资料库批量标签联动，问题17）、/api/v1/videos/{id}/smart-note（视频智能笔记）。

### 三、学习笔记 note 模块重构（frontend/modules/note/note.js，v1.0.0→v1.1.0，已HTTP验证+浏览器实测）
修复问题25（按钮hover看不清）、问题26（新建按钮/死按钮），并落实铁律②（禁硬编码）：
1. **删除constructor里3条2025年假笔记**（工程造价/招投标/流水施工），state.notes=[] + loaded标志 + 列表「正在加载…/暂无笔记」空状态。
2. **修复init与afterRender重复加载**（同dashboard旧bug）：数据只在afterRender加载一次，init不再触发_loadRealNotes。
3. **工具栏约25个装饰死按钮全部接真实功能**（事件委托，mousedown阻止contenteditable失焦）：bold/underline/italic/undo/redo/有序无序列表/分隔线/左中右对齐/清除格式/引用块/代码块/正文标题切换/字号/文字颜色/字体/链接/图片/表格(行列prompt生成)/符号插入/全屏；行高给明确toast。浏览器实测加粗产生`<b>`。
4. **章节下拉全部接教材章节树真实API** `/api/v1/question/chapter_tree?subject=当前科目`（取tree[].chapters[].num/title，label=「第N章 标题」）：侧栏筛选、编辑器内select、新建/编辑弹窗三处统一；章节树未加载时退化为「已用章节聚合」，不写死。实测下拉35项（全部章+34真实章）。
5. **编辑器内章节select接入保存**（旧版选章不生效）：saveInlineNote读取章节写book_id；富文本保存改用 innerHTML 保留加粗等格式；无选中笔记时点保存=自动新建。
6. **hover对比度增强**（铁律⑨配色）：工具栏按钮hover由#e5e7eb改为#dbeafe底+#1d4ed8字；列表项hover #eff6ff、active #dbeafe，文字清晰。
7. 弹窗取消/保存由脆弱内联 `this.closest('div[style*=fixed]')` 改为 addEventListener 绑定 data-note-cancel/data-note-save；导出/朗读绑定从异步_loadRealNotes末尾移到bindEvents（避免每次重载重复绑定）。
- 实测：8条真实笔记、无假数据、25按钮全带data-cmd、新建弹窗35真实章节、加粗生效、原生JS错误0。测试中临时创建的笔记已删除（恢复8条，无脏数据）。
- 影子副本 frontend/static/modules/note/note.js 已同步（注：该目录不被服务，仅备份）。

### 四、analytics 清理硬编码（frontend/modules/analytics/analytics.js）
- 删除constructor里无引用的 this.chapters（15个写死章节，死数据）；this.weakPoints 初始改 []，由 /analytics/weak_points 真实数据填充。语法OK、HTTP生效。

### 五、新增可复跑脚本（项目根）
- analyze_weak_modules.cjs：静态分析薄弱模块（fetch数/事件绑定数/API URL/占位词/行数），用于替代「只数button」的误判。
- fix_analytics_hardcode.py：清理analytics硬编码并同步影子。

### 六、下一步（待办，按49项与真实缺口排序）
1. material.js 含「开发中」占位（问题27视频讲义/大纲教材计数与目录树）需定位接通。
2. 三个缺失后端接口：/api/ai/generate-questions（sprint+问题45人工复核）、/api/v1/fl/files/batch-tag（问题17批量标签联动）、videos smart-note。
3. 对 memory/mindmap/video/knowledge/sprint 静态分析「有绑定」的模块逐一浏览器点到底层验证（静态只证明有代码，未证明端到端可用）。


---

## 2026-09-19 课程教材 material 模块真实数据重构 + 旧单体看板异步竞态崩溃根治

### 一、material 课程教材模块（frontend/modules/material/material.js，v1.1.0 → v1.2.0）
**根因（典型"两层皮/字段不匹配致真实数据从不加载"）**：旧 `_loadRealFiles` 假设 `/material/list` 返回 `items`、`/material/tree` 有 `children` 字段，实际真实结构是 `list` 与 `tree[].materials[].chapters`；最外层 `if(materials&&materials.items)` 恒为 false，整段短路，页面永远显示 constructor 里写死的 1 教材/3 章/12 拆分文件假数据。PDF 预览点击仅 `alert('PDF预览功能开发中')`。大纲 Tab 6 章全写死。

**真实 API 结构（已 PowerShell 实测，重写直接采用）**：
- `GET /material/list?page=1&page_size=200` → `{total,page,page_size,list:[...]}`（字段是 **list**）；全局 api 封装按当前科目过滤，一造管理仅 1 本（id=48「2025一造管理教材」file_path=uploads/37e2772f….pdf）；不带科目共 5 本。
- `GET /material/tree` → `{tree:[{subject,materials:[{id,title,chapters:[{num,title,start_page,end_page,level}]}]}]}`（**无 children**）；id=48 共 34 章（level1=6 章、level2=28 节）。
- `GET /material/split_files/{mid}` → `{files:[{name,size,url}],zip_path,csv_path}`；id=48 共 27 个拆分 PDF，url=`/uploads/split_output/48/xxx.pdf`。
- `GET /syllabus/list` → `{list,total:1}`；唯一大纲 id=7「2025大纲-一造管理.pdf」chapter_count=6/point_count=87。
- `GET /syllabus/{sid}` → `{...,content:{chapters:[{name,sections:[{name,points:[{name}]}]}]}}`（真实章→节→考点树，渲染 6 章/116 节考点行）。
- PDF 直链 `/uploads/{file_path}` 返回 200 application/pdf（教材 34MB），可直接 iframe 预览并 `#page=N` 跳页。

**改动**：删除全部硬编码 textbooks/catalog/files（改 []+空状态）；数据加载移到 afterRender 单次（_loadAll：list→tree→当前教材 chapters/split_files→syllabus）；教材目录树渲染当前教材真实 level1/level2（章可折叠、节点击打开整教材 PDF 并跳 start_page，修复问题33 树下拉空）；分解教材列表渲染真实 27 文件+打包 ZIP/目录 CSV 链接；大纲 Tab 左列表右内容、点击大纲调详情渲染真实 87 考点（修复问题27 大纲计数，标题用真实 title）；openReader 改为全屏 modal + `<iframe src="/uploads/...#page=N">` 原生 PDF 预览（跳页输入/新窗口/关闭），替换"开发中"alert；删除 bindEvents 重复绑定；保留 2Tab 左右分栏 CSS 布局不动（铁律①）。
**实测（bu，setPage('material')，清 SW 缓存后）**：教材下拉 2 项（占位+一造管理 id48，selected=48）、章标题 6、节 28、拆分文件 27、ZIP/CSV 链接在；大纲 Tab 1 大纲/6 章/116 节考点行/标题真实；点节弹出阅读器 iframe src=`/uploads/37e2772f….pdf#page=1`；原生 JS 错误 0。

### 二、旧单体 renderDashboard 异步竞态崩溃根治（frontend/js/app_v3_897262.js，问题44）
**根因**：旧单体 `renderDashboard(c)`（L4061，497 行，5 个 await：/analytics/overview、/question/wrong/today、/assistant/study_plan、Promise.all(subject_balance+exam_stage)、/analytics/chapter_accuracy）在看板页启动后异步 await；期间用户切到其他模块（如 material），容器 c 被替换，await  resolve 后继续 `getElementById('statTotal').textContent=…` 等操作 → `Cannot set properties of null`，每次进出看板刷 6 个 TypeError（潜在运行崩溃源）。
**修复**（fix_dashboard_guard.py）：函数开头插 `if(!c||!c.isConnected)return;`，5 个 await 语句之后各插 `if(!c.isConnected)return;`（共 6 处守卫）；页面已切走则中止旧渲染，看板正常停留时 c 始终 connected 不影响渲染。语法 OK、HTTP 验证 6 处 isConnected 生效。
**实测**：连续 3 次"进 dashboard 等 1.2s 立刻切 material"竞态后，renderDashboard 错误 0、原生 JS 错误 0；material 数据正常恢复（6 章/27 文件/大纲 116）。

### 三、验证与同步
- material.js 语法 OK、HTTP 返回含 _loadAll、旧硬编码教材名已消失；影子 frontend/static/modules/material/material.js 已同步。
- app_v3 语法 OK、HTTP isConnected=6；影子 frontend/static/js/app_v3_897262.js 已同步。
- 经验固化：判定"功能缺失/硬编码"必须看真实 API 字段（用 PowerShell 取 JSON keys），字段名不匹配（items vs list、children vs tree[].materials[].chapters）是真实数据不加载的最常见根因；旧单体 async render 函数在模块化单页里必须加容器 isConnected 守卫防切页竞态。
- 脚本：fix_dashboard_guard.py（已运行）。


---

## 2026-09-19 智能知识库 knowledge 模块实测确认 + 去硬编码（问题36）

**结论：知识库 RAG 功能本就真实接通，并非"未运行"；本轮实测端到端通过并清理预置假数据。**
- 后端（已 POST 实测 200）：`/api/v1/rag/search?use_rerank=true` 返回 `{code,data:{query,total,top_k,results:[{doc_id,title,content,category,similarity,metadata}]}}`；`/api/v1/rag/chat` 返回 `{code,data:{answer}}`。注意响应统一 `{code,data}` 包裹，前端 knowledge.js 已正确解析 `json.data.results` / `json.data.answer`（L432/L494）。
- 本地大模型为 CPU 推理，chat 约 75 秒超时后后端**自动降级**：data.answer 返回"本地大模型未完成回答，以下是最相关资料片段"+检索片段（环境限制，非 bug，前端有"思考中 30-90 秒"loading 并能展示降级文本）。
- UI 实测（setPage('knowledge')）：检索"预备费计算"→ 找到 10 条真实教材 PDF 片段（已 AI 重排序，显示分类/相关度/正文，如"WM_50.第6章第5节：竣工阶段造价管理.pdf"）；对话 Tab 发送"什么是基本预备费"→ 用户气泡+AI 思考气泡正常，原生 JS 错误 0。
- 治理（fix_knowledge_hardcode.py）：constructor 预置的 6 条 `_knowledgeBase` 假知识（工程造价/招投标/网络计划/资金时间价值/预备费等写死条目）清空为 `[]`。核实 showAddModal/showEditModal/deleteKnowledge 等本地增删改方法**无任何 UI 入口**（结果项 L234-243 仅展示 title/source/relevance/content，无编辑删除按钮），属死代码，预置数据从不显示，清空仅为杜绝将来误调用；RAG 检索结果不受本地方法污染。searchHistory 三个热门搜索词为 UI 引导保留。
- 影子 frontend/static/modules/knowledge/knowledge.js 已同步，HTTP 验证 `_knowledgeBase=[]`、假数据不残留、语法 OK。


---

## 2026-09-19 冲刺中心sprint数据真实化 + 框架navigate参数透传 + 题库章节自动定位（问题39/框架级）

### 一、冲刺中心 sprint 去硬编码、接真实API（frontend/modules/sprint/sprint.js，v1.1.0）
- **根因**：constructor 硬编码 hotPoints 6条、weakPoints 5条；`_loadHeatmap`/`_loadHotList` 请求 `?subject=`（空科目，后端返回99章多科目混合，首条"2相关法律法规"=79题）；`_loadWeakList` 不传科目；"AI智能出题"按钮 POST `/api/ai/generate-questions`（后端确认404缺失）却 `.then` 弹"已生成N题"假成功。
- **修复**：
  1. hotPoints/weakPoints 初始置空，加"加载中/暂无数据"空状态，全部由真实API填充。
  2. 新增 `_subject()`（Store.currentSubject→localStorage currentSubject→默认一造管理），heatmap、weak_points、hot 三处URL统一 `encodeURIComponent(this._subject())`。
  3. `_loadWeakList`/`_loadHotList` 缓存 `this._realWeak`/`this._realHot`，供AI出题取真实薄弱章节。
  4. AI智能出题改为：取 `_realWeak[0].chapter`，`Framework.navigate('question',{chapter,filter:'weak'})` 跳真实薄弱章节训练；删除404假成功fetch。
- **实测（清SW缓存后）**：subject=一造管理，高频TOP6首条73题（一造管理口径，区别于空科目79题）、薄弱8条、热力图10章、模考趋势 recent_scores 10条；AI出题/薄弱项/高频项点击均跳 #/question；0原生错误、无 generate-questions 404。解决"高频考点只有3章"。

### 二、框架级修复：navigate 参数透传 + hashchange 覆盖（frontend/index.html）
- **根因1**：`Framework.navigate(pageId,params)` 只 `hash='/'+pageId; renderPage(pageId)`，**params被丢弃**；renderPage 给模块 init 的 params 只有 `{pageId}`。
- **根因2（竞态覆盖）**：navigate 先改 hash 再 renderPage；hash 变化异步触发 `hashchange` 监听器，其无参 `renderPage(pageId)` 在带参渲染之后再次执行，把模块 options.params 覆盖回 `{pageId}`，导致跨页跳转参数丢失（同页 navigate 因 hash 不变不触发 hashchange，故手动测试曾"正常"，极具迷惑性）。
- **修复**：
  1. `renderPage(pageId,navParams)`：init 的 params 改 `Object.assign({pageId}, navParams||{})`。
  2. `Framework.navigate(pageId,params)`：置 `Framework._navHandled=pageId` 后改 hash，并 `renderPage(pageId,params)`。
  3. hashchange 监听器：若 `Framework._navHandled===pageId` 则消费标记并 return（navigate已带参渲染，不重复无参覆盖）；浏览器前进/后退/手动改URL仍走无参 renderPage。

### 三、题库刷题消费 chapter 参数自动定位（frontend/modules/question/question-practice.js）
- afterRender 在 `await _loadChapterStats()`（章节树已重渲染）后新增 `_locateParamChapter()`：读 `this.options.params.chapter`，复用唯一真源 `_parseChapter`（已兼容"第X章第Y节/第X章/X.Y/裸数字开头章名/规范章名"五种格式）。
- 节级（sec!=null）：只勾选目标节（如 2.1），父章由现有级联 onchange 按全选状态决定，避免误勾整章。
- 章级（sec==null）：勾选父章并触发其 onchange 级联勾选全部子节；scrollIntoView 定位 + toast 提示"点击开始练习强化"，不自动开始（用户确认）。
- **实测**：节级"第2章第1节 建筑法…"→仅勾 2.1；章级"工程项目管理"→勾 3+3.1~3.7；裸章名"2相关法律法规"→勾 2+2.1~2.4；params 正确携带 chapter；0错误。

### 四、变更文件与验证
- frontend/modules/sprint/sprint.js（同步 frontend/static 影子）、frontend/index.html、frontend/modules/question/question-practice.js（同步影子）。
- 脚本：fix_sprint.py、fix_nav_params.py、fix_hash_guard.py、fix_question_locate.py、fix_locate_sec.py、verify_sprint.cjs。
- 全部经 node vm 语法检查 + HTTP(?z=时间戳,no-store)内容验证 + 清SW缓存浏览器端到端实测。
- 遗留：POST /api/ai/generate-questions 后端仍缺失（问题45 AI生成+人工复核流，当前AI出题以"定位真实薄弱章节训练"替代，不再假成功）；filter:'hot'/'weak' 参数 question 侧目前仅用 chapter 定位，未按 filter 改变题型筛选（章节强化已满足主诉求）。


---

## 2026-09-19 思维导图mindmap渲染报错根治 + 节点编辑事件委托（问题34/35，纯功能不改布局）

### 实测确认（已具备，无需重做）
- 节导图/章导图/科目导图三级均用 **markmap 真实渲染图形**（svg.markmap），非 Markdown 文本简化；选中节后问题版（填空）+答案版双图。
- 新建导图：自动加载模板（核心概念/知识框架/易混辨析/记忆口诀等结构），**无"加载模板"按钮**（已自动加载）。
- 顶部无"合成导图/从PDF生成/智能导图拆分"按钮（已移至文件资料库）；"我的导图"为真实数据（13张，编辑/删除）。
- 数据来自真实导图库（如1.1节 questionId=18/answerId=15），节点编辑器 MindElixir 4.3.4 正常（打开后11个svg节点，支持Tab加子节点/Enter同级/F2改文字/Delete/拖拽）。

### 修复① markmap/d3 的 SVGLength 渲染报错（36个→0）
- **根因**：`_mount` 创建 `svg width/height=100%` 后立即 `Markmap.create`；当容器处于隐藏 Tab/折叠面板（clientWidth/clientHeight=0）时，d3 无法解析相对长度，抛 `NotSupportedError: Failed to read the 'value' property from 'SVGLength': Could not resolve relative length`（科目导图一次性渲染多图时集中爆发）。
- **修复**（mindmap.js `_mount`）：create前轮询等待容器具备真实布局尺寸（最多2秒）；仍为0时用绝对像素兜底（960×380）创建，杜绝相对长度解析失败；svg 属性写像素、内联 style 仍 100% 自适应；挂 ResizeObserver，Tab 由隐藏变可见时自动 `inst.fit()`。**不改任何容器尺寸/布局**（曾临时加 minHeight:360px，后按用户"不改布局"铁律撤销，功能修复不受影响）。

### 修复② 节点编辑按钮点击偶发失效（事件委托）
- **根因**：选中节后导图 md 异步加载，`.mm-node-edit` 按钮在 `bindEvents` 之后才插入 DOM，直接 `el.onclick=` 绑定漏绑新按钮，表现为点击无反应。
- **修复**：改为在容器上一次性**事件委托**（`_mmNodeDelegated` 标记防重复），`e.target.closest('.mm-node-edit')` 捕获，无论按钮何时异步插入都能打开 `_openNodeEditor(which)`。

### 验证
- 清SW缓存后：节/章/科目三级导图 markmap 正常；真实点击路径（选节→点✏️节点编辑）MindElixir 全屏编辑器正常打开（11 svg）；SVGLength 错误 0、其他原生致命错误 0。
- 变更文件：frontend/modules/mindmap/mindmap.js（同步 frontend/static 影子）；脚本 fix_mindmap_svg.py、fix_mindmap_nodeedit.py、revert_mindmap_minheight.py。


---

## 2026-09-19 思维导图章/科目Tab新布局：只留答案版（用户明确布局指令）

### 需求（用户原话）
"章导图和科目导图只留答案版，章只显示下拉章供选择，科目不用下拉，直接显示。"

### 改动（frontend/modules/mindmap/mindmap.js，仅章/科目Tab，节导图不动）
1. **章导图**：保留"下拉选章"（#mmChapterSelect，6章）+ 导出本章MD；**移除答案版/问题版切换按钮**（_modeToggle('mmCh')），挂载与导出固定 `mode='answer'`；删除 .mmChMode 切换绑定。切换下拉章即刷新该章答案版导图。
2. **科目导图**：**无下拉、无模式切换**，进入Tab直接 `_mountAgg('mmSubjectBody','answer',()=>true)` 显示全科汇总答案版；标题改"科目导图 - 一造管理（全科汇总·答案版）"；导出固定答案版；删除 .mmSubMode 切换绑定。
3. **节导图保持原样**：选中节后仍是"问题版（填空）+答案版"双 markmap 图、各带✏️节点编辑（question/answer），未受影响。

### 实测（清SW缓存）
- 章导图：下拉6章、无切换按钮、仅答案版（第1章5节→5个答案svg；切第3章→该章答案导图，正文真实）；导出按钮在。
- 科目导图：无下拉、进入即显示全科答案版（27节 svg，3.7暂无导图故27）、无切换按钮。
- 节导图：选中1.1→问题版+答案版2个svg、节点编辑 question/answer 两个按钮均在。
- 全程0原生错误（含SVGLength）。
- 脚本 fix_mindmap_answer_only.py；frontend/static 影子已同步。


---

## 2026-09-19 视频「来源文件夹可选 + 讲义自动关联」与题库「左右滑动切题」（用户两需求闭环）

### 需求（用户原话）
1. "播放视频来源文件夹要可选择，讲义自动同步关联显示"；视频讲义数据源应为"精讲班-蒋.莉莉(50个)"而非"精题必练(14个)"。
2. "题库刷题支持左右触屏滑动切题"。

### 一、数据修复（根因，先治数据再治代码）
- 核查 `/api/v1/video/list`：共 **64** 个视频，folder 已正确分组——`01.精讲班-蒋.莉莉` **50**（.flv，chapter=节级 1.1）、`02.精题必练-蒋.莉莉` **14**（.mp4，chapter=章级 1）。
- 核查 lectures 表：未删 **98** 条（01精讲班50 + 02知识点精讲48），关联键=chapter（覆盖27节）。但 **71 份讲义PDF物理缺失**（DB file_path 指向的 uploads hash 文件不在盘；uploads/lectures 根目录平铺的50个pdf全是 is_deleted=1 旧批次遗留）。
- 源文件定位与桥接（脚本 restore_lecture_files.py，dry-run 后 --apply，**只增不删不改库**）：
  - 精讲50讲源=`backend/data/files/考试类学习资料/一造培训资料/2026-一造管理 环球/02.精讲班-蒋.莉莉/讲义/`（文件名"第N讲"，与DB WM序号一一对应）；
  - 知识点精讲源=`backend/data/files/2025-一造管理 蒋.莉莉/02.知识点精讲/讲义/`；
  - 按"讲次N"匹配，复制到DB期望的 `backend/uploads/lectures/01.精讲班-蒋.莉莉/<hash>.pdf`（50）与 `02.知识点精讲/`（补21）。
  - 结果：已在位27 + 复制71 = **98条讲义全部物理就位、0缺失**；HTTP `/uploads/lectures/01.../<hash>.pdf` 实测 200 application/pdf（首个文件曾404系SW缓存早先404，注销SW+清caches后200）。

### 二、后端（backend/api/v1/lecture.py）
- `/lecture/list` 每条补返 `file_path` 与 `url`；url 在循环内按磁盘绝对路径中 `uploads/` 子串计算为 `/uploads/lectures/...` 相对URL（修复首版误拼成 `/F:/...`）。
- 注意：main.py 的 uvicorn 未开 --reload，运行中的旧后端进程为管理员权限、普通权限杀不掉；**接口层 url 字段生效需双击项目根"重启后端.bat"并在UAC点"是"**。前端已用 _handoutUrl 从 file_path 自行提取相对URL，**不依赖后端重启即可用**。

### 三、前端 video.js（权威 frontend/modules/video/video.js，已同步 static 影子）
1. **来源文件夹下拉**：播放列表头部 `#videoFolderSelect`（全部64 / 01精讲班50 / 02精题必练14，带数量）；切换 onchange 设 currentFolder→重渲染→setTimeout 恢复 initFlvPlayer。
2. **默认精讲班**：_applyDefaultFolder 自动选中名字含"精讲班"的文件夹（进入即列50讲，不再默认精题必练14）。
3. **讲义自动关联**：afterRender 拉 `/lecture/list?subject=一造管理&page_size=500`（98条）；播放视频时 _matchLectures 按 **chapter + 班次** 精准匹配——精讲班视频只关联同班次精讲讲义（同章节的"知识点精讲"不再张冠李戴），精题必练视频（讲义表无该班次）返回空并在 `#videoHandoutBar` 提示"该讲次为「精题必练」，配套PDF讲义请在「文件资料库」中查看"；章级视频兜底 startsWith(ch+'.')。
4. **健壮URL**：_handoutUrl 从 file_path/url 反斜杠转正斜杠后提取 `uploads/` 起的相对路径，兼容绝对磁盘路径与旧后端，兜底 `/api/v1/lecture/{id}/download`。
5. **关键bug修复**：normalizeVideos 原未保留 chapter（且用 item.chapter 兜底污染 folder），改为独立 `chapter: item.chapter||''`、folder 仅取 item.folder/extractFolder——否则讲义完全匹配不到。
6. chip 标题去 WM_序号/路径前缀；样式 .video-folder-select/.video-handout-bar/.video-handout-chip（蓝胶囊）。**未改任何布局结构**。
- 脚本：fix_video_handout.py、fix_handout_url_fe.py、fix_video_chapter.py、fix_match_lectures.py；诊断 check_lectures.py、diag_lecture_map.py、diag_lecture_src.py；后端 fix_lecture_url.py/fix_lecture_url2.py；数据 restore_lecture_files.py。

### 四、前端 question-practice.js（左右滑动切题，已同步 static 影子）
- bindEvents 首行调 `_bindSwipeNav()`（container 事件委托，`_qpSwipeBound` 只绑一次，跨 render 持续有效）：
  - **触屏**：touchstart/touchend（passive，单指），水平位移须 >50px 且 >垂直位移×1.4；左滑(dx<0)触发 #qpNext、右滑(dx>0)触发 #qpPrev，与键盘 ←/→、Enter 同一通道（首题上一题按钮 disabled 自动跳过）。
  - **PC鼠标**：仅当 mousedown 目标不在 button/a/input/textarea/select/label/.qp-option/[contenteditable] 时才置位（题干/卡片空白处），window mouseup 横向拖拽>80px 切题；点选项/按钮不误触。
- 脚本 fix_question_swipe.py。

### 五、实测（清SW缓存，setPage 真实路径，14寸）
- 视频：下拉3选项数量正确；默认精讲班列50；点 chapter=1.1 精讲视频→讲义条出现**1个**精讲chip（📖【变】第1章第1节…，href=/uploads/lectures/01.精讲班-蒋.莉莉/a15691e….pdf，HTTP 200）；切精题必练列14、点章级视频显示资料库提示（0 chip）；切全部列64、切回精讲50；视频/讲义相关0新增错误（仅旧单体 app_v3 的 OfflineMediaCache 在 http 模式的预期提示，与本次无关）。
- 题库：进入20题练习，触屏连续左滑 1→2→3→4、连续右滑 4→3→2；小位移(20px)、纵向滑动不切；PC鼠标题干空白左拖 2→3、右拖 3→2；在 .qp-option 上拖拽不切、短拖(40px)不切；题库页0新增错误。

### 待办（不阻塞本两需求）
- 后端 lecture url 字段接口层生效需用户提权双击"重启后端.bat"（功能已被前端 _handoutUrl 绕过）。
- 视频上传测试(问题16)、网站资源播放器/扫码登录(问题32，webVideos仍3条B站硬编码)未在本次范围。


---

## 2026-09-20 视频讲义条位置调整：移至播放列表头部「文件夹下拉右侧」（用户明确布局指令）

### 需求（用户原话）
"讲义没有在 01.精讲班-蒋.莉莉(50个) 右侧显示。"

### 改动（frontend/modules/video/video.js，仅位置迁移，功能逻辑不变）
- 将 `#videoHandoutBar` 从播放器卡片内（播放器下方、智慧笔记上方）**移到播放列表头部 `.video-playlist-header` 内**，DOM 顺序：`共N个视频` → `#videoFolderSelect 文件夹下拉` → `#videoHandoutBar 讲义条` → `🔄刷新按钮`；讲义chip紧跟文件夹下拉右侧、同一行。
- CSS：`.video-playlist-header` 加 `flex-wrap:wrap`；`.video-handout-bar` 由独立卡片（自带背景/上边框/max-height:92px）改为 header 内联（`flex:1 1 220px; min-width:200px;` 透明背景、无边框、不限高），chip 仍为蓝胶囊。
- `_renderHandoutBar/_refreshHandoutBar` 逻辑、id 不变（精讲关联同班次讲义、精题必练提示去文件资料库、_handoutUrl 健壮URL全部保留）。

### 实测（清SW缓存，setPage('video')，14寸）
- header 子元素顺序 SPAN→videoFolderSelect→videoHandoutBar→刷新按钮；bar 在 select 右侧且同一行（barRightOfSelect=true、sameRow=true）；播放器内已无讲义条。
- 点 chapter=1.1 精讲视频，下拉右侧出现1个chip"📖【变】第1章第1节：工程造价基本内容"；flv 播放器正常播放。
- 脚本 fix_handout_bar_pos.py；frontend/static 影子已同步。


---

## 2026-09-20 变更记录（视频“文件夹对文件夹” + 文件资料库tab口径 + 移除朗读）

### 1. 视频播放列表改为“文件夹对文件夹”（用户明确布局指令，权威 frontend/modules/video/video.js）
- 旧实现：播放列表把“视频文件夹”机械左右平分，两列都是视频；讲义仅为头部/播放器内单个关联chip，方向错误。
- 新实现（用户原话：选择一个文件夹，左侧显示对应文件夹的视频，右侧显示对应文件夹的讲义）：
  - 下部播放列表固定两列：左列「🎬 视频文件夹（点击播放）」、右列「📖 配套讲义文件夹（点击打开PDF）」。
  - 顶部文件夹下拉选择：选某视频文件夹时，左列只显示该文件夹视频，右列只显示“对应讲义文件夹”；选“全部文件夹”时左列显示全部视频文件夹、右列显示全部讲义文件夹。
  - 对应规则 `_corrLecFolder()`：同名优先（01.精讲班-蒋.莉莉 视频↔01.精讲班-蒋.莉莉 讲义），否则按 01/02 序号前缀对应（02.精题必练-蒋.莉莉 视频 ↔ 02.知识点精讲 讲义）。
  - 新增 `_renderLectureColumn()`：讲义按 folder 分组、按 chapter 排序，每项为 `<a target=_blank>` 直接打开 PDF（_handoutUrl 取 /uploads/lecture/...）。
  - 讲义异步到达后局部刷新右列与头部计数（不整体 render，避免打断播放）；移除原 #videoHandoutBar 单讲义chip及其位置。
- 实测（清SW缓存，14寸视口）：默认精讲班=左50视频/右01精讲50讲义；精题必练=左14视频/右02知识点精讲48讲义；全部=左64视频(01精讲50+02精题14)/右98讲义(01精讲50+02知识点48)；讲义链接 /uploads/lecture/...pdf 可打开。

### 2. 文件资料库tab口径修复（49项问题15、27，权威 frontend/modules/library/file-library.js）
- 问题15：tab“🎬 视频讲义”改名为“🎬 视频”。
- 问题27：原“大纲教材”tab错误地把全部非视频文档（258个）计入；现按旧框架 _typeFilter=['教材','大纲'] 修正为仅“大纲/教材”两类，按文件夹分组显示为「教材(6个文件)」「考试大纲(2个文件)」两个文件夹（即用户心智中的教材1、大纲1两个文件夹；文件数为真实扫描，含一建大纲/水利定额等用户真实文件，不硬删）。
- getFilteredFiles 拆分：'doc'=全部非视频文档（供“全部”tab文档资料区，仍258个不丢）、'book'=仅大纲/教材（大纲教材tab，8个）；render() 相应使用 docFiles/bookFiles，tab计数同步修正。
- 实测tab：全部(322) / 视频(64) / 大纲教材(8)；全部tab仍为 文档资料(258)+视频(64)。

### 3. 移除文档资料朗读（49项问题19）
- 文件行操作本就只有 🏷️打标签/✏️重命名/📥下载/🗑️删除，朗读按钮已不渲染；清理 bindEvents 中残留的 .fl-speak-btn/TtsService“资料库朗读”死绑定，预览弹窗无朗读。

### 待续（资料库域）
- 问题17/20 批量标签：后端确认无 /api/v1/fl/files/batch-tag 路由；选中文件批量 batchTag() 已循环走可用的 PUT /api/v1/fl/{id}；文件夹级 folderTag() 仍写 localStorage、_batchTagFiles/batchTagFiles 仍调404接口，三套逻辑待收敛为一套并保证文件夹标签与内部文件标签联动（本次按用户纠正未展开）。
- 影子副本 frontend/static/... 已同步；node vm 语法校验通过；浏览器实测通过。


---

## 2026-09-20 变更记录（题库报错闭环 / 闪卡多模式导入 / 朗读语音草稿 / 二级模块导航修复）

### 0. 关键根因修复：二级模块导航从不刷新（影响闪卡卡片管理、思维导图、系统管理等所有子tab可达性）
- 现象：`#/flashcard` 等页面顶部二级导航（`#framework-module-nav`）始终 `display:none`，`layout-module-nav` 的 `currentPage` 永远停在 `dashboard`；闪卡“卡片管理”、思维导图“新建导图/模板库”等子页用户无法进入（批量导入等功能虽实现却够不到）。
- 根因：`index.html` 的 `renderPage()` 实际 emit 的是 `page:change`（单数，payload `{pageId}`），而 `module-nav.js` 监听的是 `page:changed`（复数，仅侧边栏点击时由 sidebar.js emit）；hash 路由/刷新/`Framework.navigate` 进入只走 renderPage，故二级导航不更新。另 navConfigs 的键是**模块名**（file-library/system-admin），而事件携带的是**路由id**（file_library/system_admin），口径不一致。
- 修复（权威 frontend/index.html、frontend/modules/layout/module-nav.js，影子 frontend/static 已同步）：
  - renderPage 改 emit `page:change {pageId, moduleName}`，并补发一次 `page:changed(pageId)` 同步侧边栏高亮（覆盖侧边栏点击/hash/刷新/navigate 全部进入路径）。
  - module-nav 新增 `applyPage(pid)`，监听权威 `page:change`（取 `moduleName`）；`page:changed` 仅作兼容且加 `navConfigs[pid]` 存在性守卫，避免路由id误清空。
- 实测（清SW+缓存、带时间戳）：闪卡二级导航显示5项（闪卡练习/数字考点/朗读记忆专练/公式专练/卡片管理），点“卡片管理”真实进入管理视图（批量导入/新建/导出按钮齐全、表格为真实卡片），切回正常；思维导图3项（思维导图/新建导图/模板库）恢复。系统管理为独立窗口页（window.open system-admin.html，无Framework属设计）。

### 1. 题库“🐛报错”端到端闭环（49项问题关联：识别错误题回流后台分析）
- 前端（frontend/modules/question/question-practice.js）：`_reportError()` 用系统统一弹窗（CommonUtils.showModal），7类错误（题干识别/选项/答案/解析/图片不清/重复脏题/其他）+描述；提交拼题目快照（题目ID/类型/说明/题干/选项/系统答案/年份/章节）POST `/api/v1/recognition_errors`；失败写离线队列 localStorage `qp_error_queue`。
- 后端（backend/api/v1/errors.py、models/recognition_error.py）：POST/GET `/api/v1/recognition_errors`、PUT `/api/v1/recognition_errors/{id}/status`，对齐真实表 recognition_errors（id/question_id/error_type/description/user_id/status default pending/created_at）。
- **修复双 v1 前缀 bug**：errors.py 的 router 原带 `prefix="/v1"`，main.py 挂载又加 `/api/v1`，实际注册成 `/api/v1/v1/recognition_errors`（前端请求单v1故404）；已去掉 router 的 /v1 前缀（fix_errors_prefix.py）。
- **修复自动补传时机**：`_flushErrorQueue()` 原在 `if(mode==='practice')` 块内，select 首页不执行；已提升到 bindEvents 顶层（fix_flush_timing.py），进入模块即幂等补传。
- 实测：HTTP 端到端 POST 真入库、GET 中文正确（“答案错误”无乱码）、PUT 改 fixed 成功；浏览器塞离线队列后停在 select 首页即自动补传入库；测试记录已清理（保留1条用户真实报错 qid3385 供后台分析）。

### 2. 闪卡“多种模式上传/导入”（用户最新明确需求）
- 后端（backend/api/v1/flashcard.py 末尾新增，已随重启生效）：
  - GET `/api/v1/flashcard/template_excel`：openpyxl 动态生成 .xlsx 模板（表头 正面*/背面*/口诀/类型/标签/章节/知识点名称/年份/页码 + 示例行 + 填写说明sheet，冻结首行）。
  - POST `/api/v1/flashcard/preview_excel`（multipart：file+subject）：支持 .xlsx(openpyxl)/.xls(xlrd)/.csv(utf-8-sig)，按表头别名智能映射列，正面/背面缺失行进 skipped（带行号原因），只解析不落库。
  - 落库复用既有 POST `/api/v1/flashcard/batch_import`（含质量门禁 FlashcardQualityPipeline、MD5去重、事务保护，返回 success/failed/total）。
- 前端（frontend/modules/flashcard/flashcard.js 重写 showBatchImport）：统一弹窗三 Tab——📊 Excel/CSV（下载模板、选择文件 accept=.xlsx/.xls/.csv、拖拽区、XHR upload.onprogress 真实进度条）、📝 文本粘贴（10/3/2字段 `|||` 格式，_fcParseText 复刻后端解析）、{ } JSON；三模式统一“解析→预览表格（每行勾选/全选、正面/背面/口诀类型标签、跳过行原因、统计）→确认导入”，确认走 batch_import，进度条+结果提示，完成后 _loadRealCards 刷新并自动关弹窗。
- **修复 Tab 切换 bug**：面板用 data-pane 而切换逻辑读 dataset.tab，切Tab后面板全隐藏；已统一为 data-pane/dataset.tab 比较（fix_fc_tab.py）。
- 实测（浏览器真实端到端，测试卡已清理，残留0）：文件模式上传 .xlsx 预览2张、跳过“第4行背面空”、字段（口诀/类型/标签/科目）完整，确认导入成功2失败0；文本模式2/3字段混合解析2张导入成功；JSON模式3条（1缺back被忽略提示）导入2成功；模板按钮真实下载 flashcard_template.xlsx（6512字节，completed）。

### 3. 题库朗读 + 语音答题（免看屏）
- 朗读 `_speakQuestion()`：未作答读“题目…选项A…B…”；作答后读“回答有误/正确，你选的是X…正确答案…解析…”。
- 语音 `_voiceAnswer()`：浏览器原生 SpeechRecognition（中/英、连续甲乙丙丁戊、第X个/X项、判断对错、念选项内容包含匹配），单选直判、多选累积说“提交/确定/确认/好了”才提交，TTS 播报对错。
- **修复解析误判**（fix_voice_parse.py 重写 _parseVoiceLetters）：原正则连续天干“甲丙”只识别出C、“百分之十二”的“二”误判为B；改为天干逐字全局扫描、中文数字要求“第X/X个/X项”语境或整句≤2字、念选项内容做中文数字归一化后包含匹配（key≥4字符）。实测 甲丙→AC、甲乙戊→ABE、百分之十二→[]、大于12→D、第二个→B、判断正确→A/不对→B 全对；端到端判分（单选/多选）正确。

### 4. 题库草稿纸
- localStorage `qp_drafts`（{questionId:{text,savedAt}}），textarea oninput 400ms 防抖自动保存，普通题与案例题均有面板；切题草稿隔离、切回恢复、刷新后 _ensureDrafts 重载、清空只清当前题。浏览器实测通过。

### 5. 运行态与验证
- 后端经“重启后端.bat”UAC 重启，新 PID=2084，单 v1 报错接口、闪卡 template_excel/preview_excel 均经 openapi/HTTP 验证为新代码（health 200 不能判别新旧，以 openapi 路径与新接口行为为准）。
- 前端权威 frontend/ 改动均 node vm.Script 语法校验通过并 Copy 同步 frontend/static 影子；浏览器验证前注销 SW + caches.delete + 带新 `?_z=` 时间戳。
- 复跑脚本（项目根）：fix_module_nav.py、fix_errors_prefix.py、fix_flush_timing.py、fix_fc_import.py、fix_fc_tab.py、fix_voice_parse.py、add_flashcard_excel_api.py、verify_error_http.py、verify_flush_auto.py、verify_fc_excel.py、make_test_xlsx.py、cleanup_fc_test.py、scan_syntax.cjs。测试样例 xlsx 与测试卡/测试报错均已清理。


---

## 变更记录 · 题库刷题/解析/错题/学习分析 14 项专项（V4.5.15，2026-09-20）

> 原则：不改布局只改功能；全部走真实 HTTP + 浏览器 bu 点击端到端实测；严禁硬编码/演示/随机假数据；权威 frontend/ 改完 node vm.Script 校验并 Copy 同步 frontend/static；后端经“重启后端.bat”重启并以新字段/接口行为验证。

### 后端补丁（均已重启、HTTP 验证）
1. `backend/modules/qb/service.py`：`_Q_COLUMNS/_Q_KEYS` 由 17 列扩到 34 列（补 score/is_outdated/outdated_reason/section_name/point_name/point_id/chapter_id/is_high_freq/is_constant/case_background/case_sub_questions/case_total_score/sub_questions），修复 /api/qb/all 不返回 is_outdated 致前端过滤失效。
2. `record_answer` 错题首错计数 bug：原先 INSERT wrong_count=1 再 UPDATE +1（首错变 2），改为 INSERT 0 + 统一 +1，首错=1。
3. `backend/schemas/schemas.py` NoteIn 加 question_id:int=None、subject:str=""；`backend/models/models.py` Note 模型加 question_id 列（index，关联刷题快速笔记）；`backend/crud/crud.py` create_note 写入。修复 `'question_id' is an invalid keyword argument for Note`。
4. `backend/api/v1/analytics.py` weak_points 每组附带真实 `question_ids`（未掌握错题ID），供前端 AI 薄弱练习精准组卷，不做随机假题。

### 前端补丁（frontend/modules/question/question-practice.js，patch_fe_qb_1~10，均语法校验+同步+bu 实测）
- #1 草稿纸改**手写画板**（类华为笔记）：canvas 高清 2 倍、鼠标+触屏手写、颜色/粗细/橡皮、切题隔离、dataURL 存 localStorage(qp_drafts)、切回恢复；非 textarea。实测非白像素 2225、dataURL 16150 字符、持久化生效。后期简答题可复用。
- #2 提交后三色+文字徽标：选对 `user-correct`绿“✓ 选对”、错选 `wrong`红“✗ 错选”、漏选正确项 `missed`橙“● 正确答案”。实测单选、多选漏选(ACD选AC)、多选含错选(BCDE选AB) 三态全对。
- #3 朗读/语音**统一开关** #qpVoiceToggle（localStorage voice_enabled 持久化），朗读 #qpSpeakBtn、语音答题 #qpVoiceAnswer；实测开关 false→true、TTS speak 实际调用无报错。**音量键融合取消**：Web/PWA 无可靠音量键 API，按“消耗大则取消”，移动端保留大按钮。
- #4 报错新增 **AI解析失败** 类型（reportAiExplainFail 走统一报错弹窗 POST /api/v1/recognition_errors，含题目快照）；报错类型 9 类。实测弹窗预选、POST 200、成功提示；离线入 qp_error_queue 自动补传。
- #5 解析**考点定位**：“📍 第X章 章名 · 第Y节 节名 · 知识点标题”（_formatChapter，节名取章节树真实名）。**页码无数据源**：questions 表无 page 字段，不造假，需后续 OCR 入库补 page 字段。
- #6 桌面端切题过灵敏：_bindSwipeNav 删除 mousedown/mousemove/mouseup 切题，仅保留 touchstart/touchend（触屏左右滑动）；鼠标事件只用于画板。复制文字不再误切题。
- #7 专项训练精准化：SPECIAL_MAP 8 专项按章节锚点 secs + 主题词 strong + 排除词 ban 组卷，ban 排除→strong 命中 kp/title→或 inSecs+theme；无命中提示“暂无精准匹配，未用其他题目凑数”退回。实测“工程造价构成”命中 12 题全在第1章，无他章混入（原短词匹配混入 12 题）。
- #8 章节解析修复：_parseChapter 节级正则先命中“第11章第5节”判越界 null、走不到老章名映射；补 _legacyChapterByName（老版第7-14章按节名映射 1-6）。36 道老版章号题归位，未分类 46→10。
- #9 章节练习量与重刷：limit=Number(questionCount)||20（原固定20，设100仍20）；每次 _startPractice 清空 userAnswers/currentQuestion=0，重刷不回填历史。实测设100得100、无过时题、重刷干净。
- #10 **快速笔记**：答题区“转闪卡”旁加快捷笔记，#qpNoteSync POST /api/v1/note/create（book_id=刷题笔记、title 含章节知识点、question_id、subject、tags），本地 qnote_<qid> 暂存。实测落库 id 核对正确（已清理）。
- #11 **AI 薄弱点去硬编码+真实组卷**：原 _renderAiTab 写死 8 条虚构薄弱点（资金时间价值等）、_startPractice('ai') 无分支实为随机抽题。改为渲染 analytics/weak_points 真实数据（章节、正确率、错题数、可练题数、空状态），一键练习按 question_ids 仅练真实未掌握错题（可勾选章节）。实测“基于169道未掌握错题识别5章节可强化162题”，练习20题 allFromWeak=true。章节 tab 薄弱横幅取同一真源；init 与切 ai tab 自动加载。
- #12 **过时考点机制**：/api/qb/all 返回 is_outdated/outdated_reason；练习池 _startPractice、章节树 _loadChapterStats、真题年份统计三处统一过滤 is_outdated=1；题面新增过时警示条与“报错：过时考点”按钮（_reportError('过时考点')）。PPP 财政承受能力题 id=5535 已标 is_outdated=1，实测练习池/章节树/真题均不可刷。is_outdated=1 共 45 条（一造管理44）。
- #13 解析下**关联口诀**：删除硬编码 MNEMONICS，改从真实 flash_cards.mnemonic 按知识点匹配（_normMnKey/_matchMnemonic/_loadMnemonic）；题目知识点只到“节”、具体考点在题干，故匹配文本纳入 title，具体知识点卡按专业词拆词命中（章级卡只精确匹配防泛化，GENERIC 泛词过滤），阈值 score≥24，匹配不到隐藏不编造。实测静态投资/施工许可证/流水施工题均命中真实相关闪卡口诀。
- #14 **错题自动归集+错误次数**：答错 record_answer 自动 upsert wrong_questions，wrong_count 累计、首错=1（已修）；HTTP 实测 added_to_wrong=true、计数正确。

### 数据真相（以 DB 实测为准，不凑数）
- questions 未删 **1080**（一造管理1043/一造水利案例31/一造计价6）；一造管理排除 44 道过时后可练 **999**（归章989+未分类10），章节计数 1:86/2:169/3:204/4:203/5:152/6:175。用户印象“2000多”与库不符，以真实数据为准。
- flash_cards 未删 483；getFlashcards('一造管理') 返回 349（subject 过滤/分页）。
- questions 表无 page 字段（#5 页码待 OCR 补字段）。

### 待办 / 需后续（不做假实现）
- #11 后半“按薄弱点推荐视频听课”：视频当前按班次文件夹组织、无章节知识点标签，需先在视频模块补章节元数据才能精准推荐，暂不做假推荐。
- #5 页码：待 OCR/入库补 questions.page。
- #3 音量键：Web 无 API，已取消，移动端用大按钮。
- 复跑脚本（项目根）：patch_backend_qb.py / patch_backend_note.py / patch_note_model.py / patch_backend_weakids.py / patch_fe_qb_1~10.py；探查 http_test_qb.py、probe_qb_all.py、probe_special.py、inspect_chapter_parse.py、verify_mnemonic_data.py；清理 cleanup_qb_test.py、cleanup_wrong_test.py、cleanup_multi_test.py、cleanup_error_test.py（测试笔记/错题/报错均已还原：notes=11、wrong_questions user1未删=567、recognition_errors=15 含用户真实报错）。
