skycurtain
a9eaaa6023
- 新增品牌命名、商业化策略、SDK视觉噪音处理、可视化库设计和系统架构文档 - 更新开发规则，明确禁止主动修改项目源代码文件 - 所有文档均为中文编写，用于记录项目设计讨论和决策
92 lines
4.4 KiB
Markdown
92 lines
4.4 KiB
Markdown
# 前端可视化库设计草案 (@structrail/viz)
|
||
|
||
本文档描述了将平台前端渲染逻辑沉淀为独立可视化库的设计构想。
|
||
|
||
## 1. 项目定位
|
||
|
||
我们将“数据生成”（Tracer SDK）与“数据展示”（Visualization Lib）完全解耦，旨在沉淀一套标准化的、可嵌入的前端可视化引擎。
|
||
|
||
* **Tracer SDK (后端/客户端)**：负责生成标准化的、语言无关的 JSON 指令流（Trace Protocol）。
|
||
* **Visualization Lib (前端)**：负责解析指令流，重建数据状态，并提供交互式的可视化组件。
|
||
|
||
这套库不仅服务于 StructRail 平台，未来也可被嵌入到博客、电子书或教学文档中，成为算法可视化的基础设施。
|
||
|
||
## 2. 核心架构 (Architecture)
|
||
|
||
库的核心遵循 **Player + Store + Renderer** 的分层架构，本质上是一个支持时间旅行（Time Travel）的确定性状态机。
|
||
|
||
### 2.1 Player (播放器/控制器)
|
||
* **职责**：负责解析 Tracer 生成的 JSON 指令流，控制播放进度（Frame/Step）。
|
||
* **功能**：提供 `play()`, `pause()`, `next()`, `prev()`, `seek(index)` 等 API。
|
||
* **特性**：它不关心具体怎么画，只关心“当前是第几步”以及“播放速度”。
|
||
|
||
### 2.2 Store (状态仓库/沙盒)
|
||
* **职责**：负责根据指令重构数据结构的状态。
|
||
* **机制**：维护一个“影子内存”（Shadow Memory）。
|
||
* 当 Player 处于第 0 步时，Store 是空的。
|
||
* 当收到 `ArrayTracer.create` 指令时，Store 里建立一个数组模型。
|
||
* 当收到 `patch` 指令时，Store 更新对应数组的元素值。
|
||
* 当收到 `pick` 指令时，Store 标记对应元素为“高亮状态”。
|
||
* **输出**：它能在任何时间点，输出一份**只读的、标准化的数据快照 (Snapshot)** 给渲染层。
|
||
|
||
### 2.3 Renderer (渲染器/组件库)
|
||
* **职责**：纯粹的 UI 展示层（View），遵循 `f(state) => UI` 的原则。
|
||
* **实现**：可以使用 React/Vue 组件，也可以是 Canvas/WebGL（针对大规模数据）。
|
||
* **特点**：它完全不知道“指令”的存在，它只接收 `Store` 给它的快照。
|
||
* 例如：`<ArrayVisualizer data={[1, 2, 3]} highlights={[1]} />`
|
||
|
||
## 3. 库的形态设计 (API Preview)
|
||
|
||
如果这个库被开发出来，它在前端项目中的使用方式可能如下（以 React 为例）：
|
||
|
||
```typescript
|
||
import { Player, ArrayVisualizer, GraphVisualizer } from '@structrail/viz';
|
||
|
||
// 1. 载入 Tracer 生成的 JSON 数据
|
||
const events = await fetch('algorithm-trace.json');
|
||
const player = new Player(events);
|
||
|
||
// 2. 绑定到 UI
|
||
function AlgorithmDemo() {
|
||
// 使用 player 的 hook 获取当前帧的数据快照
|
||
const snapshot = usePlayerSnapshot(player);
|
||
|
||
return (
|
||
<div>
|
||
{/* 播放控制栏 */}
|
||
<ControlBar player={player} />
|
||
|
||
{/* 渲染区域：根据 snapshot 中的数据自动渲染 */}
|
||
<div className="canvas">
|
||
{snapshot.tracers.map(tracer => {
|
||
if (tracer.type === 'array') {
|
||
return <ArrayVisualizer key={tracer.id} model={tracer} />
|
||
}
|
||
if (tracer.type === 'graph') {
|
||
return <GraphVisualizer key={tracer.id} model={tracer} />
|
||
}
|
||
})}
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
## 4. 关键技术挑战 (Technical Challenges)
|
||
|
||
### 4.1 增量计算与快照管理
|
||
* **问题**：如果算法有 100 万步，不能每一步都存一个深拷贝的快照。
|
||
* **策略**：使用类似 Git 的机制或 immer.js。Store 只记录关键帧（Keyframe）的快照，中间步骤通过重放指令（Replay）动态计算。
|
||
|
||
### 4.2 动画过渡 (Animation)
|
||
* **问题**：当从“第 1 步”跳到“第 2 步”时，如果只是数据的突变（1 -> 2），体验很生硬。
|
||
* **策略**：渲染层需要比较 `PrevSnapshot` 和 `CurrentSnapshot`（Diff）。
|
||
* 如果发现数组 index 0 的元素位置变了，它应该生成一个移动动画。
|
||
* 这就是为什么我们的 `patch` / `swap` 指令语义很重要，它们对应了不同的动画原语。
|
||
|
||
### 4.3 自动布局 (Auto-Layout)
|
||
* **问题**：后端 Tracer 通常不包含坐标信息（除非我们以后添加坐标指令，但通常不建议耦合 UI 细节）。
|
||
* **策略**：前端库需要内置强大的自动布局算法。
|
||
* Graph: Force-directed graph (力导向图)
|
||
* Tree: Reingold-Tilford 树布局
|