# AI 文档模板生成系统 · 可视化区块编辑器重构任务拆解清单

基线版本：当前 `master` 分支

目标：将系统从"按 Heading 解析段落"升级为"Word 富文本渲染 + 可视化框选区块 + 精确写回"的文档生成系统，类似腾讯文档的交互体验。

总工期估算：6-8 周（两人并行：前端 + 后端）

## 第一阶段：Word → HTML 渲染引擎（第 1-2 周）

### 后端：Word 转 HTML 服务（5-7 天）
- [x] 新建 `services/word_to_html.py`，将 docx 转为保留样式的 HTML
- [x] 段落渲染：字体（font-family / font-size / color / bold / italic）、对齐、行距、段前段后间距、首行缩进
- [x] 表格渲染：完整保留边框样式（内外边框、线宽、颜色）、单元格背景色/底纹、合并单元格（rowspan/colspan）、列宽
- [ ] 图片处理：提取 docx 内嵌图片，上传到 MinIO 并生成 URL
- [x] 列表项渲染：有序/无序列表及缩进层级（检测 w:numPr，支持 bullet/ordered，CSS ::before 标记）
- [ ] 页眉页脚渲染（可选，标记为 `data-region="header"` / `data-region="footer"`）
- [x] 为每个渲染元素标记 `data-block-index`（对应原始 docx XML 元素序号），作为后续写回锚点
- [x] 输出完整的独立 HTML 文档字符串（内联样式，可直接在 iframe 中渲染）

### 后端：解析器升级 — 块级结构输出（3-4 天）
- [x] 新增 `parse_template_v2()` 函数，输出 `list[TemplateBlock]` 而非 `list[ParsedParagraph]`
- [x] 每个块记录：`block_index`（XML 元素序号）、`block_type`（heading/text/table/image）、`html_snippet`、`style_json`
- [x] 保留旧 `parse_template()` 兼容现有流程
- [x] 上传模板时同时生成 HTML 快照并存入 MinIO（或数据库 TEXT 字段）

### 前端：文档渲染组件（3-4 天）
- [x] 新建 `components/DocRenderer.vue`，用 iframe 渲染后端返回的 HTML
- [x] 适配 A4 纸张宽度（794px），支持缩放
- [x] 鼠标 hover 时高亮当前 block（通过 `data-block-index` 定位）
- [x] 支持文本选择（保留浏览器原生 Selection API）

## 第二阶段：可视化框选与区块定义（第 2-3 周）

### 前端：框选交互层（4-5 天）
- [x] 在 DocRenderer 上实现拖拽框选交互（mousedown → mousemove → mouseup）
- [x] 绘制半透明选区矩形（overlay div）
- [x] 计算选区覆盖的 `data-block-index` 范围（start → end）
- [x] 选区边界自动吸附到完整块边界（IntersectionRect 检测 + 按 data-block-index 全块选中）
- [x] 选中后弹出浮动工具栏：设为 AI 块 / 设为固定块 / 取消选择
- [x] 已定义的块在文档上显示彩色边框 + 标签（AI 块紫色 / 固定块灰色 / 变量块绿色）
- [x] 支持多选区（Ctrl+框选 追加选区）
- [x] 支持点击已有块查看/编辑配置

### 前端：左右面板联动升级（3-4 天）
- [ ] 左侧块列表改为树形结构（支持父子嵌套）
- [x] 块列表项显示：块类型图标 + 标题 + 所属区域标签
- [x] 点击块列表 ↔ 画布中块高亮滚动联动
- [x] 右侧配置面板根据 `block_type` 动态切换表单项：
  - AI 块：模型选择 / 提示词 / 输出格式 / 是否需要参考文件
  - 固定块：只读信息 / 转为 AI 块按钮
  - 变量块：变量名 / 默认值 / 必填标记
- [x] 拖拽排序（dragstart/dragover/drop 事件，排序后自动保存块配置）

### 前端：编辑模式切换（2-3 天）
- [x] 顶部工具栏新增模式切换：「预览模式」「框选模式」「编辑模式」
- [x] 预览模式：只读查看文档渲染效果
- [x] 框选模式：可拖拽选择区域定义为块（默认模式）
- [ ] 编辑模式（后续迭代）：contenteditable 直接修改文档内容

## 第三阶段：块级数据持久化与模板保存（第 3-4 周）

### 后端：块存储 API（2-3 天）
- [x] 新建/修改 `routers/templates.py` 中的块保存接口 `PUT /api/v1/templates/{id}/blocks`
- [x] 接口接收 `list[TemplateBlock]`，批量 upsert（新增/更新/删除）
- [x] 旧 `paragraphs` 接口保留兼容，内部转换到新块结构
- [x] 模板详情返回时优先返回 blocks，fallback 到 paragraphs

### 后端：模板快照管理（2-3 天）
- [x] 上传模板时生成 HTML 快照存入 `template_snapshots` 表或 MinIO
- [x] 每次保存块配置时同步更新快照中的块标记（html_snippet 注入 block-ai/block-fixed CSS class）
- [x] 加载模板时直接返回带块标记的 HTML，前端无需二次计算

### 数据库增量变更（1-2 天）
- [x] 确认 `template_blocks` 表字段完整性（已有，需检查）
- [x] 如需新增字段：`anchor_start_index`、`anchor_end_index`、`html_snippet`
- [x] 新增 `template_snapshots` 表：HTML 快照改为存储在 `template_blocks.html_snippet` 字段（无需独立表）
- [x] 输出增量 SQL 脚本（已在 database.py 中通过 init_db 自动迁移）

## 第四阶段：生成链路适配（第 4-5 周）

### 后端：块级 AI 生成调度（4-5 天）
- [x] 重构 `generation_runtime.py`：生成单元从 Paragraph 切换为 TemplateBlock
- [x] 只对 `edit_mode='ai'` 的块调用 AI
- [x] 固定块的内容直接作为上下文传递给相邻 AI 块
- [ ] 变量块按变量值直接替换，不经过 AI
- [ ] 并发控制：按模板全局 Semaphore 限流
- [x] SSE 进度推送单位改为块（`done/total` 按块计数）

### 后端：AI 提示词上下文增强（2-3 天）
- [x] 构建 AI 请求时，自动附带同一锚点下相邻固定块的内容作为上下文
- [ ] 文件附件绑定改为块级别（`block_id` 替代 `paragraph_id`）
- [ ] 文件摘要按块关联传入 AI

### 前端：生成页适配（2-3 天）
- [x] 生成页支持段落/块模式切换（RadioButton 切换 genMode）
- [x] 块模式显示 AI 块列表（替代段落文件配置）
- [x] 块模式调用 generateFullV2 接口
- [ ] 生成页左侧模板预览改为渲染 HTML 快照 + 块标记
- [ ] 文件上传区按 AI 块分列展示
- [ ] 进度展示与块列表联动（当前正在生成哪个块）

## 第五阶段：导出引擎重构（第 5-6 周）

### 后端：基于块索引的精确写回（5-7 天）
- [x] 重构 `document_export.py`，基于 `block_index` 定位而非 `anchor_title` 文本匹配
- [x] 导出流程：
  1. 从 MinIO 拉取原始模板 docx
  2. 按块索引定位到原始 XML 元素
  3. 固定块：保留原始内容不变
  4. AI 块：用生成结果替换（文本块替换 `<w:t>`，表格块替换整个 `<w:tbl>`）
  5. 变量块：替换为变量值
- [x] 支持块顺序调整后的正确写回（按 sort_index 重排文档元素，gap 元素保持原位置）
- [x] 保留未选中区域（没有被任何 Block 覆盖的文档部分）原样保留
- [ ] 表格样式继承：AI 生成的表格复用同一文档中最近的表格样式

### 后端：导出正确性验证（2-3 天）
- [ ] 单块替换正确性验证
- [ ] 多块顺序写回正确性验证
- [ ] 固定块 + AI 块混合导出验证
- [ ] 封面区域（非标题内容）导出验证
- [ ] 表格块导出样式一致性验证

## 第六阶段：预览编辑与结果管理（第 5-6 周）

### 前端：预览编辑页升级（3-4 天）
- [x] 预览页面改为渲染带块标记的 HTML 文档（DocRenderer + 模板 HTML 快照）
- [x] AI 块紫色边框标注（左侧紫色边框 + 标签）
- [x] 支持单块重新生成（块列表中的重新生成按钮 + regenerateBlock API）
- [x] 支持恢复到模板默认内容（resetBlock API + 确认弹窗）
- [x] 导出按钮支持块级导出（Word / Word v2 / PDF）
- [x] 块/段落双模式自动切换（根据 has_blocks 标志自动选择视图）

### 前端：历史记录页增强（2-3 天）
- [ ] 历史列表卡片展示文档缩略图（HTML 快照截图）
- [ ] 按模板、按状态筛选
- [ ] 对比模式：并排展示原始模板 vs 生成结果

## 第七阶段：联调、修边与验收（第 7-8 周）

- [ ] 真实复杂模板全流程联调（含封面 / 摘要 / 多级标题 / 复杂表格 / 图片）
- [ ] 框选交互边界测试（跨页选区、嵌套表格选区、空选区）
- [ ] 不同浏览器兼容性测试（Chrome / Edge / Safari）
- [ ] 大文档性能测试（50 页+ Word 文档渲染性能）
- [ ] 导出结果与原 Word 样式一致性验收
- [ ] 旧数据（基于 Paragraph 的历史记录）兼容性验证
- [ ] 错误提示完善、加载状态/骨架屏补充
- [ ] 操作日志与使用说明整理

## 阶段交付物

| 阶段 | 交付物 |
|------|--------|
| 第 1-2 周 | Word→HTML 渲染引擎、块级解析器、文档渲染组件 |
| 第 2-3 周 | 可视化框选交互、块配置面板、模式切换 |
| 第 3-4 周 | 块存储 API、模板快照管理、数据库增量变更 |
| 第 4-5 周 | 块级 AI 生成调度、生成页适配 |
| 第 5-6 周 | 基于块索引的精确写回引擎、预览编辑页升级 |
| 第 7-8 周 | 全流程联调、兼容性测试、验收交付 |

## 与现有改造任务的关系

| 现有任务 | 本方案处理方式 |
|---------|-------------|
| 04-后续迭代（占位体系） | 变量块覆盖占位需求，不再需要独立占位语法 |
| 05-在线编辑重构（AI选区模式） | 本方案的框选交互即为 AI 选区模式的完整实现 |
| 05-模板源写回 | 合并到本方案第五阶段导出引擎重构 |
| 旧 Paragraph 表 | 保留兼容，逐步由 TemplateBlock 替代 |

## 核心架构变化

```
【改造前】
Word 上传 → 按 Heading 切段落 → 段落列表 → 配置 → AI 生成 → 按标题文本写回

【改造后】
Word 上传 → 解析为 HTML + 块索引 → 可视化框选定义块 → 块配置 → AI 按块生成 → 按索引精确写回
```

## 风险与缓解

| 风险 | 等级 | 缓解措施 |
|------|------|---------|
| Word→HTML 样式还原度不足 | 中 | 优先保证字体/表格/对齐，复杂格式（分栏/文本框）暂不支持 |
| 大文档 HTML 渲染性能 | 中 | 虚拟滚动 + 按需加载，超过 100 页的文档分页渲染 |
| 块索引在多次编辑后偏移 | 高 | 每次保存时重新解析并更新索引；导出时以最新快照为准 |
| 框选交互在 iframe 中的复杂性 | 中 | 备选方案为 div 直接渲染（放弃 iframe 隔离），简化事件处理 |
| 旧数据兼容 | 低 | Paragraph→TemplateBlock 转换脚本，历史数据只读 |