# 文本编辑器技术架构文档

## 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](./text-editor-feature-design.md#3-阶段-0打通基础链路)

### 2.1 后端 Document Service

```python
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](./text-editor-feature-design.md#4-阶段-1word-模板--工作流文档编辑)

### 3.1 Word 模板处理核心逻辑

#### 上传模板时
```python
# 解析模板样式元数据
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
```

#### 下载时合并内容与模板
```python
# 将编辑器内容写入模板，保留原始样式
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 数据库新增

```sql
-- 模板表
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`

```python
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}`

```python
@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 适配两个平台的不同通信方式：

```typescript
interface EditorComponentProps {
  documentId: string;
  token?: string;                        // oil-agent 免登录场景传入
  platform: 'mod-chat' | 'oil-agent';
  apiBaseUrl: string;
  onSave?: (content: string) => void;
  onClose?: () => void;
}
```

**WS Client 内部实现**：

```typescript
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 配置

```typescript
// vite.config.ts（编辑器打包为远程模块，供两个平台加载）
federation({
  name: 'editorModule',
  filename: 'remoteEntry.js',
  exposes: {
    './DocumentEditor': './src/components/editor/DocumentEditor',
  },
  shared: ['react', 'react-dom'],
})
```

### 4.7 Token Service

```python
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 版本管理数据表

```sql
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 前端团队