# 文档编辑器 - 架构设计

> **版本**: v1.1
> **创建日期**: 2026-01-05
> **最后更新**: 2026-01-15
> **负责人**: 前端团队
> **状态**: 已落地（前端）

---

## 📖 目录

- [1. 系统架构](#1-系统架构)
- [2. 技术选型](#2-技术选型)
- [3. 核心模块与分层](#3-核心模块与分层)
- [4. 数据与状态模型](#4-数据与状态模型)
- [5. 对外 API 边界](#5-对外-api-边界)
- [6. 性能与安全](#6-性能与安全)

---

## 1. 系统架构

### 1.1 模块定位

文档编辑器是**前端组件模块**，为业务模块提供富文本编辑能力，不包含后端服务与数据持久化。

### 1.2 架构视图

```
┌──────────────────────────────────────────┐
│               业务模块层                  │
│  知识库 / 表单 / 公告 / 工单等             │
└─────────────────────┬────────────────────┘
                      │ 组件集成
┌─────────────────────┴────────────────────┐
│             文档编辑器（本模块）           │
│  - React 组件层（DocumentEditor）         │
│  - ProseMirror 内核                        │
│  - 扩展体系（Node/Mark/Plugin）            │
│  - 状态管理（Zustand）                     │
│  - 序列化（Markdown 导出）                 │
└──────────────────────────────────────────┘
```

### 1.3 依赖关系

- 业务模块依赖编辑器模块
- 编辑器模块不依赖业务模块
- 编辑器模块只依赖通用前端基础设施

---

## 2. 技术选型

| 技术 | 版本/说明 | 用途 |
|------|-----------|------|
| ProseMirror | v1.x | 编辑器内核与 Schema |
| React | 19 | UI 组件与渲染 |
| Zustand | 5 | 轻量状态管理 |
| highlight.js | 语法高亮 | 代码块高亮 |
| Tailwind CSS | 项目标准 | 组件样式 |

---

## 3. 核心模块与分层

### 3.1 分层职责

| 层次 | 职责 | 对应目录 |
|------|------|----------|
| 组件层 | 组合 UI 与行为 | `components/` |
| 扩展层 | 节点/标记/插件 | `extensions/` |
| 核心层 | 扩展基类与管理 | `core/` |
| 状态层 | 编辑器状态 | `stores/` |
| 工具层 | 序列化与工具函数 | `utils/` |

### 3.2 关键对象

- `ExtensionManager`：聚合 Schema/Plugins/Rules/Toolbar/SlashMenu
- `DocumentEditor`：主组件，负责生命周期与 UI 容器
- `useEditor`：初始化编辑器实例与事件绑定

---

## 4. 数据与状态模型

- 编辑器内容：ProseMirror JSON
- 持久化：由业务模块决定（本模块不提供存储）
- 状态：`useEditorStore` 保存焦点、字数统计等

---

## 5. 对外 API 边界

- 对外仅暴露**前端组件 API**（见 `07-api.md`）
- 不提供后端 HTTP/WebSocket 服务
- 协同编辑/版本管理为未来规划，当前不纳入实现

---

## 6. 性能与安全

### 6.1 性能

- 编辑器初始化尽量轻量化，扩展按需加载
- 大文档场景由业务侧控制内容分页或拆分策略

### 6.2 安全

- 本模块不处理鉴权与数据权限
- 业务侧负责内容保存与权限控制

---

## 7. 当前实现结构

### 7.1 目录布局

```
frontend/src/features/document-editor/
├── index.ts                           # 公共 API 导出
├── core/                              # 核心层
│   ├── types.ts                       # 类型定义
│   ├── Extension.ts                   # Extension 基类
│   └── ExtensionManager.ts            # 扩展管理器
├── extensions/                        # 扩展层
│   ├── nodes/                         # 节点扩展 (15个)
│   ├── marks/                         # 标记扩展 (7个)
│   ├── plugins/                       # 插件扩展 (6个)
│   ├── utils/                         # 扩展工具
│   └── index.ts                       # 扩展导出
├── components/                        # UI 组件
│   ├── DocumentEditor.tsx             # 主组件
│   ├── SlashMenu/                     # 斜杠命令菜单
│   ├── LinkEditor/                    # 链接编辑器
│   ├── FloatingToolbar/               # 浮动工具栏
│   ├── Toolbar/                       # 顶部工具栏
│   ├── ImageUploader/                 # 图片上传组件
│   └── index.ts                       # 组件导出
├── hooks/                             # React Hooks
│   ├── useEditor.ts                   # 编辑器初始化 Hook
│   └── index.ts
├── stores/                            # 状态管理
│   └── useEditorStore.ts              # Zustand Store
├── utils/                             # 工具函数
│   ├── markdownSerializer.ts          # Markdown 序列化
│   └── index.ts
└── styles/                            # 样式
    └── editor.css                     # 编辑器样式
```

### 7.2 关键组件清单

| 类别 | 组件 | 说明 |
|------|------|------|
| **节点 (15)** | Doc, Text, Paragraph, Heading, BulletList, OrderedList, ListItem, Blockquote, CodeBlock, HorizontalRule, Image, Callout, Table, TableRow, TableCell | 完整的文档结构节点 |
| **标记 (7)** | Bold, Italic, Code, Link, Underline, Strike, Highlight | 内联格式标记 |
| **插件 (6)** | History, Placeholder, DropCursor, GapCursor, SlashMenuPlugin, CodeHighlight | 编辑器行为增强 |
| **UI 组件** | DocumentEditor, SlashMenu, LinkEditor, FloatingToolbar, Toolbar, ImageUploader | React 组件层 |
| **Hooks** | useEditor | 编辑器实例初始化与事件绑定 |
| **Store** | useEditorStore | Zustand 状态（焦点、字数统计等） |
| **工具** | markdownSerializer | ProseMirror 文档 → Markdown 导出 |