# 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 导出）