doc-forge-remark/docs/需求与设计/06-可视化区块编辑器重构任务拆解清单.md

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

基线版本：当前 master 分支

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

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

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

后端：Word 转 HTML 服务（5-7 天）

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

后端：解析器升级 — 块级结构输出（3-4 天）

• 新增 parse_template_v2() 函数，输出 list[TemplateBlock] 而非 list[ParsedParagraph]
• 每个块记录：block_index（XML 元素序号）、block_type（heading/text/table/image）、html_snippet、style_json
• 保留旧 parse_template() 兼容现有流程
• 上传模板时同时生成 HTML 快照并存入 MinIO（或数据库 TEXT 字段）

前端：文档渲染组件（3-4 天）

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

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

前端：框选交互层（4-5 天）

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

前端：左右面板联动升级（3-4 天）

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

前端：编辑模式切换（2-3 天）

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

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

后端：块存储 API（2-3 天）

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

后端：模板快照管理（2-3 天）

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

数据库增量变更（1-2 天）

• 确认 template_blocks 表字段完整性（已有，需检查）
• 如需新增字段：anchor_start_index、anchor_end_index、html_snippet
• 新增 template_snapshots 表：HTML 快照改为存储在 template_blocks.html_snippet 字段（无需独立表）
• 输出增量 SQL 脚本（已在 database.py 中通过 init_db 自动迁移）

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

后端：块级 AI 生成调度（4-5 天）

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

后端：AI 提示词上下文增强（2-3 天）

• 构建 AI 请求时，自动附带同一锚点下相邻固定块的内容作为上下文
• 文件附件绑定改为块级别（block_id 替代 paragraph_id）
• 文件摘要按块关联传入 AI

前端：生成页适配（2-3 天）

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

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

后端：基于块索引的精确写回（5-7 天）

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

后端：导出正确性验证（2-3 天）

• 单块替换正确性验证
• 多块顺序写回正确性验证
• 固定块 + AI 块混合导出验证
• 封面区域（非标题内容）导出验证
• 表格块导出样式一致性验证

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

前端：预览编辑页升级（3-4 天）

• 预览页面改为渲染带块标记的 HTML 文档（DocRenderer + 模板 HTML 快照）
• AI 块紫色边框标注（左侧紫色边框 + 标签）
• 支持单块重新生成（块列表中的重新生成按钮 + regenerateBlock API）
• 支持恢复到模板默认内容（resetBlock API + 确认弹窗）
• 导出按钮支持块级导出（Word / Word v2 / PDF）
• 块/段落双模式自动切换（根据 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 转换脚本，历史数据只读