skycurtain
0e61e4f5b9
- 新增 AI 时代下的 StructRail 战略定位与发展路线图，明确 AI 集成方向 - 更新前端可视化库设计方案，细化架构、技术挑战与商业化结合点 - 重构商业化策略文档为 Q&A 形式，深入探讨市场、产品与增长策略
95 lines
4.7 KiB
Markdown
95 lines
4.7 KiB
Markdown
# 前端可视化库设计方案 (`@structrail/viz`)
|
||
|
||
## 1. 核心目标
|
||
- **解耦**：将 Tracer SDK（数据生成）与前端渲染逻辑（数据展示）完全分离。
|
||
- **复用**：打造一个通用的、可嵌入的算法可视化库，服务于 StructRail 平台及第三方场景（博客、文档、IDE 插件）。
|
||
- **标准**：作为 Tracer Protocol 的标准消费者，建立可视化渲染的事实标准。
|
||
|
||
## 2. 架构设计：确定性状态机 (Deterministic State Machine)
|
||
|
||
采用 **Player + Store + Renderer** 的分层架构，确保时间旅行（Time Travel）的可靠性。
|
||
|
||
### 2.1 Player (播放器/控制器)
|
||
- **职责**：解析 JSON 指令流，控制时间轴（Play, Pause, Seek, Speed）。
|
||
- **特性**：
|
||
- 维护当前帧索引 `currentIndex`。
|
||
- 支持步进（Step）和连续播放。
|
||
- 处理“自动暂停”指令（如 `tracer.wait()`）。
|
||
|
||
### 2.2 Store (状态仓库/沙盒)
|
||
- **职责**：维护“影子内存”（Shadow Memory），根据指令计算数据结构状态。
|
||
- **机制**：
|
||
- **增量计算**：基于 immer.js 或类似机制，只存储指令序列和初始状态，通过重放（Replay）或关键帧（Keyframe）技术快速计算任意时刻的状态。
|
||
- **快照 (Snapshot)**：向渲染层提供只读的、标准化的数据快照。
|
||
- **State(t) = Apply(InitialState, Events[0...t])**
|
||
|
||
### 2.3 Renderer (渲染器/组件库)
|
||
- **职责**：纯 UI 展示层，遵循 `UI = Render(State)` 原则。
|
||
- **实现**：
|
||
- **DOM/SVG 渲染器**：用于常规数据结构（数组、链表、树），支持 CSS 动画和高质量文本渲染。
|
||
- **Canvas/WebGL 渲染器**：用于大规模数据（如 10w+ 节点的图、矩阵热力图）。
|
||
- **组件化**：提供 `<ArrayVisualizer>`, `<GraphVisualizer>` 等独立组件。
|
||
|
||
## 3. 关键技术挑战与策略 (Advanced Technical Considerations)
|
||
|
||
为了确保该库能适应复杂的互联网环境（移动端、嵌入式、高性能场景），需重点关注以下方面：
|
||
|
||
### 3.1 响应式与移动端适配 (Responsive & Mobile First)
|
||
- **自适应布局**：Renderer 需具备流式布局能力。例如 `ArrayVisualizer` 在窄屏（手机/VS Code 侧边栏）下应自动切换为“折行显示”或“垂直列表模式”，避免横向滚动。
|
||
- **触控交互**：设计移动端友好的交互模式（如长按代替 Hover，双指缩放代替滚轮）。
|
||
|
||
### 3.2 样式隔离与嵌入性 (Style Isolation)
|
||
- **Shadow DOM**：推荐使用 Web Components (Shadow DOM) 封装渲染器，彻底隔离宿主页面（如博客全局 CSS）的样式干扰。
|
||
- **CSS Modules / CSS-in-JS**：作为备选方案，确保类名哈希化，防止污染宿主环境。
|
||
|
||
### 3.3 性能降级与 LOD (Level of Detail)
|
||
- **自动后端切换**：根据数据规模动态选择渲染后端。
|
||
- 节点 < 500：使用 SVG（交互性好，调试方便）。
|
||
- 节点 > 500：自动降级为 Canvas/WebGL（高性能）。
|
||
- **LOD 策略**：在缩放或快速播放时，自动隐藏非关键细节（如节点文本、阴影），保证渲染帧率。
|
||
|
||
### 3.4 状态序列化与分享 (Serialization)
|
||
- **State Export**：支持将当前 Store 的状态快照导出为 JSON。
|
||
- **Deep Link**：支持将状态编码为 URL 参数（如 `?state=base64...`），实现“分享当前步骤”功能。
|
||
|
||
### 3.5 插件系统与扩展性 (Plugin System)
|
||
- **Renderer Provider**：设计开放的注册接口，允许第三方开发者注册自定义渲染器。
|
||
```typescript
|
||
// 允许用户注册自定义渲染器，支持“主题市场”商业化
|
||
VizRegistry.register('GraphTracer', CyberpunkGraphRenderer);
|
||
```
|
||
- **中间件机制**：允许拦截和修改指令流，实现自定义的逻辑增强（如增加声音音效）。
|
||
|
||
## 4. 预期形态
|
||
该库将发布为 NPM 包，提供如下使用方式：
|
||
|
||
```typescript
|
||
import { Player, ArrayVisualizer } from '@structrail/viz';
|
||
import '@structrail/viz/dist/style.css'; // 或自动注入 Shadow DOM 样式
|
||
|
||
// 1. 初始化播放器
|
||
const player = new Player(events);
|
||
|
||
// 2. 渲染组件 (React 示例)
|
||
function App() {
|
||
const snapshot = usePlayerSnapshot(player);
|
||
|
||
return (
|
||
<div className="viz-container">
|
||
<ArrayVisualizer
|
||
model={snapshot.tracers['array-1']}
|
||
theme="cyberpunk" // 支持主题切换
|
||
/>
|
||
<Controls player={player} />
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
## 5. 商业化结合点
|
||
- **开源核心**：建立协议标准，获取流量。
|
||
- **付费扩展**：
|
||
- **高级主题包**：赛博朋克、手绘风、企业定制皮肤。
|
||
- **高性能渲染器**：3D 图算法渲染、大数据分析引擎。
|
||
- **云端服务**：高清视频导出 (MP4/GIF)。
|