新编辑器实现路线图.md 9.9 KB
新编辑器实现路线图
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.tsAPI层 - 编写单元测试
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
议程:
- 上周完成情况回顾
- 本周任务分配
- 技术难点讨论
- 风险识别
5.3 文档更新
- 设计决策记录在docs/
- API变更及时更新文档
- README保持最新
6. 验收标准
6.1 功能验收
- 加载文档并显示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
状态: 计划中