# AI 文档模板生成系统

> 通用型 AI 文档模板配置与生成平台 — 上传 Word 模板 → 自动解析结构 → 配置 AI 生成规则 → 分章节生成内容 → 回填 Word 模板 → 导出 Word/PDF。

---

## 一句话定位

**Word 模板标注器**：上传 Word 后，系统在页面中间展示文档预览，为每个标题/段落/表格生成唯一 block_id。用户点击预览区某个区域后，左侧显示该区域的提示词配置表单，可设置区域类型、数据来源、提示词、输出格式和审核要求。右侧显示文档结构树，与预览区联动。保存配置后，该区域成为 AI 可生成区域。

---

## 技术栈

| 层 | 技术 | 版本要求 |
|---|------|---------|
| 前端框架 | Vue 3 | ^3.4 |
| 构建工具 | Vite | ^5.x |
| UI 组件库 | Ant Design Vue | ^4.x |
| 状态管理 | Pinia | ^2.x |
| 路由 | Vue Router 4 | ^4.x |
| 后端框架 | Python FastAPI | ^0.110 |
| Python 版本 | Python 3.11+ | |
| 数据库 | MySQL 8.0 | |
| 缓存 | Redis 7.x | 可选 |
| 对象存储 | MinIO | |
| 文档解析 | python-docx | ^1.1 |
| 模板回填 | python-docx-template | ^1.0 |
| PDF 转换 | LibreOffice 无头模式 | |
| 容器化 | Docker + Docker Compose | |

---

## 目录结构

```
ai-doc-template/
├── README.md
├── SKILL.md                    # Hermes 技能文件
├── AGENTS.md                   # AI 编码助手指引
├── .gitignore
├── .env.example
├── docker-compose.yml
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app/
│       ├── __init__.py
│       ├── main.py             # 应用入口 + FastAPI 实例
│       ├── database.py         # 数据库连接 + Session
│       ├── models/
│       │   ├── __init__.py
│       │   ├── template.py     # template 表 Model
│       │   ├── template_block.py
│       │   └── block_config.py
│       ├── api/
│       │   ├── __init__.py
│       │   ├── templates.py    # 模板上传/查询接口
│       │   ├── blocks.py       # 区域配置接口
│       │   └── data_sources.py # 数据源管理接口
│       ├── services/
│       │   ├── __init__.py
│       │   ├── storage.py      # MinIO 文件存储
│       │   ├── template_service.py
│       │   ├── doc_parser.py   # Word 解析引擎
│       │   └── html_generator.py # HTML 预览生成
│       └── schemas/
│           ├── __init__.py
│           └── template.py     # Pydantic 模型
├── frontend/
│   ├── Dockerfile
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── index.html
│   └── src/
│       ├── main.ts             # 入口 + 插件注册
│       ├── App.vue
│       ├── router/
│       │   └── index.ts        # 路由配置
│       ├── stores/
│       │   ├── templateStore.ts
│       │   ├── selectionStore.ts
│       │   └── uiStore.ts
│       ├── api/
│       │   └── base.ts         # Axios 实例
│       ├── styles/
│       │   └── variables.css   # 全局 CSS 变量
│       ├── views/
│       │   ├── TemplateCenter.vue
│       │   └── TemplateEdit.vue
│       └── components/
│           └── TemplateEdit/
│               ├── LeftMenu.vue
│               ├── TopToolbar.vue
│               ├── WordPreview.vue
│               ├── ConfigPanel.vue
│               └── StructureTree.vue
└── docs/
    └── architecture.md
```

---

## 快速开始

### 前置依赖

- Docker & Docker Compose
- Python 3.11+
- Node.js 18+
- LibreOffice（可选，PDF 导出需要）

### 启动后端

```bash
# 1. 启动 MySQL + MinIO
docker compose up -d mysql minio

# 2. 安装后端依赖
cd backend
pip install -r requirements.txt

# 3. 复制环境变量
cp ../.env.example .env

# 4. 初始化数据库
alembic upgrade head

# 5. 启动后端
uvicorn app.main:app --reload --port 8000
```

### 启动前端

```bash
cd frontend
npm install
npm run dev
```

### 访问

- 前端页面：http://localhost:5173
- API 文档：http://localhost:8000/docs
- MinIO Console：http://localhost:9001

---

## 开发阶段

| 阶段 | 目标 | 预估 |
|------|------|:----:|
| 第一阶段：模板标注 MVP | 上传 Word → 解析 → 预览 → 点击配置 → 保存 | 3-4 周 |
| 第二阶段：生成测试 | 上传资料 → AI 逐区域生成 → 预览结果 | 1-2 周 |
| 第三阶段：回填导出 | block 回填 → Word/PDF 导出 | 1-2 周 |
| 第四阶段：高级功能 | 提示词历史、数据源管理、审核流程等 | 2-3 周 |

---

## 核心流程

### 创建模板

```
上传 Word → 保存原始文件 → 解析标题/段落/表格 → 生成 block_id
→ 生成 HTML 预览 → 用户点击段落 → 配置提示词 → 保存配置
```

### 生成文档

```
选择模板 → 上传资料 → AI 提取结构化数据 → 按区域逐块生成
→ 人工审核修改 → 回填 Word 模板 → 导出 Word/PDF
```

---

## 数据库核心表

| 表名 | 说明 |
|------|------|
| template | 模板基本信息、文件路径、版本 |
| template_block | 解析出的文档区域（标题/段落/表格），含 block_id 和层级 |
| block_config | 用户为每个区域配置的提示词、类型、数据来源等 |
| data_source | 数据源配置 |

---

## 设计原则

1. **Word 保持版式，系统管理结构，AI 生成内容**
2. **HTML 只负责预览和交互，原始 docx 负责最终导出**
3. **block_id 是关键索引**：所有功能（点击、配置、生成、回填）都围绕 block_id
4. **先提取、再生成、再审核、再回填**，不把资料一次性扔给 AI
5. **第一版不做在线 Word 编辑**，聚焦标注和配置