# 144 专家视角 · 水利智学系统全量深度检测与修复报告

- 系统：水利智学一体化题库系统（FastAPI + 原生 HTML/JS PWA + SQLite + Ollama 本地 AI）
- 检测/修复日期：**2026-10-03**
- 系统真实版本：**V4.5.18**（`backend/data/version.json` 的 `app_version=4.5.18`，实测双重佐证）
- 代码根：`F:\水利智学系统\可运行版（解压即用，双击start.bat）`
- 检测组织方式：以"144 个专项检查视角"覆盖 **静态质量 / 导入完整性 / 运行时全 API / 前后端契约 / 数据库完整性 / 核心写流程 / AI 链路 / 文件资产 / 前端脚本** 九大类，逐项实测、不留盲区
- 判定方式：**只采信可复现证据**（编译/测试退出码、真实 HTTP 状态码、副本库前后行数、真实语音转写结果），不以"代码看起来对"为准

---

## 一、总体结论

| 维度 | 结果 | 证据 |
|---|---|---|
| 全后端字节码编译 | ✅ 0 错误 | `compileall` exit=0 |
| 未定义名称 F821 | ✅ **0 处**（早前 67 处已全部清零） | `pyflakes` 全量 |
| 文件头 BOM | ✅ 0 个（早前 8 个已全部去除） | 字节扫描 |
| 跨模块名称/导入一致性 | ✅ 998 条目 / 0 模块加载失败 / **0 坏名** | 自研 import 名称审计 |
| 自动化单测 | ✅ **38 passed**（0.63s） | pytest |
| 题目↔媒资关联测试 | ✅ **14 passed / 0 failed** | test_media_rel.py |
| 前端自有脚本语法 | ✅ **119 个 JS 全部通过**（0 失败） | `node --check`（排除 libs/vendor/min） |
| 全量只读 GET 运行时冒烟 | ✅ **358 个端点：0×500、0×异常** | 进程内 ASGI 实测 |
| 前后端接口契约 | ✅ 245 路径全核对，**2 个真死链已修复归位** | 自研契约审计+真实请求甄别 |
| 核心写流程（判题/错题/闪卡） | ✅ 副本库端到端 ALL_PASS，主库零污染 | smoke_write |
| 视频 AI 智能笔记链路 | ✅ 真实转写+AI 出笔记，三分支全过 | smoke_fix3 |
| 生产主库洁净度 | ✅ 无任何测试标签/测试记录泄漏 | 最终只读核查 |

**最终判定：本轮发现的全部真实缺陷已根治并通过回归；系统在静态、运行时、契约、数据、写流程、AI 链路六层均达到"全绿"。** 另发现 1 项历史数据残留（2 个已软删的上传测试损坏视频），因涉及不可逆删除，保留原物并在第六节给出处置建议。

---

## 二、检测与验证方法（保证结论可信）

1. **不占用线上端口**：所有运行时验证均用 `httpx.ASGITransport` 在进程内直接打 ASGI 应用；本会话 8000 端口无监听，全程**未重启服务、未触碰用户其它进程**。
2. **关闭限流干扰**：进程内对 `RateLimitMiddleware.dispatch` 打桩透传、`RATE_LIMIT_PATHS=()`，避免压测触发 429 掩盖真实问题（与生产限流逻辑无关，仅测试旁路）。
3. **免登录**：`LOCAL_MODE=true`（在导入业务模块前设置），以默认用户身份走完整鉴权依赖。
4. **写操作零污染铁律**：凡涉及写库的实测，先用 SQLite 在线备份把**生产库只读复制到临时副本**，将 `DATABASE_URL` 指向副本后再测；测完 `engine.dispose()` 并删除副本，**前后只读比对生产库表行数**证明零污染。生产库全程以 `mode=ro` 打开。
5. **异常不中断**：冒烟脚本单点失败不退出，结尾落盘 JSON，确保 358 个端点每个都有独立结论。

---

## 三、本轮发现并根治的缺陷（按严重度）

### 🔴 严重 1：数据自检 `/all` 冻结整个服务事件循环（性能/可用性重大缺陷）

- **现象**：数据检查的 tables / consistency / files / all 等端点是 `async def`，却在协程内执行**同步 SQLite**（引擎 `busy_timeout=30000`），且每个检查都 `INSERT data_check_records` 并 commit。一旦与题库治理写者发生锁冲突，`/all` 串联等待约 **90 秒**，期间**冻结整个 ASGI 事件循环**——所有用户的所有请求一起卡死。
- **根治**：
  - 六个端点（tables/consistency/files/all/db_status/history）**全部由 `async def` 改为普通 `def`**，由 FastAPI 自动放入线程池，同步 DB 操作不再阻塞事件循环；去除误用的 `await`，各会话补 `try/finally db.close()`。
  - 新增模块级 `_record_check(...)`：用**独立短连接**（`busy_timeout=2000`）写检查历史；库文件不存在则不连接（防止自动建空库）；遇锁忙只告警并**跳过历史写入，绝不影响只读校验结果本身**。
- **验证**：10 个检查端点定向实测全 200；`/all` 从"卡死约 90s"变为 **0.0–0.7s 返回**。

### 🔴 严重 2：连带挖出 `BASE_DIR` 少上溯一级的路径错位（潜伏的数据误报根源）

- **根因**：`data_check.py` 位于 `backend/api/v1/`，原代码 `BASE_DIR = dirname×2(__file__)` 只到 `backend/api`（正确应为 `dirname×3` 到 `backend`），导致 `UPLOAD_DIR / DATA_DIR` 全部错位。
- **危害**：
  - 上传文件完整性校验长期**误报"上传目录不存在"**；
  - 运行时在错误路径自动建出 `backend/api/data/shuili_exam.db`（**0 字节空库**）、`data/rag_knowledge`、`uploads/lectures` 等垃圾目录。
- **根治**：改为三级 `dirname`；加"库文件存在才连接"守卫；删除确认全为 0 字节/空目录的垃圾。
- **回归**：files 端点随后读到**真实上传目录**——`11798 个文件 / 810,288,552 字节(772.75MB) / 44 个 PDF / 2 个视频 / 0 issue`。
- **排查彻底性**：自研 AST/正则两版 BASE_DIR 审计后再人工核验 `diagnosis.py / preprocess_config.py / _rag_engine.py / effect_evaluator.py / rag_engine/config.py`，确认**仅 data_check 一个孤例**，其余三级路径均正确。

### 🔴 严重 3：RAG 模型列表端点 NameError 必挂

- **现象**：`/api/v1/rag/models` 在完整冒烟中是唯一的进程内异常（EXC）。根因是 `list_local_models` 定义在 `_rag_models.py`，而 `_rag_routes.py` 只 `from ._rag_engine import *`；星号导入使该名称不可见，**且这一漏网被 pyflakes F821 漏掉**（星号导入的名字静态检查无法判定）。
- **根治**：`_rag_routes.py` 显式 `from ._rag_models import list_local_models`；该端点内含同步 `urllib` HTTP（timeout=4），一并由 async 改为同步 `def` 入线程池。
- **验证**：复跑后该端点 200，返回**真实本地模型清单**。

### 🔴 严重 4：文件库"批量打标签"假成功（数据完整性 + 前后端死链）

- **现象**：活跃前端 `file-library.js` 向 `/api/v1/fl/files/batch-tag` 发 POST——**多写了 `/files` 段**（该路由前缀为 `/api/v1/fl`），后端从无此端点，必然 404；而前端**不检查返回码**，404 时仍弹"成功"。用户看到成功，标签却根本没写入。
- **根治（后端补齐 + 前端纠错双管齐下）**：
  - 后端新增 `POST /api/v1/fl/batch-tag`：Pydantic 入参，`tags` 同时兼容字符串与数组；与原标签取**并集、去重并保序（原标签在前）**；返回 `updated/skipped`；空标签或空选择返回 400。
  - 前端 URL 改为 `/api/v1/fl/batch-tag`，并按 `res.ok && data.success` 判定，失败时把后端原因显示出来。
- **验证（副本库）**：HTTP 200，`updated=2`；fl id=1/185 的标签由 `一造管理,其他,知识点` 正确变为 `一造管理,其他,知识点,__T1__,__T2__`（**旧标签完整保留 + 新标签并集**）。生产库最终核查 `__T1__/__T2__` 泄漏数 = **0**。

### 🔴 严重 5：视频"智能笔记"点击完全无反应（功能从未实现 + 路径错误）

- **现象**：`video.js` 调 `POST /api/v1/videos/{id}/smart-note`（**复数**、且不带视频类型），后端路由前缀是单数 `/api/v1/video`，**该功能后端从未实现** → 404 → `data.note` 为 undefined → 前端静默，用户点按钮毫无反应。
- **根治（把薄弱功能真正做出来，而非仅修链接）**：
  - 后端新增 `POST /api/v1/video/{video_type}/{video_id}/smart-note`（同步 `def` 入线程池，不阻塞）：
    - `_resolve_video_file`：本地视频查 `LocalVideo` 并校验文件存在；在线嵌入视频查 `EmbeddedVideo`（无本地文件）；
    - 复用 `utils/video_mnemonic_extractor.py` 的 `ffmpeg → Whisper(faster-whisper-tiny)` 转写；ffmpeg 硬编码路径失效时回退 `shutil.which('ffmpeg')`；
    - `_ai_study_note`：调本地 Ollama `qwen2.5:3b` 把讲稿整理成结构化 Markdown 笔记（要点/关键概念公式/易错点）；AI 不可用时**退回原始转写稿**保证按钮仍有产出；
    - 在线嵌入视频（B 站等）返回 `{supported:false, 明确提示}`；视频不存在 404；**文件损坏返回明确 400**（见下条）；转写为空返回友好提示。
  - 前端按当前视频 `platform/url` 自动区分 local/embedded，改单数正确路径，并处理"不支持 / 失败原因 / 空转写"三种情况，**彻底消除静默**。
- **端到端实测（三分支全过，ALL_PASS）**：
  - 损坏截断视频 → **HTTP 400**："视频文件无法读取或已损坏（可能上传不完整或格式不支持），请重新上传后再试"；
  - 在线嵌入视频 → **HTTP 200，supported=false**，明确告知无本地音轨；
  - 自造带中文语音视频（Windows SAPI 合成 + ffmpeg）→ **HTTP 200，耗时 22.7s，真实识别 62 字**，qwen2.5:3b 产出结构完整的笔记（含"工程造价/综合单价法"等正确要点）；
  - 主库 `local_videos` 测试前后均为 0，**零污染**。

### 🟠 中 6：损坏视频抛出笼统 500 堆栈（健壮性）

- 修复前任何不可解复用的视频都会抛裸异常→500 并打印长堆栈。已在智能笔记链路中把"输入文件无法读取/截断"单独捕获并转为**语义明确的 400**，仅真正的识别内部错误才是 500。

---

## 四、全量运行时冒烟证据（358 个只读 GET）

进程内透传限流、单请求 30s 超时、异常不中断、结尾落盘 `smoke2_result.json`：

| HTTP 结果 | 数量 | 说明 |
|---|---|---|
| 200 | **347** | 正常 |
| 204 | 1 | 正常（无内容） |
| 500 | **0** | 无服务端错误 |
| 进程内异常 EXC | **0** | 无崩溃 |
| 400 | 2 | 设计性缺参拒绝（tts 文本为空、folder_files 缺 dir） |
| 404 | 1 | `/api/common/lan-ca` 根证书尚未生成（功能未启用的预期拒绝） |
| 422 | 7 | 设计性参数校验（textbook 缺 subject/node_code ×4、tts 缺 text、ai/analysis 缺 file_path、question_tags 缺 tag） |

> 全部非 200 项均经逐一甄别，确认为"缺参/未启用"的**设计性拒绝**，非缺陷。修复 RAG NameError 前曾有 1 个 EXC，修复后复跑归零。

---

## 五、核心写流程副本库实测（ALL_PASS）

用真实在用题目（一造管理，正确答案 C）在**隔离副本**端到端验证：

| 用例 | HTTP | 结果 | 副本表行数变化 |
|---|---|---|---|
| 答对 | 200 | `is_correct=true` | question_answer_logs 1756→1758 |
| 答错 | 200 | `is_correct=false`，自动入错题本 | wrong_questions 799→800 |
| 建闪卡 | 200 | 成功 | flash_cards 1088→1089 |

**生产主库前后三项行数完全不变**，副本测后即删。最终只读复核：生产库无 `__T1__/__T2__` 测试标签、无 999001/999002 测试视频记录。

---

## 六、数据层发现与处置建议（未擅自删除用户数据）

- `backend/uploads/videos/` 下两个 mp4 均为**上传中断的截断文件**（ffprobe/ffmpeg 报 `moov atom not found / Invalid data`，无法播放）：
  - `cc726144…mp4` = 2,000,000 字节、`e5b3e134…mp4` = 1,500,000 字节；
  - 对应 `embedded_videos` 记录 **id=437「S3进度条验证」、id=436「S3流式上传测试」**，`platform=local`，且 **`is_deleted=1`（已软删、前端列表不显示）**。
- **处置**：因物理删除不可逆，本轮**保留原文件**，仅将智能笔记对其的报错优化为明确 400。建议在您确认后：删除这两个损坏物理文件（共约 3.34 MB），并按需清理 id=436/437 两条已软删记录。这是本报告唯一的待您拍板事项。

---

## 七、生产库 / 文件系统最终洁净度复核（只读）

- 版本 `app_version = 4.5.18`；主库 `data/shuili_exam.db` 正常。
- 表行数（只读实测）：fl_file_library=1602、local_videos=0、embedded_videos=437、flash_cards=1088。
- 测试标签泄漏=0；测试视频记录残留=0。
- 路径错位垃圾 `backend/api/data`、`backend/api/uploads` 均**不存在（未复活）**。
- RAG 向量：19,393 块 × 512 维，覆盖率 **100%**，健康。

---

## 八、本轮改动文件清单

**后端**
- `backend/api/v1/data_check.py`：六端点 async→同步、独立短连接写历史、BASE_DIR 三级修正、库存在守卫。
- `backend/api/v1/_rag_routes.py`：补 `list_local_models` 显式导入、`/models` async→同步。
- `backend/modules/common/file_library_routes.py`：新增 `BatchTagIn` 与 `POST /batch-tag`（并集/去重/保序）。
- `backend/api/v1/video.py`：导入补 `LocalVideo`；新增 `_resolve_video_file`、`_ai_study_note`、`POST /{video_type}/{video_id}/smart-note`；损坏文件明确 400。

**前端**
- `frontend/modules/library/file-library.js`：batch-tag 正确 URL + 按 success 判定 + 失败显因。
- `frontend/modules/video/video.js`：智能笔记区分本地/在线、正确单数路径、处理不支持/失败/空转写。

**清理**：删除路径错位产生的 0 字节空库与空目录（`backend/api/data`、`backend/api/uploads`，删除前已确认均为空）。

> 更早阶段已完成并在本轮回归确认的修复：`models/models.py`（补 KnowledgePointProgress、消除 DailyStudyPlan 漂移列）、`modules/common/routes.py`（两个 subject 端点重写）、`analytics.py / mindmap.py / deduplication.py / pdf_toolkit.py / ai_brain_hub.py / pdf_watermark_service.py / backup_manager.py` 及测试夹具等；并曾清退 12.9GB 历史测试备份垃圾。

---

## 九、上线生效说明（重要）

- 本轮所有验证均在**进程内**完成，为不干扰共享环境，**未擅自重启服务**（8000 端口本会话也无监听）。
- **要让上述全部修复在实际使用中生效，请重启一次后端**：双击根目录 `start.bat`（或重启 uvicorn）。重启后前端刷新即可，PWA 会经 Service Worker 更新到最新脚本。

---

## 十、复现与证据索引

证据脚本与原始输出均位于本次审计工作目录 `…\.sessions\38445241926591490\agents\m_0cwpacU7Za2\audit\`：

| 文件 | 内容 |
|---|---|
| `smoke2_result.json` / `smoke2_full.txt` | 358 GET 最终 347×200 / 0×500 / 0×EXC |
| `import_name_out4.txt` | import 名称审计 0 失败 0 坏名 |
| `smoke_write_out.txt` | 判题/错题/闪卡副本库 ALL_PASS |
| `contract_out.txt` / `contract_probe_out.txt` | 245 路径契约核对、44 候选真实请求甄别 |
| `smoke_fix2_out.txt` | batch-tag 并集落库、在线不支持、404、损坏文件 |
| `smoke_fix3_out.txt` | 智能笔记三分支 ALL_PASS + 真实转写笔记正文 |
| `pt_unit2.txt` / `media2.txt` | 38 passed、14/14 |

**环境**：解释器 Python 3.11（`D:\Python311\python.exe`）、Node v22.23.2、ffmpeg/ffprobe（`D:\软件安装\万能播放器\`）、faster-whisper-tiny、Ollama 11434（qwen2.5:3b 文本、bge-m3/bge-small-zh 向量等在线）。

---

*本报告所有数字均来自当场可复现的命令输出或副本库实测；凡涉及生产数据的写验证，均以"主库前后行数一致 + 测试标记零残留"双重证明零污染。*
