{"repo": "18287452845/lesson-tools", "files": {"README.md": {"0a9dfb51760e04c428738d6177ba5345f78e6abd": {"t": 1785746609.1237247, "n": 19910, "h": "9e94cfa8e1d7e167", "c": "# 智能教案助手 (Intelligent Lesson Plan Assistant)\n\n\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成、批量生产和在线编辑功能。\n\n[](https://www.python.org/)\n[](https://nodejs.org/)\n[](LICENSE)\n[](https://github.com/18287452845/lesson-tools)\n\n[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用指南](#-使用指南) • [API文档](#-api-文档) • [常见问题](#-常见问题)\n\n
\n\n---\n\n## 📸 功能预览\n\n| 模板管理 | 批量生成 | 可视化编辑 |\n|:---:|:---:|:---:|\n| 上传和管理 Word 模板 | 一键生成整学期教案 | TipTap 富文本编辑器 |\n\n## 简介\n\n智能教案助手是一款专为教育工作者设计的全栈 Web 应用，通过人工智能技术大幅简化教案创建流程。无论是单份教案还是整学期批量生成，都能在几分钟内完成专业质量的教案文档。\n\n**核心优势：**\n- 🚀 **高效** - 批量生成整学期教案，节省 90% 时间\n- 🎨 **专业** - 完美保留 Word 格式，符合学校规范\n- 🔄 **灵活** - 可视化模板编辑，自定义教案结构\n- 💾 **智能** - AI 优化内容，自动扩展重写\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **📦 批量生成** - 按课时数批量生成整学期教案，支持章节缓存\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n- **📚 教材章节层级** - 默认支持教材-章节-小节三层结构\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n### 批量生成特性\n- **课时数驱动** - 输入总课时（如64、72），自动计算教案数量\n- **数量固定** - 最终教案数量始终由总课时 ÷ 每份教案课时决定，章节仅作参考\n- **灵活分组** - 可配置每份教案课时数（默认2课时/教案）\n- **章节缓存** - 生成的章节模板自动缓存，数量不匹配时自动清理并重新生成\n- **多种输入方式** - 可选输入章节参考，AI 按课时重新划分\n- **实时进度** - 后台生成，实时查看进度和状态\n- **ZIP打包** - 所有教案自动打包下载，文件命名清晰\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 管理脚本（便捷启动/停止）\n\n项目提供了跨平台的管理脚本来简化启动和停止操作：\n\n**Windows:**\n```batch\n# 启动前后端服务\nstart.bat\n\n# 查看服务状态\nstatus.bat\n\n# 停止服务\nstop.bat\n```\n\n**Linux/Mac:**\n```bash\n# 启动前后端服务\n./start.sh\n\n# 查看服务状态\n./status.sh\n\n# 停止服务\n./stop.sh\n```\n\n**脚本功能：**\n- `start.bat/sh` - 后台启动前后端服务，日志保存在 `logs/` 目录\n- `status.bat/sh` - 查看服务运行状态和端口监听情况\n- `stop.bat/sh` - 停止所有服务并清理遗留进程\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n### 方式四：Docker 部署（推荐用于生产环境）\n\n使用 Docker Compose 可以快速部署整个应用，无需手动配置 Python 和 Node.js 环境。\n\n```bash\n# 1. 配置环境变量\ncp .env.example .env\n# 编辑 .env 文件，填入您的 API Key\n\n# 2. 构建并启动服务\ndocker-compose up -d --build\n\n# 3. 查看运行状态\ndocker-compose ps\n\n# 4. 查看日志\ndocker-compose logs -f\n\n# 5. 停止服务\ndocker-compose down\n```\n\n**访问地址：**\n- 前端界面：http://localhost:8081\n- 后端 API：http://localhost:8001\n- API 文档：http://localhost:8001/docs\n\n**数据持久化：** `storage/` 目录中的数据会自动挂载并持久化保存。\n\n详细的 Docker 部署说明请参考 `DOCKER_DEPLOYMENT.md`。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── lesson_plans.py # 教案检索管理 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ ├── settings.py # 设置管理 API\n│ │ ├── batch.py # 批量生成 API 📦\n│ │ └── classes.py # 班级管理 API\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── template_sync.py # 模板自动同步服务\n│ │ ├── template_versioning.py # 版本历史管理\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── document_modifier.py # 文档修改服务\n│ │ ├── lesson_plan_service.py # 教案业务逻辑\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ ├── chapter_splitter.py # 课程章节拆分服务 📦\n│ │ ├── batch_processor.py # 批量生成处理器 📦\n│ │ └── background_runner.py # 后台任务运行器 📦\n│ ├── tests/ # 后端测试\n│ │ ├── conftest.py # Pytest 配置和 Fixtures\n│ │ ├── test_api_templates.py # 模板 API 测试\n│ │ ├── test_api_batch.py # 批量 API 测试\n│ │ ├── test_database.py # 数据库测试\n│ │ └── ... # 其他测试文件\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── LessonPlanDetail.tsx # 教案详情\n│ │ ├── History.tsx # 历史记录\n│ │ ├── BatchGenerate.tsx # 批量生成 📦\n│ │ ├── BatchDownloads.tsx # 批量下载 📦\n│ │ ├── BatchTaskDetail.tsx # 批量任务详情 📦\n│ │ ├── CachedLessonPlans.tsx # 缓存章节模板 📦\n│ │ ├── ClassManager.tsx # 班级管理\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ ├── batchApi.ts # 批量生成 API 客户端 📦\n│ │ ├── settingsApi.ts # 设置 API\n│ │ └── fileService.ts # 文件下载服务\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ ├── editorStore.ts # 编辑器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── test-data/ # 测试数据\n│ └── mock-responses.json # Mock AI 响应\n│\n├── test-results/ # 测试结果输出\n│ └── screenshots/ # E2E 测试截图\n│\n├── logs/ # 服务日志（自动创建）\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── pytest.ini # Pytest 配置\n├── start.bat / start.sh # 启动前后端服务（Windows/Linux）\n├── status.bat / status.sh # 查看服务状态\n├── stop.bat / stop.sh # 停止服务\n├── .env # 环境变量配置（需创建）\n├── .gitignore # Git 忽略规则\n├── CLAUDE.md # Claude Code 项目说明\n├── WORD_EXPORT_FIX.md # Word 导出技术说明\n├── REALTIME_GENERATION_FEATURE.md # 实时生成功能说明\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/stream` | POST | SSE 流式生成 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n| `/api/generate` | GET | 获取教案列表 |\n| `/api/generate/{id}` | GET | 获取教案详情 |\n| `/api/generate/{id}` | DELETE | 删除教案 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/upload` | POST | 上传现有文档 |\n| `/api/edit/{id}` | GET | 获取文档详情 |\n| `/api/edit/{id}/section` | POST | 编辑特定章节 |\n| `/api/edit/{id}/ai-enhance` | POST | AI 增强内容 |\n| `/api/edit/{id}/add-section` | POST | 添加缺失章节 |\n| `/api/edit/{id}/save` | POST | 保存并下载 |\n| `/api/edit/{id}/undo` | POST | 撤销编辑 |\n| `/api/edit/{id}/history` | GET | 获取编辑历史 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n| `/api/settings/app-info` | GET | 获取应用信息 |\n\n#### 批量生成 📦\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/batch/split-chapters` | POST | 根据总课时拆分章节 |\n| `/api/batch/split-chapters-stream` | POST | SSE 流式章节拆分 |\n| `/api/batch/create-task` | POST | 创建批量生成任务 |\n| `/api/batch/tasks/{id}` | GET | 获取任务状态和进度 |\n| `/api/batch/tasks` | GET | 获取批量任务列表 |\n| `/api/batch/tasks/{id}/download` | GET | 下载生成的 ZIP 文件 |\n| `/api/batch/tasks/{id}` | DELETE | 取消或删除任务 |\n| `/api/batch/chapter-templates` | GET | 获取缓存的章节模板列表 |\n\n#### 班级管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/classes` | GET/POST | 获取/创建班级 |\n| `/api/classes/{id}` | GET | 获取班级详情 |\n| `/api/classes/{id}` | PUT | 更新班级 |\n| `/api/classes/{id}` | DELETE | 删除班级 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n**嵌套结构（教学目标分类）：**\n```\n{% for goal_type in ['知识目标', '能力目标', '素质目标'] %}\n{{ goal_type }}：\n{% for goal in teaching_goals[goal_type] %}\n- {{ goal }}\n{% endfor %}\n\n{% endfor %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n7. 导出为 Word 文档\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n### 6. 批量生成教案 📦\n\n批量生成功能可以一次性创建整学期的所有教案：\n\n#### 步骤 1: 填写课程信息\n- **课程名称**: 如 \"Java程序设计\"\n- **学科/年级**: 选择对应的学科和年级\n- **总课时数**: 如 64 课时（自动计算教案数量）\n- **每份教案课时**: 默认 2 课时（可调整）\n- **章节来源**:\n - **AI 自动生成**: AI 根据课程信息与课时自动划分知识点\n - **手动输入**: 可输入章节标题作为参考，AI 会按总课时重新划分\n - **使用已有模板**: 复用历史章节作为参考，AI 会按总课时重新划分\n\n#### 步骤 2: 确认章节\n- 查看 AI 生成的章节列表\n- 可直接在表格中编辑课题和内容概述\n- 确认教案模板是否已选择\n\n#### 步骤 3: 监控生成进度\n- 后台自动生成所有教案\n- 实时显示进度条（已完成/总数）\n- 完成后可前往下载页面获取 ZIP 文件\n\n#### 使用已有模板\n如果之前生成过相同课程，可选择\"使用已有模板\"：\n- 自动加载历史章节配置作为参考\n- AI 根据课时重新划分，节省时间\n- 模板使用次数会自动记录\n\n#### 下载说明\n- 所有教案打包为 ZIP 文件\n- 文件命名: `课程名称_批量教案_时间戳.zip`\n- 内部文档: `课程名称_01.docx`, `课程名称_02.docx` ...\n- 每个文档包含配置数量的教案\n\n### 7. 班级管理\n\n1. 进入**班级管理**页面\n2. 点击**添加新班级**\n3. 填写班级信息（名称、学科、年级、学生人数等）\n4. 保存后可在生成教案时选择班级\n5. 支持编辑和删除班级\n\n## ❓ 常见问题\n\n### OnlyOffice 集成\n\n**Q: 打开模板编辑器提示“OnlyOffice Document Server URL not configured”？**\n\nA: 确认后端环境变量已设置且进程重启：\n```env\nONLYOFFICE_DOCS_URL=https://your-onlyoffice-domain # 例如 https://only.linnera.link\nONLYOFFICE_JWT_SECRET=your-jwt-secret # 文档安全令牌\nPUBLIC_BASE_URL=https://your-frontend-domain # 例如 https://ls.linnera.link\n```\nDocker 模式修改 `.env` 后需 `docker-compose up -d --build` 重新构建。\n\n**Q: OnlyOffice 提示“文档安全令牌格式不正确”或 JWT 校验失败？**\n\nA: 文档服务器与后端的密钥必须一致，且 Document Server 开启了 JWT 验证。\n1. 确认 `.env` 的 `ONLYOFFICE_JWT_SECRET` 与 Document Server `/etc/onlyoffice/documentserver/local.json` 中的 `services.CoAuthoring.secret` 相同。\n2. 重启 Document Server（或其容器）和后端。\n3. 浏览器清除缓存后重试。\n\n**Q: 控制台报 `inspector.js ... responseType 'arraybuffer'`？**\n\nA: 升级到最新代码并确保 Document Server 使用新的静态版本号（当前为 `20260121-fix8`）。后端会在加载脚本时追加该版本号，Document Server Nginx 需将 `$cache_tag` 设为相同值并为 `inspector.js` 提供占位文件以避免调试脚本拦截。更新后重新部署 Docker 后端与前端。\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: 为什么 storage/templates/ 中的模板不显示？**\n\nA: 后端会在启动时自动扫描 `storage/templates/` 文件夹并导入新模板：\n- 只需将 `.docx` 文件放入该文件夹\n- 重启后端服务即可自动导入\n- 已导入的模板不会重复导入\n\n**Q: 如何手动导入现有模板？**\n\nA: 运行导入脚本：\n```bash\npython import_templates.py\n```\n这会扫描 `storage/templates/` 文件夹并导入所有未在数据库中的模板。\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n**Q: 模板编辑器中 Jinja2 语法不显示？**\n\nA: 确保 Jinja2 语法使用正确格式：\n- 变量: `{{ variable_name }}`\n- 循环: `{% for item in items %}...{% endfor %}`\n- 条件: `{% if condition %}...{% endif %}`\n\n### 批量生成相关\n\n**Q: 批量生成需要多长时间？**\n\nA: 取决于教案数量和 AI 响应速度：\n- 单份教案约 10-30 秒\n- 32 份教案约 5-15 分钟\n- 建议使用章节缓存功能加速\n\n**Q: 批量生成失败怎么办？**\n\nA: 系统会记录失败数量，已生成的教案不会丢失：\n- 查看错误信息了解原因\n- 检查 API 密钥是否有效\n- 可以重新创建任务\n\n**Q: 如何修改已缓存的章节模板？**\n\nA: 目前不支持直接修改，可以：\n- 创建新任务时手动调整章节\n- 或联系管理员删除缓存后重新生成\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# 运行特定类别的测试\npytest -m unit # 仅运行单元测试（快速）\npytest -m integration # 仅运行集成测试\npytest -m api # 仅运行 API 测试\npytest -m service # 仅运行服务层测试\npytest -m \"not slow\" # 跳过慢速测试\npytest -m \"not ai\" # 跳过需要 AI API 密钥的测试\npytest -m smoke # 快速冒烟测试\n\n# 带覆盖率报告的测试\npytest --cov=backend --cov-report=html\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n### 测试标记\n\n项目使用 pytest 标记来分类测试：\n- `unit` - 单元测试（快速、隔离）\n- `integration` - 集成测试（较慢、可能使用外部服务）\n- `slow` - 慢速测试（数据库、文件 I/O、AI 调用）\n- `api` - API 端点测试\n- `service` - 服务层测试\n- `database` - 数据库操作测试\n- `ai` - 调用 AI 提供商的测试（需要 API 密钥）\n- `smoke` - 快速冒烟测试\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 📝 更新日志\n\n### v1.0.0 (最新)\n- ✨ 新增批量生成功能 - 按课时数批量生成整学期教案\n- ✨ 新增章节缓存系统 - 支持快速复用历史章节配置\n- ✨ 新增可视化模板编辑器 - TipTap 富文本编辑器\n- ✨ 新增版本历史管理 - 支持版本对比和回滚\n- ✨ 新增班级管理功能 - 管理授课班级信息\n- ✨ 新增 Docker 部署支持 - 一键部署完整应用栈\n- 🔧 优化 Word 导出 - 使用 `docxtpl` 完美保留格式\n- 🔧 添加跨平台管理脚本 - Windows .bat 和 Linux .sh\n- 🔧 多 AI 提供商支持 - DeepSeek 和 Anthropic Claude\n- 🔧 后台任务处理 - 支持优雅关闭和进度追踪\n- 🧪 完善测试基础设施 - Pytest 配置和测试标记\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n[⬆ 返回顶部](#智能教案助手-intelligent-lesson-plan-assistant)\n\n
\n"}, "62cb0d86a40eac1a18552ebebe7def8629f8d57b": {"t": 1785766246.7258737, "n": 19910, "h": "9e94cfa8e1d7e167", "c": "# 智能教案助手 (Intelligent Lesson Plan Assistant)\n\n\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成、批量生产和在线编辑功能。\n\n[](https://www.python.org/)\n[](https://nodejs.org/)\n[](LICENSE)\n[](https://github.com/18287452845/lesson-tools)\n\n[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用指南](#-使用指南) • [API文档](#-api-文档) • [常见问题](#-常见问题)\n\n
\n\n---\n\n## 📸 功能预览\n\n| 模板管理 | 批量生成 | 可视化编辑 |\n|:---:|:---:|:---:|\n| 上传和管理 Word 模板 | 一键生成整学期教案 | TipTap 富文本编辑器 |\n\n## 简介\n\n智能教案助手是一款专为教育工作者设计的全栈 Web 应用，通过人工智能技术大幅简化教案创建流程。无论是单份教案还是整学期批量生成，都能在几分钟内完成专业质量的教案文档。\n\n**核心优势：**\n- 🚀 **高效** - 批量生成整学期教案，节省 90% 时间\n- 🎨 **专业** - 完美保留 Word 格式，符合学校规范\n- 🔄 **灵活** - 可视化模板编辑，自定义教案结构\n- 💾 **智能** - AI 优化内容，自动扩展重写\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **📦 批量生成** - 按课时数批量生成整学期教案，支持章节缓存\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n- **📚 教材章节层级** - 默认支持教材-章节-小节三层结构\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n### 批量生成特性\n- **课时数驱动** - 输入总课时（如64、72），自动计算教案数量\n- **数量固定** - 最终教案数量始终由总课时 ÷ 每份教案课时决定，章节仅作参考\n- **灵活分组** - 可配置每份教案课时数（默认2课时/教案）\n- **章节缓存** - 生成的章节模板自动缓存，数量不匹配时自动清理并重新生成\n- **多种输入方式** - 可选输入章节参考，AI 按课时重新划分\n- **实时进度** - 后台生成，实时查看进度和状态\n- **ZIP打包** - 所有教案自动打包下载，文件命名清晰\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 管理脚本（便捷启动/停止）\n\n项目提供了跨平台的管理脚本来简化启动和停止操作：\n\n**Windows:**\n```batch\n# 启动前后端服务\nstart.bat\n\n# 查看服务状态\nstatus.bat\n\n# 停止服务\nstop.bat\n```\n\n**Linux/Mac:**\n```bash\n# 启动前后端服务\n./start.sh\n\n# 查看服务状态\n./status.sh\n\n# 停止服务\n./stop.sh\n```\n\n**脚本功能：**\n- `start.bat/sh` - 后台启动前后端服务，日志保存在 `logs/` 目录\n- `status.bat/sh` - 查看服务运行状态和端口监听情况\n- `stop.bat/sh` - 停止所有服务并清理遗留进程\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n### 方式四：Docker 部署（推荐用于生产环境）\n\n使用 Docker Compose 可以快速部署整个应用，无需手动配置 Python 和 Node.js 环境。\n\n```bash\n# 1. 配置环境变量\ncp .env.example .env\n# 编辑 .env 文件，填入您的 API Key\n\n# 2. 构建并启动服务\ndocker-compose up -d --build\n\n# 3. 查看运行状态\ndocker-compose ps\n\n# 4. 查看日志\ndocker-compose logs -f\n\n# 5. 停止服务\ndocker-compose down\n```\n\n**访问地址：**\n- 前端界面：http://localhost:8081\n- 后端 API：http://localhost:8001\n- API 文档：http://localhost:8001/docs\n\n**数据持久化：** `storage/` 目录中的数据会自动挂载并持久化保存。\n\n详细的 Docker 部署说明请参考 `DOCKER_DEPLOYMENT.md`。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── lesson_plans.py # 教案检索管理 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ ├── settings.py # 设置管理 API\n│ │ ├── batch.py # 批量生成 API 📦\n│ │ └── classes.py # 班级管理 API\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── template_sync.py # 模板自动同步服务\n│ │ ├── template_versioning.py # 版本历史管理\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── document_modifier.py # 文档修改服务\n│ │ ├── lesson_plan_service.py # 教案业务逻辑\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ ├── chapter_splitter.py # 课程章节拆分服务 📦\n│ │ ├── batch_processor.py # 批量生成处理器 📦\n│ │ └── background_runner.py # 后台任务运行器 📦\n│ ├── tests/ # 后端测试\n│ │ ├── conftest.py # Pytest 配置和 Fixtures\n│ │ ├── test_api_templates.py # 模板 API 测试\n│ │ ├── test_api_batch.py # 批量 API 测试\n│ │ ├── test_database.py # 数据库测试\n│ │ └── ... # 其他测试文件\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── LessonPlanDetail.tsx # 教案详情\n│ │ ├── History.tsx # 历史记录\n│ │ ├── BatchGenerate.tsx # 批量生成 📦\n│ │ ├── BatchDownloads.tsx # 批量下载 📦\n│ │ ├── BatchTaskDetail.tsx # 批量任务详情 📦\n│ │ ├── CachedLessonPlans.tsx # 缓存章节模板 📦\n│ │ ├── ClassManager.tsx # 班级管理\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ ├── batchApi.ts # 批量生成 API 客户端 📦\n│ │ ├── settingsApi.ts # 设置 API\n│ │ └── fileService.ts # 文件下载服务\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ ├── editorStore.ts # 编辑器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── test-data/ # 测试数据\n│ └── mock-responses.json # Mock AI 响应\n│\n├── test-results/ # 测试结果输出\n│ └── screenshots/ # E2E 测试截图\n│\n├── logs/ # 服务日志（自动创建）\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── pytest.ini # Pytest 配置\n├── start.bat / start.sh # 启动前后端服务（Windows/Linux）\n├── status.bat / status.sh # 查看服务状态\n├── stop.bat / stop.sh # 停止服务\n├── .env # 环境变量配置（需创建）\n├── .gitignore # Git 忽略规则\n├── CLAUDE.md # Claude Code 项目说明\n├── WORD_EXPORT_FIX.md # Word 导出技术说明\n├── REALTIME_GENERATION_FEATURE.md # 实时生成功能说明\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/stream` | POST | SSE 流式生成 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n| `/api/generate` | GET | 获取教案列表 |\n| `/api/generate/{id}` | GET | 获取教案详情 |\n| `/api/generate/{id}` | DELETE | 删除教案 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/upload` | POST | 上传现有文档 |\n| `/api/edit/{id}` | GET | 获取文档详情 |\n| `/api/edit/{id}/section` | POST | 编辑特定章节 |\n| `/api/edit/{id}/ai-enhance` | POST | AI 增强内容 |\n| `/api/edit/{id}/add-section` | POST | 添加缺失章节 |\n| `/api/edit/{id}/save` | POST | 保存并下载 |\n| `/api/edit/{id}/undo` | POST | 撤销编辑 |\n| `/api/edit/{id}/history` | GET | 获取编辑历史 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n| `/api/settings/app-info` | GET | 获取应用信息 |\n\n#### 批量生成 📦\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/batch/split-chapters` | POST | 根据总课时拆分章节 |\n| `/api/batch/split-chapters-stream` | POST | SSE 流式章节拆分 |\n| `/api/batch/create-task` | POST | 创建批量生成任务 |\n| `/api/batch/tasks/{id}` | GET | 获取任务状态和进度 |\n| `/api/batch/tasks` | GET | 获取批量任务列表 |\n| `/api/batch/tasks/{id}/download` | GET | 下载生成的 ZIP 文件 |\n| `/api/batch/tasks/{id}` | DELETE | 取消或删除任务 |\n| `/api/batch/chapter-templates` | GET | 获取缓存的章节模板列表 |\n\n#### 班级管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/classes` | GET/POST | 获取/创建班级 |\n| `/api/classes/{id}` | GET | 获取班级详情 |\n| `/api/classes/{id}` | PUT | 更新班级 |\n| `/api/classes/{id}` | DELETE | 删除班级 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n**嵌套结构（教学目标分类）：**\n```\n{% for goal_type in ['知识目标', '能力目标', '素质目标'] %}\n{{ goal_type }}：\n{% for goal in teaching_goals[goal_type] %}\n- {{ goal }}\n{% endfor %}\n\n{% endfor %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n7. 导出为 Word 文档\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n### 6. 批量生成教案 📦\n\n批量生成功能可以一次性创建整学期的所有教案：\n\n#### 步骤 1: 填写课程信息\n- **课程名称**: 如 \"Java程序设计\"\n- **学科/年级**: 选择对应的学科和年级\n- **总课时数**: 如 64 课时（自动计算教案数量）\n- **每份教案课时**: 默认 2 课时（可调整）\n- **章节来源**:\n - **AI 自动生成**: AI 根据课程信息与课时自动划分知识点\n - **手动输入**: 可输入章节标题作为参考，AI 会按总课时重新划分\n - **使用已有模板**: 复用历史章节作为参考，AI 会按总课时重新划分\n\n#### 步骤 2: 确认章节\n- 查看 AI 生成的章节列表\n- 可直接在表格中编辑课题和内容概述\n- 确认教案模板是否已选择\n\n#### 步骤 3: 监控生成进度\n- 后台自动生成所有教案\n- 实时显示进度条（已完成/总数）\n- 完成后可前往下载页面获取 ZIP 文件\n\n#### 使用已有模板\n如果之前生成过相同课程，可选择\"使用已有模板\"：\n- 自动加载历史章节配置作为参考\n- AI 根据课时重新划分，节省时间\n- 模板使用次数会自动记录\n\n#### 下载说明\n- 所有教案打包为 ZIP 文件\n- 文件命名: `课程名称_批量教案_时间戳.zip`\n- 内部文档: `课程名称_01.docx`, `课程名称_02.docx` ...\n- 每个文档包含配置数量的教案\n\n### 7. 班级管理\n\n1. 进入**班级管理**页面\n2. 点击**添加新班级**\n3. 填写班级信息（名称、学科、年级、学生人数等）\n4. 保存后可在生成教案时选择班级\n5. 支持编辑和删除班级\n\n## ❓ 常见问题\n\n### OnlyOffice 集成\n\n**Q: 打开模板编辑器提示“OnlyOffice Document Server URL not configured”？**\n\nA: 确认后端环境变量已设置且进程重启：\n```env\nONLYOFFICE_DOCS_URL=https://your-onlyoffice-domain # 例如 https://only.linnera.link\nONLYOFFICE_JWT_SECRET=your-jwt-secret # 文档安全令牌\nPUBLIC_BASE_URL=https://your-frontend-domain # 例如 https://ls.linnera.link\n```\nDocker 模式修改 `.env` 后需 `docker-compose up -d --build` 重新构建。\n\n**Q: OnlyOffice 提示“文档安全令牌格式不正确”或 JWT 校验失败？**\n\nA: 文档服务器与后端的密钥必须一致，且 Document Server 开启了 JWT 验证。\n1. 确认 `.env` 的 `ONLYOFFICE_JWT_SECRET` 与 Document Server `/etc/onlyoffice/documentserver/local.json` 中的 `services.CoAuthoring.secret` 相同。\n2. 重启 Document Server（或其容器）和后端。\n3. 浏览器清除缓存后重试。\n\n**Q: 控制台报 `inspector.js ... responseType 'arraybuffer'`？**\n\nA: 升级到最新代码并确保 Document Server 使用新的静态版本号（当前为 `20260121-fix8`）。后端会在加载脚本时追加该版本号，Document Server Nginx 需将 `$cache_tag` 设为相同值并为 `inspector.js` 提供占位文件以避免调试脚本拦截。更新后重新部署 Docker 后端与前端。\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: 为什么 storage/templates/ 中的模板不显示？**\n\nA: 后端会在启动时自动扫描 `storage/templates/` 文件夹并导入新模板：\n- 只需将 `.docx` 文件放入该文件夹\n- 重启后端服务即可自动导入\n- 已导入的模板不会重复导入\n\n**Q: 如何手动导入现有模板？**\n\nA: 运行导入脚本：\n```bash\npython import_templates.py\n```\n这会扫描 `storage/templates/` 文件夹并导入所有未在数据库中的模板。\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n**Q: 模板编辑器中 Jinja2 语法不显示？**\n\nA: 确保 Jinja2 语法使用正确格式：\n- 变量: `{{ variable_name }}`\n- 循环: `{% for item in items %}...{% endfor %}`\n- 条件: `{% if condition %}...{% endif %}`\n\n### 批量生成相关\n\n**Q: 批量生成需要多长时间？**\n\nA: 取决于教案数量和 AI 响应速度：\n- 单份教案约 10-30 秒\n- 32 份教案约 5-15 分钟\n- 建议使用章节缓存功能加速\n\n**Q: 批量生成失败怎么办？**\n\nA: 系统会记录失败数量，已生成的教案不会丢失：\n- 查看错误信息了解原因\n- 检查 API 密钥是否有效\n- 可以重新创建任务\n\n**Q: 如何修改已缓存的章节模板？**\n\nA: 目前不支持直接修改，可以：\n- 创建新任务时手动调整章节\n- 或联系管理员删除缓存后重新生成\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# 运行特定类别的测试\npytest -m unit # 仅运行单元测试（快速）\npytest -m integration # 仅运行集成测试\npytest -m api # 仅运行 API 测试\npytest -m service # 仅运行服务层测试\npytest -m \"not slow\" # 跳过慢速测试\npytest -m \"not ai\" # 跳过需要 AI API 密钥的测试\npytest -m smoke # 快速冒烟测试\n\n# 带覆盖率报告的测试\npytest --cov=backend --cov-report=html\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n### 测试标记\n\n项目使用 pytest 标记来分类测试：\n- `unit` - 单元测试（快速、隔离）\n- `integration` - 集成测试（较慢、可能使用外部服务）\n- `slow` - 慢速测试（数据库、文件 I/O、AI 调用）\n- `api` - API 端点测试\n- `service` - 服务层测试\n- `database` - 数据库操作测试\n- `ai` - 调用 AI 提供商的测试（需要 API 密钥）\n- `smoke` - 快速冒烟测试\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 📝 更新日志\n\n### v1.0.0 (最新)\n- ✨ 新增批量生成功能 - 按课时数批量生成整学期教案\n- ✨ 新增章节缓存系统 - 支持快速复用历史章节配置\n- ✨ 新增可视化模板编辑器 - TipTap 富文本编辑器\n- ✨ 新增版本历史管理 - 支持版本对比和回滚\n- ✨ 新增班级管理功能 - 管理授课班级信息\n- ✨ 新增 Docker 部署支持 - 一键部署完整应用栈\n- 🔧 优化 Word 导出 - 使用 `docxtpl` 完美保留格式\n- 🔧 添加跨平台管理脚本 - Windows .bat 和 Linux .sh\n- 🔧 多 AI 提供商支持 - DeepSeek 和 Anthropic Claude\n- 🔧 后台任务处理 - 支持优雅关闭和进度追踪\n- 🧪 完善测试基础设施 - Pytest 配置和测试标记\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n[⬆ 返回顶部](#智能教案助手-intelligent-lesson-plan-assistant)\n\n
\n"}, "247f2f43d33259b0a61230aa1f4d6c971985e6fd": {"t": 1785766248.4364002, "n": 19901, "h": "91379cb291fd4fd7", "c": "# 智能教案助手 (Intelligent Lesson Plan Assistant)\n\n\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成、批量生产和在线编辑功能。\n\n[](https://www.python.org/)\n[](https://nodejs.org/)\n[](LICENSE)\n[](https://github.com/18287452845/lesson-tools)\n\n[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用指南](#-使用指南) • [API文档](#-api-文档) • [常见问题](#-常见问题)\n\n
\n\n---\n\n## 📸 功能预览\n\n| 模板管理 | 批量生成 | 可视化编辑 |\n|:---:|:---:|:---:|\n| 上传和管理 Word 模板 | 一键生成整学期教案 | TipTap 富文本编辑器 |\n\n## 简介\n\n智能教案助手是一款专为教育工作者设计的全栈 Web 应用，通过人工智能技术大幅简化教案创建流程。无论是单份教案还是整学期批量生成，都能在几分钟内完成专业质量的教案文档。\n\n**核心优势：**\n- 🚀 **高效** - 批量生成整学期教案，节省 90% 时间\n- 🎨 **专业** - 完美保留 Word 格式，符合学校规范\n- 🔄 **灵活** - 可视化模板编辑，自定义教案结构\n- 💾 **智能** - AI 优化内容，自动扩展重写\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **📦 批量生成** - 按课时数批量生成整学期教案，支持章节缓存\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n- **📚 教材章节层级** - 默认支持教材-章节-小节三层结构\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n### 批量生成特性\n- **课时数驱动** - 输入总课时（如64、72），自动计算教案数量\n- **数量固定** - 最终教案数量始终由总课时 ÷ 每份教案课时决定，章节仅作参考\n- **灵活分组** - 可配置每份教案课时数（默认2课时/教案）\n- **章节缓存** - 生成的章节模板自动缓存，支持快速复用\n- **多种输入方式** - 可选输入章节参考，AI 按课时重新划分\n- **实时进度** - 后台生成，实时查看进度和状态\n- **ZIP打包** - 所有教案自动打包下载，文件命名清晰\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 管理脚本（便捷启动/停止）\n\n项目提供了跨平台的管理脚本来简化启动和停止操作：\n\n**Windows:**\n```batch\n# 启动前后端服务\nstart.bat\n\n# 查看服务状态\nstatus.bat\n\n# 停止服务\nstop.bat\n```\n\n**Linux/Mac:**\n```bash\n# 启动前后端服务\n./start.sh\n\n# 查看服务状态\n./status.sh\n\n# 停止服务\n./stop.sh\n```\n\n**脚本功能：**\n- `start.bat/sh` - 后台启动前后端服务，日志保存在 `logs/` 目录\n- `status.bat/sh` - 查看服务运行状态和端口监听情况\n- `stop.bat/sh` - 停止所有服务并清理遗留进程\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n### 方式四：Docker 部署（推荐用于生产环境）\n\n使用 Docker Compose 可以快速部署整个应用，无需手动配置 Python 和 Node.js 环境。\n\n```bash\n# 1. 配置环境变量\ncp .env.example .env\n# 编辑 .env 文件，填入您的 API Key\n\n# 2. 构建并启动服务\ndocker-compose up -d --build\n\n# 3. 查看运行状态\ndocker-compose ps\n\n# 4. 查看日志\ndocker-compose logs -f\n\n# 5. 停止服务\ndocker-compose down\n```\n\n**访问地址：**\n- 前端界面：http://localhost:8081\n- 后端 API：http://localhost:8001\n- API 文档：http://localhost:8001/docs\n\n**数据持久化：** `storage/` 目录中的数据会自动挂载并持久化保存。\n\n详细的 Docker 部署说明请参考 `DOCKER_DEPLOYMENT.md`。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── lesson_plans.py # 教案检索管理 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ ├── settings.py # 设置管理 API\n│ │ ├── batch.py # 批量生成 API 📦\n│ │ └── classes.py # 班级管理 API\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── template_sync.py # 模板自动同步服务\n│ │ ├── template_versioning.py # 版本历史管理\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── document_modifier.py # 文档修改服务\n│ │ ├── lesson_plan_service.py # 教案业务逻辑\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ ├── chapter_splitter.py # 课程章节拆分服务 📦\n│ │ ├── batch_processor.py # 批量生成处理器 📦\n│ │ └── background_runner.py # 后台任务运行器 📦\n│ ├── tests/ # 后端测试\n│ │ ├── conftest.py # Pytest 配置和 Fixtures\n│ │ ├── test_api_templates.py # 模板 API 测试\n│ │ ├── test_api_batch.py # 批量 API 测试\n│ │ ├── test_database.py # 数据库测试\n│ │ └── ... # 其他测试文件\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── LessonPlanDetail.tsx # 教案详情\n│ │ ├── History.tsx # 历史记录\n│ │ ├── BatchGenerate.tsx # 批量生成 📦\n│ │ ├── BatchDownloads.tsx # 批量下载 📦\n│ │ ├── BatchTaskDetail.tsx # 批量任务详情 📦\n│ │ ├── CachedLessonPlans.tsx # 缓存章节模板 📦\n│ │ ├── ClassManager.tsx # 班级管理\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ ├── batchApi.ts # 批量生成 API 客户端 📦\n│ │ ├── settingsApi.ts # 设置 API\n│ │ └── fileService.ts # 文件下载服务\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ ├── editorStore.ts # 编辑器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── test-data/ # 测试数据\n│ └── mock-responses.json # Mock AI 响应\n│\n├── test-results/ # 测试结果输出\n│ └── screenshots/ # E2E 测试截图\n│\n├── logs/ # 服务日志（自动创建）\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── pytest.ini # Pytest 配置\n├── start.bat / start.sh # 启动前后端服务（Windows/Linux）\n├── status.bat / status.sh # 查看服务状态\n├── stop.bat / stop.sh # 停止服务\n├── .env # 环境变量配置（需创建）\n├── .gitignore # Git 忽略规则\n├── CLAUDE.md # Claude Code 项目说明\n├── WORD_EXPORT_FIX.md # Word 导出技术说明\n├── REALTIME_GENERATION_FEATURE.md # 实时生成功能说明\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/stream` | POST | SSE 流式生成 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n| `/api/generate` | GET | 获取教案列表 |\n| `/api/generate/{id}` | GET | 获取教案详情 |\n| `/api/generate/{id}` | DELETE | 删除教案 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/upload` | POST | 上传现有文档 |\n| `/api/edit/{id}` | GET | 获取文档详情 |\n| `/api/edit/{id}/section` | POST | 编辑特定章节 |\n| `/api/edit/{id}/ai-enhance` | POST | AI 增强内容 |\n| `/api/edit/{id}/add-section` | POST | 添加缺失章节 |\n| `/api/edit/{id}/save` | POST | 保存并下载 |\n| `/api/edit/{id}/undo` | POST | 撤销编辑 |\n| `/api/edit/{id}/history` | GET | 获取编辑历史 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n| `/api/settings/app-info` | GET | 获取应用信息 |\n\n#### 批量生成 📦\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/batch/split-chapters` | POST | 根据总课时拆分章节 |\n| `/api/batch/split-chapters-stream` | POST | SSE 流式章节拆分 |\n| `/api/batch/create-task` | POST | 创建批量生成任务 |\n| `/api/batch/tasks/{id}` | GET | 获取任务状态和进度 |\n| `/api/batch/tasks` | GET | 获取批量任务列表 |\n| `/api/batch/tasks/{id}/download` | GET | 下载生成的 ZIP 文件 |\n| `/api/batch/tasks/{id}` | DELETE | 取消或删除任务 |\n| `/api/batch/chapter-templates` | GET | 获取缓存的章节模板列表 |\n\n#### 班级管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/classes` | GET/POST | 获取/创建班级 |\n| `/api/classes/{id}` | GET | 获取班级详情 |\n| `/api/classes/{id}` | PUT | 更新班级 |\n| `/api/classes/{id}` | DELETE | 删除班级 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n**嵌套结构（教学目标分类）：**\n```\n{% for goal_type in ['知识目标', '能力目标', '素质目标'] %}\n{{ goal_type }}：\n{% for goal in teaching_goals[goal_type] %}\n- {{ goal }}\n{% endfor %}\n\n{% endfor %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n7. 导出为 Word 文档\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n### 6. 批量生成教案 📦\n\n批量生成功能可以一次性创建整学期的所有教案：\n\n#### 步骤 1: 填写课程信息\n- **课程名称**: 如 \"Java程序设计\"\n- **学科/年级**: 选择对应的学科和年级\n- **总课时数**: 如 64 课时（自动计算教案数量）\n- **每份教案课时**: 默认 2 课时（可调整）\n- **章节来源**:\n - **AI 自动生成**: AI 根据课程信息与课时自动划分知识点\n - **手动输入**: 可输入章节标题作为参考，AI 会按总课时重新划分\n - **使用已有模板**: 复用历史章节作为参考，AI 会按总课时重新划分\n\n#### 步骤 2: 确认章节\n- 查看 AI 生成的章节列表\n- 可直接在表格中编辑课题和内容概述\n- 确认教案模板是否已选择\n\n#### 步骤 3: 监控生成进度\n- 后台自动生成所有教案\n- 实时显示进度条（已完成/总数）\n- 完成后可前往下载页面获取 ZIP 文件\n\n#### 使用已有模板\n如果之前生成过相同课程，可选择\"使用已有模板\"：\n- 自动加载历史章节配置作为参考\n- AI 根据课时重新划分，节省时间\n- 模板使用次数会自动记录\n\n#### 下载说明\n- 所有教案打包为 ZIP 文件\n- 文件命名: `课程名称_批量教案_时间戳.zip`\n- 内部文档: `课程名称_01.docx`, `课程名称_02.docx` ...\n- 每个文档包含配置数量的教案\n\n### 7. 班级管理\n\n1. 进入**班级管理**页面\n2. 点击**添加新班级**\n3. 填写班级信息（名称、学科、年级、学生人数等）\n4. 保存后可在生成教案时选择班级\n5. 支持编辑和删除班级\n\n## ❓ 常见问题\n\n### OnlyOffice 集成\n\n**Q: 打开模板编辑器提示“OnlyOffice Document Server URL not configured”？**\n\nA: 确认后端环境变量已设置且进程重启：\n```env\nONLYOFFICE_DOCS_URL=https://your-onlyoffice-domain # 例如 https://only.linnera.link\nONLYOFFICE_JWT_SECRET=your-jwt-secret # 文档安全令牌\nPUBLIC_BASE_URL=https://your-frontend-domain # 例如 https://ls.linnera.link\n```\nDocker 模式修改 `.env` 后需 `docker-compose up -d --build` 重新构建。\n\n**Q: OnlyOffice 提示“文档安全令牌格式不正确”或 JWT 校验失败？**\n\nA: 文档服务器与后端的密钥必须一致，且 Document Server 开启了 JWT 验证。\n1. 确认 `.env` 的 `ONLYOFFICE_JWT_SECRET` 与 Document Server `/etc/onlyoffice/documentserver/local.json` 中的 `services.CoAuthoring.secret` 相同。\n2. 重启 Document Server（或其容器）和后端。\n3. 浏览器清除缓存后重试。\n\n**Q: 控制台报 `inspector.js ... responseType 'arraybuffer'`？**\n\nA: 升级到最新代码并确保 Document Server 使用新的静态版本号（当前为 `20260121-fix8`）。后端会在加载脚本时追加该版本号，Document Server Nginx 需将 `$cache_tag` 设为相同值并为 `inspector.js` 提供占位文件以避免调试脚本拦截。更新后重新部署 Docker 后端与前端。\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: 为什么 storage/templates/ 中的模板不显示？**\n\nA: 后端会在启动时自动扫描 `storage/templates/` 文件夹并导入新模板：\n- 只需将 `.docx` 文件放入该文件夹\n- 重启后端服务即可自动导入\n- 已导入的模板不会重复导入\n\n**Q: 如何手动导入现有模板？**\n\nA: 运行导入脚本：\n```bash\npython import_templates.py\n```\n这会扫描 `storage/templates/` 文件夹并导入所有未在数据库中的模板。\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n**Q: 模板编辑器中 Jinja2 语法不显示？**\n\nA: 确保 Jinja2 语法使用正确格式：\n- 变量: `{{ variable_name }}`\n- 循环: `{% for item in items %}...{% endfor %}`\n- 条件: `{% if condition %}...{% endif %}`\n\n### 批量生成相关\n\n**Q: 批量生成需要多长时间？**\n\nA: 取决于教案数量和 AI 响应速度：\n- 单份教案约 10-30 秒\n- 32 份教案约 5-15 分钟\n- 建议使用章节缓存功能加速\n\n**Q: 批量生成失败怎么办？**\n\nA: 系统会记录失败数量，已生成的教案不会丢失：\n- 查看错误信息了解原因\n- 检查 API 密钥是否有效\n- 可以重新创建任务\n\n**Q: 如何修改已缓存的章节模板？**\n\nA: 目前不支持直接修改，可以：\n- 创建新任务时手动调整章节\n- 或联系管理员删除缓存后重新生成\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# 运行特定类别的测试\npytest -m unit # 仅运行单元测试（快速）\npytest -m integration # 仅运行集成测试\npytest -m api # 仅运行 API 测试\npytest -m service # 仅运行服务层测试\npytest -m \"not slow\" # 跳过慢速测试\npytest -m \"not ai\" # 跳过需要 AI API 密钥的测试\npytest -m smoke # 快速冒烟测试\n\n# 带覆盖率报告的测试\npytest --cov=backend --cov-report=html\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n### 测试标记\n\n项目使用 pytest 标记来分类测试：\n- `unit` - 单元测试（快速、隔离）\n- `integration` - 集成测试（较慢、可能使用外部服务）\n- `slow` - 慢速测试（数据库、文件 I/O、AI 调用）\n- `api` - API 端点测试\n- `service` - 服务层测试\n- `database` - 数据库操作测试\n- `ai` - 调用 AI 提供商的测试（需要 API 密钥）\n- `smoke` - 快速冒烟测试\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 📝 更新日志\n\n### v1.0.0 (最新)\n- ✨ 新增批量生成功能 - 按课时数批量生成整学期教案\n- ✨ 新增章节缓存系统 - 支持快速复用历史章节配置\n- ✨ 新增可视化模板编辑器 - TipTap 富文本编辑器\n- ✨ 新增版本历史管理 - 支持版本对比和回滚\n- ✨ 新增班级管理功能 - 管理授课班级信息\n- ✨ 新增 Docker 部署支持 - 一键部署完整应用栈\n- 🔧 优化 Word 导出 - 使用 `docxtpl` 完美保留格式\n- 🔧 添加跨平台管理脚本 - Windows .bat 和 Linux .sh\n- 🔧 多 AI 提供商支持 - DeepSeek 和 Anthropic Claude\n- 🔧 后台任务处理 - 支持优雅关闭和进度追踪\n- 🧪 完善测试基础设施 - Pytest 配置和测试标记\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n[⬆ 返回顶部](#智能教案助手-intelligent-lesson-plan-assistant)\n\n
\n"}, "bd958aaa6b048ce44649a1b5f5f00719858c3baa": {"t": 1785766250.4011276, "n": 19861, "h": "1b6c77e2384e2679", "c": "# 智能教案助手 (Intelligent Lesson Plan Assistant)\n\n\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成、批量生产和在线编辑功能。\n\n[](https://www.python.org/)\n[](https://nodejs.org/)\n[](LICENSE)\n[](https://github.com/18287452845/lesson-tools)\n\n[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用指南](#-使用指南) • [API文档](#-api-文档) • [常见问题](#-常见问题)\n\n
\n\n---\n\n## 📸 功能预览\n\n| 模板管理 | 批量生成 | 可视化编辑 |\n|:---:|:---:|:---:|\n| 上传和管理 Word 模板 | 一键生成整学期教案 | TipTap 富文本编辑器 |\n\n## 简介\n\n智能教案助手是一款专为教育工作者设计的全栈 Web 应用，通过人工智能技术大幅简化教案创建流程。无论是单份教案还是整学期批量生成，都能在几分钟内完成专业质量的教案文档。\n\n**核心优势：**\n- 🚀 **高效** - 批量生成整学期教案，节省 90% 时间\n- 🎨 **专业** - 完美保留 Word 格式，符合学校规范\n- 🔄 **灵活** - 可视化模板编辑，自定义教案结构\n- 💾 **智能** - AI 优化内容，自动扩展重写\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **📦 批量生成** - 按课时数批量生成整学期教案，支持章节缓存\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n- **📚 教材章节层级** - 默认支持教材-章节-小节三层结构\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n### 批量生成特性\n- **课时数驱动** - 输入总课时（如64、72），自动计算教案数量\n- **数量固定** - 最终教案数量始终由总课时 ÷ 每份教案课时决定，章节数量仅用于拆分/合并\n- **灵活分组** - 可配置每份教案课时数（默认2课时/教案）\n- **章节缓存** - 生成的章节模板自动缓存，支持快速复用\n- **多种输入方式** - AI自动生成章节或手动输入章节标题\n- **实时进度** - 后台生成，实时查看进度和状态\n- **ZIP打包** - 所有教案自动打包下载，文件命名清晰\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 管理脚本（便捷启动/停止）\n\n项目提供了跨平台的管理脚本来简化启动和停止操作：\n\n**Windows:**\n```batch\n# 启动前后端服务\nstart.bat\n\n# 查看服务状态\nstatus.bat\n\n# 停止服务\nstop.bat\n```\n\n**Linux/Mac:**\n```bash\n# 启动前后端服务\n./start.sh\n\n# 查看服务状态\n./status.sh\n\n# 停止服务\n./stop.sh\n```\n\n**脚本功能：**\n- `start.bat/sh` - 后台启动前后端服务，日志保存在 `logs/` 目录\n- `status.bat/sh` - 查看服务运行状态和端口监听情况\n- `stop.bat/sh` - 停止所有服务并清理遗留进程\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n### 方式四：Docker 部署（推荐用于生产环境）\n\n使用 Docker Compose 可以快速部署整个应用，无需手动配置 Python 和 Node.js 环境。\n\n```bash\n# 1. 配置环境变量\ncp .env.example .env\n# 编辑 .env 文件，填入您的 API Key\n\n# 2. 构建并启动服务\ndocker-compose up -d --build\n\n# 3. 查看运行状态\ndocker-compose ps\n\n# 4. 查看日志\ndocker-compose logs -f\n\n# 5. 停止服务\ndocker-compose down\n```\n\n**访问地址：**\n- 前端界面：http://localhost:8081\n- 后端 API：http://localhost:8001\n- API 文档：http://localhost:8001/docs\n\n**数据持久化：** `storage/` 目录中的数据会自动挂载并持久化保存。\n\n详细的 Docker 部署说明请参考 `DOCKER_DEPLOYMENT.md`。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── lesson_plans.py # 教案检索管理 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ ├── settings.py # 设置管理 API\n│ │ ├── batch.py # 批量生成 API 📦\n│ │ └── classes.py # 班级管理 API\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── template_sync.py # 模板自动同步服务\n│ │ ├── template_versioning.py # 版本历史管理\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── document_modifier.py # 文档修改服务\n│ │ ├── lesson_plan_service.py # 教案业务逻辑\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ ├── chapter_splitter.py # 课程章节拆分服务 📦\n│ │ ├── batch_processor.py # 批量生成处理器 📦\n│ │ └── background_runner.py # 后台任务运行器 📦\n│ ├── tests/ # 后端测试\n│ │ ├── conftest.py # Pytest 配置和 Fixtures\n│ │ ├── test_api_templates.py # 模板 API 测试\n│ │ ├── test_api_batch.py # 批量 API 测试\n│ │ ├── test_database.py # 数据库测试\n│ │ └── ... # 其他测试文件\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── LessonPlanDetail.tsx # 教案详情\n│ │ ├── History.tsx # 历史记录\n│ │ ├── BatchGenerate.tsx # 批量生成 📦\n│ │ ├── BatchDownloads.tsx # 批量下载 📦\n│ │ ├── BatchTaskDetail.tsx # 批量任务详情 📦\n│ │ ├── CachedLessonPlans.tsx # 缓存章节模板 📦\n│ │ ├── ClassManager.tsx # 班级管理\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ ├── batchApi.ts # 批量生成 API 客户端 📦\n│ │ ├── settingsApi.ts # 设置 API\n│ │ └── fileService.ts # 文件下载服务\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ ├── editorStore.ts # 编辑器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── test-data/ # 测试数据\n│ └── mock-responses.json # Mock AI 响应\n│\n├── test-results/ # 测试结果输出\n│ └── screenshots/ # E2E 测试截图\n│\n├── logs/ # 服务日志（自动创建）\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── pytest.ini # Pytest 配置\n├── start.bat / start.sh # 启动前后端服务（Windows/Linux）\n├── status.bat / status.sh # 查看服务状态\n├── stop.bat / stop.sh # 停止服务\n├── .env # 环境变量配置（需创建）\n├── .gitignore # Git 忽略规则\n├── CLAUDE.md # Claude Code 项目说明\n├── WORD_EXPORT_FIX.md # Word 导出技术说明\n├── REALTIME_GENERATION_FEATURE.md # 实时生成功能说明\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/stream` | POST | SSE 流式生成 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n| `/api/generate` | GET | 获取教案列表 |\n| `/api/generate/{id}` | GET | 获取教案详情 |\n| `/api/generate/{id}` | DELETE | 删除教案 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/upload` | POST | 上传现有文档 |\n| `/api/edit/{id}` | GET | 获取文档详情 |\n| `/api/edit/{id}/section` | POST | 编辑特定章节 |\n| `/api/edit/{id}/ai-enhance` | POST | AI 增强内容 |\n| `/api/edit/{id}/add-section` | POST | 添加缺失章节 |\n| `/api/edit/{id}/save` | POST | 保存并下载 |\n| `/api/edit/{id}/undo` | POST | 撤销编辑 |\n| `/api/edit/{id}/history` | GET | 获取编辑历史 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n| `/api/settings/app-info` | GET | 获取应用信息 |\n\n#### 批量生成 📦\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/batch/split-chapters` | POST | 根据总课时拆分章节 |\n| `/api/batch/split-chapters-stream` | POST | SSE 流式章节拆分 |\n| `/api/batch/create-task` | POST | 创建批量生成任务 |\n| `/api/batch/tasks/{id}` | GET | 获取任务状态和进度 |\n| `/api/batch/tasks` | GET | 获取批量任务列表 |\n| `/api/batch/tasks/{id}/download` | GET | 下载生成的 ZIP 文件 |\n| `/api/batch/tasks/{id}` | DELETE | 取消或删除任务 |\n| `/api/batch/chapter-templates` | GET | 获取缓存的章节模板列表 |\n\n#### 班级管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/classes` | GET/POST | 获取/创建班级 |\n| `/api/classes/{id}` | GET | 获取班级详情 |\n| `/api/classes/{id}` | PUT | 更新班级 |\n| `/api/classes/{id}` | DELETE | 删除班级 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n**嵌套结构（教学目标分类）：**\n```\n{% for goal_type in ['知识目标', '能力目标', '素质目标'] %}\n{{ goal_type }}：\n{% for goal in teaching_goals[goal_type] %}\n- {{ goal }}\n{% endfor %}\n\n{% endfor %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n7. 导出为 Word 文档\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n### 6. 批量生成教案 📦\n\n批量生成功能可以一次性创建整学期的所有教案：\n\n#### 步骤 1: 填写课程信息\n- **课程名称**: 如 \"Java程序设计\"\n- **学科/年级**: 选择对应的学科和年级\n- **总课时数**: 如 64 课时（自动计算教案数量）\n- **每份教案课时**: 默认 2 课时（可调整）\n- **章节来源**:\n - **AI 自动生成**: AI 根据课程信息自动拆分章节\n - **手动输入**: 每行输入一个章节标题\n - **使用已有模板**: 复用历史章节配置\n\n#### 步骤 2: 确认章节\n- 查看 AI 生成的章节列表\n- 可直接在表格中编辑课题和内容概述\n- 确认教案模板是否已选择\n\n#### 步骤 3: 监控生成进度\n- 后台自动生成所有教案\n- 实时显示进度条（已完成/总数）\n- 完成后可前往下载页面获取 ZIP 文件\n\n#### 使用已有模板\n如果之前生成过相同课程，可选择\"使用已有模板\"：\n- 自动加载历史章节配置\n- 一键复用，节省时间\n- 模板使用次数会自动记录\n\n#### 下载说明\n- 所有教案打包为 ZIP 文件\n- 文件命名: `课程名称_批量教案_时间戳.zip`\n- 内部文档: `课程名称_01.docx`, `课程名称_02.docx` ...\n- 每个文档包含配置数量的教案\n\n### 7. 班级管理\n\n1. 进入**班级管理**页面\n2. 点击**添加新班级**\n3. 填写班级信息（名称、学科、年级、学生人数等）\n4. 保存后可在生成教案时选择班级\n5. 支持编辑和删除班级\n\n## ❓ 常见问题\n\n### OnlyOffice 集成\n\n**Q: 打开模板编辑器提示“OnlyOffice Document Server URL not configured”？**\n\nA: 确认后端环境变量已设置且进程重启：\n```env\nONLYOFFICE_DOCS_URL=https://your-onlyoffice-domain # 例如 https://only.linnera.link\nONLYOFFICE_JWT_SECRET=your-jwt-secret # 文档安全令牌\nPUBLIC_BASE_URL=https://your-frontend-domain # 例如 https://ls.linnera.link\n```\nDocker 模式修改 `.env` 后需 `docker-compose up -d --build` 重新构建。\n\n**Q: OnlyOffice 提示“文档安全令牌格式不正确”或 JWT 校验失败？**\n\nA: 文档服务器与后端的密钥必须一致，且 Document Server 开启了 JWT 验证。\n1. 确认 `.env` 的 `ONLYOFFICE_JWT_SECRET` 与 Document Server `/etc/onlyoffice/documentserver/local.json` 中的 `services.CoAuthoring.secret` 相同。\n2. 重启 Document Server（或其容器）和后端。\n3. 浏览器清除缓存后重试。\n\n**Q: 控制台报 `inspector.js ... responseType 'arraybuffer'`？**\n\nA: 升级到最新代码并确保 Document Server 使用新的静态版本号（当前为 `20260121-fix8`）。后端会在加载脚本时追加该版本号，Document Server Nginx 需将 `$cache_tag` 设为相同值并为 `inspector.js` 提供占位文件以避免调试脚本拦截。更新后重新部署 Docker 后端与前端。\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: 为什么 storage/templates/ 中的模板不显示？**\n\nA: 后端会在启动时自动扫描 `storage/templates/` 文件夹并导入新模板：\n- 只需将 `.docx` 文件放入该文件夹\n- 重启后端服务即可自动导入\n- 已导入的模板不会重复导入\n\n**Q: 如何手动导入现有模板？**\n\nA: 运行导入脚本：\n```bash\npython import_templates.py\n```\n这会扫描 `storage/templates/` 文件夹并导入所有未在数据库中的模板。\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n**Q: 模板编辑器中 Jinja2 语法不显示？**\n\nA: 确保 Jinja2 语法使用正确格式：\n- 变量: `{{ variable_name }}`\n- 循环: `{% for item in items %}...{% endfor %}`\n- 条件: `{% if condition %}...{% endif %}`\n\n### 批量生成相关\n\n**Q: 批量生成需要多长时间？**\n\nA: 取决于教案数量和 AI 响应速度：\n- 单份教案约 10-30 秒\n- 32 份教案约 5-15 分钟\n- 建议使用章节缓存功能加速\n\n**Q: 批量生成失败怎么办？**\n\nA: 系统会记录失败数量，已生成的教案不会丢失：\n- 查看错误信息了解原因\n- 检查 API 密钥是否有效\n- 可以重新创建任务\n\n**Q: 如何修改已缓存的章节模板？**\n\nA: 目前不支持直接修改，可以：\n- 创建新任务时手动调整章节\n- 或联系管理员删除缓存后重新生成\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# 运行特定类别的测试\npytest -m unit # 仅运行单元测试（快速）\npytest -m integration # 仅运行集成测试\npytest -m api # 仅运行 API 测试\npytest -m service # 仅运行服务层测试\npytest -m \"not slow\" # 跳过慢速测试\npytest -m \"not ai\" # 跳过需要 AI API 密钥的测试\npytest -m smoke # 快速冒烟测试\n\n# 带覆盖率报告的测试\npytest --cov=backend --cov-report=html\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n### 测试标记\n\n项目使用 pytest 标记来分类测试：\n- `unit` - 单元测试（快速、隔离）\n- `integration` - 集成测试（较慢、可能使用外部服务）\n- `slow` - 慢速测试（数据库、文件 I/O、AI 调用）\n- `api` - API 端点测试\n- `service` - 服务层测试\n- `database` - 数据库操作测试\n- `ai` - 调用 AI 提供商的测试（需要 API 密钥）\n- `smoke` - 快速冒烟测试\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 📝 更新日志\n\n### v1.0.0 (最新)\n- ✨ 新增批量生成功能 - 按课时数批量生成整学期教案\n- ✨ 新增章节缓存系统 - 支持快速复用历史章节配置\n- ✨ 新增可视化模板编辑器 - TipTap 富文本编辑器\n- ✨ 新增版本历史管理 - 支持版本对比和回滚\n- ✨ 新增班级管理功能 - 管理授课班级信息\n- ✨ 新增 Docker 部署支持 - 一键部署完整应用栈\n- 🔧 优化 Word 导出 - 使用 `docxtpl` 完美保留格式\n- 🔧 添加跨平台管理脚本 - Windows .bat 和 Linux .sh\n- 🔧 多 AI 提供商支持 - DeepSeek 和 Anthropic Claude\n- 🔧 后台任务处理 - 支持优雅关闭和进度追踪\n- 🧪 完善测试基础设施 - Pytest 配置和测试标记\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n[⬆ 返回顶部](#智能教案助手-intelligent-lesson-plan-assistant)\n\n
\n"}, "be9d23cde6f3ed859c84cb8db800bcae60ff37c0": {"t": 1785766254.779964, "n": 19811, "h": "a2618ee3f6a267fb", "c": "# 智能教案助手 (Intelligent Lesson Plan Assistant)\n\n\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成、批量生产和在线编辑功能。\n\n[](https://www.python.org/)\n[](https://nodejs.org/)\n[](LICENSE)\n[](https://github.com/18287452845/lesson-tools)\n\n[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用指南](#-使用指南) • [API文档](#-api-文档) • [常见问题](#-常见问题)\n\n
\n\n---\n\n## 📸 功能预览\n\n| 模板管理 | 批量生成 | 可视化编辑 |\n|:---:|:---:|:---:|\n| 上传和管理 Word 模板 | 一键生成整学期教案 | TipTap 富文本编辑器 |\n\n## 简介\n\n智能教案助手是一款专为教育工作者设计的全栈 Web 应用，通过人工智能技术大幅简化教案创建流程。无论是单份教案还是整学期批量生成，都能在几分钟内完成专业质量的教案文档。\n\n**核心优势：**\n- 🚀 **高效** - 批量生成整学期教案，节省 90% 时间\n- 🎨 **专业** - 完美保留 Word 格式，符合学校规范\n- 🔄 **灵活** - 可视化模板编辑，自定义教案结构\n- 💾 **智能** - AI 优化内容，自动扩展重写\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **📦 批量生成** - 按课时数批量生成整学期教案，支持章节缓存\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n- **📚 教材章节层级** - 默认支持教材-章节-小节三层结构\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n### 批量生成特性\n- **课时数驱动** - 输入总课时（如64、72），自动计算教案数量\n- **灵活分组** - 可配置每份教案课时数（默认2课时/教案）\n- **章节缓存** - 生成的章节模板自动缓存，支持快速复用\n- **多种输入方式** - AI自动生成章节或手动输入章节标题\n- **实时进度** - 后台生成，实时查看进度和状态\n- **ZIP打包** - 所有教案自动打包下载，文件命名清晰\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 管理脚本（便捷启动/停止）\n\n项目提供了跨平台的管理脚本来简化启动和停止操作：\n\n**Windows:**\n```batch\n# 启动前后端服务\nstart.bat\n\n# 查看服务状态\nstatus.bat\n\n# 停止服务\nstop.bat\n```\n\n**Linux/Mac:**\n```bash\n# 启动前后端服务\n./start.sh\n\n# 查看服务状态\n./status.sh\n\n# 停止服务\n./stop.sh\n```\n\n**脚本功能：**\n- `start.bat/sh` - 后台启动前后端服务，日志保存在 `logs/` 目录\n- `status.bat/sh` - 查看服务运行状态和端口监听情况\n- `stop.bat/sh` - 停止所有服务并清理遗留进程\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n### 方式四：Docker 部署（推荐用于生产环境）\n\n使用 Docker Compose 可以快速部署整个应用，无需手动配置 Python 和 Node.js 环境。\n\n```bash\n# 1. 配置环境变量\ncp .env.example .env\n# 编辑 .env 文件，填入您的 API Key\n\n# 2. 构建并启动服务\ndocker-compose up -d --build\n\n# 3. 查看运行状态\ndocker-compose ps\n\n# 4. 查看日志\ndocker-compose logs -f\n\n# 5. 停止服务\ndocker-compose down\n```\n\n**访问地址：**\n- 前端界面：http://localhost:8081\n- 后端 API：http://localhost:8001\n- API 文档：http://localhost:8001/docs\n\n**数据持久化：** `storage/` 目录中的数据会自动挂载并持久化保存。\n\n详细的 Docker 部署说明请参考 `DOCKER_DEPLOYMENT.md`。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── lesson_plans.py # 教案检索管理 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ ├── settings.py # 设置管理 API\n│ │ ├── batch.py # 批量生成 API 📦\n│ │ └── classes.py # 班级管理 API\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── template_sync.py # 模板自动同步服务\n│ │ ├── template_versioning.py # 版本历史管理\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── document_modifier.py # 文档修改服务\n│ │ ├── lesson_plan_service.py # 教案业务逻辑\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ ├── chapter_splitter.py # 课程章节拆分服务 📦\n│ │ ├── batch_processor.py # 批量生成处理器 📦\n│ │ └── background_runner.py # 后台任务运行器 📦\n│ ├── tests/ # 后端测试\n│ │ ├── conftest.py # Pytest 配置和 Fixtures\n│ │ ├── test_api_templates.py # 模板 API 测试\n│ │ ├── test_api_batch.py # 批量 API 测试\n│ │ ├── test_database.py # 数据库测试\n│ │ └── ... # 其他测试文件\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── LessonPlanDetail.tsx # 教案详情\n│ │ ├── History.tsx # 历史记录\n│ │ ├── BatchGenerate.tsx # 批量生成 📦\n│ │ ├── BatchDownloads.tsx # 批量下载 📦\n│ │ ├── BatchTaskDetail.tsx # 批量任务详情 📦\n│ │ ├── CachedLessonPlans.tsx # 缓存章节模板 📦\n│ │ ├── ClassManager.tsx # 班级管理\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ ├── batchApi.ts # 批量生成 API 客户端 📦\n│ │ ├── settingsApi.ts # 设置 API\n│ │ └── fileService.ts # 文件下载服务\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ ├── editorStore.ts # 编辑器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── test-data/ # 测试数据\n│ └── mock-responses.json # Mock AI 响应\n│\n├── test-results/ # 测试结果输出\n│ └── screenshots/ # E2E 测试截图\n│\n├── logs/ # 服务日志（自动创建）\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── pytest.ini # Pytest 配置\n├── start.bat / start.sh # 启动前后端服务（Windows/Linux）\n├── status.bat / status.sh # 查看服务状态\n├── stop.bat / stop.sh # 停止服务\n├── .env # 环境变量配置（需创建）\n├── .gitignore # Git 忽略规则\n├── CLAUDE.md # Claude Code 项目说明\n├── WORD_EXPORT_FIX.md # Word 导出技术说明\n├── REALTIME_GENERATION_FEATURE.md # 实时生成功能说明\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/stream` | POST | SSE 流式生成 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n| `/api/generate` | GET | 获取教案列表 |\n| `/api/generate/{id}` | GET | 获取教案详情 |\n| `/api/generate/{id}` | DELETE | 删除教案 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/upload` | POST | 上传现有文档 |\n| `/api/edit/{id}` | GET | 获取文档详情 |\n| `/api/edit/{id}/section` | POST | 编辑特定章节 |\n| `/api/edit/{id}/ai-enhance` | POST | AI 增强内容 |\n| `/api/edit/{id}/add-section` | POST | 添加缺失章节 |\n| `/api/edit/{id}/save` | POST | 保存并下载 |\n| `/api/edit/{id}/undo` | POST | 撤销编辑 |\n| `/api/edit/{id}/history` | GET | 获取编辑历史 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n| `/api/settings/app-info` | GET | 获取应用信息 |\n\n#### 批量生成 📦\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/batch/split-chapters` | POST | 根据总课时拆分章节 |\n| `/api/batch/split-chapters-stream` | POST | SSE 流式章节拆分 |\n| `/api/batch/create-task` | POST | 创建批量生成任务 |\n| `/api/batch/tasks/{id}` | GET | 获取任务状态和进度 |\n| `/api/batch/tasks` | GET | 获取批量任务列表 |\n| `/api/batch/tasks/{id}/download` | GET | 下载生成的 ZIP 文件 |\n| `/api/batch/tasks/{id}` | DELETE | 取消或删除任务 |\n| `/api/batch/chapter-templates` | GET | 获取缓存的章节模板列表 |\n\n#### 班级管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/classes` | GET/POST | 获取/创建班级 |\n| `/api/classes/{id}` | GET | 获取班级详情 |\n| `/api/classes/{id}` | PUT | 更新班级 |\n| `/api/classes/{id}` | DELETE | 删除班级 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n**嵌套结构（教学目标分类）：**\n```\n{% for goal_type in ['知识目标', '能力目标', '素质目标'] %}\n{{ goal_type }}：\n{% for goal in teaching_goals[goal_type] %}\n- {{ goal }}\n{% endfor %}\n\n{% endfor %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n7. 导出为 Word 文档\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n### 6. 批量生成教案 📦\n\n批量生成功能可以一次性创建整学期的所有教案：\n\n#### 步骤 1: 填写课程信息\n- **课程名称**: 如 \"Java程序设计\"\n- **学科/年级**: 选择对应的学科和年级\n- **总课时数**: 如 64 课时（自动计算教案数量）\n- **每份教案课时**: 默认 2 课时（可调整）\n- **章节来源**:\n - **AI 自动生成**: AI 根据课程信息自动拆分章节\n - **手动输入**: 每行输入一个章节标题\n - **使用已有模板**: 复用历史章节配置\n\n#### 步骤 2: 确认章节\n- 查看 AI 生成的章节列表\n- 可直接在表格中编辑课题和内容概述\n- 确认教案模板是否已选择\n\n#### 步骤 3: 监控生成进度\n- 后台自动生成所有教案\n- 实时显示进度条（已完成/总数）\n- 完成后可前往下载页面获取 ZIP 文件\n\n#### 使用已有模板\n如果之前生成过相同课程，可选择\"使用已有模板\"：\n- 自动加载历史章节配置\n- 一键复用，节省时间\n- 模板使用次数会自动记录\n\n#### 下载说明\n- 所有教案打包为 ZIP 文件\n- 文件命名: `课程名称_批量教案_时间戳.zip`\n- 内部文档: `课程名称_01.docx`, `课程名称_02.docx` ...\n- 每个文档包含配置数量的教案\n\n### 7. 班级管理\n\n1. 进入**班级管理**页面\n2. 点击**添加新班级**\n3. 填写班级信息（名称、学科、年级、学生人数等）\n4. 保存后可在生成教案时选择班级\n5. 支持编辑和删除班级\n\n## ❓ 常见问题\n\n### OnlyOffice 集成\n\n**Q: 打开模板编辑器提示“OnlyOffice Document Server URL not configured”？**\n\nA: 确认后端环境变量已设置且进程重启：\n```env\nONLYOFFICE_DOCS_URL=https://your-onlyoffice-domain # 例如 https://only.linnera.link\nONLYOFFICE_JWT_SECRET=your-jwt-secret # 文档安全令牌\nPUBLIC_BASE_URL=https://your-frontend-domain # 例如 https://ls.linnera.link\n```\nDocker 模式修改 `.env` 后需 `docker-compose up -d --build` 重新构建。\n\n**Q: OnlyOffice 提示“文档安全令牌格式不正确”或 JWT 校验失败？**\n\nA: 文档服务器与后端的密钥必须一致，且 Document Server 开启了 JWT 验证。\n1. 确认 `.env` 的 `ONLYOFFICE_JWT_SECRET` 与 Document Server `/etc/onlyoffice/documentserver/local.json` 中的 `services.CoAuthoring.secret` 相同。\n2. 重启 Document Server（或其容器）和后端。\n3. 浏览器清除缓存后重试。\n\n**Q: 控制台报 `inspector.js ... responseType 'arraybuffer'`？**\n\nA: 升级到最新代码并确保 Document Server 使用新的静态版本号（当前为 `20260121-fix8`）。后端会在加载脚本时追加该版本号，Document Server Nginx 需将 `$cache_tag` 设为相同值并为 `inspector.js` 提供占位文件以避免调试脚本拦截。更新后重新部署 Docker 后端与前端。\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: 为什么 storage/templates/ 中的模板不显示？**\n\nA: 后端会在启动时自动扫描 `storage/templates/` 文件夹并导入新模板：\n- 只需将 `.docx` 文件放入该文件夹\n- 重启后端服务即可自动导入\n- 已导入的模板不会重复导入\n\n**Q: 如何手动导入现有模板？**\n\nA: 运行导入脚本：\n```bash\npython import_templates.py\n```\n这会扫描 `storage/templates/` 文件夹并导入所有未在数据库中的模板。\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n**Q: 模板编辑器中 Jinja2 语法不显示？**\n\nA: 确保 Jinja2 语法使用正确格式：\n- 变量: `{{ variable_name }}`\n- 循环: `{% for item in items %}...{% endfor %}`\n- 条件: `{% if condition %}...{% endif %}`\n\n### 批量生成相关\n\n**Q: 批量生成需要多长时间？**\n\nA: 取决于教案数量和 AI 响应速度：\n- 单份教案约 10-30 秒\n- 32 份教案约 5-15 分钟\n- 建议使用章节缓存功能加速\n\n**Q: 批量生成失败怎么办？**\n\nA: 系统会记录失败数量，已生成的教案不会丢失：\n- 查看错误信息了解原因\n- 检查 API 密钥是否有效\n- 可以重新创建任务\n\n**Q: 如何修改已缓存的章节模板？**\n\nA: 目前不支持直接修改，可以：\n- 创建新任务时手动调整章节\n- 或联系管理员删除缓存后重新生成\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# 运行特定类别的测试\npytest -m unit # 仅运行单元测试（快速）\npytest -m integration # 仅运行集成测试\npytest -m api # 仅运行 API 测试\npytest -m service # 仅运行服务层测试\npytest -m \"not slow\" # 跳过慢速测试\npytest -m \"not ai\" # 跳过需要 AI API 密钥的测试\npytest -m smoke # 快速冒烟测试\n\n# 带覆盖率报告的测试\npytest --cov=backend --cov-report=html\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n### 测试标记\n\n项目使用 pytest 标记来分类测试：\n- `unit` - 单元测试（快速、隔离）\n- `integration` - 集成测试（较慢、可能使用外部服务）\n- `slow` - 慢速测试（数据库、文件 I/O、AI 调用）\n- `api` - API 端点测试\n- `service` - 服务层测试\n- `database` - 数据库操作测试\n- `ai` - 调用 AI 提供商的测试（需要 API 密钥）\n- `smoke` - 快速冒烟测试\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 📝 更新日志\n\n### v1.0.0 (最新)\n- ✨ 新增批量生成功能 - 按课时数批量生成整学期教案\n- ✨ 新增章节缓存系统 - 支持快速复用历史章节配置\n- ✨ 新增可视化模板编辑器 - TipTap 富文本编辑器\n- ✨ 新增版本历史管理 - 支持版本对比和回滚\n- ✨ 新增班级管理功能 - 管理授课班级信息\n- ✨ 新增 Docker 部署支持 - 一键部署完整应用栈\n- 🔧 优化 Word 导出 - 使用 `docxtpl` 完美保留格式\n- 🔧 添加跨平台管理脚本 - Windows .bat 和 Linux .sh\n- 🔧 多 AI 提供商支持 - DeepSeek 和 Anthropic Claude\n- 🔧 后台任务处理 - 支持优雅关闭和进度追踪\n- 🧪 完善测试基础设施 - Pytest 配置和测试标记\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n[⬆ 返回顶部](#智能教案助手-intelligent-lesson-plan-assistant)\n\n
\n"}, "35772dbf4eb0135f20889314929c2a790b7667b6": {"t": 1785766256.47526, "n": 18854, "h": "f1fe73418cc4eb40", "c": "# 智能教案助手 (Intelligent Lesson Plan Assistant)\n\n\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成、批量生产和在线编辑功能。\n\n[](https://www.python.org/)\n[](https://nodejs.org/)\n[](LICENSE)\n[](https://github.com/18287452845/lesson-tools)\n\n[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用指南](#-使用指南) • [API文档](#-api-文档) • [常见问题](#-常见问题)\n\n
\n\n---\n\n## 📸 功能预览\n\n| 模板管理 | 批量生成 | 可视化编辑 |\n|:---:|:---:|:---:|\n| 上传和管理 Word 模板 | 一键生成整学期教案 | TipTap 富文本编辑器 |\n\n## 简介\n\n智能教案助手是一款专为教育工作者设计的全栈 Web 应用，通过人工智能技术大幅简化教案创建流程。无论是单份教案还是整学期批量生成，都能在几分钟内完成专业质量的教案文档。\n\n**核心优势：**\n- 🚀 **高效** - 批量生成整学期教案，节省 90% 时间\n- 🎨 **专业** - 完美保留 Word 格式，符合学校规范\n- 🔄 **灵活** - 可视化模板编辑，自定义教案结构\n- 💾 **智能** - AI 优化内容，自动扩展重写\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **📦 批量生成** - 按课时数批量生成整学期教案，支持章节缓存\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n### 批量生成特性\n- **课时数驱动** - 输入总课时（如64、72），自动计算教案数量\n- **灵活分组** - 可配置每份教案课时数（默认2课时/教案）\n- **章节缓存** - 生成的章节模板自动缓存，支持快速复用\n- **多种输入方式** - AI自动生成章节或手动输入章节标题\n- **实时进度** - 后台生成，实时查看进度和状态\n- **ZIP打包** - 所有教案自动打包下载，文件命名清晰\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 管理脚本（便捷启动/停止）\n\n项目提供了跨平台的管理脚本来简化启动和停止操作：\n\n**Windows:**\n```batch\n# 启动前后端服务\nstart.bat\n\n# 查看服务状态\nstatus.bat\n\n# 停止服务\nstop.bat\n```\n\n**Linux/Mac:**\n```bash\n# 启动前后端服务\n./start.sh\n\n# 查看服务状态\n./status.sh\n\n# 停止服务\n./stop.sh\n```\n\n**脚本功能：**\n- `start.bat/sh` - 后台启动前后端服务，日志保存在 `logs/` 目录\n- `status.bat/sh` - 查看服务运行状态和端口监听情况\n- `stop.bat/sh` - 停止所有服务并清理遗留进程\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n### 方式四：Docker 部署（推荐用于生产环境）\n\n使用 Docker Compose 可以快速部署整个应用，无需手动配置 Python 和 Node.js 环境。\n\n```bash\n# 1. 配置环境变量\ncp .env.example .env\n# 编辑 .env 文件，填入您的 API Key\n\n# 2. 构建并启动服务\ndocker-compose up -d --build\n\n# 3. 查看运行状态\ndocker-compose ps\n\n# 4. 查看日志\ndocker-compose logs -f\n\n# 5. 停止服务\ndocker-compose down\n```\n\n**访问地址：**\n- 前端界面：http://localhost:8081\n- 后端 API：http://localhost:8001\n- API 文档：http://localhost:8001/docs\n\n**数据持久化：** `storage/` 目录中的数据会自动挂载并持久化保存。\n\n详细的 Docker 部署说明请参考 `DOCKER_DEPLOYMENT.md`。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── lesson_plans.py # 教案检索管理 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ ├── settings.py # 设置管理 API\n│ │ ├── batch.py # 批量生成 API 📦\n│ │ └── classes.py # 班级管理 API\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── template_sync.py # 模板自动同步服务\n│ │ ├── template_versioning.py # 版本历史管理\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── document_modifier.py # 文档修改服务\n│ │ ├── lesson_plan_service.py # 教案业务逻辑\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ ├── chapter_splitter.py # 课程章节拆分服务 📦\n│ │ ├── batch_processor.py # 批量生成处理器 📦\n│ │ └── background_runner.py # 后台任务运行器 📦\n│ ├── tests/ # 后端测试\n│ │ ├── conftest.py # Pytest 配置和 Fixtures\n│ │ ├── test_api_templates.py # 模板 API 测试\n│ │ ├── test_api_batch.py # 批量 API 测试\n│ │ ├── test_database.py # 数据库测试\n│ │ └── ... # 其他测试文件\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── LessonPlanDetail.tsx # 教案详情\n│ │ ├── History.tsx # 历史记录\n│ │ ├── BatchGenerate.tsx # 批量生成 📦\n│ │ ├── BatchDownloads.tsx # 批量下载 📦\n│ │ ├── BatchTaskDetail.tsx # 批量任务详情 📦\n│ │ ├── CachedLessonPlans.tsx # 缓存章节模板 📦\n│ │ ├── ClassManager.tsx # 班级管理\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ ├── batchApi.ts # 批量生成 API 客户端 📦\n│ │ ├── settingsApi.ts # 设置 API\n│ │ └── fileService.ts # 文件下载服务\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ ├── editorStore.ts # 编辑器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── test-data/ # 测试数据\n│ └── mock-responses.json # Mock AI 响应\n│\n├── test-results/ # 测试结果输出\n│ └── screenshots/ # E2E 测试截图\n│\n├── logs/ # 服务日志（自动创建）\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── pytest.ini # Pytest 配置\n├── start.bat / start.sh # 启动前后端服务（Windows/Linux）\n├── status.bat / status.sh # 查看服务状态\n├── stop.bat / stop.sh # 停止服务\n├── .env # 环境变量配置（需创建）\n├── .gitignore # Git 忽略规则\n├── CLAUDE.md # Claude Code 项目说明\n├── WORD_EXPORT_FIX.md # Word 导出技术说明\n├── REALTIME_GENERATION_FEATURE.md # 实时生成功能说明\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/stream` | POST | SSE 流式生成 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n| `/api/generate` | GET | 获取教案列表 |\n| `/api/generate/{id}` | GET | 获取教案详情 |\n| `/api/generate/{id}` | DELETE | 删除教案 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/upload` | POST | 上传现有文档 |\n| `/api/edit/{id}` | GET | 获取文档详情 |\n| `/api/edit/{id}/section` | POST | 编辑特定章节 |\n| `/api/edit/{id}/ai-enhance` | POST | AI 增强内容 |\n| `/api/edit/{id}/add-section` | POST | 添加缺失章节 |\n| `/api/edit/{id}/save` | POST | 保存并下载 |\n| `/api/edit/{id}/undo` | POST | 撤销编辑 |\n| `/api/edit/{id}/history` | GET | 获取编辑历史 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n| `/api/settings/app-info` | GET | 获取应用信息 |\n\n#### 批量生成 📦\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/batch/split-chapters` | POST | 根据总课时拆分章节 |\n| `/api/batch/split-chapters-stream` | POST | SSE 流式章节拆分 |\n| `/api/batch/create-task` | POST | 创建批量生成任务 |\n| `/api/batch/tasks/{id}` | GET | 获取任务状态和进度 |\n| `/api/batch/tasks` | GET | 获取批量任务列表 |\n| `/api/batch/tasks/{id}/download` | GET | 下载生成的 ZIP 文件 |\n| `/api/batch/tasks/{id}` | DELETE | 取消或删除任务 |\n| `/api/batch/chapter-templates` | GET | 获取缓存的章节模板列表 |\n\n#### 班级管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/classes` | GET/POST | 获取/创建班级 |\n| `/api/classes/{id}` | GET | 获取班级详情 |\n| `/api/classes/{id}` | PUT | 更新班级 |\n| `/api/classes/{id}` | DELETE | 删除班级 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n**嵌套结构（教学目标分类）：**\n```\n{% for goal_type in ['知识目标', '能力目标', '素质目标'] %}\n{{ goal_type }}：\n{% for goal in teaching_goals[goal_type] %}\n- {{ goal }}\n{% endfor %}\n\n{% endfor %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n7. 导出为 Word 文档\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n### 6. 批量生成教案 📦\n\n批量生成功能可以一次性创建整学期的所有教案：\n\n#### 步骤 1: 填写课程信息\n- **课程名称**: 如 \"Java程序设计\"\n- **学科/年级**: 选择对应的学科和年级\n- **总课时数**: 如 64 课时（自动计算教案数量）\n- **每份教案课时**: 默认 2 课时（可调整）\n- **章节来源**:\n - **AI 自动生成**: AI 根据课程信息自动拆分章节\n - **手动输入**: 每行输入一个章节标题\n - **使用已有模板**: 复用历史章节配置\n\n#### 步骤 2: 确认章节\n- 查看 AI 生成的章节列表\n- 可直接在表格中编辑课题和内容概述\n- 确认教案模板是否已选择\n\n#### 步骤 3: 监控生成进度\n- 后台自动生成所有教案\n- 实时显示进度条（已完成/总数）\n- 完成后可前往下载页面获取 ZIP 文件\n\n#### 使用已有模板\n如果之前生成过相同课程，可选择\"使用已有模板\"：\n- 自动加载历史章节配置\n- 一键复用，节省时间\n- 模板使用次数会自动记录\n\n#### 下载说明\n- 所有教案打包为 ZIP 文件\n- 文件命名: `课程名称_批量教案_时间戳.zip`\n- 内部文档: `课程名称_01.docx`, `课程名称_02.docx` ...\n- 每个文档包含配置数量的教案\n\n### 7. 班级管理\n\n1. 进入**班级管理**页面\n2. 点击**添加新班级**\n3. 填写班级信息（名称、学科、年级、学生人数等）\n4. 保存后可在生成教案时选择班级\n5. 支持编辑和删除班级\n\n## ❓ 常见问题\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: 为什么 storage/templates/ 中的模板不显示？**\n\nA: 后端会在启动时自动扫描 `storage/templates/` 文件夹并导入新模板：\n- 只需将 `.docx` 文件放入该文件夹\n- 重启后端服务即可自动导入\n- 已导入的模板不会重复导入\n\n**Q: 如何手动导入现有模板？**\n\nA: 运行导入脚本：\n```bash\npython import_templates.py\n```\n这会扫描 `storage/templates/` 文件夹并导入所有未在数据库中的模板。\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n**Q: 模板编辑器中 Jinja2 语法不显示？**\n\nA: 确保 Jinja2 语法使用正确格式：\n- 变量: `{{ variable_name }}`\n- 循环: `{% for item in items %}...{% endfor %}`\n- 条件: `{% if condition %}...{% endif %}`\n\n### 批量生成相关\n\n**Q: 批量生成需要多长时间？**\n\nA: 取决于教案数量和 AI 响应速度：\n- 单份教案约 10-30 秒\n- 32 份教案约 5-15 分钟\n- 建议使用章节缓存功能加速\n\n**Q: 批量生成失败怎么办？**\n\nA: 系统会记录失败数量，已生成的教案不会丢失：\n- 查看错误信息了解原因\n- 检查 API 密钥是否有效\n- 可以重新创建任务\n\n**Q: 如何修改已缓存的章节模板？**\n\nA: 目前不支持直接修改，可以：\n- 创建新任务时手动调整章节\n- 或联系管理员删除缓存后重新生成\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# 运行特定类别的测试\npytest -m unit # 仅运行单元测试（快速）\npytest -m integration # 仅运行集成测试\npytest -m api # 仅运行 API 测试\npytest -m service # 仅运行服务层测试\npytest -m \"not slow\" # 跳过慢速测试\npytest -m \"not ai\" # 跳过需要 AI API 密钥的测试\npytest -m smoke # 快速冒烟测试\n\n# 带覆盖率报告的测试\npytest --cov=backend --cov-report=html\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n### 测试标记\n\n项目使用 pytest 标记来分类测试：\n- `unit` - 单元测试（快速、隔离）\n- `integration` - 集成测试（较慢、可能使用外部服务）\n- `slow` - 慢速测试（数据库、文件 I/O、AI 调用）\n- `api` - API 端点测试\n- `service` - 服务层测试\n- `database` - 数据库操作测试\n- `ai` - 调用 AI 提供商的测试（需要 API 密钥）\n- `smoke` - 快速冒烟测试\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 📝 更新日志\n\n### v1.0.0 (最新)\n- ✨ 新增批量生成功能 - 按课时数批量生成整学期教案\n- ✨ 新增章节缓存系统 - 支持快速复用历史章节配置\n- ✨ 新增可视化模板编辑器 - TipTap 富文本编辑器\n- ✨ 新增版本历史管理 - 支持版本对比和回滚\n- ✨ 新增班级管理功能 - 管理授课班级信息\n- ✨ 新增 Docker 部署支持 - 一键部署完整应用栈\n- 🔧 优化 Word 导出 - 使用 `docxtpl` 完美保留格式\n- 🔧 添加跨平台管理脚本 - Windows .bat 和 Linux .sh\n- 🔧 多 AI 提供商支持 - DeepSeek 和 Anthropic Claude\n- 🔧 后台任务处理 - 支持优雅关闭和进度追踪\n- 🧪 完善测试基础设施 - Pytest 配置和测试标记\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n[⬆ 返回顶部](#智能教案助手-intelligent-lesson-plan-assistant)\n\n
\n"}, "27a02cf35be471e7f1a5ce15894072aa2664db8a": {"t": 1785766260.0265267, "n": 17839, "h": "ad57892897e476e3", "c": "# 智能教案助手 (Intelligent Lesson Plan Assistant)\n\n\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成、批量生产和在线编辑功能。\n\n[](https://www.python.org/)\n[](https://nodejs.org/)\n[](LICENSE)\n[](https://github.com/18287452845/lesson-tools)\n\n[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用指南](#-使用指南) • [API文档](#-api-文档) • [常见问题](#-常见问题)\n\n
\n\n---\n\n## 📸 功能预览\n\n| 模板管理 | 批量生成 | 可视化编辑 |\n|:---:|:---:|:---:|\n| 上传和管理 Word 模板 | 一键生成整学期教案 | TipTap 富文本编辑器 |\n\n## 简介\n\n智能教案助手是一款专为教育工作者设计的全栈 Web 应用，通过人工智能技术大幅简化教案创建流程。无论是单份教案还是整学期批量生成，都能在几分钟内完成专业质量的教案文档。\n\n**核心优势：**\n- 🚀 **高效** - 批量生成整学期教案，节省 90% 时间\n- 🎨 **专业** - 完美保留 Word 格式，符合学校规范\n- 🔄 **灵活** - 可视化模板编辑，自定义教案结构\n- 💾 **智能** - AI 优化内容，自动扩展重写\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **📦 批量生成** - 按课时数批量生成整学期教案，支持章节缓存\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n### 批量生成特性\n- **课时数驱动** - 输入总课时（如64、72），自动计算教案数量\n- **灵活分组** - 可配置每份教案课时数（默认2课时/教案）\n- **章节缓存** - 生成的章节模板自动缓存，支持快速复用\n- **多种输入方式** - AI自动生成章节或手动输入章节标题\n- **实时进度** - 后台生成，实时查看进度和状态\n- **ZIP打包** - 所有教案自动打包下载，文件命名清晰\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 管理脚本（便捷启动/停止）\n\n项目提供了跨平台的管理脚本来简化启动和停止操作：\n\n**Windows:**\n```batch\n# 启动前后端服务\nstart.bat\n\n# 查看服务状态\nstatus.bat\n\n# 停止服务\nstop.bat\n```\n\n**Linux/Mac:**\n```bash\n# 启动前后端服务\n./start.sh\n\n# 查看服务状态\n./status.sh\n\n# 停止服务\n./stop.sh\n```\n\n**脚本功能：**\n- `start.bat/sh` - 后台启动前后端服务，日志保存在 `logs/` 目录\n- `status.bat/sh` - 查看服务运行状态和端口监听情况\n- `stop.bat/sh` - 停止所有服务并清理遗留进程\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ ├── settings.py # 设置管理 API\n│ │ └── batch.py # 批量生成 API 📦\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ ├── template_versioning.py # 版本历史管理\n│ │ ├── chapter_splitter.py # 课程章节拆分服务 📦\n│ │ ├── batch_processor.py # 批量生成处理器 📦\n│ │ └── background_runner.py # 后台任务运行器 📦\n│ ├── tests/ # 后端测试\n│ │ ├── conftest.py # Pytest 配置和 Fixtures\n│ │ ├── test_api_templates.py # 模板 API 测试\n│ │ ├── test_api_batch.py # 批量 API 测试\n│ │ ├── test_database.py # 数据库测试\n│ │ └── ... # 其他测试文件\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── BatchGenerate.tsx # 批量生成 📦\n│ │ ├── BatchDownloads.tsx # 批量下载 📦\n│ │ ├── History.tsx # 历史记录\n│ │ ├── LessonPlanDetail.tsx # 教案详情\n│ │ ├── ClassManager.tsx # 班级管理\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ ├── batchApi.ts # 批量生成 API 客户端 📦\n│ │ ├── settingsApi.ts # 设置 API\n│ │ └── fileService.ts # 文件下载服务\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ ├── editorStore.ts # 编辑器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── test-data/ # 测试数据\n│ └── mock-responses.json # Mock AI 响应\n│\n├── test-results/ # 测试结果输出\n│ └── screenshots/ # E2E 测试截图\n│\n├── logs/ # 服务日志（自动创建）\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── pytest.ini # Pytest 配置\n├── start.bat / start.sh # 启动前后端服务（Windows/Linux）\n├── status.bat / status.sh # 查看服务状态\n├── stop.bat / stop.sh # 停止服务\n├── .env # 环境变量配置（需创建）\n├── .gitignore # Git 忽略规则\n├── CLAUDE.md # Claude Code 项目说明\n├── WORD_EXPORT_FIX.md # Word 导出技术说明\n├── REALTIME_GENERATION_FEATURE.md # 实时生成功能说明\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/stream` | POST | SSE 流式生成 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n| `/api/generate` | GET | 获取教案列表 |\n| `/api/generate/{id}` | GET | 获取教案详情 |\n| `/api/generate/{id}` | DELETE | 删除教案 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/upload` | POST | 上传现有文档 |\n| `/api/edit/{id}` | GET | 获取文档详情 |\n| `/api/edit/{id}/section` | POST | 编辑特定章节 |\n| `/api/edit/{id}/ai-enhance` | POST | AI 增强内容 |\n| `/api/edit/{id}/add-section` | POST | 添加缺失章节 |\n| `/api/edit/{id}/save` | POST | 保存并下载 |\n| `/api/edit/{id}/undo` | POST | 撤销编辑 |\n| `/api/edit/{id}/history` | GET | 获取编辑历史 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n| `/api/settings/app-info` | GET | 获取应用信息 |\n\n#### 批量生成 📦\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/batch/split-chapters` | POST | 根据总课时拆分章节 |\n| `/api/batch/split-chapters-stream` | POST | SSE 流式章节拆分 |\n| `/api/batch/create-task` | POST | 创建批量生成任务 |\n| `/api/batch/tasks/{id}` | GET | 获取任务状态和进度 |\n| `/api/batch/tasks` | GET | 获取批量任务列表 |\n| `/api/batch/tasks/{id}/download` | GET | 下载生成的 ZIP 文件 |\n| `/api/batch/tasks/{id}` | DELETE | 取消或删除任务 |\n| `/api/batch/chapter-templates` | GET | 获取缓存的章节模板列表 |\n\n#### 班级管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/classes` | GET/POST | 获取/创建班级 |\n| `/api/classes/{id}` | GET | 获取班级详情 |\n| `/api/classes/{id}` | PUT | 更新班级 |\n| `/api/classes/{id}` | DELETE | 删除班级 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n**嵌套结构（教学目标分类）：**\n```\n{% for goal_type in ['知识目标', '能力目标', '素质目标'] %}\n{{ goal_type }}：\n{% for goal in teaching_goals[goal_type] %}\n- {{ goal }}\n{% endfor %}\n\n{% endfor %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n7. 导出为 Word 文档\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n### 6. 批量生成教案 📦\n\n批量生成功能可以一次性创建整学期的所有教案：\n\n#### 步骤 1: 填写课程信息\n- **课程名称**: 如 \"Java程序设计\"\n- **学科/年级**: 选择对应的学科和年级\n- **总课时数**: 如 64 课时（自动计算教案数量）\n- **每份教案课时**: 默认 2 课时（可调整）\n- **章节来源**:\n - **AI 自动生成**: AI 根据课程信息自动拆分章节\n - **手动输入**: 每行输入一个章节标题\n - **使用已有模板**: 复用历史章节配置\n\n#### 步骤 2: 确认章节\n- 查看 AI 生成的章节列表\n- 可直接在表格中编辑课题和内容概述\n- 确认教案模板是否已选择\n\n#### 步骤 3: 监控生成进度\n- 后台自动生成所有教案\n- 实时显示进度条（已完成/总数）\n- 完成后可前往下载页面获取 ZIP 文件\n\n#### 使用已有模板\n如果之前生成过相同课程，可选择\"使用已有模板\"：\n- 自动加载历史章节配置\n- 一键复用，节省时间\n- 模板使用次数会自动记录\n\n#### 下载说明\n- 所有教案打包为 ZIP 文件\n- 文件命名: `课程名称_批量教案_时间戳.zip`\n- 内部文档: `课程名称_01.docx`, `课程名称_02.docx` ...\n- 每个文档包含配置数量的教案\n\n### 7. 班级管理\n\n1. 进入**班级管理**页面\n2. 点击**添加新班级**\n3. 填写班级信息（名称、学科、年级、学生人数等）\n4. 保存后可在生成教案时选择班级\n5. 支持编辑和删除班级\n\n## ❓ 常见问题\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: 为什么 storage/templates/ 中的模板不显示？**\n\nA: 后端会在启动时自动扫描 `storage/templates/` 文件夹并导入新模板：\n- 只需将 `.docx` 文件放入该文件夹\n- 重启后端服务即可自动导入\n- 已导入的模板不会重复导入\n\n**Q: 如何手动导入现有模板？**\n\nA: 运行导入脚本：\n```bash\npython import_templates.py\n```\n这会扫描 `storage/templates/` 文件夹并导入所有未在数据库中的模板。\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n**Q: 模板编辑器中 Jinja2 语法不显示？**\n\nA: 确保 Jinja2 语法使用正确格式：\n- 变量: `{{ variable_name }}`\n- 循环: `{% for item in items %}...{% endfor %}`\n- 条件: `{% if condition %}...{% endif %}`\n\n### 批量生成相关\n\n**Q: 批量生成需要多长时间？**\n\nA: 取决于教案数量和 AI 响应速度：\n- 单份教案约 10-30 秒\n- 32 份教案约 5-15 分钟\n- 建议使用章节缓存功能加速\n\n**Q: 批量生成失败怎么办？**\n\nA: 系统会记录失败数量，已生成的教案不会丢失：\n- 查看错误信息了解原因\n- 检查 API 密钥是否有效\n- 可以重新创建任务\n\n**Q: 如何修改已缓存的章节模板？**\n\nA: 目前不支持直接修改，可以：\n- 创建新任务时手动调整章节\n- 或联系管理员删除缓存后重新生成\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# 带覆盖率报告的测试\npytest --cov=backend --cov-report=html\n\n# 运行特定标记的测试\npytest -m unit # 仅单元测试\npytest -m integration # 仅集成测试\npytest -m api # 仅 API 测试\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n### 测试标记\n\n项目使用 pytest 标记来分类测试：\n- `unit` - 单元测试（快速、隔离）\n- `integration` - 集成测试（较慢、可能使用外部服务）\n- `slow` - 慢速测试（数据库、文件 I/O、AI 调用）\n- `api` - API 端点测试\n- `service` - 服务层测试\n- `database` - 数据库操作测试\n- `ai` - 调用 AI 提供商的测试（需要 API 密钥）\n- `smoke` - 快速冒烟测试\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 📝 更新日志\n\n### v1.0.0 (最新)\n- ✨ 新增批量生成功能 - 按课时数批量生成整学期教案\n- ✨ 新增章节缓存系统 - 支持快速复用历史章节配置\n- ✨ 新增可视化模板编辑器 - TipTap 富文本编辑器\n- ✨ 新增版本历史管理 - 支持版本对比和回滚\n- ✨ 新增班级管理功能 - 管理授课班级信息\n- 🔧 优化 Word 导出 - 使用 `docxtpl` 完美保留格式\n- 🔧 添加跨平台管理脚本 - Windows .bat 和 Linux .sh\n- 🔧 多 AI 提供商支持 - DeepSeek 和 Anthropic Claude\n- 🔧 后台任务处理 - 支持优雅关闭和进度追踪\n- 🧪 完善测试基础设施 - Pytest 配置和测试标记\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n[⬆ 返回顶部](#智能教案助手-intelligent-lesson-plan-assistant)\n\n
\n"}, "869d299d140abd7f6111eca5d4c886ac06f171de": {"t": 1785766263.0102086, "n": 15476, "h": "b28702c61c9a4845", "c": "# 智能教案助手 (Intelligent Lesson Plan Assistant)\n\n\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成、批量生产和在线编辑功能。\n\n[](https://www.python.org/)\n[](https://nodejs.org/)\n[](LICENSE)\n[](https://github.com/18287452845/lesson-tools)\n\n[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用指南](#-使用指南) • [API文档](#-api-文档) • [常见问题](#-常见问题)\n\n
\n\n---\n\n## 📸 功能预览\n\n| 模板管理 | 批量生成 | 可视化编辑 |\n|:---:|:---:|:---:|\n| 上传和管理 Word 模板 | 一键生成整学期教案 | TipTap 富文本编辑器 |\n\n## 简介\n\n智能教案助手是一款专为教育工作者设计的全栈 Web 应用，通过人工智能技术大幅简化教案创建流程。无论是单份教案还是整学期批量生成，都能在几分钟内完成专业质量的教案文档。\n\n**核心优势：**\n- 🚀 **高效** - 批量生成整学期教案，节省 90% 时间\n- 🎨 **专业** - 完美保留 Word 格式，符合学校规范\n- 🔄 **灵活** - 可视化模板编辑，自定义教案结构\n- 💾 **智能** - AI 优化内容，自动扩展重写\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **📦 批量生成** - 按课时数批量生成整学期教案，支持章节缓存\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n### 批量生成特性\n- **课时数驱动** - 输入总课时（如64、72），自动计算教案数量\n- **灵活分组** - 可配置每份教案课时数（默认2课时/教案）\n- **章节缓存** - 生成的章节模板自动缓存，支持快速复用\n- **多种输入方式** - AI自动生成章节或手动输入章节标题\n- **实时进度** - 后台生成，实时查看进度和状态\n- **ZIP打包** - 所有教案自动打包下载，文件命名清晰\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 管理脚本（便捷启动/停止）\n\n项目提供了跨平台的管理脚本来简化启动和停止操作：\n\n**Windows:**\n```batch\n# 启动前后端服务\nstart.bat\n\n# 查看服务状态\nstatus.bat\n\n# 停止服务\nstop.bat\n```\n\n**Linux/Mac:**\n```bash\n# 启动前后端服务\n./start.sh\n\n# 查看服务状态\n./status.sh\n\n# 停止服务\n./stop.sh\n```\n\n**脚本功能：**\n- `start.bat/sh` - 后台启动前后端服务，日志保存在 `logs/` 目录\n- `status.bat/sh` - 查看服务运行状态和端口监听情况\n- `stop.bat/sh` - 停止所有服务并清理遗留进程\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ ├── settings.py # 设置管理 API\n│ │ └── batch.py # 批量生成 API 📦\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ ├── template_versioning.py # 版本历史管理\n│ │ ├── chapter_splitter.py # 课程章节拆分服务 📦\n│ │ ├── batch_processor.py # 批量生成处理器 📦\n│ │ └── background_runner.py # 后台任务运行器 📦\n│ ├── utils/ # 工具函数\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── BatchGenerate.tsx # 批量生成 📦\n│ │ ├── BatchDownloads.tsx # 批量下载 📦\n│ │ ├── History.tsx # 历史记录\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ ├── batchApi.ts # 批量生成 API 客户端 📦\n│ │ └── settingsApi.ts # 设置 API\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── start.bat / start.sh # 启动前后端服务（Windows/Linux）\n├── status.bat / status.sh # 查看服务状态\n├── stop.bat / stop.sh # 停止服务\n├── .env # 环境变量配置（需创建）\n├── CLAUDE.md # Claude Code 项目说明\n├── BACKEND_SETUP_COMPLETE.md # 后端配置完成报告\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/optimize` | POST | AI 优化内容 |\n| `/api/edit/expand` | POST | AI 扩展内容 |\n| `/api/edit/rewrite` | POST | AI 重写内容 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n\n#### 批量生成 📦\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/batch/split-chapters` | POST | 根据总课时拆分章节 |\n| `/api/batch/create-task` | POST | 创建批量生成任务 |\n| `/api/batch/tasks/{id}` | GET | 获取任务状态和进度 |\n| `/api/batch/tasks` | GET | 获取批量任务列表 |\n| `/api/batch/tasks/{id}/download` | GET | 下载生成的 ZIP 文件 |\n| `/api/batch/tasks/{id}` | DELETE | 取消或删除任务 |\n| `/api/batch/chapter-templates` | GET | 获取缓存的章节模板列表 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n### 6. 批量生成教案 📦\n\n批量生成功能可以一次性创建整学期的所有教案：\n\n#### 步骤 1: 填写课程信息\n- **课程名称**: 如 \"Java程序设计\"\n- **学科/年级**: 选择对应的学科和年级\n- **总课时数**: 如 64 课时（自动计算教案数量）\n- **每份教案课时**: 默认 2 课时（可调整）\n- **章节来源**:\n - **AI 自动生成**: AI 根据课程信息自动拆分章节\n - **手动输入**: 每行输入一个章节标题\n\n#### 步骤 2: 确认章节\n- 查看 AI 生成的章节列表\n- 可直接在表格中编辑课题和内容概述\n- 确认教案模板是否已选择\n\n#### 步骤 3: 监控生成进度\n- 后台自动生成所有教案\n- 实时显示进度条（已完成/总数）\n- 完成后可前往下载页面获取 ZIP 文件\n\n#### 使用已有模板\n如果之前生成过相同课程，可选择\"使用已有模板\"：\n- 自动加载历史章节配置\n- 一键复用，节省时间\n- 模板使用次数会自动记录\n\n#### 下载说明\n- 所有教案打包为 ZIP 文件\n- 文件命名: `课程名称_批量教案_时间戳.zip`\n- 内部文档: `课程名称_01.docx`, `课程名称_02.docx` ...\n- 每个文档包含 2 份教案（可配置）\n\n## ❓ 常见问题\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: 为什么 storage/templates/ 中的模板不显示？**\n\nA: 后端会在启动时自动扫描 `storage/templates/` 文件夹并导入新模板：\n- 只需将 `.docx` 文件放入该文件夹\n- 重启后端服务即可自动导入\n- 已导入的模板不会重复导入\n\n**Q: 如何手动导入现有模板？**\n\nA: 运行导入脚本：\n```bash\npython import_templates.py\n```\n这会扫描 `storage/templates/` 文件夹并导入所有未在数据库中的模板。\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n### 批量生成相关\n\n**Q: 批量生成需要多长时间？**\n\nA: 取决于教案数量和 AI 响应速度：\n- 单份教案约 10-30 秒\n- 32 份教案约 5-15 分钟\n- 建议使用章节缓存功能加速\n\n**Q: 批量生成失败怎么办？**\n\nA: 系统会记录失败数量，已生成的教案不会丢失：\n- 查看错误信息了解原因\n- 检查 API 密钥是否有效\n- 可以重新创建任务\n\n**Q: 如何修改已缓存的章节模板？**\n\nA: 目前不支持直接修改，可以：\n- 创建新任务时手动调整章节\n- 或联系管理员删除缓存后重新生成\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 📝 更新日志\n\n### v1.0.0 (最新)\n- ✨ 新增批量生成功能 - 按课时数批量生成整学期教案\n- ✨ 新增章节缓存系统 - 支持快速复用历史章节配置\n- ✨ 新增可视化模板编辑器 - TipTap 富文本编辑器\n- ✨ 新增版本历史管理 - 支持版本对比和回滚\n- 🔧 优化 Word 导出 - 使用 `docxtpl` 完美保留格式\n- 🔧 添加跨平台管理脚本 - Windows .bat 和 Linux .sh\n- 🔧 多 AI 提供商支持 - DeepSeek 和 Anthropic Claude\n\n---\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n\n[⬆ 返回顶部](#智能教案助手-intelligent-lesson-plan-assistant)\n\n
\n"}, "12585e03ddb3a56cf9a8d79fb608090c2e749844": {"t": 1785766264.6270447, "n": 11690, "h": "549c1f7e05cb7ea5", "c": "# 智能教案助手\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成和在线编辑功能。\n\n## ✨ 功能特性\n\n### 核心功能\n- **📝 模板管理** - 上传、预览和管理教案模板 (.docx)\n- **🤖 智能生成** - 基于 AI 自动生成教案内容\n- **✏️ 在线编辑** - 富文本编辑器支持模板内容在线编辑\n- **🎨 可视化编辑** - TipTap 富文本编辑器，支持表格、颜色、字体等\n- **🔄 版本管理** - 自动保存编辑历史，支持版本对比和回滚\n- **👁️ 实时预览** - 预览 Jinja2 模板渲染效果\n- **💾 AI 优化** - 一键优化、扩展、重写教案内容\n- **📄 文档导出** - 支持导出为 Word 文档格式（完美保留格式和表格）\n- **🔌 多 AI 提供商** - 支持 DeepSeek 和 Anthropic Claude\n- **💻 桌面应用** - 支持 Electron 跨平台桌面应用\n\n### 模板编辑器特性\n- **Jinja2 语法支持** - 可视化插入变量、循环和条件\n- **格式工具栏** - 加粗、斜体、下划线、颜色、字体等\n- **表格编辑** - 完整的表格操作（插入、删除、合并单元格）\n- **自动保存** - 3秒防抖自动保存，避免数据丢失\n- **语法验证** - 实时验证 Jinja2 语法错误\n- **DOCX ↔ HTML** - 双向无损转换，保留原始格式\n\n## 📋 系统要求\n\n- **Python**: 3.8+ (推荐 3.10+，已测试 3.12.3)\n- **Node.js**: 16+ (推荐 18+)\n- **操作系统**: Windows / macOS / Linux\n- **磁盘空间**: 至少 500MB 可用空间\n- **内存**: 建议 4GB+\n\n## 🚀 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/18287452845/lesson-tools.git\ncd lesson-tools\n```\n\n#### 2. 配置环境变量\n\n```bash\n# 复制环境变量模板\ncp backend/.env.example .env\n\n# 编辑 .env 文件，填入你的 API Key\n# Windows 用户可使用: notepad .env\n# Linux/Mac 用户可使用: nano .env 或 vim .env\n```\n\n**.env 文件示例：**\n```env\n# 必填：选择AI提供商\nAI_PROVIDER=deepseek\n\n# 必填：DeepSeek API Key（从 https://platform.deepseek.com/ 获取）\nDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：Anthropic API Key（从 https://console.anthropic.com/ 获取）\n# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 可选：服务器配置\n# API_HOST=127.0.0.1\n# API_PORT=8000\n```\n\n#### 3. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 启动后端服务\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n**验证后端是否成功启动：**\n- 访问 http://127.0.0.1:8000/health 应返回 `{\"status\": \"healthy\"}`\n- 访问 http://127.0.0.1:8000/docs 查看 API 文档\n\n#### 4. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 方式二：桌面应用模式\n\n桌面应用模式仍需要后端服务运行。\n\n```bash\n# 1. 先按照方式一启动后端服务\npython run_backend.py\n\n# 2. 新开终端，进入前端目录\ncd frontend\n\n# 3. 安装依赖\nnpm install\n\n# 4. 启动 Electron 开发模式\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\n# 1. 进入前端目录\ncd frontend\n\n# 2. 构建前端资源\nnpm run build\n\n# 3. 打包 Electron 应用\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n**注意：** 桌面应用仍需要后端服务支持，建议将后端一起打包或提供独立的后端安装包。\n\n## 🎯 AI 提供商配置\n\n本项目支持两种 AI 提供商，可根据需求选择：\n\n### DeepSeek（推荐）\n\n- **优势**: 性价比高，中文理解优秀，API 稳定\n- **价格**: 相对便宜\n- **获取 API Key**: https://platform.deepseek.com/\n- **默认模型**: `deepseek-chat`\n\n```env\nAI_PROVIDER=deepseek\nDEEPSEEK_API_KEY=sk-your-deepseek-key\n```\n\n### Anthropic Claude\n\n- **优势**: 高质量输出，强大的推理能力\n- **价格**: 相对较贵\n- **获取 API Key**: https://console.anthropic.com/\n- **默认模型**: `claude-sonnet-4-20250514`\n\n```env\nAI_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-your-anthropic-key\n```\n\n### 运行时切换 AI 提供商\n\n也可以在应用的**设置页面**动态切换 AI 提供商，无需重启服务。\n\n## 🛠 技术栈\n\n### 后端\n- **FastAPI** 0.109+ - 高性能异步 Web 框架\n- **Uvicorn** - ASGI 服务器\n- **SQLite + aiosqlite** - 异步轻量级数据库\n- **python-docx** 1.1+ - Word 文档处理\n- **docxtpl** 0.16+ - Word 模板渲染（Jinja2）\n- **mammoth** 1.6+ - .docx → HTML 转换\n- **htmldocx** 0.0.6+ - HTML → .docx 转换\n- **beautifulsoup4** - HTML 解析\n- **Anthropic SDK** 0.18+ - Anthropic API 客户端\n- **httpx** - 异步 HTTP 客户端（DeepSeek API）\n- **Pydantic** 2.5+ - 数据验证和设置管理\n\n### 前端\n- **React** 18.2 - 用户界面框架\n- **TypeScript** 5.3 - 类型安全\n- **Vite** 5.0 - 快速构建工具\n- **Ant Design** 5.13 - UI 组件库\n- **TipTap** 2.1 - 富文本编辑器\n - Table、Color、TextStyle、FontFamily 等多个扩展\n- **Zustand** 4.4 - 轻量级状态管理\n- **Axios** - HTTP 客户端\n- **React Router** 6.21 - 路由管理\n- **Nunjucks** 3.2 - Jinja2 模板预览\n\n### 桌面应用\n- **Electron** 28+ - 跨平台桌面应用框架\n- **electron-builder** - 应用打包工具\n\n## 📁 项目结构\n\n```\nlesson-tools/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由层\n│ │ ├── templates.py # 模板管理 API (18个端点)\n│ │ ├── generate.py # AI 教案生成 API\n│ │ ├── edit.py # AI 编辑 API\n│ │ ├── documents.py # 文档管理 API\n│ │ └── settings.py # 设置管理 API\n│ ├── models/ # 数据模型\n│ │ ├── database.py # 数据库连接和表定义\n│ │ └── schemas.py # Pydantic 数据模型\n│ ├── services/ # 业务逻辑层\n│ │ ├── ai_provider.py # AI 提供商抽象（工厂模式）\n│ │ ├── ai_generator.py # 教案生成服务\n│ │ ├── ai_editor.py # AI 编辑服务\n│ │ ├── template_parser.py # 模板解析（Jinja2）\n│ │ ├── document_renderer.py # 文档渲染（docxtpl）\n│ │ ├── docx_converter.py # DOCX ↔ HTML 双向转换\n│ │ ├── jinja_protector.py # Jinja2 语法保护\n│ │ └── template_versioning.py # 版本历史管理\n│ ├── utils/ # 工具函数\n│ ├── config.py # 配置管理（Pydantic Settings）\n│ ├── main.py # FastAPI 应用入口\n│ └── requirements.txt # Python 依赖\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ │ ├── main.js # Electron 入口\n│ │ └── preload.js # 预加载脚本\n│ └── src/\n│ ├── components/ # React 组件\n│ │ └── Editor/ # 富文本编辑器组件 (10个)\n│ │ ├── TipTapEditor.tsx # 主编辑器\n│ │ ├── EditorToolbar.tsx # 工具栏\n│ │ ├── TableToolbar.tsx # 表格工具栏\n│ │ ├── JinjaInsertModal.tsx # Jinja2 插入弹窗\n│ │ ├── PreviewPanel.tsx # 预览面板\n│ │ ├── VersionHistory.tsx # 版本历史\n│ │ └── ... # 其他扩展\n│ ├── pages/ # 页面组件\n│ │ ├── Home.tsx # 首页\n│ │ ├── TemplateManager.tsx # 模板管理\n│ │ ├── TemplateEditor.tsx # 模板编辑器 ⭐\n│ │ ├── NewLessonPlan.tsx # 新建教案\n│ │ ├── EditLessonPlan.tsx # 编辑教案\n│ │ ├── History.tsx # 历史记录\n│ │ └── Settings.tsx # 设置\n│ ├── services/ # API 服务\n│ │ ├── api.ts # 主 API 客户端\n│ │ └── settingsApi.ts # 设置 API\n│ ├── stores/ # Zustand 状态管理\n│ │ ├── templateStore.ts # 模板状态\n│ │ ├── templateEditorStore.ts # 编辑器状态 ⭐\n│ │ ├── generatorStore.ts # 生成器状态\n│ │ └── settingsStore.ts # 设置状态\n│ ├── hooks/ # React Hooks\n│ │ └── useAutoSave.ts # 自动保存 Hook ⭐\n│ └── types/ # TypeScript 类型定义\n│\n├── storage/ # 存储目录（自动创建）\n│ ├── templates/ # 用户上传的模板文件\n│ ├── uploads/ # 临时上传文件\n│ ├── outputs/ # 生成的 Word 文档\n│ └── database.db # SQLite 数据库\n│\n├── run_backend.py # 后端启动脚本\n├── verify_backend.py # 后端环境验证脚本\n├── .env # 环境变量配置（需创建）\n├── CLAUDE.md # Claude Code 项目说明\n├── BACKEND_SETUP_COMPLETE.md # 后端配置完成报告\n└── README.md # 本文件\n```\n\n## 📡 API 文档\n\n启动后端后访问：\n- **Swagger UI**: `http://127.0.0.1:8000/docs` - 交互式 API 文档\n- **ReDoc**: `http://127.0.0.1:8000/redoc` - 美观的 API 文档\n- **Health Check**: `http://127.0.0.1:8000/health` - 健康检查\n\n### 核心 API 端点\n\n#### 模板管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates/upload` | POST | 上传新模板 |\n| `/api/templates/{id}` | GET | 获取模板详情 |\n| `/api/templates/{id}` | PATCH | 更新模板元数据 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/templates/{id}/download` | GET | 下载模板 |\n\n#### 模板编辑器 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/html` | GET | 获取 HTML 编辑格式 |\n| `/api/templates/{id}/save-html` | POST | 保存 HTML 为 .docx |\n| `/api/templates/{id}/preview-html` | POST | 预览渲染效果 |\n| `/api/templates/{id}/validate-jinja` | POST | 验证 Jinja2 语法 |\n\n#### 版本历史 API ⭐\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates/{id}/versions` | GET | 获取版本列表 |\n| `/api/templates/{id}/versions/{vid}` | GET | 获取版本内容 |\n| `/api/templates/{id}/versions/compare` | POST | 对比两个版本 |\n| `/api/templates/{id}/versions/{vid}/restore` | POST | 恢复版本 |\n| `/api/templates/{id}/versions/cleanup` | DELETE | 清理旧版本 |\n\n#### 教案生成\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/generate` | POST | 生成教案 |\n| `/api/generate/{id}/regenerate-field` | POST | 重新生成单个字段 |\n| `/api/generate/{id}/export` | POST | 导出为 Word 文档 |\n\n#### AI 编辑\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/edit/optimize` | POST | AI 优化内容 |\n| `/api/edit/expand` | POST | AI 扩展内容 |\n| `/api/edit/rewrite` | POST | AI 重写内容 |\n\n#### 设置管理\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/settings/ai-provider` | GET/POST | 获取/设置 AI 提供商 |\n| `/api/settings/ai-providers` | GET | 获取可用 AI 提供商列表 |\n\n## 📖 使用指南\n\n### 1. 上传模板\n\n在 Word 中创建教案模板，使用 Jinja2 语法标记可替换内容：\n\n**基本变量：**\n```\n课程名称: {{ subject }}\n年级: {{ grade }}\n课题: {{ topic }}\n课时: {{ duration }}\n授课教师: {{ teacher_name }}\n```\n\n**多行内容：**\n```\n教学目标：\n{{ teaching_goals }}\n\n教学重点：\n{{ key_points }}\n```\n\n**循环（教学步骤）：**\n```\n{% for step in teaching_steps %}\n{{ loop.index }}. {{ step.title }}\n 时间：{{ step.duration }}\n 内容：{{ step.content }}\n{% endfor %}\n```\n\n**条件判断：**\n```\n{% if homework %}\n作业布置：\n{{ homework }}\n{% endif %}\n```\n\n### 2. 在线编辑模板 ⭐\n\n1. 进入**模板管理**页面\n2. 点击模板右侧的**编辑**按钮\n3. 进入可视化模板编辑器：\n - 使用富文本工具栏编辑内容\n - 点击**插入 Jinja2** 按钮添加变量、循环或条件\n - 支持表格编辑、颜色、字体等格式\n - 自动保存（3秒防抖）\n - 查看版本历史并随时回滚\n\n### 3. 生成教案\n\n1. 进入**新建教案**页面\n2. 选择模板\n3. 填写基本信息（学科、年级、课题等）\n4. 点击**生成**按钮\n5. AI 会根据模板结构生成完整教案内容\n6. 可对单个字段进行重新生成\n\n### 4. AI 编辑功能\n\n在编辑器中选中文本后，可使用以下 AI 功能：\n- **优化**: 改进语言表达，使内容更流畅专业\n- **扩展**: 在现有内容基础上增加细节和深度\n- **重写**: 用不同方式重新表达相同内容\n\n### 5. 导出 Word 文档\n\n1. 编辑完成后，点击**导出文档**按钮\n2. 系统使用 `docxtpl` 渲染模板\n3. 保留原始格式、表格结构和样式\n4. 文档保存在 `storage/outputs/` 目录\n5. 可直接下载使用\n\n## ❓ 常见问题\n\n### 安装和启动\n\n**Q: 后端启动失败，提示\"No module named 'fastapi'\"？**\n\nA: 虚拟环境未激活或依赖未安装：\n```bash\n# 确保激活虚拟环境\nsource venv/bin/activate # Linux/Mac\nvenv\\Scripts\\activate # Windows\n\n# 安装依赖\npip install -r backend/requirements.txt\n```\n\n**Q: 前端启动失败，提示\"Cannot find module\"？**\n\nA: Node 依赖未安装：\n```bash\ncd frontend\nrm -rf node_modules package-lock.json # 清理\nnpm install # 重新安装\n```\n\n**Q: 端口被占用怎么办？**\n\nA: 修改端口配置：\n```env\n# .env 文件\nAPI_PORT=8001 # 修改后端端口\n```\n\n### AI 相关\n\n**Q: AI 生成失败，提示\"未设置API密钥\"？**\n\nA: 检查 `.env` 文件是否正确配置了 API Key。\n\n**Q: DeepSeek API 调用失败？**\n\nA: 可能原因：\n1. API Key 无效或过期\n2. 账户余额不足\n3. 网络问题\n4. 请求超时（当前超时设置为 120 秒）\n\n### 模板和编辑\n\n**Q: 上传模板失败，提示\"Template validation failed\"？**\n\nA: 模板语法错误，检查：\n1. 所有 `{{` 都有对应的 `}}`\n2. 所有 `{% for %}` 都有对应的 `{% endfor %}`\n3. 所有 `{% if %}` 都有对应的 `{% endif %}`\n\n**Q: Word 导出后格式丢失？**\n\nA: 项目已修复此问题（使用 `docxtpl` 库），确保：\n- `backend/services/document_renderer.py` 使用 `DocxTemplate`\n- 如果问题依然存在，运行测试：`python test_docxtpl.py`\n\n## 🧪 开发\n\n### 运行测试\n\n```bash\n# 后端单元测试\ncd backend\npytest\n\n# API 集成测试\npython test_api.py\n\n# 模板解析测试\npython debug_template.py\n\n# 文档渲染测试\npython test_renderer.py\npython test_docxtpl.py\n\n# 环境验证\npython verify_backend.py\n```\n\n### 代码规范\n\n**后端（Python）：**\n- 遵循 PEP 8 规范\n- 使用类型注解（Type Hints）\n- 文档字符串使用 Google 风格\n- 异步函数使用 `async/await`\n\n**前端（TypeScript）：**\n- 使用 TypeScript 严格模式\n- 组件使用函数式组件 + Hooks\n- 遵循 React 最佳实践\n- CSS 使用 Ant Design 主题系统\n\n## 🔐 安全最佳实践\n\n⚠️ **重要安全提示**：\n\n1. **保护 API Key**\n - 永远不要将 `.env` 文件提交到 Git\n - 不要在代码中硬编码 API Key\n - 定期轮换 API Key\n\n2. **生产环境部署**\n - 修改 CORS 配置，限制允许的域名\n - 使用 HTTPS 保护 API 通信\n - 添加速率限制防止滥用\n - 设置防火墙规则\n\n3. **数据安全**\n - 定期备份数据库\n - 限制 `storage/` 目录的访问权限\n - 不要在模板中包含敏感信息\n\n## 📄 许可证\n\nMIT License\n\n## 🤝 贡献\n\n欢迎贡献！请遵循以下步骤：\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 贡献指南\n\n- 提交前运行测试确保通过\n- 遵循现有代码风格\n- 更新相关文档\n- 一个 PR 只做一件事\n- 编写清晰的提交信息\n\n## 🙏 致谢\n\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架\n- [React](https://react.dev/) - 用户界面库\n- [Ant Design](https://ant.design/) - 企业级 UI 组件库\n- [TipTap](https://tiptap.dev/) - 无头富文本编辑器\n- [docxtpl](https://github.com/elapouya/python-docx-template) - Word 模板引擎\n- [DeepSeek](https://www.deepseek.com/) - 高性价比 AI 服务\n- [Anthropic](https://www.anthropic.com/) - Claude AI 服务\n\n---\n\n**开始使用智能教案助手，让 AI 助力教学！** 🎓✨\n"}, "d8eaf2eb1f3911aa4bae87c739729fb311940c62": {"t": 1785766266.2556825, "n": 3975, "h": "140bd7dd9ba8739a", "c": "# 智能教案助手\n\n一款基于 AI 的教案生成与编辑工具，支持模板管理、智能生成和在线编辑功能。\n\n## 功能特性\n\n- **模板管理** - 上传、预览和管理教案模板 (.docx)\n- **智能生成** - 基于 AI 自动生成教案内容\n- **在线编辑** - 富文本编辑器支持教案内容编辑\n- **AI 优化** - 一键优化教案内容\n- **文档导出** - 支持导出为 Word 文档格式\n- **桌面应用** - 支持 Electron 桌面应用\n\n## 快速开始\n\n### 方式一：Web 应用模式\n\n#### 1. 环境准备\n\n确保已安装：\n- Python 3.8+\n- Node.js 16+\n\n#### 2. 后端启动\n\n```bash\n# 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Windows:\nvenv\\Scripts\\activate\n# Linux/Mac:\nsource venv/bin/activate\n\n# 安装依赖\npip install -r backend/requirements.txt\n\n# 配置环境变量（创建 .env 文件）\necho AI_PROVIDER=deepseek > .env\necho DEEPSEEK_API_KEY=your_api_key_here >> .env\n\n# 启动后端\npython run_backend.py\n```\n\n后端将在 `http://127.0.0.1:8000` 启动\n\n#### 3. 前端启动\n\n```bash\n# 新开一个终端窗口\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n```\n\n前端将在 `http://localhost:5173` 启动\n\n### 方式二：桌面应用模式\n\n```bash\n# 进入前端目录\ncd frontend\n\n# 安装依赖\nnpm install\n\n# 构建前端并启动 Electron\nnpm run electron:dev\n```\n\n### 方式三：打包桌面应用\n\n```bash\ncd frontend\nnpm run build\nnpm run electron:build\n```\n\n打包后的安装包位于 `frontend/dist-electron/` 目录\n\n## 环境变量配置\n\n在项目根目录创建 `.env` 文件：\n\n```env\n# AI 服务配置\nAI_PROVIDER=deepseek # 可选: deepseek, anthropic\nDEEPSEEK_API_KEY=sk-xxx # DeepSeek API Key\nANTHROPIC_API_KEY=sk-ant-xxx # Anthropic API Key (可选)\n\n# 服务配置（可选）\nAPI_HOST=0.0.0.0\nAPI_PORT=8000\n```\n\n> 获取 API Key：\n> - DeepSeek: https://platform.deepseek.com/\n> - Anthropic: https://console.anthropic.com/\n\n## 技术栈\n\n### 后端\n- **FastAPI** - 高性能异步 Web 框架\n- **SQLite** - 轻量级数据库\n- **python-docx** - Word 文档处理\n- **DocxTemplate** - Word 模板渲染\n\n### 前端\n- **React 18** - 用户界面框架\n- **TypeScript** - 类型安全\n- **Vite** - 快速构建工具\n- **Ant Design** - UI 组件库\n- **TipTap** - 富文本编辑器\n- **Zustand** - 状态管理\n\n### 桌面应用\n- **Electron** - 跨平台桌面应用框架\n\n## 项目结构\n\n```\nlessonToos/\n├── backend/ # 后端服务\n│ ├── api/ # API 路由\n│ │ ├── templates.py # 模板管理\n│ │ ├── generate.py # 教案生成\n│ │ ├── edit.py # AI 编辑\n│ │ ├── documents.py # 文档管理\n│ │ └── settings.py # 设置管理\n│ ├── models/ # 数据模型\n│ ├── services/ # 业务逻辑\n│ ├── utils/ # 工具函数\n│ ├── config.py # 配置管理\n│ └── main.py # 应用入口\n│\n├── frontend/ # 前端应用\n│ ├── electron/ # Electron 主进程\n│ └── src/\n│ ├── components/ # React 组件\n│ ├── pages/ # 页面组件\n│ ├── services/ # API 服务\n│ └── stores/ # 状态管理\n│\n├── storage/ # 存储目录\n│ ├── templates/ # 模板文件\n│ ├── uploads/ # 上传文件\n│ ├── outputs/ # 生成文档\n│ └── database.db # SQLite 数据库\n│\n├── run_backend.py # 后端启动脚本\n└── .env # 环境变量配置\n```\n\n## API 文档\n\n启动后端后访问：\n- Swagger UI: `http://127.0.0.1:8000/docs`\n- ReDoc: `http://127.0.0.1:8000/redoc`\n\n### 核心 API 端点\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/templates` | GET | 获取模板列表 |\n| `/api/templates` | POST | 上传新模板 |\n| `/api/templates/{id}` | DELETE | 删除模板 |\n| `/api/generate` | POST | 生成教案 |\n| `/api/edit/optimize` | POST | AI 优化内容 |\n| `/api/edit/expand` | POST | AI 扩展内容 |\n| `/api/edit/rewrite` | POST | AI 重写内容 |\n| `/api/documents/download/{filename}` | GET | 下载文档 |\n| `/api/settings` | GET/POST | 管理设置 |\n\n## 使用指南\n\n### 创建模板\n\n1. 在 Word 中创建教案模板\n2. 使用 `{{ 变量名 }}` 语法标记可替换内容\n3. 上传模板到系统\n\n```\n课程名称: {{ course_name }}\n授课教师: {{ teacher_name }}\n授课时间: {{ teaching_date }}\n教学目标: {{ teaching_objectives }}\n```\n\n### 生成教案\n\n1. 选择模板\n2. 填写生成参数（课程名称、主题等）\n3. 点击生成按钮\n4. 等待 AI 生成内容\n\n### 编辑导出\n\n1. 在编辑器中查看生成内容\n2. 可使用 AI 辅助优化/扩展/重写\n3. 手动编辑调整\n4. 导出为 Word 文档\n\n## 常见问题\n\n**Q: 后端启动失败？**\n- 检查虚拟环境是否激活\n- 检查依赖是否正确安装\n- 检查 `.env` 文件中的 API Key 是否正确\n\n**Q: AI 生成失败？**\n- 确认 API Key 有效且有足够额度\n- 检查网络连接\n- 查看 API 服务状态\n\n**Q: 前端无法连接后端？**\n- 确认后端服务已启动\n- 检查端口是否被占用\n- 查看浏览器控制台错误信息\n\n## 开发\n\n### 运行测试\n\n```bash\n# 后端测试\ncd backend\npytest\n\n# API 测试\npython test_api.py\n```\n\n### 代码规范\n\n- 后端遵循 PEP 8 规范\n- 前端使用 ESLint + TypeScript 规范\n\n## 许可证\n\nMIT License\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request！\n"}}, "docker-deploy.sh": {"0a9dfb51760e04c428738d6177ba5345f78e6abd": {"t": 1786068349.8880167, "n": 3766, "h": "e03492bc06e12b83", "c": "#!/bin/bash\n\n# Docker 快速部署脚本\n# 用于一键启动智能教案助手 Docker 服务\n\nset -e # 遇到错误时退出\n\n# 颜色定义\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\n# 打印带颜色的消息\nprint_info() {\n echo -e \"${BLUE}[信息]${NC} $1\"\n}\n\nprint_success() {\n echo -e \"${GREEN}[成功]${NC} $1\"\n}\n\nprint_warning() {\n echo -e \"${YELLOW}[警告]${NC} $1\"\n}\n\nprint_error() {\n echo -e \"${RED}[错误]${NC} $1\"\n}\n\n# 检查Docker是否安装\ncheck_docker() {\n print_info \"检查 Docker 环境...\"\n\n if ! command -v docker &> /dev/null; then\n print_error \"未检测到 Docker，请先安装 Docker\"\n echo \"安装指南: https://docs.docker.com/get-docker/\"\n exit 1\n fi\n\n if ! command -v docker-compose &> /dev/null; then\n print_error \"未检测到 Docker Compose，请先安装 Docker Compose\"\n echo \"安装指南: https://docs.docker.com/compose/install/\"\n exit 1\n fi\n\n print_success \"Docker 环境检查通过\"\n docker --version\n docker-compose --version\n}\n\n# 检查.env文件\ncheck_env() {\n print_info \"检查环境配置...\"\n\n if [ ! -f .env ]; then\n print_warning \".env 文件不存在，正在从 .env.example 创建...\"\n\n if [ -f .env.example ]; then\n cp .env.example .env\n print_warning \"请编辑 .env 文件并填入您的 API 密钥：\"\n echo \" nano .env # Linux/Mac\"\n echo \" 或\"\n echo \" notepad .env # Windows\"\n echo \"\"\n echo \"必填项：\"\n echo \" - AI_PROVIDER=deepseek\"\n echo \" - DEEPSEEK_API_KEY=sk-your-api-key\"\n echo \"\"\n read -p \"配置完成后按 Enter 继续...\"\n else\n print_error \".env.example 文件不存在\"\n exit 1\n fi\n fi\n\n # 检查必填的环境变量\n if ! grep -q \"DEEPSEEK_API_KEY=sk-\" .env && ! grep -q \"ANTHROPIC_API_KEY=sk-\" .env; then\n print_error \"未检测到有效的 API 密钥，请在 .env 文件中配置\"\n exit 1\n fi\n\n print_success \"环境配置检查通过\"\n}\n\n# 创建必要的目录\ncreate_directories() {\n print_info \"创建存储目录...\"\n\n mkdir -p storage/templates\n mkdir -p storage/uploads\n mkdir -p storage/outputs\n mkdir -p storage/exports\n\n print_success \"存储目录创建完成\"\n}\n\n# 构建并启动服务\nstart_services() {\n print_info \"构建并启动 Docker 服务...\"\n\n if [ \"$1\" = \"--build\" ]; then\n print_info \"强制重新构建镜像...\"\n docker-compose up -d --build\n else\n docker-compose up -d\n fi\n\n print_success \"Docker 服务已启动\"\n}\n\n# 等待服务就绪\nwait_for_services() {\n print_info \"等待服务启动...\"\n\n max_attempts=30\n attempt=0\n\n while [ $attempt -lt $max_attempts ]; do\n if curl -s http://localhost:8000/health > /dev/null 2>&1; then\n print_success \"后端服务已就绪\"\n break\n fi\n\n attempt=$((attempt + 1))\n echo -n \".\"\n sleep 2\n done\n\n echo \"\"\n\n if [ $attempt -eq $max_attempts ]; then\n print_warning \"后端服务启动超时，请检查日志\"\n print_info \"查看日志命令: docker-compose logs -f backend\"\n fi\n}\n\n# 显示访问信息\nshow_info() {\n echo \"\"\n echo \"======================================\"\n print_success \"部署完成！\"\n echo \"======================================\"\n echo \"\"\n echo \"访问地址：\"\n echo \" 前端界面: ${GREEN}http://localhost${NC}\"\n echo \" 后端API: ${GREEN}http://localhost:8000${NC}\"\n echo \" API文档: ${GREEN}http://localhost:8000/docs${NC}\"\n echo \"\"\n echo \"常用命令：\"\n echo \" 查看日志: ${BLUE}docker-compose logs -f${NC}\"\n echo \" 查看状态: ${BLUE}docker-compose ps${NC}\"\n echo \" 停止服务: ${BLUE}docker-compose stop${NC}\"\n echo \" 重启服务: ${BLUE}docker-compose restart${NC}\"\n echo \" 完全清理: ${BLUE}docker-compose down -v${NC}\"\n echo \"\"\n}\n\n# 主函数\nmain() {\n echo \"======================================\"\n echo \" 智能教案助手 Docker 快速部署\"\n echo \"======================================\"\n echo \"\"\n\n check_docker\n check_env\n create_directories\n start_services \"$@\"\n wait_for_services\n show_info\n}\n\n# 执行主函数\nmain \"$@\"\n"}}}}