# 块编辑器功能设计

## 1. 功能状态

| 功能               | 当前状态   | 实现位置                                        |
| ------------------ | ---------- | ----------------------------------------------- |
| 文档加载           | 已实现     | `editorStore`、`blockService`                   |
| 标题和段落编辑     | 已实现     | `HeadingBlock`、`ParagraphBlock`                |
| 富文本格式         | 已实现     | `RichTextEditor`、`RichTextToolbar`             |
| 表格编辑           | 已实现     | `TableBlock`、`TableToolbar`、`blockOperations` |
| 图片上传和调整     | 已实现     | `ImageBlock`、`imageUpload`                     |
| 目录和大纲         | 已实现     | `TOCBlock`、`DocumentOutline`                   |
| 自动保存和重试     | 已实现     | `editorStore`                                   |
| Word 导出          | 已实现     | `exportService`                                 |
| PDF/Markdown 导出  | 已实现     | `clientExportService`                           |
| 块级拖拽排序       | 当前未提供 | 不应在文档中描述为已实现                        |
| 协同编辑和版本回滚 | 未实现     | 需要独立设计                                    |
| 全文搜索替换       | 未实现     | 需要独立设计                                    |

## 2. 文档和块编辑

### 2.1 打开和加载

用户从聊天消息或导出记录打开文档后，前端根据文档 ID 请求 `GET /api/v1/documents/{documentId}/blocks`。返回的 blocks 按 `block_order` 排序后进入 `editorStore`。加载失败时编辑器显示错误状态并通过 Ant Design message 给出提示。

### 2.2 标题和段落

- 标题支持 H1 到 H6。
- 段落支持普通文本、有序列表和无序列表元数据。
- 块菜单支持插入正文、标题、图片、表格、复制、移动和删除等操作。
- Enter 可按当前格式创建后续块；有序列表会计算下一个序号。
- 标题和段落都使用 `RichTextEditor` 编辑 `RichText[]`。

### 2.3 富文本

当前支持加粗、斜体、下划线、删除线、文本颜色、字号、字体和段落对齐。选中文本时显示浮动工具栏；工具栏使用 click 展开，入口显示和保持悬停由编辑器区域统一管理。颜色弹层支持外部点击、Escape 和离开相关区域关闭。

表格单元格不显示普通浮动工具栏，表格结构操作使用 `TableToolbar`。

## 3. 表格功能

### 3.1 结构操作

表格支持插入和删除行列、合并选中的视觉单元格、拆分横向/纵向/混合合并单元格、拖拽调整列宽和行高、单元格内容、文本样式和垂直对齐。

表格使用原生 `table`、`tr` 和 `td` 渲染。由于合并单元格会占据视觉网格中的多个位置，结构更新必须经过 `getTableVisualCellPositions` 和重建函数，不能直接对原始数组做简单 splice。

### 3.2 数据约束

```ts
interface TableCell {
  text: string | RichText[];
  rowspan: number;
  colspan: number;
  style: CellStyleOverrides;
}
```

隐藏单元格使用 `rowspan: 0` 或 `colspan: 0` 表示，不应在渲染层直接删除后再猜测其位置。

## 4. 图片功能

- 支持 JPG、PNG、GIF、WebP 和 BMP。
- 单个文件最大 10 MB。
- 最大边长 10000 像素，总像素数不超过 4000 万。
- 图片以 Data URL 存储在 block content 中。
- 支持替换、删除、左右/居中对齐和宽高调整。
- 渲染时预留宽高比例，使用 lazy loading 和 async decoding。

上传前检查文件类型和大小，读取后再次检查图片真实尺寸，避免仅依赖文件扩展名。

## 5. 保存行为

编辑操作先更新 Zustand 内存状态：

```text
updateBlock
  -> dirtyBlocks
  -> hasModified
  -> 自动保存计时器
  -> 按块保存并发限制
```

默认自动保存延迟为 3 秒。工具栏提供自动保存/手动保存切换。关闭存在未保存修改的文档时会要求确认。网络失败的块会记录到 `failedBlocks`，可通过重试流程再次保存。

## 6. 导出

| 格式     | 方式             | 说明                                    |
| -------- | ---------------- | --------------------------------------- |
| Word     | 后端 API         | 生成导出记录后下载文件                  |
| PDF      | 浏览器动态加载库 | 截取 `.block-canvas` 并生成 PDF         |
| Markdown | 浏览器生成 Blob  | 按 block 顺序转换标题、段落、表格和图片 |

导出入口位于 `MainToolbar`。Word 导出需要有效的文档 ID；PDF 导出需要当前页面存在编辑器画布。

## 7. 当前明确不支持

以下内容不能作为当前产品能力对外承诺：多人实时协同编辑、版本历史和回滚、块级拖拽排序、全文搜索和替换、浏览器端真正安全的 API 密钥保护。实现这些功能前，应先补充数据协议、权限模型、状态冲突策略和测试方案。