text-editor-architecture.md 20 KB
文本编辑器技术架构文档
1. 整体架构演进
系统按阶段渐进引入组件，每个阶段只加当前必要的依赖。
2. 阶段 0：基础链路（当前）
目标：打通 mod-chat 中"AI 生成文档 → 编辑器打开 → 编辑 → 保存回 Chat"闭环。
┌──────────────────────────────────────┐
│ mod-chat（前端） │
│ Chat UI ──► DocumentEditor Modal │
│ （Slate.js） │
└───────────────────┬──────────────────┘
│ REST API
▼
┌──────────────────────────────────────┐
│ FastAPI 后端（单服务） │
│ /api/v1/documents （CRUD） │
│ /api/v1/export/doc （导出） │
│ /api/v1/export/records （下载记录） │
│ /api/v1/admin/storage （存储监控） │
└───────────┬──────────────────┬───────┘
│ SQLAlchemy │ 本地文件系统
▼ ▼
PostgreSQL ./tmp/{user_id}/
（documents 表 {YYYY-MM-DD}/
export_records 表） *.doc 文件
依赖清单：FastAPI、SQLAlchemy、PostgreSQL、python-docx、mistune
无需：Redis、S3、Token 服务、Webhook、API Gateway
前端组件结构、状态管理设计见 功能设计文档 - 阶段 0
2.1 导出与存储监控
导出流程由 export_service.py 承担核心逻辑：接收 Markdown 内容 → 加载默认样式文件（./tmp/default.json）→ 通过 DocxRenderer（基于 mistune AST + python-docx）渲染为 .doc 字节流 → 按 ./tmp/{user_id}/{YYYY-MM-DD}/ 分区写入磁盘 → 写入 export_records 表并返回永久下载链接。
storage_monitor.py 在应用启动时注册后台定时任务（每 30 分钟），并在每次导出后触发实时检查：tmp/ 总占用超磁盘 50% 时向所有有文件用户发警告并记录管理员日志；单用户超均分额度时在导出响应的 warning 字段附带提示。
下载记录的增删查由 export_record_service.py 管理，删除时同步硬删除磁盘文件。
2.2 后端 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 文档提取全量样式，导出 .doc 时可选择自定义样式；支持上传带占位符的 Word 模板，工作流生成文档后下载保持模板格式。
用户上传 Word 文档（样式提取）/ 带占位符模板（模板管理）
│
▼
┌─────────────────────────────────────────┐
│ FastAPI 后端 │
│ ├── /api/v1/styles （样式管理） │
│ ├── /api/v1/templates （模板管理） │
│ ├── /api/v1/documents （CRUD） │
│ ├── /api/v1/export/doc （样式导出） │
│ └── /api/v1/export/docx （模板填充导出）│
└────────────────┬────────────────────────┘
┌─────────┴──────────┐
▼ ▼
PostgreSQL 文件存储
（文档 + 样式/模板元数据） （样式 JSON + 模板 .docx）
│
python-docx
（样式 XML 提取 + 注入 / 模板内容合并）
新增依赖：python-docx（已在阶段 0 引入）、docxtpl（可选，模板填充）
前端编辑器应用模板样式的实现见 功能设计文档 - 阶段 1
3.1 样式管理核心逻辑
上传 Word 文档提取样式时
from docx import Document as DocxDocument
from lxml import etree
def element_to_dict(elem) -> dict:
"""递归将 lxml Element 转为嵌套字典，保留所有属性、子元素和命名空间。"""
d = {"@tag": elem.tag, "@attrib": dict(elem.attrib)}
if elem.text:
d["#text"] = elem.text
children = {}
for child in elem:
child_dict = element_to_dict(child)
tag = child.tag
if tag in children:
existing = children[tag]
if not isinstance(existing, list):
children[tag] = [existing]
children[tag].append(child_dict)
else:
children[tag] = child_dict
if children:
d["@children"] = children
return d
def extract_styles(docx_path: str) -> dict:
"""提取文档中所有样式的完整 XML 定义，保留字体摘要和段落格式摘要。"""
doc = DocxDocument(docx_path)
styles = []
for style in doc.styles:
styles.append({
"name": style.name,
"style_id": style.style_id,
"type": str(style.type),
"builtin": style.builtin,
"hidden": style.hidden,
"quick_style": style.quick_style,
# ... font_summary、paragraph_format_summary 同理
"full_xml_definition": element_to_dict(style.element),
})
return {"source_file": docx_path, "total_styles": len(styles), "styles": styles}
导出时，inject_styles_from_json() 将 JSON 中所有样式的 full_xml_definition 以 upsert 方式注入到新文档的 <w:styles> 节点，DocxRenderer 渲染各 Markdown 节点时通过 w:styleId 直接引用注入后的样式，无需手动设颜色/字号。
上传带占位符模板时
# 解析模板占位符列表
import re
from docx import Document as DocxDocument
def parse_template_placeholders(docx_path: str) -> list[str]:
doc = DocxDocument(docx_path)
placeholders = []
pattern = re.compile(r'\{\{(.+?)\}\}')
for para in doc.paragraphs:
matches = pattern.findall(para.text)
placeholders.extend(matches)
return list(dict.fromkeys(placeholders)) # 去重保序
导出 DOCX（模板填充）时
# 将文档内容按标题名称匹配占位符并替换
from docxtpl import DocxTemplate
def export_with_template(template_path: str, content_blocks: dict) -> bytes:
tpl = DocxTemplate(template_path)
context = {name: content for name, content in content_blocks.items()}
tpl.render(context)
buffer = io.BytesIO()
tpl.save(buffer)
return buffer.getvalue()
3.2 数据库新增
-- 样式文件缓存表（从上传的 Word 文档提取）
CREATE TABLE style_files (
id VARCHAR PRIMARY KEY,
name VARCHAR NOT NULL, -- 样式文件名（源文档文件名去扩展名）
source_file VARCHAR NOT NULL, -- 原始上传文件名（含扩展名）
file_path VARCHAR NOT NULL, -- 样式 JSON 文件存储路径
summary JSONB, -- 摘要（默认字体、标题字体、样式总数等）
is_default BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP
);
-- 模板表（带占位符的 Word 文档）
CREATE TABLE document_templates (
id VARCHAR PRIMARY KEY,
name VARCHAR NOT NULL,
file_key VARCHAR NOT NULL, -- 模板文件存储路径
placeholders JSONB, -- 占位符名称列表
has_header BOOLEAN DEFAULT FALSE,
has_footer BOOLEAN DEFAULT FALSE,
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 + mistune（阶段 0 引入）；docxtpl（阶段 1 模板填充，可选） | 阶段 0/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） |
文档版本: v5.0 最后更新: 2026-06-18 维护者: Axonix 前端团队