docs: sync documentation with current progress

README.md

@@ -15,14 +15,17 @@ CodeMind 是一个面向计算机知识学习场景的 RAG（Retrieval-Augmented
 - 在线 LLM RAG 回答和来源编号校验
 - 文档库、原始文档预览、片段查看与来源跳转
 - 问答历史列表、详情查看和历史来源快照
-- 知识库思维导图异步生成、进度展示和历史管理
-- 思维导图节点追问、节点扩展和画布交互
+- 知识地图异步生成、分阶段进度、失败恢复和历史版本管理
+- 总览、章节、概念、细节四类节点，以及关键记忆点和学习建议
+- 节点来源核对、针对性追问、AI 分支扩展和相关资料检索
+- 节点搜索定位、路径导航、本机掌握进度和继续学习入口
+- 画布缩放、布局、撤销重做、分支折叠、全屏及 PNG/SVG/JSON/Markdown 导出
 - 文档、向量、原始文件和知识库级联清理
 - Docker Compose 本地及服务器部署
 
 后续计划：
 
-- 用户反馈持久化和管理员反馈页面
+- 用户反馈持久化、管理员反馈页面和相应自动化测试
 - 基于固定测试集的相似度阈值评估
 - RAG 问答与思维导图的真实模型端到端测试
 - 前端产物体积优化和项目成果物整理
@@ -50,7 +53,9 @@ flowchart LR
     Backend --> Uploads[("上传文件")]
     Backend --> Embedding["Embedding API"]
     Backend --> LLM["在线 LLM API"]
-    Backend --> MindMap["RAG 回答与思维导图生成"]
+    Backend --> RAG["RAG 问答"]
+    Backend --> MindMap["知识地图任务与历史"]
+    RAG --> LLM
     MindMap --> LLM
 ```
 
@@ -236,7 +241,8 @@ Get-Content -Raw database\migrations\20260711_preserve_qa_source_snapshots.sql |
 6. 查看回答中的来源片段和相关度。
 7. 点击“查看片段”或进入“文档库”核对原文。
 8. 在“问答历史”中回看回答；原文被删除后仍保留来源快照。
-9. 进入“知识地图”异步生成思维导图，并对节点追问或继续扩展。
+9. 进入“知识地图”异步生成学习结构，并查看节点类型、记忆点、学习建议和原文覆盖率。
+10. 搜索或定位节点，标记本机掌握状态，对节点追问、扩展分支或导出地图。
 
 如果检索不到资料，请先确认文档处理状态、Embedding 配置和相似度阈值。阈值与 Embedding 模型及切分粒度有关，更换模型后必须重新评估。
 
@@ -269,6 +275,7 @@ Authorization: Bearer <access_token>
 | `GET`          | `/api/qa-records/{id}`      | 问答历史详情     |
 | `POST`         | `/api/mind-maps/jobs`       | 创建导图生成任务 |
 | `GET`          | `/api/mind-maps/jobs/{id}`  | 查询任务进度     |
+| `POST`         | `/api/mind-maps/generate`   | 同步生成导图（调试接口） |
 | `POST`         | `/api/mind-maps/ask`        | 对导图节点追问   |
 | `POST`         | `/api/mind-maps/expand`     | 扩展导图节点     |
 | `GET/POST`     | `/api/mind-maps/histories`  | 查询或保存导图历史 |
@@ -286,7 +293,7 @@ python -m pip install pytest==8.3.5
 python -m pytest -q
 ```
 
-当前后端测试共 46 项，覆盖认证、权限、文档处理、删除清理、检索降级、Prompt、LLM 异常、RAG 编排、问答历史和思维导图服务。
+当前后端测试共 53 项，覆盖认证、权限、文档处理、删除清理、检索降级、Prompt、LLM 异常、RAG 编排、问答历史，以及知识地图生成、并发控制、任务、历史和接口权限。
 
 前端生产构建检查：
 
@@ -356,6 +363,12 @@ Docker Compose 使用三个命名卷：
 
 确认知识库中存在 `completed` 文档，并检查相似度阈值。不要直接把其他 Embedding 模型下的阈值用于当前模型。
 
+### 知识地图无法生成或一直等待
+
+知识地图必须配置在线 LLM。先查看 `docker compose logs -f backend`，确认任务是否进入 `failed`，再检查 LLM 模型、超时和网络。前端会在页面切换后恢复同一知识库的未完成任务，并逐步降低轮询频率。
+
+知识地图节点的 `node_type`、`key_points` 和 `learning_tip` 保存在历史记录的 JSON 中，不需要新增数据库列；旧历史缺少这些字段时会使用兼容默认值。
+
 ### 修改 schema.sql 后数据库没有变化
 
 初始化脚本不会作用于已有数据卷。请执行对应的 `database/migrations/*.sql`，不要为了应用结构变化直接删除生产数据卷。
@@ -371,10 +384,15 @@ $OutputEncoding = [System.Text.Encoding]::UTF8
 
 ## 项目文档
 
+- [文档导航与实现状态](docs/README.md)
+- [前端开发说明](frontend/README.md)
+- [后端开发说明](backend/README.md)
 - [需求分析](docs/需求分析.md)
 - [API 接口设计](docs/API接口设计.md)
 - [生成侧接口约定](docs/生成侧接口约定.md)
+- [GitHub Wiki 首页草稿](docs/wiki/Home.md)
 - [数据库结构](database/schema.sql)
+- [数据库与迁移说明](database/README.md)
 
 ## 安全说明
 
@@ -386,3 +404,7 @@ $OutputEncoding = [System.Text.Encoding]::UTF8
 ## License
 
 本项目用于课程实训。若后续需要公开发布或允许外部复用，请由项目组补充正式开源许可证。
+
+---
+
+文档状态：已按 `main` 提交 `839890b`（合并 PR #11）同步，更新时间为 2026-07-13。

backend/README.md

@@ -1,25 +1,104 @@
 # CodeMind Backend
 
-FastAPI 后端负责提供文档管理、RAG 问答、问答历史和系统管理接口。
+FastAPI 后端负责认证、知识库与文档管理、Embedding 入库、Chroma 检索、RAG 问答、问答历史和知识地图服务。
 
-## 开发命令
+## 模块结构
+
+| 目录或文件 | 职责 |
+| --- | --- |
+| `app/api/routes.py` | REST API 与 HTTP 错误转换 |
+| `app/core/config.py` | `.env` 配置读取和路径解析 |
+| `app/db/session.py` | SQLAlchemy Engine 与 Session |
+| `app/services/document_service.py` | 上传、后台解析、入库、重建和删除 |
+| `app/services/retrieval_service.py` | 问题重写、Embedding、Chroma 召回、过滤与 rerank |
+| `app/services/rag_service.py` | 检索、Prompt、LLM、历史保存的问答编排 |
+| `app/services/mind_map_service.py` | 知识地图结构生成、节点追问和分支扩展 |
+| `app/services/mind_map_job_service.py` | 异步任务状态、进度和结果持久化 |
+| `app/services/mind_map_history_service.py` | 地图历史版本和画布状态持久化 |
+| `tests/` | 后端自动化测试 |
+
+## 环境配置
+
+在 `backend/` 下创建 `.env`。字段模板位于仓库根目录 `.env.example`，至少配置：
+
+```dotenv
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=replace_with_database_password
+MYSQL_DATABASE=codemind
+
+LLM_API_KEY=replace_with_llm_key
+LLM_BASE_URL=https://provider.example.com/v1
+LLM_MODEL=replace_with_chat_model
+
+EMBEDDING_API_KEY=replace_with_embedding_key
+EMBEDDING_BASE_URL=https://provider.example.com/v1
+EMBEDDING_MODEL=replace_with_embedding_model
+
+JWT_SECRET_KEY=replace_with_a_long_random_secret
+```
+
+Embedding 未配置时，文档入库和检索会明确失败；普通 RAG 问答在 LLM 未配置时保留本地演示回答。知识地图依赖结构化 LLM 输出，因此必须配置在线 LLM。
+
+## 原生开发
+
+Windows PowerShell：
+
+```powershell
+cd backend
+E:\Python\python.exe -m pip install -r requirements.txt
+E:\Python\python.exe -m uvicorn app.main:app --reload
+```
+
+Linux、macOS 或 WSL：
 
 ```bash
-python -m venv .venv
-.venv/Scripts/activate
-pip install -r requirements.txt
-uvicorn app.main:app --reload
+cd backend
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+python -m uvicorn app.main:app --reload
 ```
 
-默认服务地址：
+默认地址：
+
+- API：`http://localhost:8000`
+- Swagger：`http://localhost:8000/docs`
+- 健康检查：`http://localhost:8000/api/health`
 
-```text
-http://localhost:8000
+除健康检查、注册和登录外，业务接口需要：
+
+```http
+Authorization: Bearer <access_token>
 ```
 
-接口文档地址：
+## 知识地图说明
+
+- `POST /api/mind-maps/jobs` 创建后台任务，`GET /api/mind-maps/jobs/{job_id}` 查询进度。
+- 任务会分批提炼资料，再合并为总览、章节、概念和细节节点。
+- 每个节点可包含 `key_points`、`learning_tip`、原文来源和子节点。
+- 同一后端实例的知识地图 LLM 调用并发上限为 3；分批调用失败时会取消剩余请求。
+- 自动生成结果会保存历史版本；前端也可创建、更新和删除版本。
+- 新增节点学习字段位于历史 JSON 中，旧数据可使用默认值读取，不需要数据库迁移。
 
-```text
-http://localhost:8000/docs
+## 运行测试
+
+```bash
+cd backend
+python -m pytest -q
 ```
 
+当前基线为 `53 passed`。测试使用 SQLite 和替身服务覆盖主要业务，不等同于真实 MySQL、Chroma 和在线模型端到端验证。
+
+## Docker 运行
+
+完整环境建议从仓库根目录启动：
+
+```bash
+docker compose up -d --build
+docker compose logs -f backend
+```
+
+已有数据库升级时还需按根目录 README 执行 `database/migrations/` 中尚未应用的脚本。
+

database/README.md

@@ -0,0 +1,53 @@
+# CodeMind Database
+
+CodeMind 使用 MySQL 保存结构化业务数据，使用 Chroma 保存文档片段向量。两者承担不同职责，不能互相替代。
+
+## MySQL 表
+
+| 表 | 用途 |
+| --- | --- |
+| `users` | 用户、密码哈希、角色和状态 |
+| `knowledge_bases` | 私人知识库和用户归属 |
+| `documents` | 文件信息、处理状态、错误和片段数量 |
+| `document_chunks` | 文本片段、位置、页码和 `vector_id` |
+| `qa_records` | 问题、重写问题、回答和来源数量 |
+| `qa_sources` | 历史来源快照和可空的原文关联 |
+| `feedbacks` | 反馈目标表；当前业务接口尚未持久化 |
+| `mind_map_histories` | 地图结果 JSON、节点数和画布状态 |
+| `mind_map_jobs` | 地图后台任务、阶段、进度、结果和错误 |
+
+新数据库由 `schema.sql` 初始化。Docker 中该脚本只会在 `mysql_data` 数据卷第一次创建时运行。
+
+## 已有数据库迁移
+
+| 脚本 | 用途 |
+| --- | --- |
+| `migrations/20260711_add_document_error_message.sql` | 增加文档处理失败原因 |
+| `migrations/20260711_preserve_qa_source_snapshots.sql` | 删除原文后保留问答来源快照 |
+| `migrations/20260712_create_mind_map_tables.sql` | 创建地图历史和后台任务表 |
+
+生产数据库执行迁移前必须备份。迁移脚本按说明执行一次，不要通过删除 Docker 数据卷来替代迁移。
+
+Linux、macOS 或 WSL 示例：
+
+```bash
+docker compose exec -T mysql sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE"' \
+  < database/migrations/<migration>.sql
+```
+
+Windows PowerShell 示例：
+
+```powershell
+Get-Content -Raw database\migrations\<migration>.sql |
+  docker compose exec -T mysql sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE"'
+```
+
+## Chroma 关联
+
+`document_chunks.vector_id` 与 Chroma 记录 ID 一一对应。Chroma metadata 至少包含用户、知识库、文档、片段序号、文件名、页码和偏移信息，以便权限过滤和来源反查。
+
+更换 Embedding 模型或向量维度后，旧向量不能与新向量混用。应停止写入、备份数据、清空或重建 Chroma 索引，并对现有文档重新入库；MySQL 用户和业务记录不应随向量重建一起删除。
+
+## 知识地图字段兼容
+
+`node_type`、`key_points` 和 `learning_tip` 位于 `mind_map_histories.result_json`，不是独立数据库列。新增字段由后端模型提供默认值，因此 PR #11 不需要额外数据库迁移，旧地图历史可以继续读取。