init: RAG 知识库服务初始提交

- 后端 API（Flask + Gunicorn）
- RAG 引擎（混合检索 + 云端 Reranker + 引用溯源）
- 文档解析（MinerU + 多格式支持）
- Docker 生产部署配置
- 排除前端项目、敏感配置、模型文件

docs/开发与系统模块说明.md

@@ -0,0 +1,925 @@
+# 开发与系统模块说明
+
+> 本文档由原《开发文档》与《模块说明》合并而成，涵盖开发环境配置、技术栈、架构以及细粒度模块说明。
+
+## 第一部分：开发文档体系
+
+# RAG 知识库问答系统 - 开发文档
+
+> **项目版本**: v7.0.0
+> **更新日期**: 2026-04-18
+> **文档用途**: 架构说明、技术栈、部署指南
+
+> **API 接口文档**: 详见 [后端对接规范.md](./后端对接规范.md)
+
+---
+
+## 一、项目概述
+
+### 1.1 项目定位
+
+本项目是智能出题系统的**核心知识服务层**，为上层 Dify 工作流提供知识检索能力。系统通过 RAG（检索增强生成）技术，实现基于企业制度文档的智能问答，支持：
+
+- **知识库问答**：基于向量检索 + BM25 + Rerank 的混合检索
+- **Agentic RAG**：智能问答流程（Query Rewriting、Context Compression、Answer Grounding）
+- **多轮对话**：会话历史管理、代词消解
+- **图谱推理**：基于 Neo4j 的多跳关系查询（可选）
+- **网络搜索**：实时信息获取（可选，需配置 Serper API）
+
+### 1.2 系统架构
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          前端应用层                                  │
+│                    (chat-ui/ 开发测试界面)                           │
+└───────────────────────────────┬─────────────────────────────────────┘
+                                │ HTTP API / SSE
+                                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       API 服务层 (api/)                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
+│  │   /chat     │  │    /rag     │  │ /sessions   │  │  /search   │ │
+│  │ 智能聊天    │  │ SSE 流式问答│  │ 会话管理    │  │ 混合检索   │ │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────┬──────┘ │
+└─────────┼────────────────┼────────────────┼───────────────┼────────┘
+          │                │                │               │
+          ▼                ▼                ▼               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       核心能力层 (core/)                             │
+│  ┌─────────────────────────────────────────────────────────────┐   │
+│  │                     Agentic RAG (agentic.py)                 │   │
+│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌──────────┐ │   │
+│  │  │  Query    │  │  检索层   │  │  Context  │  │  Answer  │ │   │
+│  │  │ Rewriting │  │向量+BM25  │  │Compression│  │ Grounding│ │   │
+│  │  │ 统一入口  │  │ +Rerank   │  │ Token控制 │  │ 幻觉闭环 │ │   │
+│  │  └───────────┘  └───────────┘  └───────────┘  └──────────┘ │   │
+│  └─────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       数据存储层                                     │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
+│  │  ChromaDB   │  │   .data/    │  │  SQLite     │  │ documents/ │ │
+│  │  向量数据库  │  │  图片存储   │  │  会话数据   │  │  文档源    │ │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 1.3 技术栈
+
+| 层级 | 技术 | 说明 |
+|------|------|------|
+| API 服务 | Flask + Flask-CORS | RESTful API，SSE 流式返回 |
+| 文档解析 | MinerU 3.0+ | PDF/DOCX/PPTX/图片统一解析 |
+| 向量检索 | ChromaDB + BGE-base-zh | 本地向量数据库 + 嵌入模型 |
+| 关键词检索 | BM25 + jieba | 中文分词 + 倒排索引 |
+| 重排序 | BGE-reranker-base | CrossEncoder 精排 |
+| 大模型 | Qwen (通义千问) | 问答生成、实体提取 |
+| 数据库 | SQLite | 会话管理、审计日志 |
+
+---
+
+## 二、项目结构
+
+```
+├── main.py                  # 统一启动入口
+├── config.py                # API 配置（需自行创建）
+├── requirements.txt         # 依赖列表
+│
+├── api/                     # API 路由层（Flask Blueprint）
+│   ├── __init__.py          #   create_app() 应用工厂
+│   ├── chat_routes.py       #   /chat, /rag (SSE), /search
+│   ├── session_routes.py    #   /sessions, /history
+│   ├── auth_routes.py       #   /health, /auth/me
+│   ├── kb_routes.py         #   /collections
+│   ├── document_routes.py   #   /documents/upload
+│   ├── sync_routes.py       #   /sync
+│   ├── image_routes.py      #   /images/<id>
+│   └── feedback_routes.py   #   /feedback
+│
+├── core/                    # RAG 核心引擎
+│   ├── agentic.py           #   AgenticRAG 智能问答
+│   ├── engine.py            #   检索引擎封装
+│   ├── bm25_index.py        #   BM25 索引
+│   ├── chunker.py           #   文本分块
+│   ├── query_classifier.py  #   查询分类器
+│   ├── confidence_gate.py   #   置信度门控
+│   ├── quality_assessor.py  #   质量评估器
+│   ├── loop_guard.py        #   循环防护
+│   └── reasoning_reflector.py # 推理反思器
+│
+├── parsers/                 # 文档解析器
+│   ├── mineru_parser.py     #   MinerU 统一解析 (PDF/DOCX/PPTX/图片)
+│   ├── excel_parser.py      #   Excel 专属管道
+│   └── image_extractor.py   #   图片噪音过滤
+│
+├── knowledge/               # 知识库管理
+│   ├── manager.py           #   多向量库管理器
+│   ├── router.py            #   知识库路由器
+│   └── sync.py              #   同步服务
+│
+├── services/                # 业务服务
+│   ├── session.py           #   会话管理 (SQLite)
+│   ├── audit.py             #   审计日志
+│   └── feedback.py          #   反馈系统
+│
+├── auth/                    # 认证与安全
+│   ├── gateway.py           #   网关认证 (DEV_MODE mock token)
+│   └── security.py          #   安全防护
+│
+├── data/                    # SQLite 数据库
+│   ├── db.py                #   统一数据访问层
+│   ├── rag_core.db          #   会话/审计数据
+│   └── knowledge.db         #   知识管理数据
+│
+├── .data/                   # 运行时数据
+│   ├── files/images/        #   提取的图片
+│   └── mineru_output/       #   MinerU 解析输出
+│
+├── chat-ui/                 # 前端测试界面
+│   ├── index.html           #   主页面
+│   ├── app.js               #   主逻辑
+│   └── api-test.js          #   API 测试面板
+│
+├── docs/                    # 文档
+│   ├── 后端对接规范.md       #   API 接口规范 (主要)
+│   ├── 开发文档.md           #   本文档
+│   └── ...
+│
+├── scripts/                 # 工具脚本
+│   └── analyze_chunks.py    #   切片分析
+│
+├── tools/                   # 开发工具
+│   └── export_chunks.py     #   导出切片
+│
+└── exam_pkg/                # 出题系统（可选）
+    ├── manager.py           #   出题与批卷
+    └── api.py               #   Flask Blueprint
+```
+
+---
+
+## 三、Agentic RAG 流程
+
+### 3.1 完整流程图
+
+```
+用户问题 (query)
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  1. Query Rewriting（统一入口）                              │
+│     - 有历史对话 → 强制改写（消歧）                           │
+│     - 短查询 (<10字符) → 强制改写（扩展）                     │
+│     - 其他 → LLM 判断是否需要改写                            │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  2. 查询分类 (QueryClassifier)                              │
+│     - FACT: 事实查询 → 直接检索                              │
+│     - COMPARISON: 比较查询 → 分解检索                        │
+│     - META: 元问题 → 直接回答                                │
+│     - REALTIME: 实时信息 → 网络搜索（可选）                   │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  3. 检索流程                                                 │
+│     - 向量检索 + BM25 + Rerank                               │
+│     - 置信度门控检查 (threshold=0.3)                         │
+│     - 多维质量评估 (相关性/完整性/准确性/覆盖率)              │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  4. Context Compression                                      │
+│     - Rerank 过滤 (score < 0.3 丢弃)                         │
+│     - 去重 (相同来源+页码只保留一个)                          │
+│     - Token 控制 (max=3500 tokens, max=20 条)               │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  5. 答案生成                                                 │
+│     - 多源融合 (知识库 + 网络 + 图谱)                        │
+│     - 来源标注                                               │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  6. Answer Grounding（幻觉闭环）                             │
+│     - 幻觉检测 (推理反思器)                                  │
+│     - 发现幻觉 → 补充检索 → 重新生成                         │
+│     - 最多重试 1 次                                          │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  7. 输出                                                     │
+│     - answer: 回答内容                                       │
+│     - sources: 来源列表（已去重，含页码范围）                 │
+│     - images/tables: 富媒体信息                              │
+│     - session_id: 会话ID（用于多轮对话）                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 关键配置参数
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| `MAX_CONTEXT_TOKENS` | 3500 | 上下文最大 token 数 |
+| `MAX_CONTEXT_COUNT` | 20 | 上下文最大条数 |
+| `RERANK_THRESHOLD` | 0.3 | Rerank 过滤阈值 |
+| `MAX_GROUNDING_RETRY` | 1 | 幻觉修正最多重试次数 |
+| `max_iterations` | 3 | 最大迭代检索次数 |
+
+---
+
+## 四、API 接口
+
+> **详细 API 文档**: 详见 [后端对接规范.md](./后端对接规范.md)
+
+### 核心接口概览
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/chat` | POST | 智能聊天 |
+| `/rag` | POST | 知识库问答（SSE 流式） |
+| `/search` | POST | 混合检索（供 Dify 调用） |
+| `/sessions` | GET | 会话列表 |
+| `/history/<id>` | GET | 会话历史 |
+| `/collections` | GET | 向量库列表 |
+| `/images/<id>` | GET | 获取图片 |
+| `/sync` | POST | 触发同步 |
+| `/health` | GET | 健康检查 |
+
+---
+
+## 五、开发环境配置
+
+### 5.1 环境准备
+
+```powershell
+# 创建虚拟环境
+python -m venv venv
+.\venv\Scripts\Activate.ps1
+
+# 安装依赖
+pip install -r requirements.txt
+```
+
+### 5.2 配置文件
+
+复制 `config.example.py` 为 `config.py`：
+
+```python
+# config.py - 必需配置
+
+# 通义千问 API（必需）
+DASHSCOPE_API_KEY = "your-api-key"
+DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+DASHSCOPE_MODEL = "qwen-flash"           # 文本模型
+DASHSCOPE_VL_MODEL = "qwen-vl-plus"      # 视觉模型（图片描述）
+
+# 兼容变量
+API_KEY = DASHSCOPE_API_KEY
+BASE_URL = DASHSCOPE_BASE_URL
+MODEL = DASHSCOPE_MODEL
+
+# 文档路径
+DOCUMENTS_PATH = "./documents"
+
+# 开发模式（支持 mock 用户）
+DEV_MODE = True
+```
+
+### 5.3 开发模式特性
+
+| 特性 | 说明 |
+|------|------|
+| Mock 用户 | 支持 `mock-token-admin` 等模拟 token |
+| 本地登录 | `/auth/login` 接口支持用户名密码登录 |
+| 会话存储 | SQLite 本地存储，无需外部数据库 |
+| 前端界面 | `http://localhost:5001` 直接访问测试 |
+
+**模拟用户列表**：
+
+| 用户名 | 密码 | 角色 |
+|--------|------|------|
+| admin | admin123 | admin |
+| manager | manager123 | manager |
+| user | test123 | user |
+
+---
+
+## 六、运行命令
+
+### 6.1 启动服务
+
+```powershell
+# 激活虚拟环境
+.\venv\Scripts\Activate.ps1
+
+# 启动服务
+python main.py                  # 端口 5001
+python main.py --port 8080      # 指定端口
+```
+
+### 6.2 同步知识库
+
+```powershell
+# 通过 API 触发同步
+curl -X POST http://localhost:5001/sync
+
+# 或通过前端界面操作
+```
+
+---
+
+## 七、会话管理
+
+### 7.1 多轮对话流程
+
+```
+首次对话:
+POST /rag { "message": "出差补助标准", "collections": ["public_kb"] }
+    ↓
+finish 事件返回 session_id
+    ↓
+前端保存 session_id
+
+后续对话:
+POST /rag { "message": "它有什么限制", "session_id": "xxx", "collections": ["public_kb"] }
+    ↓
+RAG 服务自动从 SQLite 加载历史
+    ↓
+Query Rewriting: "它" → "出差补助"
+    ↓
+生成带上下文的回答
+```
+
+### 7.2 会话相关 API
+
+| 接口 | 说明 |
+|------|------|
+| `GET /sessions` | 获取用户会话列表 |
+| `GET /history/<session_id>` | 获取会话历史 |
+| `DELETE /session/<session_id>` | 删除会话 |
+
+---
+
+## 八、部署指南
+
+### 8.1 生产环境建议
+
+| 项目 | 建议 |
+|------|------|
+| DEV_MODE | 设置为 `false` |
+| WSGI 服务器 | gunicorn 或 uWSGI |
+| 反向代理 | Nginx |
+| HTTPS | 配置 SSL 证书 |
+
+### 8.2 职责边界
+
+| 后端负责 | RAG 服务负责 |
+|----------|--------------|
+| 用户认证 | 知识库问答 |
+| 权限判断 | 向量检索 |
+| 会话管理（生产） | 返回溯源 |
+| 消息存储 | 文档处理 |
+
+---
+
+## 九、错误码说明
+
+| 状态码 | 说明 | 处理建议 |
+|--------|------|----------|
+| 200 | 成功 | - |
+| 400 | 请求参数错误 | 检查请求体格式 |
+| 401 | 未认证 | 检查 Header 认证信息 |
+| 403 | 权限不足 | 检查用户角色权限 |
+| 404 | 资源不存在 | 检查 session_id 或资源路径 |
+| 500 | 服务器内部错误 | 查看服务日志 |
+
+---
+
+## 十、相关文档
+
+- [后端对接规范.md](./后端对接规范.md) - API 接口规范（主要）
+- [数据库设计文档.md](./数据库设计文档.md) - 数据库结构
+- [模块说明.md](./模块说明.md) - 模块详细说明
+- [Agentic_RAG完整指南.md](./Agentic_RAG完整指南.md) - Agentic RAG 详解
+
+
+---
+
+## 第二部分：模块规范体系
+
+# 项目模块说明文档 (v6.1.0)
+
+> **注**：本项目经过大规模重构，采用模块化架构。当前版本已包含细粒度多向量库权限控制、文档生命周期跟踪、本地化自动出题系统及FAQ问答闭环反馈收集。
+
+## 项目架构概览
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              API 服务层                                      │
+│                            main.py (入口)                                   │
+│    (Flask 应用工厂，整合所有 Blueprint，提供 REST API)                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+         │         │         │         │         │         │         │
+         ▼         ▼         ▼         ▼         ▼         ▼         ▼
+┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐
+│ RAG 核心 ││  图谱模块 ││ 出题系统 ││ 安全模块 ││ 同步服务 ││ 反馈闭环 ││ 纲要生成 │
+│core/     ││graph/    ││exam_pkg/ ││auth/     ││knowledge/││services/ ││services/ │
+│agentic.py││graph_    ││manager.py││gateway.py││sync.py   ││feedback.py││outline.py│
+│engine.py ││manager.py││api.py    ││security.py││          ││          ││          │
+│bm25_     ││entity_   ││local_db.py││          ││          ││          ││          │
+│index.py  ││extractor ││analysis.py││          ││          ││          ││          │
+│chunker.py││graph_rag ││question_ ││          ││          ││          ││          │
+│          ││graph_    ││hook.py   ││          ││          ││          ││          │
+│          ││build.py  ││          ││          ││          ││          ││          │
+└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘
+     │                                                    │
+     ▼                                                    │
+┌──────────────────────────┐                              │
+│   多向量库管理            │                              │
+│ knowledge/manager.py     │                              │
+│ knowledge/router.py      │                              │
+└──────────────────────────┘                              │
+                              ┌─────────────────────┼─────────────────────┐
+                              │                     │                     │
+                              ▼                     ▼                     ▼
+                       ┌──────────┐          ┌──────────┐          ┌──────────┐
+                       │会话管理  │          │题库分析  │          │ 审计日志 │
+                       │services/ │          │exam_pkg/ │          │services/ │
+                       │session.py│          │analysis.py│         │audit.py  │
+                       └──────────┘          └──────────┘          └──────────┘
+```
+
+---
+
+## 目录结构
+
+```
+项目根目录/
+├── main.py                  # ✨ 统一启动入口（推荐）
+├── config.py                # API 配置（不提交）
+├── config.example.py        # API 配置模板
+├── requirements.txt         # 依赖列表
+│
+├── api/                     # API 路由层（Flask Blueprint）
+│   ├── __init__.py          #   create_app() 应用工厂
+│   ├── chat_routes.py       #   /chat, /rag, /rag/stream, /search
+│   ├── session_routes.py    #   /sessions, /history, /session, /clear
+│   ├── auth_routes.py       #   /stats, /health, /auth/me
+│   ├── audit_routes.py      #   /audit/logs
+│   ├── kb_routes.py         #   /collections, /documents/sync, /kb/route
+│   ├── document_routes.py   #   /documents/upload, /documents/list, 版本管理
+│   ├── sync_routes.py       #   /sync, /subscribe, /notifications
+│   ├── graph_routes.py      #   /graph/search, /graph/build, /graph/stats
+│   ├── question_routes.py   #   /questions/*, /knowledge-points
+│   ├── outline_routes.py    #   /outline/*, /recommend/*
+│   ├── feedback_routes.py   #   /feedback/*, /reports/*, /faq/*
+│   └── image_routes.py      #   图片相关接口
+│
+├── core/                    # RAG 核心引擎
+│   ├── __init__.py
+│   ├── agentic.py           #   AgenticRAG 智能问答
+│   ├── engine.py            #   检索引擎封装
+│   ├── bm25_index.py        #   BM25 关键词索引
+│   ├── chunker.py           #   语义分块器
+│   ├── query_classifier.py  #   查询分类器
+│   ├── confidence_gate.py   #   置信度门控
+│   ├── quality_assessor.py  #   质量评估器
+│   ├── reasoning_reflector.py # 推理反思器
+│   └── loop_guard.py        #   循环防护
+│
+├── parsers/                 # 文档解析器
+│   ├── __init__.py
+│   ├── mineru_parser.py      #   MinerU 统一解析（PDF/DOCX/PPTX/图片）
+│   ├── pdf_mineru.py         #   MinerU PDF 兼容别名
+│   ├── excel_parser.py       #   Excel 解析（Pandas 管道）
+│   ├── txt_parser.py         #   TXT 解析
+│   └── image_extractor.py   #   图片提取器
+│
+├── knowledge/               # 知识库管理模块
+│   ├── __init__.py
+│   ├── manager.py           #   多向量库管理器
+│   ├── router.py            #   知识库路由器
+│   ├── sync.py              #   同步服务
+│   ├── lifecycle.py         #   文档生命周期
+│   ├── diff.py              #   文档差异分析
+│   └── vector_store/        #   向量数据库与BM25索引
+│       ├── chroma/          #   ChromaDB存储
+│       └── bm25/            #   BM25索引存储
+│
+├── exam_pkg/                # 考试系统
+│   ├── __init__.py
+│   ├── manager.py           #   出题与批卷
+│   ├── api.py               #   Flask Blueprint (exam_bp)
+│   ├── analysis.py          #   考试分析
+│   ├── local_db.py          #   本地题库
+│   └── question_hook.py     #   题目维护钩子
+│
+├── services/                # 业务服务
+│   ├── __init__.py
+│   ├── session.py           #   会话管理
+│   ├── audit.py             #   审计日志
+│   ├── feedback.py          #   反馈质量闭环
+│   ├── outline.py           #   纲要生成与推荐
+│   └── user_info.py         #   用户信息服务
+│
+├── auth/                    # 认证与安全
+│   ├── __init__.py
+│   ├── gateway.py           #   网关认证
+│   └── security.py          #   输入/输出安全
+│
+├── data/                    # SQLite 数据库
+│   ├── __init__.py
+│   ├── db.py                #   统一数据访问层
+│   ├── rag_core.db          #   核心数据（会话、审计、反馈）
+│   ├── knowledge.db         #   知识管理（同步、大纲、版本）
+│   └── exam.db              #   出题系统（题目、试卷、批卷）
+│
+├── graph/                   # 知识图谱
+│   ├── __init__.py
+│   ├── graph_manager.py     #   Neo4j 图谱管理
+│   ├── entity_extractor.py  #   实体提取器
+│   ├── graph_rag.py         #   图谱增强检索
+│   └── graph_build.py       #   图谱构建工具
+│
+├── documents/               # 知识库文档目录
+├── models/                  # 本地模型目录
+├── scripts/                 # 工具脚本
+│   ├── migrate_version_status.py  # 版本状态迁移
+│   ├── rebuild_multi_kb.py        # 重建多向量库
+│   ├── run_exam.py                # 运行考试
+│   └── test_rag_questions.py      # RAG问题测试
+├── tests/                   # 测试
+├── chat-ui/                 # 前端界面
+├── venv/                    # 虚拟环境
+│
+```
+
+> **注意**: 根目录下的 `.py` 文件大多已迁移至子包，保留仅为向后兼容。
+> 新代码请使用子包路径导入，如 `from auth.gateway import require_gateway_auth`。
+
+---
+
+## 模块详细说明
+
+### 一、API 路由层 (api/)
+
+#### 1. `api/__init__.py` - 应用工厂
+
+**职责**：创建并配置 Flask 应用，注册所有 Blueprint
+
+**主要功能**：
+- 初始化共享服务（SessionManager、AuditLogger、AgenticRAG）
+- 注册所有 API Blueprint
+- 可选模块按需加载
+
+**使用方式**：
+```python
+from api import create_app
+
+app = create_app()
+app.run(host='0.0.0.0', port=5001)
+```
+
+#### 2. API Blueprint 分组
+
+| Blueprint | 文件 | 端点前缀 | 主要功能 |
+|-----------|------|----------|----------|
+| `auth_bp` | auth_routes.py | - | /stats, /health, /auth/me |
+| `session_bp` | session_routes.py | - | /sessions, /history, /session, /clear |
+| `audit_bp` | audit_routes.py | - | /audit/logs |
+| `chat_bp` | chat_routes.py | - | /chat, /rag, /rag/stream, /search |
+| `kb_bp` | kb_routes.py | - | /collections, /documents/sync, /kb/route |
+| `document_bp` | document_routes.py | - | /documents/upload, /documents/list |
+| `sync_bp` | sync_routes.py | - | /sync, /subscribe, /notifications |
+| `graph_bp` | graph_routes.py | - | /graph/search, /graph/build, /graph/stats |
+| `question_bp` | question_routes.py | - | /questions/*, /knowledge-points |
+| `outline_bp` | outline_routes.py | - | /outline/*, /recommend/* |
+| `feedback_bp` | feedback_routes.py | - | /feedback/*, /reports/*, /faq/* |
+| `image_bp` | image_routes.py | - | 图片上传、处理相关接口 |
+| `exam_bp` | exam_pkg/api.py | /exam | 出题系统相关接口 |
+
+---
+
+### 二、核心 RAG 模块 (core/)
+
+#### 3. `core/agentic.py` - Agentic RAG 核心
+
+**职责**：智能问答的 Agent 决策引擎
+
+**主要功能**：
+- Agent 决策循环（检索、改写、分解、回答）
+- 网络搜索集成（Serper API）
+- 图谱检索集成
+- 多源结果融合
+- SSE 流式输出
+
+**关键类/函数**：
+| 类/函数 | 说明 |
+|---------|------|
+| `AgenticRAG` | 主类，封装所有 Agent 功能 |
+| `process()` | 处理用户查询 |
+| `chat_search()` | 聊天搜索（支持网络搜索） |
+| `simple_query()` | 简化调用接口 |
+
+**使用方式**：
+```python
+from core.agentic import AgenticRAG, simple_query
+
+# 完整模式
+rag = AgenticRAG()
+result = rag.process("出差补助标准是什么？")
+
+# 简化模式
+result = simple_query("出差补助标准")
+```
+
+#### 4. `core/engine.py` - 检索引擎封装
+
+**职责**：统一的检索引擎接口
+
+**主要功能**：
+- 向量检索
+- BM25 关键词检索
+- 混合检索 + Rerank
+
+#### 5. `core/bm25_index.py` - BM25 索引管理
+
+**职责**：BM25 关键词索引的构建和查询
+
+#### 6. `core/query_classifier.py` - 查询分类器
+
+**职责**：对用户查询进行意图分类，辅助选择合适的检索策略
+
+#### 7. `core/confidence_gate.py` - 置信度门控
+
+**职责**：基于置信度判断是否需要额外的检索或改写
+
+#### 8. `core/quality_assessor.py` - 质量评估器
+
+**职责**：评估检索结果和生成回答的质量
+
+#### 9. `core/reasoning_reflector.py` - 推理反思器
+
+**职责**：对推理过程进行反思和优化
+
+#### 10. `core/loop_guard.py` - 循环防护
+
+**职责**：防止 Agent 陷入无限循环，控制最大迭代次数
+
+---
+
+### 三、知识库管理模块 (knowledge/)
+
+#### 11. `knowledge/manager.py` - 多向量库管理器
+
+**职责**：多向量库的创建、管理和检索
+
+**主要功能**：
+- 多向量库创建与管理（public_kb + dept_xxx）
+- 每个向量库独立的 BM25 索引
+- 并行检索多个向量库
+- RRF 融合结果
+
+**使用方式**：
+```python
+from knowledge.manager import get_kb_manager
+
+kb_manager = get_kb_manager()
+
+# 创建向量库
+kb_manager.create_collection('dept_finance', display_name='财务部知识库')
+
+# 检索
+results = kb_manager.search_multiple(['public_kb', 'dept_finance'], query_vector)
+```
+
+#### 12. `knowledge/router.py` - 知识库路由器
+
+**职责**：根据查询意图和用户权限智能选择目标向量库
+
+**主要功能**：
+- 规则匹配（关键词识别部门）
+- LLM 意图分析（复杂查询）
+- 权限过滤
+
+#### 13. `knowledge/sync.py` - 知识库同步服务
+
+**职责**：自动检测文档变更并触发增量更新
+
+---
+
+### 四、数据库模块 (data/)
+
+#### 14. `data/db.py` - 统一数据访问层
+
+**职责**：集中管理所有数据库连接
+
+**主要功能**：
+- 统一数据库路径配置
+- 连接池管理（上下文管理器）
+- WAL 模式 + 外键约束
+- 自动事务管理
+
+**数据库架构**：
+| 数据库 | 主要功能 |
+|--------|----------|
+| `rag_core.db` | 会话、审计、反馈、FAQ |
+| `knowledge.db` | 同步、大纲、文档版本 |
+| `exam.db` | 题目、试卷、批卷、分析 |
+
+**使用方式**：
+```python
+from data.db import get_connection, init_databases
+
+# 初始化数据库
+init_databases()
+
+# 使用连接
+with get_connection("core") as conn:
+    cursor = conn.cursor()
+    cursor.execute("SELECT * FROM sessions WHERE user_id = ?", (user_id,))
+    rows = cursor.fetchall()
+```
+
+---
+
+### 五、出题系统模块 (exam_pkg/)
+
+#### 15. `exam_pkg/manager.py` - 出题核心逻辑
+
+**职责**：试卷生成、保存、批阅的核心业务逻辑
+
+**主要功能**：
+- 调用 Dify 工作流生成试卷
+- 试卷 CRUD 操作
+- 审核流程管理
+- 自动批阅与报告生成
+
+#### 16. `exam_pkg/api.py` - 出题系统 API
+
+**职责**：出题系统的 Flask Blueprint
+
+**API 端点**：
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/exam/generate-by-file` | POST | 按文件生成题目（带溯源） |
+| `/exam/generate` | POST | 生成试卷 |
+| `/exam/list` | GET | 获取试卷列表 |
+| `/exam/<id>` | GET/PUT/DELETE | 试卷 CRUD |
+| `/exam/grade-from-mysql` | POST | 基于 MySQL 数据批卷 |
+
+#### 17. `exam_pkg/analysis.py` - 题库分析模块
+
+**职责**：题目与制度文档关联、知识点分析
+
+---
+
+### 六、服务模块 (services/)
+
+#### 18. `services/session.py` - 会话管理
+
+**职责**：多用户对话历史管理
+
+**主要功能**：
+- 会话创建与管理
+- 消息历史存储
+- 上下文压缩
+- 会话过期清理
+
+**使用方式**：
+```python
+from services.session import SessionManager
+
+sm = SessionManager()
+session_id = sm.create_session("user_123")
+sm.add_message(session_id, "user", "出差补助标准是什么？")
+history = sm.get_history(session_id)
+```
+
+#### 19. `services/audit.py` - 审计日志
+
+**职责**：用户操作审计
+
+**主要功能**：
+- 记录查询日志
+- 记录检索结果
+- 日志查询
+
+#### 20. `services/feedback.py` - 反馈服务
+
+**职责**：用户反馈收集与 FAQ 自动沉淀
+
+#### 21. `services/outline.py` - 纲要生成器
+
+**职责**：自动生成文档结构纲要
+
+---
+
+### 七、认证与安全模块 (auth/)
+
+#### 22. `auth/gateway.py` - 网关认证
+
+**职责**：网关注入的 Header 认证与多向量库权限控制
+
+**主要功能**：
+- 从 Header 读取用户信息（X-User-ID、X-User-Role、X-User-Department）
+- 角色映射
+- 多向量库权限控制
+- `@require_gateway_auth` 装饰器
+
+**网关注入的 Header**：
+| Header | 说明 |
+|--------|------|
+| `X-User-ID` | 用户唯一标识 |
+| `X-User-Name` | 用户名 |
+| `X-User-Role` | 用户角色 |
+| `X-User-Department` | 部门 |
+
+#### 23. `auth/security.py` - 安全防护
+
+**职责**：Prompt 注入防护
+
+---
+
+### 八、图谱模块 (graph/)
+
+> **注意**：图谱模块为可选功能，需在 `config.py` 中配置 `USE_GRAPH_RAG=True` 和 Neo4j 连接。
+
+#### 24. `graph/graph_manager.py` - 图谱管理器
+
+**职责**：Neo4j 图数据库管理
+
+#### 25. `graph/entity_extractor.py` - 实体提取器
+
+**职责**：使用 LLM 从文本提取实体和关系
+
+#### 26. `graph/graph_rag.py` - 图谱 RAG
+
+**职责**：图谱增强检索
+
+#### 27. `graph/graph_build.py` - 图谱构建工具
+
+**使用方式**：
+```bash
+python -m graph.graph_build --stats
+python -m graph.graph_build --file documents/xxx.pdf
+```
+
+---
+
+## 数据库文件说明
+
+| 文件名 | 主要功能 | 详细文档 |
+|--------|----------|----------|
+| `data/rag_core.db` | 会话管理、审计日志、用户反馈、FAQ | [数据库设计文档.md](./数据库设计文档.md) |
+| `data/knowledge.db` | 知识库同步、文档哈希、纲要缓存、版本管理 | [数据库设计文档.md](./数据库设计文档.md) |
+| `data/exam.db` | 题目存储、试卷管理、批阅记录、分析报告 | [数据库设计文档.md](./数据库设计文档.md) |
+| `knowledge/vector_store/` | 多向量库存储（ChromaDB） | [多向量库实现权限划分.md](./多向量库实现权限划分.md) |
+
+---
+
+## 运行命令
+
+```powershell
+# ✨ 推荐方式 - 新入口
+python main.py                  # 启动 API 服务（端口 5001）
+python main.py --port 8080      # 指定端口
+
+# 旧入口（仍可用）
+python main.py                  # 启动统一网关与大模型 API 服务
+python scripts/test_rag_questions.py  # 自动化问答自评估测试
+python scripts/rebuild_multi_kb.py    # 强制重建各个部门/集合维度的知识库
+```
+
+---
+
+## 相关文档
+
+- [API接口文档.md](./API接口文档.md) - REST API 详细说明
+- [数据库设计文档.md](./数据库设计文档.md) - 所有数据库结构
+- [认证与权限配置指南.md](./认证与权限配置指南.md) - 网关认证说明
+- [多向量库实现权限划分.md](./多向量库实现权限划分.md) - 权限架构说明
+
+---
+
+## 最后更新
+
+- 文档版本：v6.1.0
+- 更新时间：2026-04-16
+- 主要更新：
+  - 补充 core/ 目录新增模块（query_classifier、confidence_gate、quality_assessor、reasoning_reflector、loop_guard）
+  - 补充 api/ 目录新增的 image_routes.py
+  - 补充 parsers/ 目录新增的 image_extractor.py
+  - 修正 knowledge/ 目录重复描述，合并 vector_store 子目录说明
+  - 补充 scripts/ 目录实际存在的脚本文件
+  - 重新编号所有模块说明章节