# 新编辑器文档导航

## 📚 文档总览

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

---

## 🗂️ 文档索引

### 1. [新编辑器架构设计.md](./新编辑器架构设计.md)
**适合人群**: 架构师、技术Lead  
**内容概要**:
- 技术选型和架构决策
- 后端blocks数据模型详解
- 前端数据层设计(Store/API/数据流)
- 核心组件架构
- 表格、图片、富文本实现方案
- 性能优化策略
- 迁移路径

**关键章节**:
- §2: 后端blocks数据模型
- §4: 编辑器组件架构
- §5: 表格编辑实现
- §7: 富文本编辑实现

---

### 2. [新编辑器功能设计.md](./新编辑器功能设计.md)
**适合人群**: 产品经理、UX设计师、前端开发  
**内容概要**:
- 功能模块清单和优先级
- 用户交互设计
- UI示例和线框图
- 快捷键设计
- 无障碍设计

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

---

### 3. [新编辑器开发手册.md](./新编辑器开发手册.md)
**适合人群**: 前端开发工程师  
**内容概要**:
- 开发环境搭建
- TypeScript类型定义
- Store实现示例
- API Service层实现
- 工具函数库
- 核心组件代码示例
- 调试技巧和常见问题

**关键章节**:
- §2: 类型定义
- §3: Store实现
- §5: 工具函数
- §6: 核心组件实现
- §9: 常见问题

---

### 4. [新编辑器实现路线图.md](./新编辑器实现路线图.md)
**适合人群**: 项目经理、开发团队  
**内容概要**:
- 10周详细开发计划
- 里程碑和交付物
- 每周任务分解
- 风险管理
- 验收标准
- 发布计划

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

---

### 5. [新编辑器与聊天面板集成方案.md](./新编辑器与聊天面板集成方案.md) ⭐
**适合人群**: 全体开发人员  
**内容概要**:
- 现有双面板布局说明
- 新编辑器集成策略(保留聊天面板)
- EditorPanel改造方案
- Feature flag切换机制
- 数据迁移兼容性
- 灰度发布计划

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

---

### 6. [集成快速参考.md](./集成快速参考.md) 🔥
**适合人群**: 开发工程师(必读)  
**内容概要**:
- 核心原则速查
- 文件变更清单(不变/新增/修改)
- Feature flag配置示例
- 测试检查清单
- 开发流程4步走
- DO/DON'T注意事项

**快速查找**:
- 哪些文件完全不能改?
- 只需要改哪个文件?
- 如何配置环境变量?
- 如何测试切换?

---

## 🚀 快速开始

### 给架构师和Tech Lead

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

### 给前端开发工程师

1. **搭建环境**: 按照[开发手册](./新编辑器开发手册.md) §1准备环境
2. **理解类型**: 学习§2类型定义
3. **实现Store**: 参考§3实现editorStore
4. **编写组件**: 参考§6核心组件实现
5. **集成方案**: ⭐ 阅读[集成方案](./新编辑器与聊天面板集成方案.md) §3了解如何替换EditorPanel内核

### 给产品经理

1. **功能清单**: 阅读[功能设计.md](./新编辑器功能设计.md) §1
2. **交互设计**: 查看§3-§6各功能模块的UI设计
3. **验收标准**: 查看[路线图](./新编辑器实现路线图.md) §6

### 给项目经理

1. **时间规划**: 查看[路线图](./新编辑器实现路线图.md) §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[]`数组,实现部分文本样式覆盖:
```typescript
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