zwt13703
193 lines
4.8 KiB
Markdown
193 lines
4.8 KiB
Markdown
# doc-forge
|
||
|
||
上传 Word 模板 → AI 逐段落生成 → 预览编辑 → 导出尽量保留原始样式的 Word 文档。
|
||
|
||
## 技术栈
|
||
|
||
- **前端**: Vue 3.4 + Vite 5 + TypeScript + Ant Design Vue 4.x + Pinia + Axios
|
||
- **后端**: Python 3.11+ + FastAPI + SQLAlchemy 2.0 async
|
||
- **数据库**: MySQL 8.0（asyncmy 驱动）
|
||
- **对象存储**: MinIO（模板 / 参考文件 / 导出文档）
|
||
- **文档处理**: python-docx、openpyxl
|
||
|
||
## 当前可用能力
|
||
|
||
- 上传 `.docx` 模板并按 Heading 1~6 解析段落
|
||
- 在模板编辑页配置段落的编辑方式、模型、提示词、文件要求、输出格式
|
||
- 管理模型配置，API Key 以加密形式存储，前端仅显示脱敏内容
|
||
- 执行整份文档生成：已支持按模型配置发起真实调用，异常时自动回退为模拟结果
|
||
- 生成过程中支持 SSE 进度推送与取消生成
|
||
- 查看生成记录与预览页真实结果
|
||
- 导出 Word：基于原模板替换标题下内容并生成可下载文件
|
||
|
||
## 运行方式
|
||
|
||
推荐开发方式：`Docker 启动依赖 + 本地启动前后端`
|
||
|
||
### 1. 启动 MySQL 和 MinIO
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
docker compose up -d mysql minio
|
||
```
|
||
|
||
启动后可访问：
|
||
|
||
- MySQL: `localhost:3306`
|
||
- MinIO API: `http://localhost:9000`
|
||
- MinIO Console: `http://localhost:9001`
|
||
|
||
默认账号：
|
||
|
||
- MinIO 用户名: `docforge`
|
||
- MinIO 密码: `docforge123`
|
||
|
||
### 2. 启动后端
|
||
|
||
```bash
|
||
cd /Users/zhouwentao/Workspaces/Yangliu/doc-forge/backend
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
后端地址：
|
||
|
||
- API 根地址: `http://localhost:8000`
|
||
- 健康检查: `http://localhost:8000/health`
|
||
|
||
后端默认读取 [backend/.env](/Users/zhouwentao/Workspaces/Yangliu/doc-forge/backend/.env)：
|
||
|
||
```env
|
||
DEBUG=True
|
||
|
||
DB_HOST=localhost
|
||
DB_PORT=3306
|
||
DB_USER=docforge
|
||
DB_PASSWORD=docforge123
|
||
DB_NAME=doc_forge
|
||
|
||
MINIO_ENDPOINT=localhost:9000
|
||
MINIO_ACCESS_KEY=docforge
|
||
MINIO_SECRET_KEY=docforge123
|
||
MINIO_USE_SSL=False
|
||
|
||
ENCRYPTION_KEY=change-this-to-a-32-byte-key-in-production!!
|
||
```
|
||
|
||
### 3. 启动前端
|
||
|
||
```bash
|
||
cd /Users/zhouwentao/Workspaces/Yangliu/doc-forge/web
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
前端地址：
|
||
|
||
- `http://localhost:5173`
|
||
|
||
### 4. 初步使用流程
|
||
|
||
1. 打开“模板管理”，上传一个 `.docx` 模板。
|
||
2. 进入模板编辑页，为段落配置 AI / 手动、提示词、模型等。
|
||
3. 打开“模型管理”，添加至少一个模型配置。
|
||
4. 打开“执行生成”，选择模板并发起生成。
|
||
5. 到“生成记录”查看历史，点击“预览”查看实际生成内容。
|
||
6. 在预览页点击“导出 Word”下载导出文件。
|
||
|
||
## Docker 全套启动
|
||
|
||
如果想直接用 Docker 跑全套，可以在项目根目录准备 `.env`：
|
||
|
||
```env
|
||
ENCRYPTION_KEY=change-this-to-a-32-byte-key-in-production!!
|
||
```
|
||
|
||
然后执行：
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
暴露端口：
|
||
|
||
- 前端: `5173`
|
||
- 后端: `8000`
|
||
- MinIO: `9000`
|
||
- MinIO Console: `9001`
|
||
- MySQL: `3306`
|
||
|
||
## 常见问题
|
||
|
||
### `.idea` 不小心提交了怎么办？
|
||
|
||
不影响项目运行，但建议尽快移除并加入忽略：
|
||
|
||
```bash
|
||
echo ".idea/" >> .gitignore
|
||
git rm -r --cached .idea
|
||
git add .gitignore
|
||
git commit -m "移除 IDE 配置文件"
|
||
```
|
||
|
||
### 为什么我本地 `python main.py` 报缺少模块？
|
||
|
||
说明当前 Python 环境还没安装依赖，先执行：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
推荐用虚拟环境：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
### 为什么导出 PDF 还不可用？
|
||
|
||
当前阶段已经支持基础 Word 导出，PDF 导出还未接入 LibreOffice 转换流程。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
doc-forge/
|
||
├── web/ Vue 3 前端
|
||
│ └── src/
|
||
│ ├── views/ 页面
|
||
│ ├── components/ 通用组件
|
||
│ ├── api/ Axios 请求层
|
||
│ ├── stores/ Pinia 状态管理
|
||
│ └── router/ 路由配置
|
||
├── backend/ Python FastAPI 后端
|
||
│ ├── models/ ORM 数据模型
|
||
│ ├── routers/ API 路由
|
||
│ ├── schemas/ Pydantic 校验
|
||
│ ├── services/ 业务逻辑层
|
||
│ ├── config.py 配置
|
||
│ └── database.py 异步数据库引擎
|
||
├── docker-compose.yml MySQL + MinIO + 后端 + 前端
|
||
├── init.sql 数据库初始化 SQL
|
||
└── docs/ 项目文档
|
||
```
|
||
|
||
## 核心流程
|
||
|
||
```text
|
||
上传模板 → 解析段落 → 标注配置 → 保存模板
|
||
→ 执行生成（上传文件 → AI 生成）
|
||
→ 预览编辑 → 导出 Word
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Python 3.11+
|
||
- Node.js 18+
|
||
- pnpm 8+
|
||
- Docker + Docker Compose
|
||
- LibreOffice（可选，用于未来的 PDF 导出）
|