text-editor-architecture.md 16 KB
文本编辑器技术架构文档
1. 整体架构演进
系统按阶段渐进引入组件，每个阶段只加当前必要的依赖。
2. 阶段 0：基础链路（当前）
目标：打通 mod-chat 中"AI 生成文档 → 编辑器打开 → 编辑 → 保存回 Chat"闭环。
┌──────────────────────────────────────┐
│ mod-chat（前端） │
│ Chat UI ──► DocumentEditor Modal │
│ （Slate.js） │
└───────────────────┬──────────────────┘
│ REST API
▼
┌──────────────────────────────────────┐
│ FastAPI 后端（单服务） │
│ /api/v1/documents （CRUD） │
└───────────────────┬──────────────────┘
│ SQLAlchemy
▼
PostgreSQL
（documents 表，content text）
依赖清单：FastAPI、SQLAlchemy、PostgreSQL
无需：Redis、S3、Token 服务、Webhook、API Gateway
前端组件结构、状态管理设计见 功能设计文档 - 阶段 0
2.1 后端 Document Service
class DocumentService:
def __init__(self, db: AsyncSession):
self.db = db
async def create_document(self, data: DocumentCreate, user_id: str | None = None) -> Document:
doc = Document(
title=data.title,
content=data.content, # 直接存 text，上限 200KB
format=data.format,
session_id=data.session_id,
created_by=user_id,
source='chat',
)
self.db.add(doc)
await self.db.commit()
await self.db.refresh(doc)
return doc
async def update_document(self, document_id: str, data: DocumentUpdate) -> Document:
doc = await self.get_document(document_id)
if not doc:
raise ValueError("Document not found")
if data.content and len(data.content) > 200_000:
raise ValueError("Content exceeds 200KB limit")
if data.title is not None:
doc.title = data.title
if data.content is not None:
doc.content = data.content
doc.updated_at = datetime.utcnow()
await self.db.commit()
return doc
3. 阶段 1：Word 模板 + 工作流文档编辑
目标：支持上传 Word 模板，工作流生成文档，编辑器打开编辑，下载后保持模板格式。
工作流（上传模板 / 触发生成）
│
▼
┌───────────────────────────────────────┐
│ FastAPI 后端 │
│ ├── /api/v1/templates （模板管理） │
│ ├── /api/v1/documents （CRUD） │
│ └── /api/v1/export/docx （下载导出） │
└───────────────────┬───────────────────┘
┌─────────┴──────────┐
▼ ▼
PostgreSQL 文件存储
（文档 + 模板元数据） （模板 .docx 文件）
│
python-docx / docxtpl
（模板解析 + 内容合并）
新增依赖：python-docx、docxtpl（可选）
前端编辑器应用模板样式的实现见 功能设计文档 - 阶段 1
3.1 Word 模板处理核心逻辑
上传模板时
# 解析模板样式元数据
from docx import Document as DocxDocument
def parse_template_styles(docx_path: str) -> dict:
doc = DocxDocument(docx_path)
styles = {}
for style in doc.styles:
if style.type.name == 'PARAGRAPH':
styles[style.name] = {
'font': style.font.name,
'size': style.font.size,
'bold': style.font.bold,
}
return styles
下载时合并内容与模板
# 将编辑器内容写入模板，保留原始样式
from docxtpl import DocxTemplate
def export_with_template(template_path: str, content_data: dict) -> bytes:
tpl = DocxTemplate(template_path)
tpl.render(content_data)
buffer = io.BytesIO()
tpl.save(buffer)
return buffer.getvalue()
3.2 数据库新增
-- 模板表
CREATE TABLE document_templates (
id VARCHAR PRIMARY KEY,
name VARCHAR NOT NULL,
file_key VARCHAR NOT NULL, -- 模板文件存储路径
styles JSONB, -- 解析出的样式元数据
created_at TIMESTAMP
);
-- documents 表新增字段
ALTER TABLE documents ADD COLUMN template_id VARCHAR REFERENCES document_templates(id);
ALTER TABLE documents ADD COLUMN source VARCHAR DEFAULT 'chat';
4. 阶段 2：oil-agent 跨平台集成
目标：将编辑器封装为独立的 Editor Component + WS Client，Backend 居中，mod-chat 通过 REST/SSE 与 Backend 通信，oil-agent 通过 REST/WebSocket 与 Backend 通信。
4.1 整体架构
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
│ mod-chat │ │ Backend │ │ oil-agent │
│ │ │ (Python) │ │ │
│ ┌─────────────┐ │ REST/ │ ┌──────────┐ │ REST/ │ ┌─────────┐ │
│ │ Editor │ |◄────────►│ │ Document │ |◄────────►│ │ Editor │ │
│ │ Component │ │ SSE │ │ Service │ │WebSocket │ │Component│ │
│ │ + WS Cli │ │ │ └──────────┘ │ │ └─────────┘ │
│ └─────────────┘ │ │ │ │ │
└─────────────────┘ └──────┬───────┘ └─────────────┘
│
┌────────────┴────────────┐
▼ ▼
PostgreSQL Redis
（文档 + 模板） （Token 会话）
4.2 通信链路说明
链路 1：mod-chat ↔ Backend（REST/SSE）
mod-chat 是 Axonix 自有平台，Editor Component 内置 WS Client，对外同时支持 SSE 监听（接收后端推送）和 REST 请求（主动发送操作）：
- mod-chat Editor Component 通过 REST 发起请求（创建文档、保存内容等）
- WS Client 建立 SSE 连接，后端通过 SSE 主动推送事件给 mod-chat（如文档被 oil-agent 端修改后通知更新）
后端检测到文档内容变更
↓
SSE 推送 document.updated 事件到 mod-chat
↓
mod-chat Editor Component 收到事件，自动拉取最新内容
SSE 连接地址：GET /api/v1/documents/{documentId}/events
from sse_starlette.sse import EventSourceResponse
@router.get("/documents/{document_id}/events")
async def document_events(document_id: str):
async def event_generator():
while True:
event = await get_document_event(document_id)
if event:
yield {"event": event.type, "data": event.json()}
await asyncio.sleep(1)
return EventSourceResponse(event_generator())
链路 2：oil-agent ↔ Backend（REST/WebSocket）
oil-agent 是外部平台，SSE 可能受限于其网络环境或代理配置不被支持，改用兼容性更强的 WebSocket：
- oil-agent Editor Component 通过 REST 发起普通请求（Token 校验、文档读取等）
- 通过 WebSocket 维持与后端的双向长连接，实时同步编辑内容变更
oil-agent Editor Component 建立 WebSocket 连接（携带 Token）
↓
双向通信：编辑器推送内容变更 / 后端推送文档更新
↓
编辑器关闭时断开连接，后端触发 session.closed → SSE 通知 mod-chat
WebSocket 地址：ws://api.axonix.com/ws/edit-sessions/{sessionId}?token={token}
@router.websocket("/ws/edit-sessions/{session_id}")
async def websocket_edit_session(websocket: WebSocket, session_id: str, token: str):
payload = await token_service.verify_token(token)
if not payload:
await websocket.close(code=4001)
return
await websocket.accept()
try:
while True:
data = await websocket.receive_json()
await handle_edit_message(session_id, data)
# 广播变更到 SSE，通知 mod-chat 端同步
await broadcast_to_sse(payload["document_id"], data)
except WebSocketDisconnect:
await close_session(session_id)
4.3 通信方式对比
| 链路 | 方式 | 原因 |
|---|---|---|
| mod-chat ↔ Backend | REST + SSE | 自有平台，WS Client 通过 SSE 接收后端推送；REST 发送操作请求 |
| oil-agent ↔ Backend | REST + WebSocket | 外部平台，SSE 可能不被支持；WebSocket 双向通信兼容性强 |
4.4 数据存储职责
| 存储 | 内容 | 备注 |
|---|---|---|
| PostgreSQL | 文档内容、文档元数据、模板元数据 | 阶段 1 新增模板表 |
| Redis | Token 会话（edit_token、edit_session） | 阶段 2 引入，短效 KV，不落盘 |
4.5 Editor Component 设计
Editor Component 通过 Props 适配两个平台的不同通信方式：
interface EditorComponentProps {
documentId: string;
token?: string; // oil-agent 免登录场景传入
platform: 'mod-chat' | 'oil-agent';
apiBaseUrl: string;
onSave?: (content: string) => void;
onClose?: () => void;
}
WS Client 内部实现：
class EditorTransport {
private sse: EventSource | null = null;
private ws: WebSocket | null = null;
connect(platform: 'mod-chat' | 'oil-agent', url: string) {
if (platform === 'mod-chat') {
// mod-chat：SSE 监听后端推送，REST 发送请求
this.sse = new EventSource(url);
this.sse.onmessage = (e) => this.handleEvent(JSON.parse(e.data));
} else {
// oil-agent：WebSocket 双向通信
this.ws = new WebSocket(url);
this.ws.onmessage = (e) => this.handleEvent(JSON.parse(e.data));
}
}
send(data: object) {
if (this.ws) {
// oil-agent：WebSocket 直接发
this.ws.send(JSON.stringify(data));
}
// mod-chat：发送走 REST API，不通过 SSE
}
disconnect() {
this.sse?.close();
this.ws?.close();
}
}
4.6 Module Federation 配置
// vite.config.ts（编辑器打包为远程模块，供两个平台加载）
federation({
name: 'editorModule',
filename: 'remoteEntry.js',
exposes: {
'./DocumentEditor': './src/components/editor/DocumentEditor',
},
shared: ['react', 'react-dom'],
})
4.7 Token Service
class TokenService:
async def generate_edit_token(
self,
document_id: str,
platform: str,
expires_in: int = 3600,
) -> tuple[str, str]:
session_id = f"edit_session_{secrets.token_urlsafe(16)}"
payload = {
"session_id": session_id,
"document_id": document_id,
"platform": platform,
"exp": datetime.utcnow() + timedelta(seconds=expires_in),
}
token = jwt.encode(payload, self.secret_key, algorithm="HS256")
await redis.setex(f"edit_token:{session_id}", expires_in, token)
return session_id, token
async def verify_token(self, token: str) -> dict | None:
try:
payload = jwt.decode(token, self.secret_key, algorithms=["HS256"])
stored = await redis.get(f"edit_token:{payload['session_id']}")
return payload if stored else None
except jwt.InvalidTokenError:
return None
新增依赖：Redis、PyJWT、sse-starlette（SSE 端点）、Module Federation（前端构建）
5. 阶段 3：编辑器增强 + 协同编辑
目标：完善编辑体验，支持版本管理，按需启用多人协同。
新增依赖：Yjs、y-websocket、S3/MinIO（大文档迁移）、API Gateway
5.1 协同编辑架构（Yjs）
┌───────────────────────┐ ┌───────────────────────┐
│ Client A │ │ Client B │
│ Slate.js + y-slate │ │ Slate.js + y-slate │
│ Yjs Doc（本地副本） │ │ Yjs Doc（本地副本） │
└──────────┬────────────┘ └────────────┬──────────┘
│ CRDT 增量操作 │ CRDT 增量操作
└─────────────┬──────────────────┘
│ WebSocket
▼
┌──────────────────────┐
│ y-websocket Server │
│ 合并 CRDT 操作 │
│ 广播给所有客户端 │
└──────────┬───────────┘
│
PostgreSQL
（持久化版本快照）
CRDT 工作原理：每个客户端持有文档的本地副本，编辑操作转为 CRDT 增量（不是全量内容），服务端合并所有客户端的增量后广播，冲突由算法自动解决，无需人工干预。
5.2 大文档迁移到 S3
阶段 3 引入 S3/MinIO 后，超过 200KB 的文档内容从 PostgreSQL text 字段迁移到对象存储：
documents 表
content → NULL（大文档不再存 DB）
content_key → "documents/doc-abc123.md" （S3 对象路径）
读取时按 content_key 从 S3 拉取，写入时上传到 S3 再更新 content_key。
5.3 版本管理数据表
CREATE TABLE document_versions (
id VARCHAR PRIMARY KEY,
document_id VARCHAR NOT NULL,
content TEXT NOT NULL,
created_by VARCHAR,
summary VARCHAR,
created_at TIMESTAMP
);
6. 技术栈汇总
| 组件 | 技术 | 引入阶段 |
|---|---|---|
| 前端框架 | React 18 + TypeScript + Vite | 阶段 0 |
| UI 组件库 | Ant Design | 阶段 0 |
| 编辑器核心 | Slate.js | 阶段 0 |
| 状态管理 | Zustand | 阶段 0 |
| 后端框架 | FastAPI（Python 3.10+） | 阶段 0 |
| ORM | SQLAlchemy 2.0 | 阶段 0 |
| 数据库 | PostgreSQL | 阶段 0 |
| DOCX 处理 | python-docx + docxtpl | 阶段 1 |
| Token 会话 | Redis + PyJWT | 阶段 2 |
| 微前端打包 | Module Federation（Vite） | 阶段 2 |
| 实时协同 | Yjs + y-websocket | 阶段 3 |
| 大文档存储 | S3 / MinIO | 阶段 3 |
| 网关 | API Gateway | 阶段 3 |
7. 安全设计
阶段 0/1
- 编辑器 API 复用 mod-chat 现有认证，无额外层
阶段 2 引入
- JWT + Redis 双重校验，Token 与文档 ID 绑定
- Token 默认 1 小时，最长 24 小时，关闭会话立即撤销
通用
- 用户输入 HTML 经 DOMPurify 过滤后存储
- 文件上传限制类型（.docx）和大小（≤ 20MB）
- API 限流防滥用
8. 性能基准目标
| 指标 | 目标值 |
|---|---|
| 编辑器首次加载 | < 2s |
| 文档保存响应 | < 500ms |
| DOCX 导出生成 | < 3s |
| 10 万字文档渲染 | 流畅（60fps） |
| 并发协同用户 | 50 人/文档（阶段 3） |
文档版本: v4.0 最后更新: 2026-06-11 维护者: Axonix 前端团队