---
name: ai-doc-template-system
description: "通用型 AI 文档模板生成系统 — Word 模板标注与 AI 文档生成平台。触发：需要建设/开发/维护 AI 文档模板生成平台时使用。"
version: 1.0.0
metadata:
  hermes:
    tags: [文档生成, AI, Word模板, 系统建设, FastAPI, Vue3]
    related_skills: [requirements-analysis, task-splitting-methodology, prototype-design]
---

# AI 文档模板生成系统

> 一个面向多类文档的"模板管理 + 提示词配置 + AI 内容生成 + Word 样式回填"平台。

---

## 系统定位

本系统**不是一个**纯 Word 在线编辑器，而是一个 Word 模板标注器：

1. 用户上传 Word → 系统自动解析标题/段落/表格 → 生成预览 HTML
2. 用户点击文档中的某个区域 → 左侧显示配置表单
3. 用户配置区域名称、区域类型、数据来源、提示词、输出格式、审核要求
4. 保存配置后，该区域成为 AI 可生成区域
5. 后续生成文档时，AI 根据各区域提示词生成内容并回填到原 Word

---

## 技术架构

| 层 | 选型 | 说明 |
|---|------|------|
| 前端 | Vue3 + Vite + Ant Design Vue + Pinia | 组件化单页应用 |
| 后端 | Python FastAPI | RESTful API |
| 数据库 | MySQL 8.0 + SQLAlchemy + Alembic | 关系型数据 |
| 文件存储 | MinIO / 本地文件系统 | 模板和资料文件 |
| 文档解析 | python-docx | 读取 Word 结构 |
| 模板回填 | python-docx-template | 内容回填 Word |
| AI 集成 | 大模型 API + LangChain | 内容生成 |
| 容器化 | Docker + Docker Compose | 一键部署 |

---

## 目录结构

```
ai-doc-template/
├── backend/
│   ├── app/
│   │   ├── main.py           # FastAPI 入口 + CORS
│   │   ├── database.py       # MySQL + SQLAlchemy
│   │   ├── models/           # SQLAlchemy Model 定义
│   │   ├── api/              # RESTful 路由
│   │   ├── services/         # 业务逻辑层
│   │   └── schemas/          # Pydantic 请求/响应
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── views/            # 页面级组件
│   │   ├── components/       # 业务组件
│   │   ├── stores/           # Pinia 状态管理
│   │   ├── api/              # Axios API 客户端
│   │   └── styles/           # 全局样式变量
│   └── package.json
├── docker-compose.yml
├── .env.example
└── README.md
```

---

## 数据库表

详见 `后端开发 > 数据模型`，核心三张表：

### template — 模板

| 字段 | 说明 |
|------|------|
| id, name, type, version | 基本信息 |
| original_file_path | 原始 docx 存储路径 |
| status | 1=启用, 0=停用 |

### template_block — 文档区域

| 字段 | 说明 |
|------|------|
| template_id | 所属模板 |
| block_id | 唯一标识（block_001） |
| block_type | title/heading/paragraph/table |
| level | 层级（0/1/2） |
| parent_block_id | 父级 |
| table_rows, table_cols | 表格行列 |

### block_config — 区域配置

| 字段 | 说明 |
|------|------|
| template_id + block_id | 联合唯一键 |
| region_type | ai_generate/manual/fixed/table |
| prompt | 提示词 |
| data_sources | 数据来源列表（JSON） |
| need_review | 是否需要审核 |

---

## API 接口清单

### 模板
- `POST /api/templates/upload` — 上传 docx
- `GET  /api/templates/{id}` — 模板详情（含预览 HTML + blocks + 配置）

### 区域配置
- `POST /api/templates/{id}/blocks/{blockId}/config` — 保存/更新区域配置
- `GET  /api/data-sources` — 数据源列表
- `POST /api/data-sources` — 新增数据源

### 生成（后续阶段）
- `POST /api/templates/{id}/generate-test` — 生成测试
- `GET  /api/tasks/{id}/download-docx` — 下载 Word
- `GET  /api/tasks/{id}/download-pdf` — 下载 PDF

---

## 开发任务（第一阶段 MVP）

共 **73 个任务**，按模块分组：

| 模块 | 任务数 | 核心产出 |
|------|:------:|---------|
| 环境搭建 | 11 | FastAPI + Vue3 项目骨架 + Docker |
| 数据库建表 | 3 | template, template_block, block_config |
| 模板上传 | 4 | 文件接收校验 → 存储 → 入库 |
| Word 解析 | 7 | 标题/段落/表格识别 → block_id → 结构树 |
| HTML 预览 | 4 | heading/paragraph/table 转 HTML |
| 查询+配置接口 | 4 | 详情查询、配置保存、数据源 |
| 四栏布局 | 6 | 菜单/工具栏/预览/配置/树 shell |
| 左侧菜单 | 3 | 数据模型、展开收起、高亮 |
| 工具栏 | 4 | 面包屑、版本号、保存状态、操作按钮 |
| Word 预览区 | 7 | v-html渲染、点击、高亮、颜色、标签、缩放 |
| 结构树 | 4 | 递归组件、展开折叠、状态圆点、滚动联动 |
| 配置面板 | 9 | 名称/类型/数据源/提示词/审核/备注/保存 |
| Pinia Store | 3 | templateStore, selectionStore, uiStore |
| 三区联动 | 4 | watch 驱动的配置加载、树同步、loading |

详见 `docs/tasks-v3.md`

---

## 开发阶段规划

### 第一阶段：模板标注 MVP（3-4 周）

核心流程：上传 Word → 解析 → 预览 → 点击配置 → 保存

交付物：
- 可用的模板编辑页面（四栏布局）
- Word 解析服务（标题/段落/表格）
- 区域配置面板（类型/提示词/数据来源）
- 结构树联动

### 第二阶段：生成测试（1-2 周）

- 上传资料 → AI 逐区域生成 → 预览结果 → 人工编辑

### 第三阶段：回填导出（1-2 周）

- block 回填原始 Word → Word/PDF 导出

### 第四阶段：高级功能（2-3 周）

- 提示词历史、数据源管理、审核流程

---

## 关键设计决策

| 决策 | 原因 |
|------|------|
| 不做 Word→HTML→Word 转换 | 格式丢失严重，Word 做底座 |
| HTML 只预览，docx 负责导出 | 分离预览和最终输出 |
| block_id 作为统一索引 | 解析、配置、生成、回填共享同一定位 |
| 分阶段迭代 | MVP 先跑通标注流程 |
| python-docx 而非 docxtpl | 第一版需要精确位置控制 |