init

2026-07-02 14:48:05 +08:00
parent a1a314cf99
commit e558733f05
64 changed files with 3258 additions and 1 deletions
@@ -0,0 +1,40 @@
+# AI 文档模板生成系统 · 项目概述
+
+## 一句话
+上传 Word 模板 → AI 自动解析段落结构 → 配置各段落生成规则 → 上传参考文件 → AI 并行生成 → 在线预览编辑 → 导出保留原始样式的 Word 文档。
+
+## 核心架构
+```
+┌─────────────────────────────────────────────────────┐
+│                  前端 Vue 3 + Ant Design Vue         │
+│  模板管理  模型管理  执行生成  生成记录  预览编辑    │
+└────────────┬───────────────────────────┬────────────┘
+             │ REST API + SSE 进度       │
+             ▼                           ▼
+┌─────────────────────────────────────────────────────┐
+│              后端 FastAPI + SQLAlchemy               │
+│  模板解析 → 段落管理 → AI 调度 → 文档生成 → 导出    │
+└─────────────────────────────────────────────────────┘
+```
+
+## 核心流程（7步闭环）
+1. **上传模板** — 上传 .docx → 解析段落结构 + 完整样式 → 存库
+2. **段落标注** — 三栏编辑器：左栏点段落→中栏定位→右栏配置（编辑方式/模型/提示词/参考文件）
+3. **保存模板** — 段落配置持久化
+4. **执行生成** — 选模板 → 按需上传参考文件 → 启动生成
+5. **并行生成** — 无依赖段落同时请求 AI，SSE 实时推进度
+6. **预览编辑** — 富文本编辑器查看结果，手动精修
+7. **导出 Word** — 基于原模板替换内容，样式零损失
+
+## 关键设计决策
+| 决策 | 选择 | 原因 |
+|------|------|------|
+| 段落边界 | Word 内置标题样式 (Heading 1~6) | 最稳定，用户学习成本低 |
+| 输出格式 | AI 返回结构化 JSON | 支持文字+表格混合，后端可控解析 |
+| 导出策略 | 基于原模板替换内容 | 样式零损失，不限模板格式 |
+| 生成方式 | 多段落并行请求 AI | 大幅缩短等待时间 |
+| 样式保留 | 导出时读取原模板段落样式映射 | 精度最高 |
+
+## 技术栈
+- **前端**: Vue 3.4 + Vite 5 + TypeScript + Ant Design Vue 4.x + Pinia + Axios
+- **后端**: Python 3.11+ + FastAPI + SQLAlchemy 2.0 (async) + SQLite + python-docx + openpyxl + httpx
@@ -0,0 +1,182 @@
+# AI 文档模板生成系统 · 需求规格说明书
+
+## 一、功能需求
+
+### 1.1 模板管理
+| 功能 | 描述 | 优先级 |
+|------|------|--------|
+| 模板列表 | 卡片式展示所有模板，含名称、段落数、状态、最后编辑时间 | P0 |
+| 新建模板 | 上传 .docx 文件，自动解析段落结构 | P0 |
+| 模板编辑器（三栏） | 左栏段落列表、中栏文档预览、右栏段落配置 | P0 |
+| 段落标注 | 配置每个段落的编辑方式、模型、提示词、参考文件 | P0 |
+| 保存模板 | 将段落配置持久化到数据库 | P0 |
+
+### 1.2 模型管理
+| 功能 | 描述 | 优先级 |
+|------|------|--------|
+| 模型列表 | 卡片式展示所有 AI 模型，含启用/禁用开关 | P0 |
+| 添加/编辑模型 | 弹窗表单：名称、厂商、API 格式、地址、Key（加密存储） | P0 |
+| 默认模型分配 | 设置文本/表格/图表各自的默认生成模型 | P0 |
+
+### 1.3 执行生成
+| 功能 | 描述 | 优先级 |
+|------|------|--------|
+| 选择模板 | 下拉选择已保存的模板 | P0 |
+| 上传参考文件 | 按段落需上传的文件类型提示并上传 | P0 |
+| 开始生成 | 启动多段落并行 AI 生成 | P0 |
+| 实时进度 | SSE 推送每个段落的生成状态 | P0 |
+| 取消生成 | 中断正在进行的生成任务 | P1 |
+
+### 1.4 生成记录
+| 功能 | 描述 | 优先级 |
+|------|------|--------|
+| 统计卡片 | 总次数、成功、失败、中断 | P0 |
+| 历史列表 | 卡片式展示已生成文档 | P0 |
+| 筛选 | 按模板、按状态筛选 | P1 |
+| 预览 | 跳转到预览编辑页 | P0 |
+| 下载 | 下载已生成的 Word 文档 | P0 |
+
+### 1.5 预览编辑
+| 功能 | 描述 | 优先级 |
+|------|------|--------|
+| 富文本编辑 | 在线编辑文档内容 | P0 |
+| AI 内容标注 | AI 生成的段落标紫色边框+模型来源 | P0 |
+| 重新生成单段落 | 对某一段落单独重新请求 AI | P0 |
+| 导出 Word | 保留原始模板样式 | P0 |
+| 导出 PDF | 通过 LibreOffice 转换 | P1 |
+
+## 二、段落解析规则
+
+### 2.1 段落边界定义
+段落以 Word 内置标题样式为边界：
+
+```
+Heading 1  → 一级段落（如 "一、经营指标"）
+Heading 2  → 二级段落（如 "1.1 营收分析"）
+Heading 3  → 三级段落
+无标题样式 → 合并到上一个标题下的正文内容
+表格       → 独立段落，归属于前一个标题
+```
+
+### 2.2 标题下的正文内容
+标题与下一个标题之间的所有正文、表格、图片：
+- 作为该段落的 `content` 字段
+- 供 AI 生成时作为上下文参考
+- 导出时保留原样式
+
+### 2.3 AI 返回格式约定
+AI 输出必须是结构化 JSON：
+
+```json
+{
+  "content": [
+    {"type": "text", "text": "正文内容..."},
+    {"type": "table", "headers": ["列1","列2"], "rows": [["a","b"],["c","d"]]},
+    {"type": "text", "text": "更多正文..."}
+  ]
+}
+```
+
+后端解析逻辑：
+- type=text → 替换文档中对应段落的文本
+- type=table → 在对应位置插入 Word 表格，表格样式参照该段落附近已有表格
+
+### 2.4 正文内编号处理
+AI 生成的 1、2、3 编号属于该段落的内部子结构，不拆分为新段落。导出时作为该段落的正文内容，应用该段落的样式。
+
+## 三、导出策略
+
+采用 **基于原模板替换内容** 策略：
+
+1. 解析时记录每个段落在原始 docx 中的段落索引 + xpath
+2. 导出时复制原始模板文件
+3. 遍历每个段落，找到对应位置替换内容：
+   - 纯文本：替换 `<w:t>` 节点文本
+   - 表格：删除原有表格占位，插入新表格的 XML 节点
+4. 样式完全不修改（字体、字号、颜色、行距、段间距、页边距、页眉页脚、页码全部保留）
+
+## 四、AI 并行生成设计
+
+```
+用户点击"开始生成"
+        │
+        ▼
+解析模板段落依赖关系（当前无依赖，全部并行）
+        │
+        ▼
+创建 asyncio.Task 池，Semaphore 控制并发数（默认 5）
+        │
+        ├── 段落1 → AI 请求 → SSE 推送完成
+        ├── 段落2 → AI 请求 → SSE 推送完成  
+        ├── 段落3 → AI 请求 → SSE 推送完成
+        ├── 段落4 → AI 请求 → SSE 推送完成
+        └── 段落5 → AI 请求 → SSE 推送完成
+        │
+        ▼
+所有 Task 完成后，统一更新文档状态为 completed
+        │
+        ▼
+SSE 推送 "全部完成"，前端跳转到预览编辑
+```
+
+## 五、数据结构
+
+### 5.1 模板 (template)
+```
+id: int (PK)
+name: str
+description: str
+file_path: str          # 原始模板文件路径
+paragraph_count: int
+status: str            # draft / ready
+created_at: datetime
+updated_at: datetime
+```
+
+### 5.2 段落 (paragraph)
+```
+id: int (PK)
+template_id: int (FK)
+sort_index: int
+title: str             # 段落标题
+content: str           # 正文内容（供 AI 参考）
+style_json: json       # 完整样式定义
+is_table: bool
+table_json: json       # 表格结构
+edit_mode: str         # manual / ai
+model_id: int (FK, nullable)
+need_prompt: bool
+prompt_text: str
+need_file: bool
+file_note: str
+output_format: str     # text / table / mixed / chart
+created_at: datetime
+updated_at: datetime
+```
+
+### 5.3 AI 模型 (ai_model)
+```
+id: int (PK)
+name: str
+provider: str
+api_format: str        # anthropic / openai
+api_endpoint: str
+api_key_encrypted: str
+status: str            # enabled / disabled
+created_at: datetime
+updated_at: datetime
+```
+
+### 5.4 生成文档 (document)
+```
+id: int (PK)
+template_id: int (FK)
+name: str
+para_count_done: int
+para_count_total: int
+status: str            # pending / generating / completed / failed / cancelled
+file_path: str         # 生成的文档路径
+error: str
+created_at: datetime
+updated_at: datetime
+```
@@ -0,0 +1,133 @@
+# 模板格式规范
+
+## 一、对用户（模板提供方）的要求
+
+### 必须遵守
+| 要求 | 说明 |
+|------|------|
+| 标题样式 | 需要 AI 生成的段落，其标题必须应用 Word 内置标题样式（Heading 1~3） |
+| 段落独立性 | 每个标题段落的内容应当主题独立，方便 AI 分别生成 |
+
+### 强烈建议
+| 建议 | 说明 |
+|------|------|
+| 正文提供参考内容 | 标题下的现有文本可作为 AI 生成的上下文，建议保留 |
+| 表格上方有说明文字 | 表格前最好有一段文字说明，方便定位表格归属 |
+| 文件名中文 | 模板文件名建议用中文，方便识别 |
+
+### 不约束
+| 项 | 说明 |
+|----|------|
+| 字体/配色/布局 | 不限，导出时完全保留 |
+| 页眉页脚 | 不限，导出时完全保留 |
+| 图片 | 不限，解析时保留占位，导出时保持不动 |
+| 封面/附录 | 不限，不作为段落处理，导出时保留 |
+
+## 二、解析规则（面向开发）
+
+### 2.1 段落检测算法
+```
+for each paragraph in document.paragraphs:
+    style = paragraph.style.name
+    
+    if style starts with "Heading":
+        → 新段落开始
+        → style 等级 = heading level (1~6)
+        → 该段落为「标题段落」
+    elif style is "Normal" or None:
+        → 属于上一个标题段落的「正文内容」
+        → 追加到 paragraph.content
+    elif paragraph is inside a table cell:
+        → 属于表格内容，跳过段落检测
+```
+
+### 2.2 表格归属
+```
+当前检测到的表格 → 归属于最近的标题段落
+if 无标题段落:
+    → 独立成段，段名 = "表格_{序号}"
+```
+
+### 2.3 样式捕获字段
+对每个标题段落，捕获以下样式信息：
+```json
+{
+  "font": {
+    "name": "等线",
+    "eastAsia": "等线",
+    "size": 16,
+    "bold": true,
+    "italic": false,
+    "color": "000000"
+  },
+  "paragraph": {
+    "alignment": "CENTER",
+    "spaceBefore": 12,
+    "spaceAfter": 6,
+    "lineSpacing": 1.5,
+    "firstLineIndent": 0
+  },
+  "headingLevel": 1
+}
+```
+
+### 2.4 表格样式捕获
+```json
+{
+  "rows": 5,
+  "cols": 6,
+  "gridSpan": {},
+  "cellStyles": [
+    {
+      "font": {"name": "宋体", "size": 10.5, "bold": false},
+      "shading": "D9E2F3",
+      "alignment": "CENTER",
+      "borders": {"top": "single", "bottom": "single", "left": "single", "right": "single"}
+    }
+  ],
+  "tableWidth": 5000
+}
+```
+
+## 三、AI 输出解析规则
+
+### 3.1 强制输出 JSON
+```
+在 prompt 末尾附加：
+请以 JSON 格式返回，不要包含任何其他说明文字。
+{
+  "content": [
+    {"type": "text|table", ...}
+  ]
+}
+```
+
+### 3.2 JSON 解析
+```
+收到 AI 响应后：
+1. 尝试解析为 JSON
+2. 若解析失败，尝试从响应的 ```json ``` 代码块中提取
+3. 若仍然失败，将整个响应作为纯文本处理（type=text）
+```
+
+### 3.3 表格插入
+```
+当 type=table:
+1. 在原始 docx 中找到该段落后面的第一个表格占位
+2. 删除占位表格的 XML 节点
+3. 创建新表格（python-docx add_table）
+4. 逐格填充数据
+5. 应用模板中该位置的表格样式（边框、底纹、对齐）
+```
+
+## 四、段落编辑方式
+
+### 人工编辑
+- 段落内容完全由用户手动输入
+- 不参与 AI 生成流程
+- 导出时保留用户输入的内容
+
+### AI 生成
+- 参与 AI 生成流程
+- 可配置：生成模型、提示词、参考文件、输出格式
+- 生成后可在预览编辑页手动修改
@@ -0,0 +1,112 @@
+# AI 文档模板生成系统 · 任务拆解清单
+
+总工期估算：5-6 周（两人并行：前端 + 后端）
+
+## 第一阶段：架构与规范（第 1 周）
+
+- [ ] 搭建前端脚手架（Vue 3 + Vite + TS + Ant Design Vue + Pinia + Router）
+- [ ] 搭建后端脚手架（FastAPI + SQLAlchemy async + SQLite）
+- [ ] 数据库表设计与建表
+- [ ] 模板格式规范定稿（段落边界规则、标题样式要求、表格归属）
+- [ ] AI 输出格式规范定稿（JSON 结构、表格标记、错误兜底）
+- [ ] 导出策略定稿（基于原模板替换内容）
+- [ ] 前后端 API 接口约定
+
+## 第二阶段：后端核心开发（第 2-3 周）
+
+### Word 解析器（5-7 天）
+- [ ] python-docx 打开模板，逐段落遍历
+- [ ] 标题样式识别（Heading 1~6）→ 段落边界
+- [ ] 正文内容捕获 → 合并到上一标题
+- [ ] 表格结构提取（行列数、合并单元格、边框、底纹）
+- [ ] 样式捕获（字体名、字号、加粗、颜色、对齐、缩进、间距、行距）
+- [ ] 段落索引记录（在文档中的位置，用于导出定位）
+- [ ] 输出结构化 JSON
+
+### AI 服务层（5-7 天）
+- [ ] OpenAI 格式适配（GPT-4o、DeepSeek-V3、通义千问）
+- [ ] Anthropic 格式适配（Claude 3.5 Sonnet）
+- [ ] 统一接口：call_ai(paragraph, files, callback) → content
+- [ ] 提示词拼接：系统提示词 + 段落预设提示词 + 文件摘要
+- [ ] 超时/重试/错误处理
+- [ ] 并发控制（asyncio.Semaphore）
+- [ ] 文件摘要生成（Excel 解析 + 数据统计）
+
+### 文档生成器（3 天）
+- [ ] 单段落生成流程
+- [ ] 多段落并行生成编排（asyncio.gather）
+- [ ] SSE 进度推送
+- [ ] 取消生成支持
+- [ ] 生成结果入库
+
+### Word 导出引擎（5-7 天）
+- [ ] 复制原模板文件作为骨架
+- [ ] 段落定位（按索引/xpath/标题文本三级匹配）
+- [ ] 纯文本替换（保留原样式）
+- [ ] 表格填充（删除占位表格 → 创建新表格 → 填充数据 → 应用样式）
+- [ ] 混合内容处理（文字 + 表格交替）
+- [ ] PDF 导出（调用 LibreOffice 命令）
+
+### 路由与 API（3 天）
+- [ ] 模板 CRUD 路由
+- [ ] 模型 CRUD 路由
+- [ ] 生成相关路由（测试/全量/进度SSE/取消）
+- [ ] 导出路由（Word/PDF）
+- [ ] 文件上传/管理
+
+## 第三阶段：前端核心开发（第 2-4 周）
+
+### 通用组件（3 天）
+- [ ] FileUploader 组件（拖拽 + 点击上传）
+- [ ] ModelModal 组件（添加/编辑模型弹窗）
+- [ ] TestModal 组件（段落测试三步弹窗）
+- [ ] 状态标签、加载状态、空状态组件
+
+### 模板管理页（5-7 天）
+- [ ] 模板列表：卡片布局 + 搜索 + 分页
+- [ ] 三栏编辑器布局
+- [ ] 左栏：段落列表（点击高亮 + 滚动联动）
+- [ ] 中栏：文档预览（A4 纸样式，段落可点击选择）
+- [ ] 右栏：段落配置面板（编辑方式/模型/提示词/文件/格式）
+- [ ] 保存模板
+
+### 模型管理页（2 天）
+- [ ] 模型卡片列表 + 启用/禁用
+- [ ] 添加/编辑弹窗表单
+
+### 执行生成页（3 天）
+- [ ] 双栏布局：左模板选择 + 右段落列表
+- [ ] 文件上传区（按段落分列）
+- [ ] 生成按钮 + 进度展示
+- [ ] 完成跳转
+
+### 生成记录页（2 天）
+- [ ] 统计卡片
+- [ ] 卡片式历史列表 + 筛选
+- [ ] 预览/下载按钮
+
+### 预览编辑页（3-4 天）
+- [ ] 富文本编辑器（contenteditable + 自定义工具栏）
+- [ ] AI 内容紫色高亮标注
+- [ ] 重新生成单段落
+- [ ] 保存/导出按钮
+
+## 第四阶段：联调与修边（第 5-6 周）
+
+- [ ] 文件上传 → 解析 → 保存 → 生成 → 导出全流程联调
+- [ ] 模板不同格式兼容性测试（不同字体、不同布局、含表格/图片/页眉页脚）
+- [ ] AI 不同模型的输出格式兼容性
+- [ ] 错误处理完善（网络中断、模型不可用、文件格式错误）
+- [ ] 边界情况处理（空模板、超大文件、特殊字符）
+- [ ] 响应式适配
+- [ ] 加载状态/骨架屏
+- [ ] 操作提示/Toast
+
+## 阶段交付物
+
+| 阶段 | 交付物 |
+|------|--------|
+| 第 1 周 | 项目脚手架、数据库表、API 接口文档 |
+| 第 2-3 周 | 后端全部功能可用（可通过 API 测试） |
+| 第 4-5 周 | 前端全部页面可用，可联调 |
+| 第 6 周 | 全流程跑通，交付验收 |