# 水利智学系统 — 144专家技术债全面治理报告

**治理日期**：2026-09-27
**备份位置**：`backups/pre_techdebt_20260927_201024/`（完整可回滚）
**体检结果**：critical=0, error=0, warning=5, info=139（治理前 critical=15）

---

## 一、治理总览

| # | 技术债领域 | 治理前 | 治理后 | 专业技术 |
|---|-----------|--------|--------|---------|
| 1 | API设计（新旧并存） | /api/v1注册39个 + 新模块38个，散落main.py | 集中注册router_registry.py，161端点标记deprecated | Strangler Fig + 路由注册集中化 + 废弃响应头 |
| 2 | 数据库性能 | 250MB，134表，含大量废弃表 | 68.2MB（-72.7%），105表 | 废弃表DROP + REINDEX + VACUUM + ANALYZE |
| 3 | 弹窗标准化 | 346处原生alert/confirm/prompt | 0处原生弹窗 | 异步confirmAction + showToast + showModal输入框 |
| 4 | 主色硬编码 | 326处#1a73e8/117文件 | 19处（仅变量定义/SVG/Canvas/color input） | CSS变量var(--primary)零色差替换 |
| 5 | 布局硬编码 | 66文件含硬编码布局值 | 72文件过渡期残留（非标准尺寸无token） | --spacing-*/--header-h CSS令牌映射 |
| 6 | 大JS性能 | app_v3 1598KB + resource 698KB | app_v3 1464KB（迁出136函数/191KB到7模块） | 代理壳范式 + IIFE模块 + window命名空间 |
| 7 | 巨型后端文件 | 7个文件14,500+行 | 拆为30+子模块，原文件变代理壳 | AST提取 + Mixin组合 + re-export兼容层 |

---

## 二、逐项治理详情

### 1. API设计治理（api_designer）

**问题**：旧`/api/v1/*`路由39个与新模块路由（/api/qb、/api/mt、/api/ai等）38个并存于main.py，约60行include_router散落。

**治理措施**：
- 新建 `backend/api/router_registry.py`，导出`register_all_routers(app)`，将59处include_router按原顺序原prefix集中
- main.py从1068行精简到930行，路由注册改为一行调用
- 新建 `backend/api/v1/_deprecated.py`，对10个旧router的161个端点添加`X-API-Deprecated: true`和`X-API-Sunset`响应头
- 生成 `backend/API_ROUTES.md`，824条路由按前缀分组，附旧→新迁移映射表
- 检测到11处预先存在的路径冲突（AI模块桩路径重复），注册顺序不变，行为不变

**验证**：import main通过；6个端点实测200（含deprecated头正确）；前端226个API调用无404风险。

---

### 2. 数据库性能治理（db_perf_expert）

**问题**：250MB数据库中约108MB是废弃PDF/闪卡管线遗留数据和FTS索引膨胀。

**治理措施**：
- 分析134表，识别29张废弃表（deprecated_*前缀9张普通表+3张FTS虚表连带15张影子表+3张*_backup表），确认backend源码零引用
- DROP 29张表，回收约182MB
- 执行REINDEX（消除索引碎片）+ VACUUM（重建数据库回收空闲页）+ ANALYZE + WAL TRUNCATE checkpoint
- 核心业务数据零改动：questions(3161行)、rag_embeddings(9482行)、flash_cards(1089行)等全部保留

**结果**：250.1MB → 68.2MB（-72.7%）；表数134→105；`PRAGMA integrity_check`=ok；核心表行数与清理前一致。

**残留**：`backend/data/`下约27个历史备份文件（合计~6GB），本次未触碰，确认无需回滚后可另行删除。

---

### 3. 弹窗标准化治理（dialog_standard_expert）

**问题**：346处原生alert/confirm/prompt，其中confirm为同步阻塞，删除/交卷等关键操作依赖其返回值。

**治理措施**（逐处阅读语义，禁止正则机械替换）：
- **alert(83处)** → `showToast(msg, type)`，按语义分info/success/error/warning
- **confirm(84处)** → `confirmAction(msg, onConfirm)`异步回调，后续代码全部包进onConfirm
  - 9处特殊定制：交卷（取消分支重启防作弊+计时）、双按钮导出（含批注/不含批注）、恢复DB（取消清空input）、大文件上传（>500MB才确认）、复合守卫拆分、嵌套批量删除等
- **prompt(27处)** → `showModal` + 唯一ID输入框/textarea，确定按钮回调获取值
- 新增全局`confirmAction`辅助函数（app_v3.js、offline.html、resource.js代理壳、3个自包含page）
- file-library.js/note.js使用项目已有的`CommonUtils.showConfirm/showPrompt/confirmAsync`
- check_js.js自包含，新增`confirmDlg/promptDlg`辅助函数

**验证**：所有修改文件node --check通过；原生弹窗残留=0（lib/wangEditor第三方库除外）；PWA的`beforeinstallprompt.prompt()`非原生弹窗，正确保留。

---

### 4. 主色硬编码治理（layout_constitution_guard）

**问题**：#1a73e8硬编码326处/117文件，而`:root{--primary:#1a73e8}`已定义。

**治理措施**：
- CSS/JS中所有CSS语境的`#1a73e8` → `var(--primary)`，零色差（因--primary值就是#1a73e8）
- 共替换319处（app_v3:2、modules:310、resource+pages:7）
- **必须保留hex的19处**：CSS变量定义本身（4处）、SVG fill/stroke表现属性（var()在SVG attribute不生效）、Canvas gradient.addColorStop、`<input type="color">`值、主题色板数据数组、JS运行时fallback

**验证**：47个JS文件node --check通过；CSS括号平衡；替换前后视觉零差异。

---

### 5. 布局硬编码治理（layout_no_hardcode）

**问题**：66文件含硬编码padding/margin值（135/56/28等）。

**治理措施**：
- 可映射到已有CSS令牌的值替换：4px→--spacing-xs、8px→--spacing-sm、16px→--spacing-md、24px→--spacing-lg、32px→--spacing-xl、48px→--spacing-2xl、56px(header)→--header-h
- 共替换4553处（app_v3:45、modules:2694、resource+pages:1814）
- 仅替换padding/margin/gap/top/right语境；严格排除font-size、border-radius、语义不明的width/height、box-shadow、clamp()/calc()内的值
- 为6个自包含页面（offline.html等）注入`:root`令牌定义（值与tokens.css完全一致）

**残留（72文件过渡期）**：非标准尺寸（6px/10px/12px/14px/18px/20px等）无对应CSS令牌，按规则保留原值。如需彻底消除需先扩展设计令牌体系。

---

### 6. 大JS性能治理（performance_specialist）

**问题**：app_v3_897262.js 1598KB（3.5万行）、resource.js 698KB，单文件加载阻塞。

**治理措施**：
- 用acorn AST解析app_v3.js，识别976个顶层函数（529个真实实现+447个已转发commonModule的soft_proxy）
- 迁出7个内聚功能组共136个函数/191KB到`frontend/js/modules/`：
  - `analytics_mgr.js`(21函数/39KB) — 学习分析&图表
  - `offline_cache_mgr.js`(28函数/33KB) — 离线缓存&同步
  - `viz_mgr.js`(11函数/33KB) — 知识图谱&ECharts
  - `admin_mgr.js`(24函数/30KB) — 备份/监控/去重/学习计划
  - `question_import_mgr.js`(22函数/27KB) — 题库导入&AI匹配
  - `formula_trainer_mgr.js`(15函数/17KB) — 公式训练器
  - `pdf_viewer_mgr.js`(15函数/12KB) — PDF查看器
- 原位置留P0-06代理壳（转发到window.<命名空间>.<函数名>），全局可访问性不变
- index.html在app_v3之前插入7个script标签，确保模块先加载
- app_v3从1647KB降至1464KB（-9%），迁出真实代码占raw实现的29.4%

**主动跳过（安全第一）**：核心渲染函数（renderDashboard/renderExam/renderQuestion等，与Store/examTimerInterval/questionFilters重度耦合且被index.html内联事件直接调用）、登录/科目选择群。建议后续在浏览器验证7个新模块页面无报错后再继续拆分。

**验证**：app_v3 + 7个新模块全部node --check通过；136/136代理壳脚本核对正确；7个模块HTTP 200可访问。

---

### 7. 巨型后端文件治理（refactor_specialist）

**问题**：7个Python文件共14,500+行，单文件职责过多。

**治理措施**（零行为变更，代理壳/re-export保持所有import路径不变）：
- `api/v1/question.py`(1711→壳8行) → 6子模块：q_query/q_crud/q_import_export/q_analysis/_q_helpers/_q_router
- `api/v1/rag_knowledge.py`(1457→壳8行) → 6子模块：_rag_engine(持有共享状态)/_rag_models/_rag_routes/_rag_ingest/_rag_chat/_rag_warmup
- `core/experts/catalog.py`(2639→壳14行) → 9子模块：_cat_helpers/_cat_chk_arch/_cat_chk_layout/_cat_chk_business/_cat_reg_a/b/c/_cat_more
- `utils/pdf_base_processor.py`(2242→壳55行) → 5个Mixin：_pb_basic/_pb_merge/_pb_image/_pb_recognize/_pb_pipeline（MRO组合，32方法保留）
- `utils/pdf_parser.py`(2175→壳4行) → 4子模块
- `utils/pdf_splitter.py`(2687→壳16行) → base+dataclass+5 Mixin组合为PDFKnowledgeSplitter
- `utils/smart_toc_extractor.py`(1842→壳72行) → TOCNode+5 Mixin组合为SmartTOCExtractor

**验证**：7模块联合import通过；`import main`成功（144专家挂载、question 32路由、rag 10路由）；所有外部消费者（含下划线名）导入通过；每个新文件≤687行；main.py无需调整。

**回归修复**：分裂后发现_cat_reg_b.py和_cat_reg_c.py缺少`import os`和`import sqlite3`（原catalog.py顶部有，分裂时子模块未继承），导致15个专家执行异常。已在模块顶部补全导入，重跑体检critical清零。

---

## 三、统一回归验证结果

| 验收项 | 结果 |
|--------|------|
| 后端干净启动（无import错误、stderr无致命异常） | ✅ stderr为空，uvicorn正常启动 |
| /api/common/health返回200 | ✅ |
| 题库CRUD API | ✅ /api/v1/question/list 200 + /api/qb/questions 200 |
| 专家API | ✅ /api/common/experts 200 + /api/common/experts/summary 200 |
| 夜间扫描API | ✅ /api/common/night-scan/list 200 + /stats 200 |
| 反馈API | ✅ /api/common/experts/feedback 200 |
| 前端主页加载 | ✅ 标题正常，侧边栏/搜索/科目选择渲染正常 |
| 无新增404 | ✅ 188个网络请求全部2xx，64JS+5CSS资源HEAD检查全部200 |
| 无新增控制台error | ✅ 92条控制台消息，0条error |
| 重跑体检critical/error | ✅ critical=0（治理前15），error=0 |
| 不引入新critical/error | ✅ 5个warning均为已知过渡期残留或检测逻辑对代理壳的误判 |

---

## 四、残留warning说明（5项，均非阻塞）

| 专家 | 内容 | 原因 |
|------|------|------|
| api_designer | 旧API39个+新模块38个并存，已标记deprecated 4个 | Strangler Fig过渡期，旧路由全部保留兼容，已加废弃响应头 |
| layout_constitution_guard | 19处#1a73e8 | 必须保留hex：CSS变量定义(4)、SVG属性(6)、Canvas(2)、color input(1)、色板数据(4)、JS fallback(2) |
| layout_no_hardcode | 72文件含硬编码布局值 | 非标准尺寸(6/10/12/14px等)无对应CSS令牌，需先扩展设计令牌 |
| performance_specialist | 2个JS>500KB（app_v3 1464KB、resource 698KB） | 已迁出136函数/191KB，核心渲染函数风险高暂留，有明确后续拆分路径 |
| render_completeness_expert | 11个render函数无DOM输出 | 实为app_v3拆分创建的代理壳（转发到模块实现），专家检测逻辑不识别代理壳范式 |

---

## 五、回滚方案

完整备份位于 `backups/pre_techdebt_20260927_201024/`：
- `backend/` — 后端代码完整副本
- `frontend/` — 前端代码完整副本
- `shuili_exam.db` — 数据库完整副本

如需回滚，停止后端服务后将对应目录/文件复制回原位即可。
