ax-frontend-app/docs/README.md

新编辑器文档导航

📚 文档总览

本目录包含新块编辑器(Block Editor)的完整设计和开发文档。新编辑器基于后端SQLite+blocks架构,取代现有的MDXEditor方案,提供更强大的表格和图片编辑能力。

---

🗂️ 文档索引

1. 新编辑器架构设计.md

适合人群: 架构师、技术Lead
内容概要:

• 技术选型和架构决策
• 后端blocks数据模型详解
• 前端数据层设计(Store/API/数据流)
• 核心组件架构
• 表格、图片、富文本实现方案
• 性能优化策略
• 迁移路径

关键章节:

• §2: 后端blocks数据模型
• §4: 编辑器组件架构
• §5: 表格编辑实现
• §7: 富文本编辑实现

---

2. 新编辑器功能设计.md

适合人群: 产品经理、UX设计师、前端开发
内容概要:

• 功能模块清单和优先级
• 用户交互设计
• UI示例和线框图
• 快捷键设计
• 无障碍设计

关键章节:

• §3: 基础编辑功能
• §4: 表格编辑功能
• §5: 图片管理功能
• §8: 快捷键设计
• §10: 搜索和替换

---

3. 新编辑器开发手册.md

适合人群: 前端开发工程师
内容概要:

• 开发环境搭建
• TypeScript类型定义
• Store实现示例
• API Service层实现
• 工具函数库
• 核心组件代码示例
• 调试技巧和常见问题

关键章节:

• §2: 类型定义
• §3: Store实现
• §5: 工具函数
• §6: 核心组件实现
• §9: 常见问题

---

4. 新编辑器实现路线图.md

适合人群: 项目经理、开发团队
内容概要:

• 10周详细开发计划
• 里程碑和交付物
• 每周任务分解
• 风险管理
• 验收标准
• 发布计划

关键章节:

• §2: 里程碑计划
• §3: 详细任务分解(Week 1-10)
• §6: 验收标准
• §7: 发布计划

---

5. 新编辑器与聊天面板集成方案.md ⭐

适合人群: 全体开发人员
内容概要:

• 现有双面板布局说明
• 新编辑器集成策略(保留聊天面板)
• EditorPanel改造方案
• Feature flag切换机制
• 数据迁移兼容性
• 灰度发布计划

关键章节:

• §1: 现有应用架构(双面板布局)
• §2: 新编辑器集成策略
• §3: 具体集成步骤
• §4: 保持不变的部分(聊天面板)
• §7: 代码变更清单

---

6. 集成快速参考.md 🔥

适合人群: 开发工程师(必读)
内容概要:

• 核心原则速查
• 文件变更清单(不变/新增/修改)
• Feature flag配置示例
• 测试检查清单
• 开发流程4步走
• DO/DON'T注意事项

快速查找:

• 哪些文件完全不能改?
• 只需要改哪个文件?
• 如何配置环境变量?
• 如何测试切换?

---

🚀 快速开始

给架构师和Tech Lead

1. 了解架构: 阅读新编辑器架构设计.md §1-4
2. 数据模型: 重点查看§2后端blocks数据模型
3. 技术选型: 查看§1.3技术栈选型和理由
4. 集成方案: ⭐ 阅读集成方案了解如何保留聊天面板

给前端开发工程师

1. 搭建环境: 按照开发手册 §1准备环境
2. 理解类型: 学习§2类型定义
3. 实现Store: 参考§3实现editorStore
4. 编写组件: 参考§6核心组件实现
5. 集成方案: ⭐ 阅读集成方案 §3了解如何替换EditorPanel内核

给产品经理

1. 功能清单: 阅读功能设计.md §1
2. 交互设计: 查看§3-§6各功能模块的UI设计
3. 验收标准: 查看路线图 §6

给项目经理

1. 时间规划: 查看路线图 §2里程碑
2. 任务分解: 查看§3详细任务(Week 1-10)
3. 风险识别: 查看§4风险管理

---

📋 核心概念速查

Blocks数据模型

所有文档内容以块(Block)为单位存储:

Block类型	用途	关键字段
heading	标题	level(1-6), content
paragraph	段落	content
table	表格	rows, cols, col_widths
image	图片	content(Base64), width, height

稀疏排序

blocks使用block_order字段排序,采用稀疏策略(间隔100):

0, 100, 200, 300, ...
插入: 0, 100, 150(新), 200, 300  // 无需更新其他块

富文本格式

块内容支持RichText[]数组,实现部分文本样式覆盖:

content: [
  { text: "普通", style: {} },
  { text: "红色粗体", style: { bold: true, color: "FF0000" } }
]

样式继承

word_style(样式文件) 
  → block.style(块级覆盖) 
    → richText.style(片段覆盖)

---

🔗 后端文档参考

新编辑器前端需配合后端blocks架构使用,相关后端文档:

文档	路径	说明
SQLite设计	../../ax-backend-v1/docs/content-sqlite-design.md	数据库表结构、blocks定义
后端API	../../ax-backend-v1/docs/text-editor-backend-api.md	RESTful API接口文档
导出功能	../../ax-backend-v1/docs/export-doc-content-mapping.md	Word导出流程

---

📞 联系方式

技术问题: 在对应文档issue中提问
设计讨论: 联系UX团队
紧急问题: 联系项目Lead

---

📝 更新日志

版本	日期	变更说明
v1.0	2026-07-03	初始文档创建

---

文档维护: 前端开发团队
最后更新: 2026-07-03