init: 初始化项目

2026-07-08 20:02:29 +08:00
parent 22590ae7b8
commit 1bb84df4ca
98 changed files with 8535 additions and 2 deletions
@@ -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,78 @@
+# 任务执行摘要
+
+## 会话 ID: 1
+- [2026-07-06 16:00]
+- **执行原因**: 用户要求按任务拆解清单逐步实施项目开发，先完成阶段一和阶段二
+- **执行过程**:
+    1. 创建项目目录结构（backend/, web/, storage/）。
+    2. 编写 docker-compose.yml（Postgres 18.3 + Redis 7）、.env.example、requirements.txt。
+    3. 实现 backend/app/core/ 核心模块：config（pydantic-settings）、database（SQLAlchemy async engine + session）、security（Fernet 加密）。
+    4. 创建 5 个 ORM 模型：AIModel、Template、GenerationPoint、GenerationTask、SystemConfig + Base/TimestampMixin/UUIDMixin。
+    5. 配置 Alembic（alembic.ini, env.py, script.py.mako）。
+    6. 编写 FastAPI 入口 main.py（CORS + health 端点）。
+    7. 实现文件存储服务 file_storage.py（上传/下载/删除）。
+    8. 初始化前端项目（Vite + React 18 + TypeScript + Ant Design + React Router），侧边栏布局 + 5 个占位页面。
+    9. 编写 4 组 Pydantic Schemas（ai_model, template, generation_point, generation_task）。
+    10. 实现文档处理服务 document_processor.py（Mammoth docx→HTML、python-docx HTML→docx、reportlab docx→PDF）。
+    11. 实现 AI 模型管理 API（CRUD + 启用/禁用切换，6 个端点）。
+    12. 实现模板管理 API（上传/获取HTML/更新HTML/下载docx+pdf，6 个端点）。
+    13. 实现生成点管理 API（CRUD + 参考文件上传 + 批量排序更新，5 个端点）。
+    14. 注册路由（api/router.py），更新 main.py，启动验证通过（/health 返回 OK）。
+- **执行结果**: 
+    - 阶段一（基础设施）：45 个文件，后端 5 张表模型导入正常，前端 TypeScript 编译零错误。
+    - 阶段二（核心业务 API）：17 个 API 端点全部注册，后端启动正常，`/health` 返回 200 OK。
+    - Git 提交：2 次提交（b5fa343, aa84521）。
+
+## 会话 ID: 2
+- [2026-07-06 16:15]
+- **执行原因**: 完成阶段三（异步任务与 AI 集成）和阶段四（前端开发）
+- **执行过程**:
+    1. 实现 AI 调用适配器 `ai_adapter.py`：工厂模式支持 openai/azure/custom 三种供应商，httpx 异步调用。
+    2. 实现参考文件解析器 `ref_parser.py`：提取 txt/docx/pdf 文本内容。
+    3. 编写 Celery 配置 `celery_app.py` + 异步生成任务 `generate.py`（模板加载→生成点排序→参考解析→AI调用→HTML插入→文档保存→状态更新）。
+    4. 实现任务管理 API：触发生成/查询状态/下载结果(docx+pdf)/取消任务/单点测试。
+    5. 注册全部 23 个 API 端点，后端启动验证通过。
+    6. 前端 API 层：axios 封装 + 4 组 API 调用（models/templates/generationPoints/tasks）。
+    7. TypeScript 类型定义（AIModel/Template/GenerationPoint/GenerationTask）。
+    8. 模型管理页面：表格 + 新增/编辑弹窗 + 启用切换 + 删除。
+    9. 模板列表页面：表格 + docx 上传 + 在线编辑/下载/删除。
+    10. 模板编辑器（核心）：TinyMCE 自托管 + 选区监听浮动标注 + 生成点弹窗 + 右侧面板（测试/编辑/删除）+ 触发生成任务 + 进度轮询 + 结果下载。
+    11. 任务历史页面：状态标签 + 下载 + 取消。
+    12. 系统设置页面：默认模型/并发/超时配置。
+    13. Vite 配置 API 代理(3000→8000) + TinyMCE 自托管。
+    14. 修复 docker-compose（postgres:18.3→16-alpine）+ Alembic 初始迁移。
+    15. 启动全套服务（PostgreSQL + Redis + Backend + Frontend），前端页面可正常访问。
+- **执行结果**:
+    - 后端 23 个 API 端点，前端 5 个页面完成，TypeScript 零错误，Vite 构建成功。
+    - 服务全部启动：前端 http://localhost:3000 返回 200，后端 /api/v1/models 返回正常。
+    - Git 提交：3 次提交（afabb64, 985a861, 0b23858）。
+    - 总计 8 次提交，约 70 个文件。
+
+## 会话 ID: 3
+- [2026-07-06 16:45]
+- **执行原因**: 完成阶段五（部署上线与安全加固）
+- **执行过程**:
+    1. 添加 `postinstall` 脚本自动复制 TinyMCE 自托管文件。
+    2. 编写 3 个 Dockerfile：backend (uvicorn)、celery-worker、web (多阶段 Node+Nginx)。
+    3. 重写 docker-compose.yml：完整 5 服务编排（postgres + redis + backend + celery + nginx）。
+    4. 编写 nginx.conf 反向代理配置 + gzip + API 代理。
+    5. 安全加固：请求体大小限制中间件、文件类型白名单校验(.docx/.txt/.pdf)、CORS 更新。
+    6. 添加 .dockerignore（backend + web）、deploy.sh 一键部署脚本。
+- **执行结果**:
+    - 后端 17 个端点 + 前端 TypeScript 编译通过 + Vite 构建成功。
+    - 生产部署：`docker compose up -d` 即可一键启动 5 个服务。
+    - Git 提交：1 次提交（017a195）。总计 14 次提交。
+
+## 会话 ID: 4
+- [2026-07-06 17:10]
+- **执行原因**: 补充完善剩余任务（拖拽排序、系统设置、安全加固、Celery验证、文档）
+- **执行过程**:
+    1. Celery Worker 启动验证：连接 Redis，`generate_document` 任务已注册并可通过 inspector 检测。
+    2. 生成点拖拽排序：HTML5 原生 Drag & Drop + `MenuOutlined` 拖拽手柄，拖拽后自动调用 `/batch-order` API。
+    3. 系统设置 API：新增 `/api/v1/settings` GET/PUT，前端 Settings 实时加载模型列表并持久化配置。
+    4. 安全加固：`bleach` HTML 净化过滤 script/onerror 等危险标签，文件类型白名单校验，请求大小限制中间件。
+    5. 修复 Fernet 加密：SHA256(SECRET_KEY) → base64url 派生合法 32 字节密钥。
+    6. 更新 README：修正技术栈版本，补充生产部署 + 本地开发完整步骤。
+- **执行结果**:
+    - API 端点 19 个，所有核心功能模块完成。
+    - 可通过 http://localhost:3000 进行端到端测试。
@@ -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-reborn
+```
+### 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. 运行数据库迁移（如有）