# 新编辑器实现路线图

## 1. 项目概述

### 1.1 目标

将现有基于MDXEditor的编辑器替换为自研的块编辑器,适配新后端的SQLite+blocks架构,提供更强大的表格和图片编辑能力。

### 1.2 时间规划

**总周期**: 10周  
**开始日期**: 2026-07-08  
**预计完成**: 2026-09-16

---

## 2. 里程碑计划

| 里程碑 | 时间 | 交付物 | 状态 |
|--------|------|--------|------|
| M1: 基础框架 | 第1-2周 | 组件骨架+Store+API | 🔴 未开始 |
| M2: 文本编辑 | 第3周 | 标题和段落编辑 | 🔴 未开始 |
| M3: 表格编辑 | 第4-5周 | 完整表格功能 | 🔴 未开始 |
| M4: 图片编辑 | 第6周 | 图片插入和调整 | 🔴 未开始 |
| M5: 高级功能 | 第7-8周 | 拖拽/撤销/导出 | 🔴 未开始 |
| M6: 优化测试 | 第9-10周 | 性能优化+测试 | 🔴 未开始 |

---

## 3. 详细任务分解

### 第1周: 项目启动和基础设施

#### Day 1-2: 环境准备
- [ ] 安装新依赖包(@dnd-kit, react-window等)
- [ ] 创建docs目录并整理现有文档
- [ ] 创建`src/components/Editor`目录结构
- [ ] 设置feature flag(`VITE_USE_NEW_EDITOR`)环境变量
- [ ] **阅读现有代码**: 理解App.tsx、ChatPanel、EditorPanel结构

#### Day 3-4: 类型定义和Store
- [ ] 创建`types/editor.ts`,定义所有Block类型
- [ ] 创建`stores/editorStore.ts`,实现基础Store
- [ ] 实现`blockService.ts` API层
- [ ] 编写单元测试

#### Day 5: 主组件骨架
- [ ] 创建`BlockEditor.tsx`主组件
- [ ] 创建`BlockCanvas.tsx`画布容器
- [ ] 创建`BlockRenderer.tsx`渲染器
- [ ] 基础CSS样式

---

### 第2周: 渲染管道和工具函数

#### Day 1-2: 渲染系统
- [ ] 实现`BlockRenderer`根据type分发渲染
- [ ] 创建各Block组件空壳(Heading/Paragraph/Table/Image)
- [ ] 实现block_order排序逻辑
- [ ] 测试加载文档并渲染

#### Day 3-4: 工具函数
- [ ] 实现`blockOperations.ts`(ID生成,order计算,重排)
- [ ] 实现`richTextConverter.ts`(RichText ↔ HTML)
- [ ] 实现`styleResolver.ts`(样式继承和合并)
- [ ] 编写单元测试

#### Day 5: 工具栏
- [ ] 创建`MainToolbar.tsx`(保存/导出/插入按钮)
- [ ] 创建`FloatingToolbar.tsx`(文本格式化浮动栏)
- [ ] 添加Ant Design图标和按钮
- [ ] CSS样式

**M1 验收**: 能加载文档并显示blocks列表,工具栏UI完成,**ChatPanel正常显示,布局未受影响**

---

### 第3周: 标题和段落编辑 + EditorPanel集成

#### Day 1-2: HeadingBlock
- [ ] 实现HeadingBlock组件
- [ ] contenteditable编辑
- [ ] H1-H6级别切换
- [ ] 富文本支持(加粗/斜体/颜色)
- [ ] 快捷键Ctrl+1~6

#### Day 3-4: ParagraphBlock
- [ ] 实现ParagraphBlock组件
- [ ] contenteditable编辑
- [ ] 富文本支持
- [ ] Enter创建新段落,Shift+Enter块内换行
- [ ] 空段落占位符

#### Day 5: RichTextEditor + EditorPanel集成
- [ ] 提取公共RichTextEditor组件
- [ ] 实现浮动格式化工具栏
- [ ] 颜色选择器
- [ ] 字号/字体选择器
- [ ] **修改EditorPanel.tsx**: 添加feature flag切换逻辑
- [ ] **环境变量配置**: .env.development和.env.production

**M2 验收**: 标题H1-H6可编辑,段落可编辑,支持富文本格式,**可通过环境变量切换新旧编辑器**

---

### 第4周: 表格基础

#### Day 1-2: TableBlock渲染
- [ ] 实现TableBlock组件(div+CSS Grid)
- [ ] 渲染表格结构(rows/cells)
- [ ] 应用col_widths和row_heights
- [ ] 合并单元格渲染(colspan/rowspan)

#### Day 3-4: TableCell编辑
- [ ] 实现TableCell组件
- [ ] 单击/双击进入编辑
- [ ] contenteditable编辑单元格
- [ ] Tab键跳转下一单元格
- [ ] 单元格富文本支持

#### Day 5: 插入表格
- [ ] 工具栏"插入表格"按钮
- [ ] 弹出对话框选择行列数
- [ ] 创建TableBlock并插入
- [ ] 默认样式和尺寸

**阶段验收**: 可创建表格,编辑单元格内容(含富文本)

---

### 第5周: 表格高级操作

#### Day 1: 插入删除行列
- [ ] 右键菜单(在上/下插入行,在左/右插入列)
- [ ] 实现insertRow/insertColumn/deleteRow/deleteColumn
- [ ] 更新metadata(rows/cols数量)
- [ ] 更新col_widths/row_heights数组

#### Day 2-3: 合并单元格
- [ ] 实现单元格多选(拖拽或Shift+点击)
- [ ] 右键菜单"合并单元格"
- [ ] 更新rowspan/colspan
- [ ] 移除被合并单元格
- [ ] 拆分单元格功能

#### Day 4-5: 调整尺寸
- [ ] 实现列宽拖拽调整
- [ ] 实时更新col_widths
- [ ] 实现行高拖拽调整(可选)
- [ ] 鼠标悬停显示调整光标

**M3 验收**: 完整表格编辑流程,插入/删除行列,合并单元格,调整列宽

---

### 第6周: 图片编辑

#### Day 1-2: 插入图片
- [ ] 工具栏"插入图片"按钮
- [ ] 文件选择对话框
- [ ] 图片转Base64
- [ ] 创建ImageBlock并插入
- [ ] 文件大小和格式验证(≤5MB, JPG/PNG/GIF/WebP)

#### Day 3-4: 调整图片
- [ ] 实现ImageBlock组件
- [ ] 选中图片显示调整手柄(8个控制点)
- [ ] 拖拽角落等比缩放
- [ ] 拖拽边缘单方向缩放
- [ ] 实时更新width/height

#### Day 5: 对齐和替换
- [ ] 工具栏对齐按钮(左/中/右)
- [ ] 更新style.align
- [ ] 右键菜单"替换图片"
- [ ] 右键菜单"删除图片"

**M4 验收**: 插入图片,调整尺寸,设置对齐,替换和删除

---

### 第7周: 拖拽和撤销

#### Day 1-3: 拖拽排序
- [ ] 集成@dnd-kit/core
- [ ] 实现DraggableBlock包装组件
- [ ] 拖拽手柄UI
- [ ] 拖拽中显示插入位置指示线
- [ ] 更新block_order

#### Day 4-5: 撤销重做
- [ ] 完善history栈(past/present/future)
- [ ] pushHistory在每次操作后调用
- [ ] 实现undo/redo逻辑
- [ ] 快捷键Ctrl+Z / Ctrl+Y
- [ ] UI显示撤销/重做按钮

**阶段验收**: 拖拽移动blocks,撤销/重做操作

---

### 第8周: 导出和搜索

#### Day 1-2: 导出功能
- [ ] 工具栏"导出"按钮
- [ ] 调用`POST /api/v1/export/doc`
- [ ] 触发浏览器下载
- [ ] 样式选择对话框(阶段1功能,可选)
- [ ] 错误处理

#### Day 2-3: 下载历史
- [ ] "文件 → 下载历史"菜单
- [ ] 侧边栏显示历史记录列表
- [ ] 重新下载功能
- [ ] 删除记录功能

#### Day 4-5: 搜索替换
- [ ] Ctrl+F打开搜索框
- [ ] 实现搜索逻辑(标题/段落/表格单元格)
- [ ] 高亮匹配文本
- [ ] 替换和全部替换功能

**M5 验收**: 导出Word,查看下载历史,搜索替换文本

---

### 第9周: 性能优化

#### Day 1-2: 虚拟滚动
- [ ] 集成react-window
- [ ] 实现VariableSizeList
- [ ] 计算每个block的高度
- [ ] 测试1000+ blocks性能

#### Day 3: 防抖和节流
- [ ] 自动保存防抖500ms
- [ ] 搜索输入防抖300ms
- [ ] 拖拽resize节流16ms(60fps)

#### Day 4-5: 代码分割
- [ ] 动态import大组件(TableBlock/ImageBlock)
- [ ] Suspense加载状态
- [ ] 减小bundle体积

**阶段验收**: 1000+ blocks流畅渲染,操作响应及时

---

### 第10周: 测试和发布

#### Day 1-2: 单元测试
- [ ] blockOperations.ts单元测试
- [ ] richTextConverter.ts单元测试
- [ ] editorStore.ts单元测试
- [ ] 覆盖率≥80%

#### Day 3: 集成测试
- [ ] 加载→编辑→保存流程测试
- [ ] 表格操作流程测试
- [ ] 导出流程测试

#### Day 4: E2E测试
- [ ] Playwright编写关键流程E2E
- [ ] 创建文档→编辑→保存→导出
- [ ] 表格编辑完整流程
- [ ] 跨浏览器测试

#### Day 5: 发布准备
- [ ] 移除MDXEditor依赖
- [ ] 更新文档
- [ ] 代码Review
- [ ] 发布到测试环境

**M6 验收**: 测试覆盖率≥80%,通过E2E测试,功能完整可用

---

## 4. 风险管理

| 风险 | 可能性 | 影响 | 应对措施 |
|------|--------|------|----------|
| contenteditable兼容性 | 高 | 高 | 提前跨浏览器测试,备选方案使用textarea |
| 大表格性能问题 | 中 | 高 | 虚拟滚动,React.memo,延迟加载 |
| blocks数据同步冲突 | 中 | 中 | 乐观锁+冲突检测 |
| 富文本格式丢失 | 中 | 中 | 完善htmlToRichText转换逻辑 |
| 进度延期 | 中 | 中 | 每周Review,及时调整优先级 |

---

## 5. 团队协作

### 5.1 Code Review

- 每个PR至少1人Review
- 关键组件(Store, BlockRenderer)2人Review
- Review清单:
  - [ ] 代码符合规范
  - [ ] 有必要的注释
  - [ ] 有单元测试
  - [ ] 无console.log

### 5.2 每周同步会议

**时间**: 每周一上午10:00  
**议程**:
1. 上周完成情况回顾
2. 本周任务分配
3. 技术难点讨论
4. 风险识别

### 5.3 文档更新

- 设计决策记录在docs/
- API变更及时更新文档
- README保持最新

---

## 6. 验收标准

### 6.1 功能验收

- [x] 加载文档并显示blocks
- [ ] **聊天面板正常工作(发送/接收消息)** ⭐
- [ ] **双面板布局正常(拖拽调整)** ⭐
- [ ] **通过环境变量切换新旧编辑器** ⭐
- [ ] 编辑标题(H1-H6)
- [ ] 编辑段落
- [ ] 富文本格式(加粗/斜体/颜色)
- [ ] 创建表格(3x3)
- [ ] 编辑表格单元格
- [ ] 插入/删除行列
- [ ] 合并单元格
- [ ] 调整列宽
- [ ] 插入图片
- [ ] 调整图片尺寸
- [ ] 图片对齐
- [ ] 拖拽移动blocks
- [ ] 撤销/重做
- [ ] 保存文档
- [ ] 导出Word
- [ ] 搜索文本

### 6.2 性能验收

- [ ] 加载1000 blocks < 3秒
- [ ] 编辑操作响应 < 100ms
- [ ] 自动保存不阻塞编辑
- [ ] 导出Word < 5秒

### 6.3 质量验收

- [ ] 单元测试覆盖率 ≥ 80%
- [ ] 集成测试通过
- [ ] E2E测试通过
- [ ] 无Critical bug
- [ ] 浏览器兼容性(Chrome/Firefox/Safari/Edge)

---

## 7. 发布计划

### 7.1 灰度发布

**第10周末**:
- 发布到测试环境
- 内部团队试用1周

**第11周**:
- 修复反馈问题
- 发布到生产环境
- Feature flag开启10%用户

**第12周**:
- 监控错误率和性能
- 逐步扩大到50%用户

**第13周**:
- 全量发布
- 移除旧编辑器代码

### 7.2 回滚计划

- 保留Feature flag,可快速切回旧编辑器
- 数据向后兼容(blocks格式兼容旧Markdown)
- 监控dashboar实时查看错误率

---

**文档版本**: v1.0  
**创建日期**: 2026-07-03  
**项目负责人**: 开发团队Lead  
**状态**: 计划中