# 新旧代码与文档全量归一报告

- 系统：水利智学一体化题库系统（FastAPI + SQLite + 原生 HTML/JS + Ollama 本地 AI）
- 治理日期：2026-10-03
- 当前真实版本：**V4.5.18**（依据 `backend/data/version.json` 的 `app_version=4.5.18` 与 `/api/health` 实测 `v4.5.18`，双重佐证）
- 治理方式：Strangler Fig（绞杀者模式）薄壳化 + "移动不删除"归档 + 文档分层索引
- 治理原则：等价才转发、不确定即保留、全程可回滚、不物理删除任何文件

---

## 一、归一标准（权威基线）

本报告严格遵守根目录《标准基线清单.md》，要点如下：

1. **旧 API 改薄壳、转发新 modules 的 service**；前端 `API_BASE` 保持不变、对用户无感知；等价性验证通过后旧 API 才归档。
2. **模块间禁止跨域 import**（qb 不得 import mt/mm/ai 的 service，类推）；跨模块通信走 API 路由或事件总线。
3. **路由层只做参数校验与响应封装**，业务逻辑下沉 service。
4. **布局锁死值严禁改动**：侧栏 135px(!important)、顶栏 56px、模块导航条 48px、底栏 28px、主色 `#1a73e8`、功能色 success `#10b981` / warning `#f59e0b` / danger `#ef4444`；V2.0 旧值（`#3949ab`、粉色侧栏、48px 顶栏等）一律作废。
5. **刷题铁律**：单选选了即出解析、多选提交才出解析，不得破坏。

迁移映射（`backend/api/router_registry.py` 顶部注释）：
`/api/v1/question→/api/qb`；`flashcard→/api/mt`；`mindmap→/api/mm`；`ai→/api/ai`；`sync→/api/sync`；`material 与 video→/api/resource`。

---

## 二、改动前可回滚备份（先备份、后改动）

改动前已完成完整备份，落点：`backups\归一治理前备份_20261003_203034\`

| 备份内容 | 实测值 |
|---|---|
| 文件总数 | **819 个** |
| 备份总大小 | **251.4 MB** |
| 数据库一致快照 | `shuili_exam.db.pre_20261003` = **85,229,568 字节** |
| 代码快照 | `backend\`、`frontend\`、`docs\`、`root_files\` |

- 数据库使用 SQLite 在线备份 API（`auto_backup.online_backup`），正确处理活动 WAL，得到一致性快照；未删除任何 WAL/shm。
- 代码用 robocopy 仅快照源码，排除 `ollama_models / ai_models / ollama / data / uploads / backups / __pycache__` 等大资产目录。

---

## 三、等价性核对结论（后端 7 域，共 191 端点）

逐端点核对**入参、返回结构、字段名、副作用**四要素。汇总：

| 分片 | 业务域 | 审计端点 | 已薄壳 | 保留原样 | 待研判 |
|---|---|---:|---:|---:|---:|
| B1 | 题库 qb（question34+tags5+dedup6+datacheck6） | 55 | 0 | 55 | 38 条 |
| B2 | 闪卡 mt | 12 | **1** | 11 | 11 条 |
| B3 | 导图 mm | 16 | 0 | 16 | 16 条 |
| B4 | AI（brain14+scan2+assistant12+explain1） | 29 | 0 | 29 | 29 条 |
| B5 | 资源 resource（material19+video19） | 38 | 0 | 38 | 38 条 |
| B6 | 同步 sync（router11+offline_router11） | 22 | 0 | 22 | 11 组 |
| B7 | 图谱+RAG（图谱8+RAG11） | 19 | 0 | 19 | 3 组 |
| **合计** | — | **191** | **1** | **190** | — |

### 唯一确认等价并已薄壳的端点

- **`DELETE /api/v1/flashcard/{cid}`** → `modules.mt.service.MtService.delete_flashcard`
  - 等价证据：旧 `crud.delete_flashcard` 与新 service 均为「按 `id + user_id` 软删 `is_deleted=True` 并 commit」，幂等、DB 终态一致；薄壳复用请求级 `db` 会话，响应契约保持旧结构 `{"message":"删除成功"}`。
  - 已通过运行时导入冒烟：`from modules.mt.service import MtService` → `IMPORT_OK True`。

### 其余 190 端点为何不薄壳（关键判定）

新 `modules/*` 是**契约分叉的并行重建，而非忠实迁移**，存在系统性差异，按铁律禁止机械转发：

1. **响应信封不同**：旧端点为扁平裸 JSON；新路由统一包 `{code,msg,data}`。
2. **鉴权不同**：旧用 JWT `get_current_user` + 请求级 `db`；新用 `user_id` 查询参数（默认 1）并自建 `SessionLocal`。
3. **字段集 / 排序 / 算法不同**：如旧 question/list 按章节排序，新 qb 快路径按 `id DESC`；新 `_row_to_question` 多喂 17 列；mt `/review` 入参由 `quality` 整数 0–5 变为 `remember/hard/forget`；`/stats` 的 mastered 定义由 `mastery>=0.8` 变为 `review_count>=5`。
4. **大量端点为占位桩 / 假数据**：mt `/batch_import` 是 stub（不落库）；mm 的 `/split-from-pdf`、`/merge`、`/ai/*` 直接返回 `{"...":"接口已迁移"}`；resource 多个端点返回空列表/回显 body；sync `/push`、`/pull` 只往 `sync_records` 插一行、不写业务表；AI 同名端点多返回"待实现"。
5. **数据模型不一致**：resource routes 裸 SQL 误查 `materials/videos` 表，而生产模型表是 `course_materials/embedded_videos`（service 才用对模型）。
6. **刷题铁律端点**：`POST /api/v1/question/answer/{qid}`（服务端判分 + 异常用时判定 + SM-2）与新逻辑根本不同，严禁改动。

### 实时数据印证（来自真实接口）

| 对比项 | 旧 v1 | 新 modules |
|---|---:|---:|
| 题库 question / qb 列表 total | **1240** | **1768**（数据集口径不同） |
| 闪卡 flashcard / mt total | **958** | **958**（数量同，信封/字段不同） |
| 导图 mindmap / mm total | **217** | **217**（数量同，信封/字段不同） |

---

## 四、改动文件清单（活路径）

### 4.1 代码文件（3 个）

| 文件 | 改动内容 |
|---|---|
| `backend/api/router_registry.py` | 从 import 元组移除已归档的 `relation`、`wrong_analysis`，并加注释说明归档位置；不影响其余路由注册 |
| `backend/core/config.py` | 版本兜底常量 `SYSTEM_VERSION` / `SYSTEM_VERSION_NUM` 由 4.5.17 更新为 **4.5.18**（仅 version.json 缺失时生效的安全网） |
| `backend/api/v1/flashcard.py` | `DELETE /{cid}` 改为薄壳，转发 `MtService.delete_flashcard`，响应保持 `{"message":"删除成功"}` |

### 4.2 文档文件（内容订正）

| 文件 | 改动内容 |
|---|---|
| `backend/API_GUIDE.md` | 第 3 行版本声明、第 28 行 health 示例 → V4.5.18 |
| `docs/培训课件.md` | 第 3 行适用版本 → V4.5.18 |
| `docs/README.md` | 第 10/11/88 行版本口径 → V4.5.18（同时为新建的唯一文档索引） |
| `新会话SOP.md` | 删除错误结论「#3949ab 新旧并存」，改为「#3949ab 为 V2.0 旧主色已作废，现行以 #1a73e8 为准」 |

### 4.3 新建文件

- **`docs/README.md`**：全系统文档唯一入口索引（现行有效文档分层、归档说明、版本口径）。

---

## 五、归档文件清单（移动不删除，共 356 个文件）

统一归档根目录：`_archive\归一治理_20261003\`（另含 `docs\_archive\`、`frontend\_archive\` 两个分层落点）。所有文件移动前后均逐一核对字节数一致，保留原相对目录结构。

### 5.1 主归档 `_archive\归一治理_20261003\`（327 个文件）

| 子目录（目标路径） | 数量 | 内容 |
|---|---:|---|
| `backend\api\v1\` | 3 | 死代码 `relation.py`(5257B)、`wrong_analysis.py`(6401B)、零引用 `requirement.py`(1842B) |
| `root_md\` | 21 | 根目录带日期历史报告（144专家系列、系统治理/诊断、新旧对比 V4.5.15、迁移思路等） |
| `root_temp_json\` | 3 | `_呈现问题扫描.json`、`_带图题比对.json`、`_平铺文字题_原始title备份.json` |
| `_mobcheck\` | 218 | 移动端核查的一次性脚本、截图、日志与中间 json |
| `_temp_integration\` | 12 | 临时集成脚本（含 checkpoints、logs 子目录） |
| `_temp_scripts\` | 70 | 历史一次性修复/审计脚本 |

> 死代码判定依据：`relation`、`wrong_analysis` 在 `router_registry` 中为元组式 import 但 `include_router` 已注释，调用即 500；关联/错题能力已由 `modules/qb` 承接。归档前经可达性闭包 + grep 复核零活引用。

根目录归档的 21 个历史报告（文件名）：
144专家全量检查修复报告_20261002、144专家全面优化修复报告_20260928、144专家模块化分析与优化报告_20260927、144专家深度审查修复报告_20260929、今晚工作记录、启动文件世界顶级审查报告_20260930、启动文件修复与技术债处理报告_20260930、弹窗改造报告、数据库审计报告、新RAG引擎全面验证报告、新旧代码全面对比与处置清单_V4.5.15、新旧代码功能对比融合清单、知识库全量重组与关系网重构_交付报告、系统启动链路审计与文件整合报告_20260929、系统治理报告_20260928、系统治理报告_第二阶段_题库刷题与夜间机制_20260928、系统深度诊断报告_20260920、系统深度诊断报告_完整版、迁移思路、迁移方案与执行记录、迁移规则与节点清单。

### 5.2 文档归档 `docs\_archive\归一治理_20261003\`（20 个文件）

- 重复手册（去重保留现行版）：`部署手册.md`（保留 `docs/部署指南.md`）、`恢复手册.md`（保留 `docs/备份恢复指南.md`）。
- 历史问题/方案：`120问题_具体策略`、`49问题_分类分析`、`实测真问题`、`治理方案_V3_完整版`、`治理方案_执行清单`、`真根因_读代码修正`、`路由下线对账`、`问题清单_120条`。
- `ai_analysis\`（5 个）、`迁移冲突清单\`（5 个）。

### 5.3 前端影子件归档 `frontend\_archive\归一治理_20261003\`（9 个文件）

| 目标路径 | 文件（大小） |
|---|---|
| 根 | `index.html.bak_p1_20260930`(29197B) |
| `css\` | `mobile-shell.css.bak_mrel_20261001`(45576B)、`mobile-shell.css.bak_p1_20260930`(43990B) |
| `data\offline\` | `questions.json.bak_flat`(16,882,423B) |
| `js\` | `resource.js`(734,142B)、`theme.js.bak_theme_flash`(17294B) |
| `modules\experts\` | `expert-center.js.bak_p1_20260930`(47693B) |
| `modules\layout\` | `statusbar.js.bak_theme_flash`(7933B) |
| `modules\question\` | `question-practice.js.bak_mrel_20261001`(216986B) |

> 8 个 `.bak` 影子件 + 不被加载的巨型旧件 `resource.js`（功能已迁入 `app_v3_897262.js`）。移动前均 grep 确认零活引用。

---

## 六、前端归一结论

| 指标 | 实测结果 |
|---|---|
| 可达闭包文件数 | **89**（index.html 直接引用 81 + 动态加载 8） |
| 真实死引用 | **0**（仅 `migration-plan.js:196` 文档字符串中有 2 处 `/static/js/x.js` 示例文本，非运行时加载） |
| 活代码指向 .bak / 归档件 | **0** |
| JS 语法检查 | node v22.23.2，**75/75 全部 PASS** |
| `API_BASE` | 保持 **`/api/v1`**（`core/api.js` 第 7 行，index.html 第 220 行加载），用户无感知 |
| 巨型文件 | `app_v3_897262.js`(1.5MB) 被 index.html 第 253 行加载→原位保留；`resource.js`(734KB) 不被加载→已归档 |
| 布局基线 | tokens.css 主色 `#1a73e8`、侧栏 135px、顶栏 56px 等锁死值均正确 |

---

## 七、各步验证命令与结果（均为真实输出）

1. **Python 解释器**：`D:\Python311\python.exe`（3.11.9）。
2. **py_compile（cwd=backend）**：
   - `python -m py_compile core\config.py` → `CONFIG_COMPILE_EXIT=0`
   - `python -m py_compile api\v1\flashcard.py` → exit 0
   - 全量 `compileall api core modules utils main.py` → 全部 exit 0。
3. **main.py 进程内导入**：成功（`import main` 无异常）。
4. **FastAPI TestClient 全链路（进程内、不绑端口，跑改动后代码）**：
   - `GET /openapi.json` → 200，**PATH_COUNT = 863**。
   - 前缀桶（路径数）：`/api/v1` 385、`/api/common` 89、`/api/qb` 74、`/api/resource` 71、`/api/ai` 61、`/api/mt` 42、`/api/mm` 27、`/api/sync` 14、`/api/knowledge-graph` 7、`/api/rag` 7 等。
   - 检查项：qb/mt/mm/ai/resource/sync 均在；**relation_gone=true、wrong_gone=true**。
   - `GET /api/health` → 200，`"version":"v4.5.18"`。
   - 六大关键接口（question/list、qb/questions、flashcard/list、mt/flashcards、mindmap/list、mm/mindmaps）→ **全部 200**，返回结构符合各自契约。
   - 说明：OpenAPI 生成时存在若干 "Duplicate Operation ID" 告警，为**既有、无害**告警，非本次改动引入。

---

## 八、144 名专家全量体检：修复前后对比

体检脚本：`backend/core/experts/run_all_report.py`（在项目根目录运行，脚本自行 chdir）。注册专家 **146 位**。

| 时点 | info | warning | critical | 结论 |
|---|---:|---:|---:|---|
| **修复前** | 144 | 2 | 0 | `HAS_FINDINGS`（仅 2 个设计性冒烟 warning） |
| **修复后（稳态）** | **144** | **2** | **0** | `HAS_FINDINGS`（与修复前一致，**无回归**） |

- 两个常驻 warning 为 `endpoint_smoke_expert`、`api_smoke_expert`：**设计如此**（启动期不真调接口、避免副作用），非缺陷。
- 体检过程中曾因**内存竞争**出现瞬时异常：一次运行报 `feature_wiring_expert` critical（"专家执行异常"）与两个冒烟专家 "Out of memory interning an attribute name"。经单独运行验证：`feature_wiring_expert` 实为 **info/PASS**（7 个关键词全找到），两个冒烟专家实为**预期 warning**。根因是当时另一并行会话的批量重灌（约 444MB）与 pytest 占用内存、空闲物理内存仅约 3GB，体检进程与运行中后端各加载一份 RAG（25945 文档 + 19393×512 矩阵）导致内存翻倍。待该任务结束、内存恢复（约 6.2GB 空闲）后重跑，已回到 **144 info + 2 warning** 稳态，0 critical。
- 元专家 `trend_expert` 曾因相邻运行 warning 计数波动短暂转 warning，稳态重跑后已转回 info。

---

## 九、回滚方法

本次全程"移动不删除"，回滚安全、完整：

1. **代码回滚**：将归档文件按原相对路径移回原位即可——
   - `_archive\归一治理_20261003\backend\api\v1\relation.py / wrong_analysis.py / requirement.py` 移回 `backend\api\v1\`；
   - 前端 9 件、docs 20 件、根目录 md 21 件同理移回；临时目录 `_temp_integration / _temp_scripts / _mobcheck` 整体移回根目录。
   - 或直接用备份目录 `backups\归一治理前备份_20261003_203034\` 中的 `backend\ / frontend\ / docs\ / root_files\` 覆盖还原。
2. **数据库回滚**：关闭后端后，用 `backups\归一治理前备份_20261003_203034\shuili_exam.db.pre_20261003`（85,229,568 字节）替换 `backend\data\shuili_exam.db`（连同 WAL/shm 一并处理）。本次治理未做任何业务数据写入，正常情况下无需回滚数据库。
3. 可参考根目录 `auto_backup.py`、`备份.bat`、`rollback_to_stable.bat`。

---

## 十、仍待研判项（需用户拍板）

1. **190 个旧端点的后续路线**（根因：新 modules 契约分叉）。两条路线二选一：
   - (A) 让新 modules **对齐旧契约**（扁平 JSON、JWT 鉴权、字段/排序/算法一致、补齐桩端点）后再逐端点薄壳；
   - (B) **前端迁移到新契约**（{code,msg,data}）后正式启用新模块、下线旧 v1。
   各分片已在 manifest 中逐端点列明差异，可直接作为改造工单。
2. **前端活文件 5 处 V2.0 旧值**是否清理：`index.html:37` 闪屏渐变 #3949ab；`app_v3:1561/1565` 登录 tab #3949ab；`mindmap.ct2.js:665` 节点色 #3949ab；`components.css:1` 渐变 #3949ab；`style.min.css:587` `.topbar{height:48px}`（与 tokens.css `--header-h:56px` 冲突；运行时由 topbar.js inline 56px 生效）。本轮保守未改。
3. **"v6.0 交付版"与 app 版本 V4.5.18 两套命名**是否统一措辞（交付文档集自称 v6.0，与系统版本号并行）。
4. **自动生成文件** `docs/API文档.md`、`落地对账总表.md` 标注"勿手改"，建议重跑对应生成脚本（如 `tools/gen_api_doc.py`）以刷新口径。
5. **既有缺陷**：`backend/api/v1/_rag_routes.py:117` 的 `GET /rag/models` 调用 `list_local_models`，该函数定义于 `_rag_models.py`、未经 `__all__` 导出，运行期疑似 NameError（本轮仅记录、未修）。
6. **生产端口加载新代码**：端口 8000 当前仍由今晨提权（UAC）启动的旧后端进程服务，非提权会话无法结束它；改动后代码已通过进程内 TestClient 全链路验证。要让新代码在 8000 端口实际生效，请**提权运行 `start.bat`（或 重启后端.bat）** 正常重启即可，无需强杀进程。

---

## 附：分片结构化清单（证据落点）

目录：`归一治理_manifests_20261003\`
`B1_qb.json`、`B2_mt.json`、`B3_mm.json`、`B4_ai.json`、`B5_resource.json`、`B6_sync.json`、`B7_kg_rag.json`、`F1_frontend.json`、`D1_docs.json`、`_reachability_v1.json`，及验证脚本与输出（`_testclient_verify.py/_out.txt`、`_single_expert.py`、`_trend_history.py` 等）。

> 本报告所有数字均来自实际命令与接口输出，未做估算。
