doc-forge-reborn/docs/技术方案概述.md

技术方案概述

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 证书。