docs: 新增并更新产品战略、技术设计与商业化规划文档
- 新增 AI 时代下的 StructRail 战略定位与发展路线图，明确 AI 集成方向 - 更新前端可视化库设计方案，细化架构、技术挑战与商业化结合点 - 重构商业化策略文档为 Q&A 形式，深入探讨市场、产品与增长策略
This commit is contained in:
@@ -1,91 +1,94 @@
|
||||
# 前端可视化库设计草案 (@structrail/viz)
|
||||
# 前端可视化库设计方案 (`@structrail/viz`)
|
||||
|
||||
本文档描述了将平台前端渲染逻辑沉淀为独立可视化库的设计构想。
|
||||
## 1. 核心目标
|
||||
- **解耦**：将 Tracer SDK（数据生成）与前端渲染逻辑（数据展示）完全分离。
|
||||
- **复用**：打造一个通用的、可嵌入的算法可视化库，服务于 StructRail 平台及第三方场景（博客、文档、IDE 插件）。
|
||||
- **标准**：作为 Tracer Protocol 的标准消费者，建立可视化渲染的事实标准。
|
||||
|
||||
## 1. 项目定位
|
||||
## 2. 架构设计：确定性状态机 (Deterministic State Machine)
|
||||
|
||||
我们将“数据生成”（Tracer SDK）与“数据展示”（Visualization Lib）完全解耦，旨在沉淀一套标准化的、可嵌入的前端可视化引擎。
|
||||
|
||||
* **Tracer SDK (后端/客户端)**：负责生成标准化的、语言无关的 JSON 指令流（Trace Protocol）。
|
||||
* **Visualization Lib (前端)**：负责解析指令流，重建数据状态，并提供交互式的可视化组件。
|
||||
|
||||
这套库不仅服务于 StructRail 平台，未来也可被嵌入到博客、电子书或教学文档中，成为算法可视化的基础设施。
|
||||
|
||||
## 2. 核心架构 (Architecture)
|
||||
|
||||
库的核心遵循 **Player + Store + Renderer** 的分层架构，本质上是一个支持时间旅行（Time Travel）的确定性状态机。
|
||||
采用 **Player + Store + Renderer** 的分层架构，确保时间旅行（Time Travel）的可靠性。
|
||||
|
||||
### 2.1 Player (播放器/控制器)
|
||||
* **职责**：负责解析 Tracer 生成的 JSON 指令流，控制播放进度（Frame/Step）。
|
||||
* **功能**：提供 `play()`, `pause()`, `next()`, `prev()`, `seek(index)` 等 API。
|
||||
* **特性**：它不关心具体怎么画，只关心“当前是第几步”以及“播放速度”。
|
||||
- **职责**：解析 JSON 指令流，控制时间轴（Play, Pause, Seek, Speed）。
|
||||
- **特性**：
|
||||
- 维护当前帧索引 `currentIndex`。
|
||||
- 支持步进（Step）和连续播放。
|
||||
- 处理“自动暂停”指令（如 `tracer.wait()`）。
|
||||
|
||||
### 2.2 Store (状态仓库/沙盒)
|
||||
* **职责**：负责根据指令重构数据结构的状态。
|
||||
* **机制**：维护一个“影子内存”（Shadow Memory）。
|
||||
* 当 Player 处于第 0 步时，Store 是空的。
|
||||
* 当收到 `ArrayTracer.create` 指令时，Store 里建立一个数组模型。
|
||||
* 当收到 `patch` 指令时，Store 更新对应数组的元素值。
|
||||
* 当收到 `pick` 指令时，Store 标记对应元素为“高亮状态”。
|
||||
* **输出**：它能在任何时间点，输出一份**只读的、标准化的数据快照 (Snapshot)** 给渲染层。
|
||||
- **职责**：维护“影子内存”（Shadow Memory），根据指令计算数据结构状态。
|
||||
- **机制**：
|
||||
- **增量计算**：基于 immer.js 或类似机制，只存储指令序列和初始状态，通过重放（Replay）或关键帧（Keyframe）技术快速计算任意时刻的状态。
|
||||
- **快照 (Snapshot)**：向渲染层提供只读的、标准化的数据快照。
|
||||
- **State(t) = Apply(InitialState, Events[0...t])**
|
||||
|
||||
### 2.3 Renderer (渲染器/组件库)
|
||||
* **职责**：纯粹的 UI 展示层（View），遵循 `f(state) => UI` 的原则。
|
||||
* **实现**：可以使用 React/Vue 组件，也可以是 Canvas/WebGL（针对大规模数据）。
|
||||
* **特点**：它完全不知道“指令”的存在，它只接收 `Store` 给它的快照。
|
||||
* 例如：`<ArrayVisualizer data={[1, 2, 3]} highlights={[1]} />`
|
||||
- **职责**：纯 UI 展示层，遵循 `UI = Render(State)` 原则。
|
||||
- **实现**：
|
||||
- **DOM/SVG 渲染器**：用于常规数据结构（数组、链表、树），支持 CSS 动画和高质量文本渲染。
|
||||
- **Canvas/WebGL 渲染器**：用于大规模数据（如 10w+ 节点的图、矩阵热力图）。
|
||||
- **组件化**：提供 `<ArrayVisualizer>`, `<GraphVisualizer>` 等独立组件。
|
||||
|
||||
## 3. 库的形态设计 (API Preview)
|
||||
## 3. 关键技术挑战与策略 (Advanced Technical Considerations)
|
||||
|
||||
如果这个库被开发出来，它在前端项目中的使用方式可能如下（以 React 为例）：
|
||||
为了确保该库能适应复杂的互联网环境（移动端、嵌入式、高性能场景），需重点关注以下方面：
|
||||
|
||||
### 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, GraphVisualizer } from '@structrail/viz';
|
||||
import { Player, ArrayVisualizer } from '@structrail/viz';
|
||||
import '@structrail/viz/dist/style.css'; // 或自动注入 Shadow DOM 样式
|
||||
|
||||
// 1. 载入 Tracer 生成的 JSON 数据
|
||||
const events = await fetch('algorithm-trace.json');
|
||||
// 1. 初始化播放器
|
||||
const player = new Player(events);
|
||||
|
||||
// 2. 绑定到 UI
|
||||
function AlgorithmDemo() {
|
||||
// 使用 player 的 hook 获取当前帧的数据快照
|
||||
// 2. 渲染组件 (React 示例)
|
||||
function App() {
|
||||
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 className="viz-container">
|
||||
<ArrayVisualizer
|
||||
model={snapshot.tracers['array-1']}
|
||||
theme="cyberpunk" // 支持主题切换
|
||||
/>
|
||||
<Controls player={player} />
|
||||
</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 树布局
|
||||
## 5. 商业化结合点
|
||||
- **开源核心**：建立协议标准，获取流量。
|
||||
- **付费扩展**：
|
||||
- **高级主题包**：赛博朋克、手绘风、企业定制皮肤。
|
||||
- **高性能渲染器**：3D 图算法渲染、大数据分析引擎。
|
||||
- **云端服务**：高清视频导出 (MP4/GIF)。
|
||||
|
||||
Reference in New Issue
Block a user