# 技术方案概述
## 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 证书。