diff --git a/.gitignore b/.gitignore index 1dd9dcb..24f7efe 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,8 @@ __pycache__/ *.py[cod] *$py.class +.idea + # C extensions *.so diff --git a/README.md b/README.md index 3cd94d1..e8b967b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,65 @@ -# doc-forge-reds - +# AI 智能文档生成系统 (Doc Forge Reds) +## 项目简介 +Doc Forge Reds 是一款外部 Web 工具，支持上传 Word 模板、在线编辑与预览，通过可视化方式标注文档中需要 AI 生成内容的区域，并可配置不同的 AI 模型进行内容生成。系统提供模型管理、模板管理、生成点管理、异步任务执行等完整功能，最终导出的文档保持原样式。 +## 核心功能 +- 📤 上传 Word 模板，在线编辑并预览 +- 🎯 框选标注生成点，配置提示词、参考文件和指定 AI 模型 +- 🤖 AI 模型管理（多供应商：OpenAI、Azure、自定义） +- ⚙️ 异步任务生成，状态追踪，结果下载 +## 技术栈 +- **前端**：React 18 + TypeScript + Ant Design + TinyMCE +- **后端**：Python 3.10 + FastAPI + SQLAlchemy +- **异步任务**：Celery + Redis +- **数据库**：PostgreSQL 18.3 +- **文档处理**：Aspose.Words (或 Mammoth + python-docx) +- **部署**：Docker + Docker Compose +## 快速开始 +### 环境要求 +- Docker & Docker Compose +- Python 3.10+ (本地开发) +- Node.js 18+ (本地开发) +### 使用 Docker 一键启动 +```bash +git clone +cd doc-forge-reds +docker-compose up -d +``` +访问 `http://localhost:3000` 进入前端界面。 +### 本地开发 +1. 启动依赖服务`docker-compose up -d postgres redis` +2. 后端`cd backend && python -m venv venv && source venv/bin/activate && pip install -r requirements.txt && uvicorn app.main:app --reload` +3. 前端`cd web && npm install && npm run dev` +4. Celery Worker`celery -A app.tasks.celery_app worker --loglevel=info` +## 项目目录结构 +``` +. +├── backend/ # Python 后端 +│ ├── app/ +│ │ ├── api/ # API 路由 +│ │ ├── core/ # 配置、安全、数据库 +│ │ ├── models/ # ORM 模型 +│ │ ├── schemas/ # Pydantic 模式 +│ │ ├── services/ # 业务逻辑 +│ │ ├── tasks/ # Celery 任务 +│ │ └── main.py +│ ├── migrations/ # Alembic 迁移 +│ ├── requirements.txt +│ └── Dockerfile +├── web/ # React 前端 +│ ├── src/ +│ │ ├── api/ # API 调用封装 +│ │ ├── components/ # 可复用 UI +│ │ ├── pages/ # 页面 +│ │ ├── hooks/ # 自定义 Hooks +│ │ └── store/ # 状态管理 +│ ├── package.json +│ └── Dockerfile +├── docker-compose.yml +└── docs/ # 项目文档 +``` +## 文档索引 +- [技术方案概述](docs/技术方案概述.md) +- [数据库设计](docs/数据库设计.md) +- [API 设计](docs/API设计.md) +- [任务拆解清单](docs/任务拆解清单.md) +- [部署指南](docs/部署指南.md) diff --git a/docs/API设计.md b/docs/API设计.md new file mode 100644 index 0000000..7e0006d --- /dev/null +++ b/docs/API设计.md @@ -0,0 +1,103 @@ +# API 设计文档 +所有接口前缀为 `/api/v1`，返回 JSON 格式数据。认证暂未启用（单用户环境）。 +## 1. AI 模型管理 (`/models`) +### 1.1 创建模型 +`POST /models` +**请求体**： +```json +{ + "name": "GPT-4", + "provider": "openai", + "endpoint": "https://api.openai.com/v1/chat/completions", + "api_key": "sk-...", + "extra_params": {"max_tokens": 1000, "temperature": 0.7}, + "is_enabled": true, + "remark": "主模型" +} +``` +**响应**：返回创建的模型对象（API Key 已加密）。 +### 1.2 获取模型列表 +`GET /models?enabled=true&page=1&limit=20` +**响应**：分页列表。 +### 1.3 获取模型详情 +`GET /models/{id}` +### 1.4 更新模型 +`PUT /models/{id}`（字段同创建） +### 1.5 删除模型 +`DELETE /models/{id}` +### 1.6 启用/禁用 +`PATCH /models/{id}/toggle` +请求体`{"is_enabled": false}` +## 2. 模板管理 (`/templates`) +### 2.1 上传模板 +`POST /templates` (multipart/form-data) +字段`file` (.docx), `name` (可选) +**响应**：模板对象（含生成的 HTML 内容）。 +### 2.2 获取模板列表 +`GET /templates` (分页) +### 2.3 获取模板 HTML 内容 +`GET /templates/{id}/html` +返回`{"html_content": "..."}` +### 2.4 更新模板 HTML（编辑后保存） +`PUT /templates/{id}/html` +请求体`{"html_content": "..."}` +后端将同步更新对应的 .docx 文件。 +### 2.5 下载最终文档 +`GET /templates/{id}/download` +返回文件流（.docx）。 +## 3. 生成点管理 (`/generation-points`) +### 3.1 创建生成点 +`POST /generation-points` +```json +{ + "template_id": "uuid", + "position": {"start": 100, "end": 200}, + "prompt": "请根据参考文件生成一段总结", + "model_id": "uuid (可选)", + "ref_file": "file (multipart, 可选)" +} +``` +**响应**：生成点对象。 +### 3.2 获取模板的所有生成点 +`GET /generation-points?template_id={id}` +### 3.3 更新生成点 +`PUT /generation-points/{id}`（字段同创建） +### 3.4 删除生成点 +`DELETE /generation-points/{id}` +## 4. 生成任务 (`/tasks`) +### 4.1 触发生成任务 +`POST /templates/{template_id}/generate` +**响应**： +```json +{ + "task_id": "uuid", + "status": "pending" +} +``` +### 4.2 查询任务状态 +`GET /tasks/{task_id}` +**响应**： +```json +{ + "id": "uuid", + "status": "done", + "result_file_path": "/path/to/result.docx", + "error_msg": null, + "created_at": "...", + "finished_at": "..." +} +``` +### 4.3 下载生成结果 +`GET /tasks/{task_id}/download` +返回 .docx 文件流。 +## 错误码规范 +- `200`: 成功 +- `400`: 请求参数错误 +- `404`: 资源不存在 +- `500`: 服务器内部错误 +错误响应格式： +```json +{ + "detail": "错误描述" +} +``` diff --git a/docs/任务拆解清单.md b/docs/任务拆解清单.md new file mode 100644 index 0000000..be2a75f --- /dev/null +++ b/docs/任务拆解清单.md @@ -0,0 +1,87 @@ +# 任务拆解清单（详细版） + +本文档将整个开发过程拆解为可执行的工作包，包含优先级、工时估算、依赖关系和里程碑。所有任务均覆盖核心功能、测试、部署及新增需求（单点测试、拖拽排序、独立模型选择、PDF导出）。 + +## 优先级说明 +- **P0**：核心功能，必须完成才能可用。 +- **P1**：重要功能，提升体验。 +- **P2**：优化和增强。 + +--- + +## 阶段一：基础设施与核心服务 (第1~2周) + +| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 | +|----|------|--------|---------|--------|------|--------| +| 1.1 | 需求分析与架构评审 | - 编写详细需求文档（含用户故事）
- 数据库模型设计评审（ER图、字段说明）
- 技术选型最终确认（含PDF导出库调研） | 24 | P0 | - | 架构基线完成 | +| 1.2 | 开发环境搭建 | - 配置后端虚拟环境，安装 FastAPI、SQLAlchemy、Celery、PyPDF2等
- 配置前端项目（Vite + React + TS + Ant Design）
- Docker Compose 定义基础服务（Postgres、Redis） | 16 | P0 | 1.1 | 可运行空框架 | +| 1.3 | 数据库与 ORM | - 使用 Alembic 创建初始迁移，建表（models, templates, generation_points, tasks, system_config）
- 编写 SQLAlchemy 模型（含`order`字段用于生成点排序）
- 实现数据库会话依赖注入 | 24 | P0 | 1.2 | 数据库就绪 | +| 1.4 | 文件存储服务 | - 实现文件上传、下载、删除工具类
- 配置存储根目录和路径生成规则（区分模板、参考文件、结果） | 16 | P0 | 1.3 | 文件操作可用 | + +## 阶段二：核心业务逻辑 (第3~5周) + +| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 | +|----|------|--------|---------|--------|------|--------| +| 2.1 | 文档处理服务（含PDF导出） | - 集成 Aspose.Words (或 Mammoth + python-docx) 实现 docx ↔ HTML 转换
- 实现 `docx_to_html` 和 `html_to_docx` 函数
- 实现 `docx_to_pdf` 函数（使用 python-docx + reportlab 或 Aspose）
- 单元测试转换效果（包含表格、图片、样式） | 48 | P0 | 1.4 | 文档转换与导出达标 | +| 2.2 | AI 模型管理 API | - 实现 CRUD 接口
- API Key 加密存储（Fernet）
- 启用/禁用切换
- 列表查询过滤（启用/全部） | 24 | P0 | 1.3 | 模型管理功能完备 | +| 2.3 | 模板管理 API | - 上传接口（接收文件，存储并转换 HTML）
- 获取 HTML 内容（含模板基本信息）
- 更新 HTML（并同步转回 docx）
- 下载接口（支持 docx 和 pdf 格式参数） | 32 | P0 | 2.1, 1.4 | 模板 CRUD 完成 | +| 2.4 | 生成点管理 API | - 创建、列表、更新、删除生成点
- 关联模板和模型校验
- 参考文件上传处理
- 支持 `order` 字段（用于排序） | 24 | P0 | 2.2, 2.3 | 生成点可标注 | +| 2.5 | 生成点顺序管理 | - 提供批量更新接口（接收生成点ID列表顺序）
- 前端拖拽排序时调用此接口 | 8 | P1 | 2.4 | 排序功能可用 | + +## 阶段三：异步任务与 AI 集成 (第6~7周) + +| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 | +|----|------|--------|---------|--------|------|--------| +| 3.1 | AI 调用适配器 | - 设计工厂模式，支持 openai, azure, custom
- 实现各供应商的请求构建和响应解析
- 编写异步调用函数（httpx）
- 支持超时、重试配置 | 32 | P0 | 2.2 | 可成功调用不同模型 | +| 3.2 | 参考文件解析器 | - 实现提取 .txt, .docx, .pdf 文本内容的功能
- 使用 python-docx, PyPDF2 等库 | 16 | P0 | 1.4 | 提取文本成功 | +| 3.3 | Celery 任务定义 | - **3.3.1** Celery 配置与连接（4h）
- **3.3.2** 任务函数骨架（加载模板、获取生成点，按 order 排序）（8h）
- **3.3.3** 参考文件解析集成（4h）
- **3.3.4** AI 调用与结果插入（基于偏移量或 XPath）（12h）
- **3.3.5** 文档保存（docx）与状态更新（8h）
- **3.3.6** 异常处理与重试逻辑（12h）
**合计** | 48 | P0 | 3.1, 3.2, 2.3, 2.4, 2.5 | 可端到端生成文档 | +| 3.4 | 任务管理 API | - 触发生成任务接口（创建 task 记录，启动 Celery）
- 查询任务状态（含进度百分比）
- 下载结果接口（支持 docx 和 pdf）
- 取消任务接口（可选） | 20 | P0 | 3.3 | 任务管理可用 | +| 3.5 | 单个生成点测试功能 | - 提供 API 允许用户测试单个生成点（不保存文档）
- 返回 AI 生成结果预览（可返回纯文本或HTML）
- 前端在标注弹窗中增加“测试”按钮，展示结果 | 16 | P1 | 3.1, 3.2 | 单点测试可用 | + +## 阶段四：前端开发 (第5~9周，与后端并行) + +| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 | +|----|------|--------|---------|--------|------|--------| +| 4.1 | 页面路由与布局 | - 使用 React Router 定义路由（/templates, /editor/:id, /models, /tasks, /settings）
- 整体布局（侧边栏 + 内容区） | 12 | P0 | 1.2 | 框架搭建 | +| 4.2 | 模型管理页面 | - 列表展示（表格 + 分页）
- 新建/编辑弹窗表单（含供应商、API Key、扩展参数JSON编辑器）
- 启用/禁用开关
- 删除确认
- 设置全局默认模型（单选按钮） | 24 | P0 | 2.2 | 模型管理交互完整 | +| 4.3 | 模板列表与上传 | - 列表页面（卡片或表格，含名称、创建时间、操作按钮）
- 上传文件组件（支持拖拽，仅 .docx）
- 点击“编辑”跳转到编辑器页 | 16 | P0 | 2.3 | 可上传和查看模板 | +| 4.4 | 模板编辑器（核心） | **拆解为以下子任务**：
- **4.4.1** 集成 TinyMCE，加载 HTML 内容，保存时调用更新接口（8h）
- **4.4.2** 实现选区监听与高亮标注（监听 mouseup，显示浮动按钮“设为AI生成点”）（12h）
- **4.4.3** 生成点弹窗表单：提示词、参考文件上传（拖拽）、模型下拉（独立选择），并集成“测试”按钮（调用3.5）（16h）
- **4.4.4** 生成点列表（右侧面板），显示每个点的摘要，支持删除、编辑（修改弹窗）（8h）
- **4.4.5** 标注区域与实际选区偏移量同步（确保插入位置准确）（4h）
- **4.4.6** 支持拖拽排序生成点（使用 react-beautiful-dnd 等），更新顺序（4h）
**合计** | 52 | P0 | 4.3, 2.4, 4.2, 3.5, 2.5 | 可编辑并标注 | +| 4.5 | 生成任务执行与监控 | - 页面内“生成文档”按钮（可放在编辑器底部或工具栏）
- 弹出确认框，显示所有生成点列表（可勾选跳过个别）
- 提交后显示任务进度条（轮询状态，含进度百分比）
- 完成后自动显示下载按钮（支持 docx 和 pdf 格式切换） | 28 | P0 | 3.4 | 完整生成流程 | +| 4.6 | 任务历史页面 | - 表格列出所有任务（模板名称、状态、开始/完成时间）
- 状态为“已完成”的可以下载（格式选择）
- 状态为“进行中”的显示进度，可取消（可选） | 16 | P1 | 3.4 | 任务可追溯 | +| 4.7 | 系统设置页面 | - 展示可编辑的系统配置（全局默认模型、最大并发数、超时时间等）
- 调用后端接口读写 system_config | 12 | P1 | 2.2 | 设置可用 | + +## 阶段五：测试与优化 (第10~11周) + +| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 | +|----|------|--------|---------|--------|------|--------| +| 5.1 | 集成测试 | - 端到端测试（上传 → 标注（含拖拽排序）→ 单点测试 → 生成 → 下载）
- 测试不同供应商模型调用
- 测试参考文件多种格式（txt, docx, pdf）
- 测试导出 PDF 功能
- 异常场景（网络超时、文件损坏、AI 返回错误） | 48 | P0 | 所有前序 | 功能稳定 | +| 5.2 | 性能调优 | - 优化大文档转换速度（异步处理）
- 数据库查询添加索引（template_id, status）
- 调整 Celery 并发参数
- 优化前端渲染（虚拟列表等） | 16 | P1 | 5.1 | 响应达标 | +| 5.3 | 安全加固 | - 检查 API Key 加密流程
- 文件上传类型和大小限制（限制50MB）
- 添加 CORS 配置
- 输入校验（防止 XSS） | 8 | P0 | 5.1 | 安全合规 | +| 5.4 | 文档编写 | - 用户手册（操作指南，含截图）
- 部署文档（Docker 详细步骤）
- API 文档（由 FastAPI 自动生成，补充说明） | 24 | P1 | - | 交付文档完整 | + +## 阶段六：部署上线 (第12周) + +| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 | +|----|------|--------|---------|--------|------|--------| +| 6.1 | Docker 化所有服务 | - 编写 Dockerfile（后端、前端、Celery）
- 编写 docker-compose.yml 整合所有服务（postgres, redis, backend, celery-worker, nginx） | 16 | P0 | 所有 | 可容器化运行 | +| 6.2 | 生产环境配置 | - 配置环境变量（数据库、Redis、密钥等）
- 配置 Nginx 反向代理（前端静态 + 后端 API 转发）
- 配置 SSL（可选） | 8 | P0 | 6.1 | 生产就绪 | +| 6.3 | 部署测试 | - 在测试服务器上部署，验证全部功能（含 PDF 导出） | 8 | P0 | 6.2 | 上线成功 | + +## 里程碑总览 + +| 里程碑 | 预计完成时间 | 关键交付 | +|--------|--------------|----------| +| M1: 架构与数据库就绪 | 第2周末 | 需求文档、数据库设计、环境搭建、文件存储 | +| M2: 核心 API 完成 | 第5周末 | 模板、模型、生成点 CRUD 完成，文档转换与导出（含PDF） | +| M3: 异步生成能力 | 第7周末 | Celery 任务可端到端生成文档，单点测试可用 | +| M4: 前端完整交互 | 第9周末 | 所有页面可用（含拖拽排序、任务历史、系统设置），生成流程顺畅 | +| M5: 测试与稳定 | 第11周末 | 通过集成测试，性能优化，安全加固 | +| M6: 正式上线 | 第12周末 | Docker 部署，生产环境运行 | + +## 总工时估算 + +- 开发：约 **468 人时**（按 8h/天 ≈ 58.5 人天） +- 含新增功能（单点测试、PDF导出、拖拽排序、系统设置）和细化拆分 +- 测试与部署额外计入，总项目周期约 **12 周**（建议 4~5 人并行开发） + +--- \ No newline at end of file diff --git a/docs/技术方案概述.md b/docs/技术方案概述.md new file mode 100644 index 0000000..df0c784 --- /dev/null +++ b/docs/技术方案概述.md @@ -0,0 +1,63 @@ +# 技术方案概述 +## 1. 总体架构 +采用前后端分离架构，后端提供 RESTful API，前端负责交互和展示。异步任务通过 Celery 处理，确保长时间 AI 调用不阻塞主线程。 +### 架构图 +``` +用户 -> Nginx (前端静态) -> React 应用 + | + +-> FastAPI 后端 (API) + | + +-> PostgreSQL (业务数据) + +-> Redis (消息队列 + 缓存) + +-> Celery Worker (异步任务) + +-> 文件存储 (模板/参考文件/结果) +``` +## 2. 技术选型 +| 层级 | 组件 | 理由 | +|------|------|------| +| 前端框架 | React + TypeScript | 生态成熟，类型安全，组件化利于维护 | +| UI 库 | Ant Design | 后台管理组件丰富，开发效率高 | +| 富文本编辑器 | TinyMCE | 支持选区操作，可扩展，兼容性好 | +| 后端框架 | FastAPI | 异步高性能，自动生成文档，易于集成 AI | +| ORM | SQLAlchemy | 功能强大，支持异步 (2.0) | +| 任务队列 | Celery + Redis | 久经考验，支持重试、状态追踪 | +| 文档处理 | Aspose.Words (优先) | 高保真 Word ↔ HTML 转换，样式保留最佳 | +| 备选文档方案 | Mammoth + python-docx | 开源免费，但复杂样式可能丢失 | +| AI 调用 | httpx (异步) | 支持异步请求，适配多种 API 格式 | +| 容器化 | Docker Compose | 简化部署，环境一致性 | +## 3. 核心模块设计 +### 3.1 AI 模型管理模块 +- 支持新建、编辑、删除、启用/禁用模型。 +- 模型信息包括：名称、供应商、接口地址、API Key（加密存储）、扩展参数、备注。 +- 提供下拉选择供生成点关联。 +### 3.2 模板管理模块 +- 上传 .docx → 存储原始文件，转换为 HTML 存于数据库。 +- 在线编辑：前端编辑器修改 HTML，后端同步转回 .docx。 +- 导出最终 .docx 文件。 +### 3.3 生成点管理模块 +- 用户在编辑器中框选文本，标注为 AI 生成点。 +- 填写提示词，上传参考文件，选择模型。 +- 保存选区位置（起始/结束偏移量或 XPath）。 +### 3.4 异步生成任务 +1. 用户触发生成，系统创建任务记录，启动 Celery 任务。 +2. 任务流程： + - 加载模板和所有生成点。 + - 对每个生成点，提取参考文件文本，构造 prompt。 + - 调用对应的 AI 模型（通过适配器）。 + - 将生成结果插入文档对应位置。 + - 保存最终文档。 +3. 前端轮询任务状态，完成后提供下载。 +## 4. 安全设计 +- **API Key 加密**：使用 `cryptography.fernet` 对称加密，密钥取自环境变量。 +- **文件隔离**：若未来引入多用户，可通过用户目录隔离文件。 +- **输入校验**：所有 API 使用 Pydantic 校验，防止注入攻击。 +- **CORS**：配置仅允许前端域名访问。 +## 5. 性能与扩展 +- **异步处理**：AI 调用和文档转换均异步，提升吞吐量。 +- **连接池**：数据库和 Redis 使用连接池，避免资源耗尽。 +- **水平扩展**：Celery worker 可多实例部署，后端 API 可水平扩展。 +- **适配器模式**：AI 调用采用工厂模式，新增供应商无需修改核心逻辑。 +## 6. 部署方案 +- 使用 Docker Compose 编排：PostgreSQL、Redis、FastAPI、Celery Worker、前端 Nginx。 +- 环境变量统一管理，通过 `.env` 配置。 +- 生产环境建议使用反向代理（如 Nginx）挂载 SSL 证书。 diff --git a/docs/数据库设计.md b/docs/数据库设计.md new file mode 100644 index 0000000..385dbfc --- /dev/null +++ b/docs/数据库设计.md @@ -0,0 +1,61 @@ +# 数据库设计 +## ER 图（核心关系） +- `templates` (1) ——> (N) `generation_points` +- `generation_points` (N) ——> (1) `models` +- `templates` (1) ——> (N) `generation_tasks` +## 表结构详细 +### 1. `models`（AI 模型配置） +| 字段名 | 类型 | 约束 | 说明 | +| -------------- | ------------- | ------------------ | -------------------------------------- | +| id | UUID | PRIMARY KEY | 主键 | +| name | VARCHAR(100) | NOT NULL | 模型名称 | +| provider | VARCHAR(50) | NOT NULL | 供应商：openai, azure, custom | +| endpoint | VARCHAR(255) | NOT NULL | 接口地址 | +| api_key | TEXT | NOT NULL | 加密存储（Fernet 对称加密） | +| extra_params | JSONB | DEFAULT '{}' | 扩展参数，如 max_tokens, temperature | +| is_enabled | BOOLEAN | DEFAULT TRUE | 是否启用 | +| remark | TEXT | | 备注 | +| created_at | TIMESTAMP | DEFAULT NOW() | | +| updated_at | TIMESTAMP | DEFAULT NOW() | | +### 2. `templates`（模板文档） +| 字段名 | 类型 | 约束 | 说明 | +| -------------- | ------------- | ------------------ | ------------------------------------------ | +| id | UUID | PRIMARY KEY | | +| name | VARCHAR(200) | NOT NULL | 模板名称 | +| file_path | VARCHAR(500) | NOT NULL | 原始 .docx 文件存储路径 | +| html_content | TEXT | | 转换后的 HTML 内容（供前端编辑） | +| created_at | TIMESTAMP | DEFAULT NOW() | | +| updated_at | TIMESTAMP | DEFAULT NOW() | | +### 3. `generation_points`（AI 生成点） +| 字段名 | 类型 | 约束 | 说明 | +| --------------- | ------------- | ------------------ | ------------------------------------------------- | +| id | UUID | PRIMARY KEY | | +| template_id | UUID | FOREIGN KEY | 关联模板 | +| position | JSONB | NOT NULL | 在 HTML 中的选区信息，如 {start: 100, end: 200} 或 XPath | +| prompt | TEXT | NOT NULL | 用户编写的提示词 | +| model_id | UUID | FOREIGN KEY | 指定使用的模型，若为空则使用全局默认模型 | +| ref_file_path | VARCHAR(500) | | 参考文件存储路径（可选） | +| created_at | TIMESTAMP | DEFAULT NOW() | | +| updated_at | TIMESTAMP | DEFAULT NOW() | | +### 4. `generation_tasks`（生成任务） +| 字段名 | 类型 | 约束 | 说明 | +| --------------- | ------------- | ------------------ | ----------------------------------------------- | +| id | UUID | PRIMARY KEY | | +| template_id | UUID | FOREIGN KEY | 关联模板 | +| status | VARCHAR(20) | NOT NULL | pending / processing / done / failed | +| result_file_path| VARCHAR(500) | | 生成后的 .docx 文件路径 | +| error_msg | TEXT | | 任务失败时的错误信息 | +| celery_task_id | VARCHAR(100) | | Celery 任务 ID，便于追踪 | +| created_at | TIMESTAMP | DEFAULT NOW() | | +| finished_at | TIMESTAMP | | 完成时间 | +### 5. `system_config`（系统配置，可选） +存储全局默认模型 ID 等键值对。 +| 字段名 | 类型 | 约束 | 说明 | +| ----------- | ------------- | -------- | -------------------- | +| key | VARCHAR(50) | PRIMARY | 配置键 | +| value | TEXT | | 配置值（JSON 格式） | +| description | VARCHAR(200) | | 描述 | +## 索引建议 +- `templates`：在 `created_at` 上建索引，便于按时间排序。 +- `generation_points`：在 `template_id` 上建外键索引，提高关联查询速度。 +- `generation_tasks`：在 `template_id,status` 上建索引，优化列表查询。 diff --git a/docs/部署指南.md b/docs/部署指南.md new file mode 100644 index 0000000..5c981e8 --- /dev/null +++ b/docs/部署指南.md @@ -0,0 +1,59 @@ +# 部署指南 (Docker Compose) +## 前置条件 +- Linux 服务器（或 Windows WSL2） +- Docker 和 Docker Compose 已安装 +- 域名（可选）和 SSL 证书（可选） +## 步骤 +### 1. 克隆代码 +```bash +git clone +cd doc-forge-reds +``` +### 2. 配置环境变量 +复制 `.env.example` 为 `.env`，并填写以下关键变量： +```env +# Database +POSTGRES_USER=docforge +POSTGRES_PASSWORD=secure_password +POSTGRES_DB=docforge +# Redis +REDIS_URL=redis://redis:6379/0 +# Backend +SECRET_KEY=your-secret-key-for-fernet-encryption +DEFAULT_MODEL_ID=uuid-of-default-model +# AI API Keys (也可在后台模型管理中配置) +OPENAI_API_KEY=sk-... +AZURE_API_KEY=... +``` +### 3. 构建并启动所有服务 +```bash +docker-compose up -d --build +``` +### 4. 执行数据库迁移（首次启动后） +```bash +docker-compose exec backend alembic upgrade head +``` +### 5. 验证服务状态 +- 前端`http://localhost:3000` +- 后端 API 文档`http://localhost:8000/docs` +- Celery Worker 日志`docker-compose logs celery-worker` +## 服务端口映射 +- 前端`3000` (可通过 `nginx` 暴露 80) +- 后端 API`8000` +- PostgreSQL`5432` (仅内部) +- Redis`6379` (仅内部) +## 生产环境优化建议 +- 使用外部 PostgreSQL（如 AWS RDS）提升可靠性。 +- 将 Redis 配置为持久化模式。 +- 挂载 SSL 证书，配置 HTTPS。 +- 设置 Celery 并发数根据 CPU 核心数调整。 +- 定期备份数据库和文件存储目录。 +## 停止服务 +```bash +docker-compose down +``` +## 升级流程 +1. `git pull` 拉取最新代码 +2. `docker-compose build` 重新构建镜像 +3. `docker-compose up -d` 重启服务 +4. 运行数据库迁移（如有）