补充运行说明并实现基础导出能力
This commit is contained in:
zwt13703
@@ -1,80 +1,191 @@
|
||||
# doc-forge
|
||||
|
||||
上传 Word 模板 → AI 逐段落生成 → 导出保留原始样式的 Word 文档。
|
||||
上传 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（模板/参考文件/导出文档）
|
||||
- **对象存储**: MinIO（模板 / 参考文件 / 导出文档）
|
||||
- **文档处理**: python-docx、openpyxl
|
||||
|
||||
## 快速开始
|
||||
## 当前可用能力
|
||||
|
||||
- 上传 `.docx` 模板并按 Heading 1~6 解析段落
|
||||
- 在模板编辑页配置段落的编辑方式、模型、提示词、文件要求、输出格式
|
||||
- 管理模型配置，API Key 以加密形式存储，前端仅显示脱敏内容
|
||||
- 执行整份文档的模拟生成
|
||||
- 查看生成记录与预览页真实结果
|
||||
- 导出 Word：基于原模板替换标题下内容并生成可下载文件
|
||||
|
||||
## 运行方式
|
||||
|
||||
推荐开发方式：`Docker 启动依赖 + 本地启动前后端`
|
||||
|
||||
### 1. 启动 MySQL 和 MinIO
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```bash
|
||||
# 1. 启动基础设施（MySQL + MinIO）
|
||||
docker-compose up -d mysql minio
|
||||
docker compose up -d mysql minio
|
||||
```
|
||||
|
||||
# 2. 启动后端
|
||||
cd backend
|
||||
启动后可访问：
|
||||
|
||||
- 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
|
||||
python main.py
|
||||
# → http://localhost:8000/docs Swagger
|
||||
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
# 3. 启动前端
|
||||
cd web
|
||||
后端地址：
|
||||
|
||||
- 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
|
||||
```
|
||||
|
||||
前端地址：
|
||||
|
||||
- `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/ 6 个页面
|
||||
│ ├── components/ 6 个通用组件
|
||||
│ ├── views/ 页面
|
||||
│ ├── components/ 通用组件
|
||||
│ ├── api/ Axios 请求层
|
||||
│ ├── stores/ Pinia 状态管理
|
||||
│ └── router/ 路由配置
|
||||
├── backend/ Python FastAPI 后端
|
||||
│ ├── app/models/ ORM 数据模型
|
||||
│ ├── app/routers/ API 路由
|
||||
│ ├── app/schemas/ Pydantic 校验
|
||||
│ ├── app/services/ 业务逻辑层
|
||||
│ ├── models/ ORM 数据模型
|
||||
│ ├── routers/ API 路由
|
||||
│ ├── schemas/ Pydantic 校验
|
||||
│ ├── services/ 业务逻辑层
|
||||
│ ├── config.py 配置
|
||||
│ └── database.py 异步数据库引擎
|
||||
├── docker-compose.yml MySQL + MinIO + 后端 + 前端
|
||||
├── init.sql 数据库建表 DDL
|
||||
├── init.sql 数据库初始化 SQL
|
||||
└── docs/ 项目文档
|
||||
```
|
||||
|
||||
## 核心流程
|
||||
|
||||
```
|
||||
```text
|
||||
上传模板 → 解析段落 → 标注配置 → 保存模板
|
||||
→ 执行生成（上传文件 → AI 并行生成 → SSE 进度）
|
||||
→ 预览编辑 → 导出 Word（保留原始样式）
|
||||
→ 执行生成（上传文件 → AI 生成）
|
||||
→ 预览编辑 → 导出 Word
|
||||
```
|
||||
|
||||
## 关键设计
|
||||
|
||||
| 决策 | 选择 | 原因 |
|
||||
|------|------|------|
|
||||
| 段落边界 | Word 标题样式 Heading 1~6 | 稳定可靠，用户学习成本低 |
|
||||
| AI 输出 | 结构化 JSON | 支持文字+表格混合，后端可控解析 |
|
||||
| 导出策略 | 基于原模板替换内容 | 样式零损失，不限模板格式 |
|
||||
| 文件存储 | MinIO 对象存储 | 可扩展，不占用本地磁盘 |
|
||||
| 数据库 | MySQL 8.0 | 生产级可靠性 |
|
||||
| 生成方式 | 多段落并行 asyncio.gather | 大幅缩短等待时间 |
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Python 3.11+
|
||||
- Node.js 18+
|
||||
- pnpm 8+
|
||||
- Docker + docker-compose（MySQL + MinIO）
|
||||
- LibreOffice（可选，用于 PDF 导出）
|
||||
- Docker + Docker Compose
|
||||
- LibreOffice（可选，用于未来的 PDF 导出）
|
||||
|
||||
Reference in New Issue
Block a user