init
This commit is contained in:
parent
c95b4a6ad6
commit
cc57cd1689
|
|
@ -4,6 +4,8 @@ __pycache__/
|
|||
*.py[cod]
|
||||
*$py.class
|
||||
|
||||
.idea
|
||||
|
||||
# C extensions
|
||||
*.so
|
||||
|
||||
|
|
|
|||
67
README.md
67
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 <repository-url>
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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": "<html>..."}`
|
||||
### 2.4 更新模板 HTML（编辑后保存）
|
||||
`PUT /templates/{id}/html`
|
||||
请求体`{"html_content": "<html>..."}`
|
||||
后端将同步更新对应的 .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": "错误描述"
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
# 任务拆解清单（详细版）
|
||||
|
||||
本文档将整个开发过程拆解为可执行的工作包，包含优先级、工时估算、依赖关系和里程碑。所有任务均覆盖核心功能、测试、部署及新增需求（单点测试、拖拽排序、独立模型选择、PDF导出）。
|
||||
|
||||
## 优先级说明
|
||||
- **P0**：核心功能，必须完成才能可用。
|
||||
- **P1**：重要功能，提升体验。
|
||||
- **P2**：优化和增强。
|
||||
|
||||
---
|
||||
|
||||
## 阶段一：基础设施与核心服务 (第1~2周)
|
||||
|
||||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||||
|----|------|--------|---------|--------|------|--------|
|
||||
| 1.1 | 需求分析与架构评审 | - 编写详细需求文档（含用户故事）<br>- 数据库模型设计评审（ER图、字段说明）<br>- 技术选型最终确认（含PDF导出库调研） | 24 | P0 | - | 架构基线完成 |
|
||||
| 1.2 | 开发环境搭建 | - 配置后端虚拟环境，安装 FastAPI、SQLAlchemy、Celery、PyPDF2等<br>- 配置前端项目（Vite + React + TS + Ant Design）<br>- Docker Compose 定义基础服务（Postgres、Redis） | 16 | P0 | 1.1 | 可运行空框架 |
|
||||
| 1.3 | 数据库与 ORM | - 使用 Alembic 创建初始迁移，建表（models, templates, generation_points, tasks, system_config）<br>- 编写 SQLAlchemy 模型（含`order`字段用于生成点排序）<br>- 实现数据库会话依赖注入 | 24 | P0 | 1.2 | 数据库就绪 |
|
||||
| 1.4 | 文件存储服务 | - 实现文件上传、下载、删除工具类<br>- 配置存储根目录和路径生成规则（区分模板、参考文件、结果） | 16 | P0 | 1.3 | 文件操作可用 |
|
||||
|
||||
## 阶段二：核心业务逻辑 (第3~5周)
|
||||
|
||||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||||
|----|------|--------|---------|--------|------|--------|
|
||||
| 2.1 | 文档处理服务（含PDF导出） | - 集成 Aspose.Words (或 Mammoth + python-docx) 实现 docx ↔ HTML 转换<br>- 实现 `docx_to_html` 和 `html_to_docx` 函数<br>- 实现 `docx_to_pdf` 函数（使用 python-docx + reportlab 或 Aspose）<br>- 单元测试转换效果（包含表格、图片、样式） | 48 | P0 | 1.4 | 文档转换与导出达标 |
|
||||
| 2.2 | AI 模型管理 API | - 实现 CRUD 接口<br>- API Key 加密存储（Fernet）<br>- 启用/禁用切换<br>- 列表查询过滤（启用/全部） | 24 | P0 | 1.3 | 模型管理功能完备 |
|
||||
| 2.3 | 模板管理 API | - 上传接口（接收文件，存储并转换 HTML）<br>- 获取 HTML 内容（含模板基本信息）<br>- 更新 HTML（并同步转回 docx）<br>- 下载接口（支持 docx 和 pdf 格式参数） | 32 | P0 | 2.1, 1.4 | 模板 CRUD 完成 |
|
||||
| 2.4 | 生成点管理 API | - 创建、列表、更新、删除生成点<br>- 关联模板和模型校验<br>- 参考文件上传处理<br>- 支持 `order` 字段（用于排序） | 24 | P0 | 2.2, 2.3 | 生成点可标注 |
|
||||
| 2.5 | 生成点顺序管理 | - 提供批量更新接口（接收生成点ID列表顺序）<br>- 前端拖拽排序时调用此接口 | 8 | P1 | 2.4 | 排序功能可用 |
|
||||
|
||||
## 阶段三：异步任务与 AI 集成 (第6~7周)
|
||||
|
||||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||||
|----|------|--------|---------|--------|------|--------|
|
||||
| 3.1 | AI 调用适配器 | - 设计工厂模式，支持 openai, azure, custom<br>- 实现各供应商的请求构建和响应解析<br>- 编写异步调用函数（httpx）<br>- 支持超时、重试配置 | 32 | P0 | 2.2 | 可成功调用不同模型 |
|
||||
| 3.2 | 参考文件解析器 | - 实现提取 .txt, .docx, .pdf 文本内容的功能<br>- 使用 python-docx, PyPDF2 等库 | 16 | P0 | 1.4 | 提取文本成功 |
|
||||
| 3.3 | Celery 任务定义 | - **3.3.1** Celery 配置与连接（4h）<br>- **3.3.2** 任务函数骨架（加载模板、获取生成点，按 order 排序）（8h）<br>- **3.3.3** 参考文件解析集成（4h）<br>- **3.3.4** AI 调用与结果插入（基于偏移量或 XPath）（12h）<br>- **3.3.5** 文档保存（docx）与状态更新（8h）<br>- **3.3.6** 异常处理与重试逻辑（12h）<br>**合计** | 48 | P0 | 3.1, 3.2, 2.3, 2.4, 2.5 | 可端到端生成文档 |
|
||||
| 3.4 | 任务管理 API | - 触发生成任务接口（创建 task 记录，启动 Celery）<br>- 查询任务状态（含进度百分比）<br>- 下载结果接口（支持 docx 和 pdf）<br>- 取消任务接口（可选） | 20 | P0 | 3.3 | 任务管理可用 |
|
||||
| 3.5 | 单个生成点测试功能 | - 提供 API 允许用户测试单个生成点（不保存文档）<br>- 返回 AI 生成结果预览（可返回纯文本或HTML）<br>- 前端在标注弹窗中增加“测试”按钮，展示结果 | 16 | P1 | 3.1, 3.2 | 单点测试可用 |
|
||||
|
||||
## 阶段四：前端开发 (第5~9周，与后端并行)
|
||||
|
||||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||||
|----|------|--------|---------|--------|------|--------|
|
||||
| 4.1 | 页面路由与布局 | - 使用 React Router 定义路由（/templates, /editor/:id, /models, /tasks, /settings）<br>- 整体布局（侧边栏 + 内容区） | 12 | P0 | 1.2 | 框架搭建 |
|
||||
| 4.2 | 模型管理页面 | - 列表展示（表格 + 分页）<br>- 新建/编辑弹窗表单（含供应商、API Key、扩展参数JSON编辑器）<br>- 启用/禁用开关<br>- 删除确认<br>- 设置全局默认模型（单选按钮） | 24 | P0 | 2.2 | 模型管理交互完整 |
|
||||
| 4.3 | 模板列表与上传 | - 列表页面（卡片或表格，含名称、创建时间、操作按钮）<br>- 上传文件组件（支持拖拽，仅 .docx）<br>- 点击“编辑”跳转到编辑器页 | 16 | P0 | 2.3 | 可上传和查看模板 |
|
||||
| 4.4 | 模板编辑器（核心） | **拆解为以下子任务**：<br>- **4.4.1** 集成 TinyMCE，加载 HTML 内容，保存时调用更新接口（8h）<br>- **4.4.2** 实现选区监听与高亮标注（监听 mouseup，显示浮动按钮“设为AI生成点”）（12h）<br>- **4.4.3** 生成点弹窗表单：提示词、参考文件上传（拖拽）、模型下拉（独立选择），并集成“测试”按钮（调用3.5）（16h）<br>- **4.4.4** 生成点列表（右侧面板），显示每个点的摘要，支持删除、编辑（修改弹窗）（8h）<br>- **4.4.5** 标注区域与实际选区偏移量同步（确保插入位置准确）（4h）<br>- **4.4.6** 支持拖拽排序生成点（使用 react-beautiful-dnd 等），更新顺序（4h）<br>**合计** | 52 | P0 | 4.3, 2.4, 4.2, 3.5, 2.5 | 可编辑并标注 |
|
||||
| 4.5 | 生成任务执行与监控 | - 页面内“生成文档”按钮（可放在编辑器底部或工具栏）<br>- 弹出确认框，显示所有生成点列表（可勾选跳过个别）<br>- 提交后显示任务进度条（轮询状态，含进度百分比）<br>- 完成后自动显示下载按钮（支持 docx 和 pdf 格式切换） | 28 | P0 | 3.4 | 完整生成流程 |
|
||||
| 4.6 | 任务历史页面 | - 表格列出所有任务（模板名称、状态、开始/完成时间）<br>- 状态为“已完成”的可以下载（格式选择）<br>- 状态为“进行中”的显示进度，可取消（可选） | 16 | P1 | 3.4 | 任务可追溯 |
|
||||
| 4.7 | 系统设置页面 | - 展示可编辑的系统配置（全局默认模型、最大并发数、超时时间等）<br>- 调用后端接口读写 system_config | 12 | P1 | 2.2 | 设置可用 |
|
||||
|
||||
## 阶段五：测试与优化 (第10~11周)
|
||||
|
||||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||||
|----|------|--------|---------|--------|------|--------|
|
||||
| 5.1 | 集成测试 | - 端到端测试（上传 → 标注（含拖拽排序）→ 单点测试 → 生成 → 下载）<br>- 测试不同供应商模型调用<br>- 测试参考文件多种格式（txt, docx, pdf）<br>- 测试导出 PDF 功能<br>- 异常场景（网络超时、文件损坏、AI 返回错误） | 48 | P0 | 所有前序 | 功能稳定 |
|
||||
| 5.2 | 性能调优 | - 优化大文档转换速度（异步处理）<br>- 数据库查询添加索引（template_id, status）<br>- 调整 Celery 并发参数<br>- 优化前端渲染（虚拟列表等） | 16 | P1 | 5.1 | 响应达标 |
|
||||
| 5.3 | 安全加固 | - 检查 API Key 加密流程<br>- 文件上传类型和大小限制（限制50MB）<br>- 添加 CORS 配置<br>- 输入校验（防止 XSS） | 8 | P0 | 5.1 | 安全合规 |
|
||||
| 5.4 | 文档编写 | - 用户手册（操作指南，含截图）<br>- 部署文档（Docker 详细步骤）<br>- API 文档（由 FastAPI 自动生成，补充说明） | 24 | P1 | - | 交付文档完整 |
|
||||
|
||||
## 阶段六：部署上线 (第12周)
|
||||
|
||||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||||
|----|------|--------|---------|--------|------|--------|
|
||||
| 6.1 | Docker 化所有服务 | - 编写 Dockerfile（后端、前端、Celery）<br>- 编写 docker-compose.yml 整合所有服务（postgres, redis, backend, celery-worker, nginx） | 16 | P0 | 所有 | 可容器化运行 |
|
||||
| 6.2 | 生产环境配置 | - 配置环境变量（数据库、Redis、密钥等）<br>- 配置 Nginx 反向代理（前端静态 + 后端 API 转发）<br>- 配置 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 人并行开发）
|
||||
|
||||
---
|
||||
|
|
@ -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 证书。
|
||||
|
|
@ -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` 上建索引，优化列表查询。
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
# 部署指南 (Docker Compose)
|
||||
## 前置条件
|
||||
- Linux 服务器（或 Windows WSL2）
|
||||
- Docker 和 Docker Compose 已安装
|
||||
- 域名（可选）和 SSL 证书（可选）
|
||||
## 步骤
|
||||
### 1. 克隆代码
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
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. 运行数据库迁移（如有）
|
||||
Loading…
Reference in New Issue