doc-forge/README.md

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

在项目根目录执行：

docker compose up -d mysql minio

启动后可访问：

• MySQL: localhost:3306
• MinIO API: http://localhost:9000
• MinIO Console: http://localhost:9001

默认账号：

• MinIO 用户名: docforge
• MinIO 密码: docforge123

2. 启动后端

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：

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. 启动前端

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：

ENCRYPTION_KEY=change-this-to-a-32-byte-key-in-production!!

然后执行：

docker compose up -d

暴露端口：

• 前端: 5173
• 后端: 8000
• MinIO: 9000
• MinIO Console: 9001
• MySQL: 3306

常见问题

.idea 不小心提交了怎么办？

不影响项目运行，但建议尽快移除并加入忽略：

echo ".idea/" >> .gitignore
git rm -r --cached .idea
git add .gitignore
git commit -m "移除 IDE 配置文件"

为什么我本地 python main.py 报缺少模块？

说明当前 Python 环境还没安装依赖，先执行：

pip install -r requirements.txt

推荐用虚拟环境：

python3 -m venv .venv
source .venv/bin/activate

为什么导出 PDF 还不可用？

当前阶段已经支持基础 Word 导出，PDF 导出还未接入 LibreOffice 转换流程。

目录结构

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/                   项目文档

核心流程

上传模板 → 解析段落 → 标注配置 → 保存模板
    → 执行生成（上传文件 → AI 生成）
    → 预览编辑 → 导出 Word

环境要求

• Python 3.11+
• Node.js 18+
• pnpm 8+
• Docker + Docker Compose
• LibreOffice（可选，用于未来的 PDF 导出）