# 新旧代码与文档全量归一报告（最终版）

- **报告日期**：2026-10-04
- **版本双佐证**：`/api/health` → status=ok, version=**v4.5.18**, database=113表, ollama=8模型；git 主线一致。
- **总结论**：0 critical / 0 error；独立验证通过，可交付。

> 替代关系：本报告为**最终版**；20261003 的旧报告仅作历史留档，不再代表当前状态。

---

## 1. 总览与结论

- 后端从"旧 v1 扁平 handler 直写"归一为"薄壳 API + modules/<域> service 业务层"。
- 前端不动、`API_BASE=/api/v1` 不变、用户无感；8000 全程可用。
- 最终专家体检（`run_all_report.py`）：**info=142 / warning=4 / critical=0 / error=0**。
  - 4 条 warning 全部为**真实应保留项**：refactor_specialist（巨型文件真实存在）、runtime_health_expert（内存 1384MB 真实观测）、endpoint_smoke / api_smoke（启动期不真打，设计性 baseline warning）。
  - material/video 两条旧误黄已修正判据后回到 info；鸿蒙文档缺字已补，doc_consistency 回到 info。

## 2. 191 端点对账总表

### 2.1 已薄壳（180 端点，转发 modules 业务层）

| 域 | 端点数 | 新 service target |
|---|---|---|
| mt 闪卡 | 12 | `modules.mt.service` |
| resource 资源 | 38 | `modules.resource.service` |
| sync 同步 | 22 | `modules.sync.service`（含 offline_sync 双路由） |
| mm 导图 | 16 | `modules.mm.service` |
| ai 智能 | 28 | `modules.ai.service.AiService.v1_*` |
| qb 题库 | 55 | `modules.qb.v1_service.QbV1Service` |
| kg_rag | 9 | knowledge_graph 8 端点 → `modules.knowledge_graph_engine.v1_exam_analysis_service`；RAG 仅切 `GET /rag/documents` → `modules.rag_engine.v1_legacy_doc_service` |
| **合计** | **180** | |

### 2.2 保留旧件（11 端点）

| 端点名 | 具体原因 | 解锁/迁移前置路线 |
|---|---|---|
| RAG 保留旧件 ×10（`rag_knowledge.py` 除 documents 外） | 与 retrieval\ / block_nodes.json / rag_knowledge\ 紧耦合，受红线保护不可动；documents 已单独切新 service | 待 RAG 解耦、Qdrant 数据迁移完成后再逐端点迁移 |
| ai `/ai/explain_question` | ai_unified 内联的稳定 7B/3B 讲解通道，含内存 OOM 护栏与模型卸载编排，与 core.ai_controller 强耦合 | 待 ai 域 service 承接 7B 讲解链路后再切 |

## 3. 各域完成度

- mt：12/12 薄壳，桩全部真实补齐（batch_import/from_question/sync/template_excel/preview_excel）。
- resource：material/video 薄壳上线，真机 material=7、video=64 与基线一致。
- sync：/sync 与 offline_sync 双路由薄壳，4 读端点真机 200。
- mm：mindmap 薄壳，list/template 真机 200。
- kg_rag：9 切 / 10 保留（10 个保留即上节 RAG 10 端点）。
- qb：55 端点薄壳，list total=2630、detail=200，4 子壳复用共享 `_q_router.router`。
- ai：28 端点薄壳；曾被简化的 v1_solve/v1_study_plan/v1_ollama_setup/test 已逐行移植旧 handler、恢复完整链路，harness 3/3 PASS。

## 4. 等价证据索引

- harness（隔离副本 + TestClient，monkeypatch 外部依赖）：
  - resource 40/40、sync 24/24、mm 19/19、ai 29/29、kg_rag 13/13、qb 61/61 PASS。
  - ai 3 端点补验：`backend/_harness_ai3.py` 3/3 PASS（solve 本地题库匹配分支 / study_plan 四维聚合 / ollama_test 编排）。
- 证据根目录：`归一迁移_20261004\evidence\<domain>\`。
- 真机命中：各域 `evidence\<domain>\live_log.txt` 含 `[<domain>.v1] hit ...`；`live_http.json` 为真机 HTTP 记录。
- 最终体检：`归一迁移_20261004\evidence\final_experts.txt`。

## 5. 真机 HTTP 与独立验证摘要

- 关键计数（可复算）：flashcard 958、question 2630、mindmap 217、video 64、material 7。
- qb 真机：`/question/list`、`/question_tags/list`、`/deduplication/scan`、`/data_check/all` 全 200。
- ai 真机：`/ai/status`、`/assistant/config`、`/ai/history`、`/assistant/providers`、`/assistant/study_plan`（source=ai_4d, days_to_exam=20）、`/assistant/ollama/test`（success=True）全 200。

## 6. 备份 / 回滚位置

- 全量治理前备份：`backups\GOLDEN_*` 与 `backups\归一治理前备份_20261003_203034\`。
- 各域旧件（.old.py，移动未删）：`_archive\归一迁移_<domain>_20261004\`（mt/resource/sync/mm/ai/kg_rag/qb）。
- 新 service 已上 git，回退 = `git checkout <前一commit> -- <文件>`。

## 7. git 分域提交清单（以 git log 为准）

| 域 | commit |
|---|---|
| mt | `79f69f5` |
| resource | `18de3fd` |
| sync | `58096a4` |
| mm | `d841cf3` |
| kg_rag | `53bb390` |
| ai/qb 首次回退 | `73622e2` |
| qb 重切 | `4c7d634` |
| ai 重切 | `92e8712` |
| ai 补齐 3 端点 | `55e9c73` |

## 8. 遗留与后续

- Qdrant 数据迁移、RAG 解耦路线（对应 10 个 RAG 保留端点）。
- 大文件真实存在：modules/ai/service.py(1993)、mm(2038)、qb/v1_service(2505)、resource/service.py 等 >1500 行，后续按职责拆分（refactor_specialist 真实告警，非误报）。
- runtime 内存 ~1.4GB 为真实观测（7B/嵌入常驻 + 体检进程叠加），非缺陷。
- 本次专家判据修正说明：material_mgmt/video_mgmt 两专家的评估对象由"旧扁平 api/v1/material.py|video.py 行数"改为"业务层 modules/resource/service.py 行数达标 + 薄壳 <200 行仅转发"，检查意图保留、未放水；鸿蒙真机验收记录补写侧栏 135px 口径。
- ai v1 方法曾因回退被 service.old.py 覆盖丢失（未提交 git），已按 `_archive\*.old.py` 逐行重建，核心路径经 harness+真机双验证。
