# universal-editor

**Repository Path**: clawrobot/universal-editor

## Basic Information

- **Project Name**: universal-editor
- **Description**: 通用编辑器框架 - 支持大屏图表、3D场景、工作流应用，多人协同编辑
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-02-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Universal Editor

> 通用编辑器框架 — 支持**大屏图表**、**3D 场景搭建**、**工作流应用**三种场景

[![Phase](https://img.shields.io/badge/Phase-0%20骨架-blue)]()
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)]()
[![Rust](https://img.shields.io/badge/Rust-1.75-orange)]()

---

## 架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                    Browser / Web Client                         │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                  packages/app (Vite)                     │  │
│  │                                                          │  │
│  │  ┌──────────┐ ┌─────────────────────────┐ ┌──────────┐  │  │
│  │  │ue-toolbar│ │   CanvasEngine (SVG)    │ │ue-props- │  │  │
│  │  │(Web Comp)│ │  ┌─────────────────┐   │ │ panel    │  │  │
│  │  └──────────┘ │  │ gridLayer  (SVG)│   │ │(Web Comp)│  │  │
│  │               │  │ groupLayer (SVG)│   │ └──────────┘  │  │
│  │  ┌──────────┐ │  │ linkLayer  (SVG)│   │               │  │
│  │  │ue-sidebar│ │  │ nodeLayer  (SVG)│   │               │  │
│  │  │(Web Comp)│ │  └─────────────────┘   │               │  │
│  │  └──────────┘ │  CSS Transform (GPU ↑) │               │  │
│  │               └─────────────────────────┘               │  │
│  │                                                          │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │  │
│  │  │ @ue/core │ │renderer  │ │plugin-   │ │plugin-   │  │  │
│  │  │EventBus  │ │   -2d    │ │workflow  │ │dashboard │  │  │
│  │  │HookSystem│ │NodeRend. │ │TopSort   │ │Charts    │  │  │
│  │  │PluginSys │ │LinkRend. │ │ConnRules │ │          │  │  │
│  │  │CanvasEng.│ │GridRend. │ └──────────┘ └──────────┘  │  │
│  │  │NodeReg.  │ │Selection │                             │  │
│  │  │HistoryMgr│ └──────────┘                             │  │
│  │  │CollabMgr │                                          │  │
│  │  │(Yjs)     │                                          │  │
│  │  └──────────┘                                          │  │
│  └──────────────────────────────────────────────────────────┘  │
│           │ WebSocket (yjs sync)    │ HTTP REST API             │
└───────────┼─────────────────────────┼───────────────────────────┘
            │                         │
┌───────────▼─────────────────────────▼───────────────────────────┐
│                    server/ (Rust + Axum)                        │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐ │
│  │ ws/collab.rs │  │ api/         │  │ collab/doc.rs         │ │
│  │  WebSocket   │  │ projects.rs  │  │ yrs Y.Doc per room    │ │
│  │  handler     │  │ assets.rs    │  │ broadcast channel     │ │
│  └──────┬───────┘  └──────┬───────┘  └────────────┬──────────┘ │
│         │                 │                        │            │
│  ┌──────▼─────────────────▼────────────────────────▼──────────┐ │
│  │              AppState (Arc<>)                              │ │
│  │         sqlx::PgPool │ redis::ConnectionManager            │ │
│  └──────────────────────┬────────────────────────────────────┘ │
└─────────────────────────┼──────────────────────────────────────┘
                          │
        ┌─────────────────┼────────────────────┐
        │                 │                    │
  ┌─────▼──────┐  ┌───────▼──────┐  (future)
  │ PostgreSQL │  │    Redis     │  S3/OSS
  │ projects   │  │ session/cache│
  │ assets     │  │              │
  └────────────┘  └──────────────┘
```

---

## 目录结构

```
universal-editor/
├── packages/
│   ├── core/               # 核心引擎
│   │   └── src/
│   │       ├── event/      # EventBus
│   │       ├── hook/       # HookSystem (中间件链)
│   │       ├── plugin/     # PluginSystem (三级注册)
│   │       ├── canvas/     # CanvasEngine (分层SVG)
│   │       ├── node/       # NodeRegistry
│   │       ├── history/    # HistoryManager (命令模式)
│   │       ├── collab/     # CollabManager (Yjs)
│   │       └── types/      # 公共类型
│   ├── ui/                 # Web Components (零框架)
│   │   └── src/components/
│   │       ├── UeToolbar   # 工具栏
│   │       ├── UeSidebar   # 节点侧边栏
│   │       └── UePropsPanel # 属性面板
│   ├── renderer-2d/        # SVG 渲染器
│   │   └── src/
│   │       ├── NodeRenderer    # 节点渲染
│   │       ├── LinkRenderer    # 贝塞尔连线
│   │       ├── GridRenderer    # 网格背景
│   │       └── SelectionRenderer # 框选
│   ├── renderer-3d/        # 3D 渲染器 (接口定义，Phase 2实现)
│   ├── plugin-workflow/    # 工作流插件
│   │   └── src/
│   │       ├── WorkflowNodes   # 节点类型定义
│   │       ├── ConnectionRules # 连线规则
│   │       └── TopologicalSort # 拓扑排序
│   ├── plugin-dashboard/   # 大屏插件
│   └── app/                # 主应用入口 (Vite)
├── server/                 # Rust 后台
│   ├── src/
│   │   ├── main.rs         # 启动入口
│   │   ├── state.rs        # AppState
│   │   ├── api/
│   │   │   ├── projects.rs # 项目 CRUD
│   │   │   └── assets.rs   # 资产管理
│   │   ├── ws/
│   │   │   └── collab.rs   # WebSocket 协同
│   │   └── collab/
│   │       └── doc.rs      # Y.Doc 管理
│   ├── migrations/
│   │   └── 0001_init.sql
│   └── Cargo.toml
├── pnpm-workspace.yaml
├── tsconfig.json           # 根 TS 配置 (project references)
└── README.md
```

---

## 快速开始

### 前置要求

- Node.js ≥ 18
- pnpm ≥ 8
- Rust ≥ 1.75
- PostgreSQL 15（已在 `/workspace/tools/pgroot` 安装）
- Redis 7（已在 `/workspace/tools/redisroot` 安装）

### 1. 启动服务（PostgreSQL + Redis）

```bash
/workspace/tools/start-services.sh
```

### 2. 安装前端依赖

```bash
cd universal-editor
pnpm install
```

### 3. 启动前端开发服务器

```bash
pnpm dev
# 访问 http://localhost:3000
```

### 4. 启动 Rust 后台

```bash
cd server
cargo run
# API: http://localhost:8080
# WS:  ws://localhost:8080/ws/collab/{room_id}
```

### 5. 构建生产版本

```bash
pnpm build
cd server && cargo build --release
```

---

## 模块说明

### `@ue/core` - 核心引擎

| 模块 | 说明 |
|------|------|
| `EventBus` | 迭代前快照 + try-catch 隔离，参考 node-red events.js |
| `HookSystem` | 链表中间件，`label:hookName` 格式，支持批量移除 |
| `PluginSystem` | 三级注册 module/set/type，生命周期 onload/onadd/onremove |
| `CanvasEngine` | 分层 SVG + CSS Transform（GPU加速），RAF 批量渲染 |
| `NodeRegistry` | 节点类型注册，工厂模式创建实例 |
| `HistoryManager` | 命令模式 Undo/Redo，支持 CompositeCommand |
| `CollabManager` | Yjs Y.Doc + WebsocketProvider + Awareness |

### `@ue/renderer-2d` - SVG 渲染器

- **NodeRenderer**：默认矩形 + 自定义渲染函数，端口圆点
- **LinkRenderer**：贝塞尔三次曲线，箭头 marker，命中区域
- **GridRenderer**：SVG pattern（dot/line/cross），高性能
- **SelectionRenderer**：框选矩形，拖拽选择

### `@ue/ui` - Web Components（零框架）

- **`<ue-toolbar>`**：工具栏，通过 EventBus 通信
- **`<ue-sidebar>`**：节点类型列表，支持拖拽放置
- **`<ue-props-panel>`**：动态属性表单，支持所有 PropDefinition 类型

### `@ue/plugin-workflow` - 工作流插件

- 4 种基础节点：`input / output / process / condition`
- 连线规则：类型兼容矩阵 + 自环检测 + 重复检测
- 拓扑排序：Kahn 算法，检测循环依赖

### `server/` - Rust 后台

| 路由 | 方法 | 说明 |
|------|------|------|
| `/api/health` | GET | 健康检查 |
| `/api/projects` | GET/POST | 项目列表/创建 |
| `/api/projects/:id` | GET/PUT/DELETE | 项目详情/更新/删除 |
| `/api/assets` | GET/POST | 资产列表/上传 |
| `/api/assets/:id` | GET/DELETE | 资产详情/删除 |
| `/ws/collab/:room_id` | WebSocket | Yrs 协同 |

---

## 设计决策

### 为什么用纯 TypeScript + Web Components（无 Vue/React）？

- **参考 node-red 和 drawio**：两者都使用纯 JS/TS，零框架依赖
- **可嵌入性**：Web Components 可以嵌入任何宿主（包括 Vue/React 应用）
- **包体积**：无框架运行时，最终 bundle 更小
- **寿命**：Web Components 是 W3C 标准，不受框架生命周期影响

### 为什么用 CSS Transform 而非 SVG viewBox 缩放？

- **GPU 加速**：CSS `transform` 由合成器线程处理，不触发 layout/paint
- **子像素精度**：SVG viewBox 在高 DPI 屏幕下有精度问题
- **参考 drawio**：drawio 也使用此方案

### EventBus 迭代前快照

```typescript
const snapshot = [...entries]; // 快照
for (const entry of snapshot) { entry.handler(data); } // 安全迭代
```
防止 handler 内部调用 `off()` 时修改正在迭代的数组（参考 node-red events.js）。

### Rust 服务用 Arc<AppState> 注入

所有 handler 共享状态，Axum 的 `State<Arc<AppState>>` 是零拷贝注入（Arc clone 只增加引用计数）。

---

## 开发路线图

### Phase 0 ✅ 基础骨架（当前）
- [x] Monorepo 结构（pnpm workspace）
- [x] 核心引擎（EventBus、HookSystem、PluginSystem、CanvasEngine、NodeRegistry、HistoryManager、CollabManager）
- [x] 2D SVG 渲染器（NodeRenderer、LinkRenderer、GridRenderer、SelectionRenderer）
- [x] Web Components UI（Toolbar、Sidebar、PropsPanel）
- [x] 工作流插件（节点定义、连线规则、拓扑排序）
- [x] 大屏插件（图表节点定义骨架）
- [x] Rust 后台（Axum + sqlx + Redis + yrs）
- [x] PostgreSQL 数据库（projects、assets 表）

### Phase 1 🔲 交互完善
- [ ] 节点拖拽移动（带网格吸附）
- [ ] 连线交互（端口拖拽连线）
- [ ] 键盘快捷键（Delete 删除、Ctrl+A 全选）
- [ ] 多选（框选 + Shift 点击）
- [ ] 项目保存/加载（REST API 对接）
- [ ] Yrs 协同（多人实时编辑）

### Phase 2 🔲 3D 场景
- [ ] Three.js / WebGPU 渲染器实现 `IRenderer3D`
- [ ] glTF 资产加载
- [ ] 相机控制（OrbitControls）
- [ ] 场景对象属性编辑

### Phase 3 🔲 大屏图表
- [ ] ECharts / D3 图表渲染器
- [ ] 实时数据绑定（WebSocket 数据推送）
- [ ] 大屏布局编辑（响应式网格）
- [ ] 发布/预览模式

### Phase 4 🔲 移动端展示
- [ ] Flutter 展示端（只读，WebSocket 接收更新）
- [ ] 3D 模型预览
- [ ] 大屏展示模式

### Phase 5 🔲 生产就绪
- [ ] Y.Doc 持久化（PostgreSQL BYTEA）
- [ ] 用户认证（JWT）
- [ ] 权限控制（项目级别）
- [ ] 文件存储（OSS/S3）
- [ ] Docker Compose 一键部署

---

## 技术栈

| 层 | 技术 |
|----|------|
| 前端编辑器 | TypeScript + Web Components + Vite |
| 画布渲染 | 自研（分层SVG + CSS Transform） |
| 协同（前端） | Yjs + y-websocket |
| 后台语言 | Rust 1.75+ |
| Web 框架 | Axum 0.7 + Tokio |
| 数据库 | PostgreSQL 15 + sqlx |
| 缓存 | Redis 7 |
| 协同（后端） | yrs（Yjs Rust 实现） |
| 移动/桌面展示 | Flutter（Phase 4） |

---

## License

MIT