水利智学系统 · “教材每一个字 → 全资源串联”核查全景图

核查对象:可运行版 V4.5.15|数据库 backend/data/shuili_exam.db(236MB,132表)|核查方式:启动链 + 数据模型 + 实测数据 + 运行态接口
总体结论:统一骨架已经建成,教材“文字层”100% 入库,主链路基本贯通;但错题本是最大断点,且“后端已聚合、前端未展示”造成多处“最后一公里”未打通。

① 以 textbook_nodes(章-节-目 189 节点)为唯一骨架,题/卡/知识点/导图/讲义/原文均挂载 node_code;② 教材可提取文字逐页 100% 入库(管理 389,361 字、案例 217,391 字,零差异);③ 节点聚合 API 一次返回 11 类资产、全局搜索覆盖 13 类、RAG 向量 5,927 个;④ 主要缺口:67.7% 错题失联、前端节点页不显示错题/收藏/知识库、错题无回溯入口、688 张教材图片未 OCR。

L0 底座教材原文层(“每一个字”)

当前在用教材:管理 material_id=48(370页)、案例 material_id=50(262页)
一造管理教材
389,361 字
✓ 逐页入库 100%(零差异)
一造水利案例教材
217,391 字
✓ 逐页入库 100%(零差异)
教材图片/图表
688 张
✗ 仅计数,图内文字未 OCR
▲ 文字层写入 page_contents(632页)+ textbook_contents(177块,约134万字,含章/节/目混合粒度)

L1 骨架统一结构树 textbook_nodes

章(1)-节(2)-目(3),模型注释明确为“知识点/题/闪卡/口诀/原文/知识库统一挂载的唯一骨架”
一造管理
111 节点
6章 · 28节 · 77目
一造水利案例
78 节点
5章 · 73节
合计
189 节点
✓ 含权威标记 is_authoritative
▲ 各资源通过 node_code / node_path 挂载到节点

L2 资源学习资源层(node_code 挂载填充率)

题库 questions
1,366
✓ 挂载 99.6%(1,360)
闪卡 flash_cards
958
▲ 挂载 82.0%(786)
└ 口诀 mnemonic
624
✓ 623 张已挂节点
知识点 knowledge_points
235
▲ 挂载 77.9%(183)
思维导图 mind_maps
141
✓ 挂载 98.6%
讲义 lectures
98
✓ 挂载 100%

L3 功能功能数据层(按学员,回流节点)

错题本 wrong_questions
643
✗ 仅 208 可追溯,435 失联(67.7%)
收藏 question_collects
正常
✓ JOIN 题目可取 node_code
题卡关系表
534
✓ question_flashcard_rel

通道三条串联通道(已打通)

① 节点聚合 API:/api/v1/textbook/content

点开任一节点(含子孙)一次返回 11 类:原文块+逐页、知识点、题、闪卡(含口诀)、导图、讲义、知识库、AI知识点、错题、收藏。已实测 4.2.1 返回原文1块/9页/2题。

② 全局搜索:/api/search/global

关键词 LIKE 毫秒级 + 语义召回,覆盖 13 类(题/教材原文/闪卡/知识点/导图/讲义/笔记/资料 + 错题/收藏/视频/文件);教材原文命中带 node_code+page_no,点击定位节点并高亮物理页。

③ RAG 语义向量库:rag_embeddings

共 5,927 个向量:教材页原文 page 1,956、导图 1,320、题 1,366、闪卡 958、知识点 229、讲义 98;每条 doc_id 编码来源,回查即“成网”。

缺口清单(按严重度)

P1
错题本 435 条“失联”(占有效错题 67.7%)

这些错题的 question_id 在 questions 表中不存在(多为拍照识题/临时题/已硬删题),导致无法 JOIN 出 node_code,错题无法落回教材节点,也无法在节点聚合中出现。错题表本身不存 node_code,串联完全依赖 JOIN。

P1
“后端已聚合、前端未展示”:节点页缺标签

/textbook/content 已返回错题、收藏、知识库、AI知识点,但前端 material 模块节点资产只渲染 6 个标签(原文/知识点/题/闪卡/导图/讲义),错题/收藏/知识库/AI点对用户不可见——数据通了,界面没通。

P2
错题本前端无“回溯入口”,列表无 node_code

错题卡片只有 查看解析/加入复习/移除错题,没有“查看教材原文/相关闪卡/口诀/知识点”按钮;后端错题列表 _Q_KEYS 不含 node_code,前端拿不到节点。错题→闪卡 /wrong/{id}/to-flashcard 后端接口已存在,但前端无按钮调用。

P2
教材 688 张图片/图表内文字是“每一个字”的盲区

page_contents 仅记录 image_count(管理390/案例298),图片未单独 OCR;公式图、流程图、扫描表格中的文字无法被检索,也未挂载到节点。has_table 标记未启用。

P2
部分资源未挂载 + 原文块粒度混乱

闪卡 18%、知识点 22%、ai_knowledge_points 100%(31条)未挂 node_code;textbook_contents 章/节/目三级粒度混杂(章级块达 11 万字、与子块内容重复),另有 2 个空块、7 个目节点无独立原文块(内容在父块中)。

P3
存在无法运行的死代码

api/v1/relation.py、wrong_analysis.py 引用模型已删除字段(Question.user_id、wrong.subject、wq.mastered 等),调用即报错;实际功能已由 modules/qb 承接,建议清理以免误用。

数据为 2026-09-27 实测;后端运行态健康检查通过(Ollama 7 模型、数据库 132 表)。