# 文档编辑引擎模块 - 架构迁移说明

> **创建日期**：2026-01-05  
> **状态**：🟡 文档已完成，代码待实现

---

## 📋 变更概述

将富文本编辑器从知识库模块中剥离，创建独立的**文档编辑引擎模块**。

### 核心理念

**问题**：知识库模块原本包含了富文本编辑器实现，但编辑能力是通用需求，不应绑定在特定业务模块中。

**解决方案**：创建独立的文档编辑引擎模块，为全系统提供统一的编辑能力。

---

## 🎯 设计原则

| 原则 | 说明 |
|------|------|
| **职责单一** | 知识管理 ≠ 文档编辑 |
| **零技术债** | 避免重复实现编辑器 |
| **高复用** | 5+ 业务模块共享编辑能力 |
| **可扩展** | 通过插件机制支持业务定制 |
| **独立演进** | 独立测试、独立发版 |

---

## 📊 架构对比

### 旧架构（耦合）

```
知识库模块
├── 知识管理（核心业务）
├── AI 智能问答
├── 搜索
├── 标签系统
└── 富文本编辑器 ❌ (耦合在内部)
    ├── TipTap 集成
    ├── 协同编辑
    └── 版本管理

问题：
❌ 表单引擎需要编辑器 → 重复实现或不合理依赖
❌ 公告系统需要编辑器 → 重复实现或不合理依赖
❌ 评论系统需要编辑器 → 重复实现或不合理依赖
❌ 维护成本高，技术债务累积
```

### 新架构（解耦）⭐

```
文档编辑引擎模块（独立）
├── 富文本编辑器 (TipTap)
├── Markdown 编辑器 (CodeMirror)
├── 代码编辑器 (Monaco)
├── 协同编辑 (Yjs)
├── 版本管理
└── 插件系统
    ↑
    │ 调用
    ├─ 知识库模块（注册术语表插件）
    ├─ 表单引擎（使用富文本字段）
    ├─ 公告系统（编辑公告内容）
    └─ 评论系统（富文本评论）

优势：
✅ 统一的编辑能力
✅ 清晰的模块边界
✅ 避免重复实现
✅ 易于测试和维护
```

---

## 📁 文档结构

### 新增文档（文档编辑引擎）

```
docs/modules/document-editor/
├── README.md                    ✅ 模块概述
├── 01-prd.md                    ✅ 产品需求文档
├── 03-architecture.md           ✅ 架构设计文档
└── 07-api.md                    ✅ API 接口文档
```

### 更新文档（知识库）

```
docs/modules/knowledge-base/
├── README.md                    ✅ 添加模块依赖说明
├── 01-prd.md                    ✅ 移除编辑器实现细节，改为引用
├── 03-architecture.md           ✅ 更新架构图，标注依赖关系
└── 99-changelog.md              ✅ 记录架构变更
```

---

## 🔄 模块关系

### 依赖关系

```
业务模块（知识库、表单、公告等）
    ↓ 依赖
文档编辑引擎（本模块）
    ↓ 依赖
基础设施（数据库、文件存储、消息队列）
```

### 调用方式

**知识库模块使用编辑器**：

```typescript
import { RichTextEditor } from '@/features/document-editor';

function KnowledgeArticleEditor({ articleId }) {
  return (
    <RichTextEditor
      initialContent={article.content}
      toolbar="full"
      plugins={[
        glossaryPlugin,      // 知识库特有：术语表插件
        aiAssistantPlugin    // 知识库特有：AI 助手
      ]}
      uploadHandler={uploadToSharePoint}
      onChange={handleChange}
      onSave={handleSave}
    />
  );
}
```

**表单引擎使用编辑器**：

```typescript
import { RichTextEditor } from '@/features/document-editor';

function RichTextField({ field }) {
  return (
    <RichTextEditor
      initialContent={field.value}
      toolbar="minimal"        // 表单场景使用简化工具栏
      onChange={(value) => field.onChange(value)}
    />
  );
}
```

---

## 📝 变更清单

### 文档变更

| 文档 | 变更类型 | 变更内容 | 状态 |
|------|---------|---------|------|
| `document-editor/README.md` | 新增 | 模块概述 | ✅ |
| `document-editor/01-prd.md` | 新增 | 产品需求文档 | ✅ |
| `document-editor/03-architecture.md` | 新增 | 架构设计文档 | ✅ |
| `document-editor/07-api.md` | 新增 | API 接口文档 | ✅ |
| `knowledge-base/01-prd.md` | 更新 | 4.1.4 节：改为引用编辑引擎 | ✅ |
| `knowledge-base/03-architecture.md` | 更新 | 更新架构图和技术栈 | ✅ |
| `knowledge-base/README.md` | 更新 | 添加模块依赖说明 | ✅ |
| `knowledge-base/99-changelog.md` | 更新 | 记录架构变更 | ✅ |

### 代码变更（待实施）

| 目录 | 变更类型 | 变更内容 | 状态 |
|------|---------|---------|------|
| `backend/src/modules/document-editor/` | 新增 | 编辑器后端模块 | ⏳ |
| `frontend/src/features/document-editor/` | 新增 | 编辑器前端组件 | ⏳ |
| `backend/prisma/schema/document_editor.prisma` | 新增 | 编辑器数据模型 | ⏳ |
| `backend/src/modules/knowledge-base/` | 重构 | 移除编辑器实现，调用编辑引擎 | ⏳ |

---

## 🚀 实施计划

### Phase 1: 文档完成（已完成）✅

- ✅ 创建文档编辑引擎模块文档
- ✅ 更新知识库模块文档
- ✅ 记录架构变更

### Phase 2: MVP 实现（2-3周）

**目标**：实现基础编辑能力，支持知识库使用

| 任务 | 时间 | 负责人 |
|------|------|--------|
| 创建文档编辑引擎模块 | 1天 | 全栈 |
| 实现富文本编辑器 | 5天 | 前端 |
| 实现 Markdown 编辑器 | 3天 | 前端 |
| 实现代码编辑器 | 2天 | 前端 |
| 实现后端 API | 3天 | 后端 |
| 知识库集成编辑器 | 2天 | 全栈 |
| 测试与文档 | 2天 | 测试 |

### Phase 3: 协同编辑（3-4周）

- 实现 Yjs CRDT 集成
- WebSocket 协同服务
- 光标位置同步
- 版本历史管理

### Phase 4: 高级功能（2-3周）

- 插件系统
- 导出功能
- 主题定制

---

## 💡 关键设计决策

### 1. 为什么使用 TipTap？

| 方案 | 优势 | 劣势 | 评分 |
|------|------|------|------|
| **TipTap** ⭐ | • 现代化<br>• 插件系统优秀<br>• 协同编辑支持好 | • 相对年轻 | 9/10 |
| Slate | • 完全可定制 | • 学习曲线陡峭 | 7/10 |
| Quill | • 成熟稳定 | • 扩展性一般 | 6/10 |

### 2. 为什么使用 Yjs？

| 方案 | 优势 | 劣势 | 评分 |
|------|------|------|------|
| **Yjs** ⭐ | • 性能最优<br>• TipTap 官方集成 | - | 9/10 |
| Automerge | • 算法先进 | • 性能较慢 | 7/10 |
| ShareDB | • 成熟稳定 | • OT 算法（非 CRDT） | 6/10 |

### 3. 为什么使用插件机制？

- ✅ 业务模块可以扩展编辑器功能（如术语表插件）
- ✅ 核心编辑器保持简洁
- ✅ 不同场景使用不同工具栏配置

---

## 🎓 参考资料

### 相关文档

- [文档编辑引擎 PRD](./01-prd.md)
- [文档编辑引擎架构](./03-architecture.md)
- [文档编辑引擎 API](./07-api.md)
- [知识库模块 PRD](../knowledge-base/01-prd.md)
- [知识库模块架构](../knowledge-base/03-architecture.md)

### 技术文档

- [TipTap 官方文档](https://tiptap.dev/)
- [Yjs CRDT 文档](https://docs.yjs.dev/)
- [ProseMirror 文档](https://prosemirror.net/)

### 设计原则

- [SOLID 原则](https://en.wikipedia.org/wiki/SOLID)
- [职责单一原则（SRP）](https://en.wikipedia.org/wiki/Single-responsibility_principle)
- [依赖倒置原则（DIP）](https://en.wikipedia.org/wiki/Dependency_inversion_principle)

---

## ❓ 常见问题

### Q1: 为什么不在知识库内部实现编辑器？

**A**: 编辑器是通用能力，多个模块需要（表单、公告、评论等）。如果耦合在知识库内，会导致：
- ❌ 其他模块重复实现（技术债）
- ❌ 或依赖知识库模块（不合理的依赖关系）

### Q2: 编辑引擎是否会变得过于复杂？

**A**: 不会。通过清晰的职责边界：
- ✅ 编辑引擎只负责编辑能力，不包含业务逻辑
- ✅ 业务逻辑由业务模块负责（如权限、审批等）
- ✅ 通过插件机制支持业务定制

### Q3: 如何保证不同模块的编辑体验一致？

**A**: 
- ✅ 统一的编辑引擎确保体验一致
- ✅ 提供预设配置（full / standard / minimal）
- ✅ 支持自定义工具栏配置

### Q4: 旧代码如何迁移？

**A**: 分阶段迁移：
1. Phase 1: 创建编辑引擎模块，知识库优先迁移
2. Phase 2: 表单引擎等其他模块逐步迁移
3. Phase 3: 清理旧代码

---

**审核状态**：✅ 文档已完成

**下一步**：开始 Phase 2 实现