超节点 3D 可视化设计规格

字段	值
版本	v0.1.0
状态	Accepted
日期	2026-06-19
作者	xiang.li
前置	无

变更历史

版本	日期	变更
v0.1.0	2026-06-19	初版草稿

@tbl-sn3d-changelog 文档变更历史

概述

本 spec 冻结超节点 3D 可视化 v1 的产品定位、视觉规格、资产管线与故事线交互。可视化目标从「程序化几何 + emissive 装饰」升级为「照片级真实感 + 可定制模板组合 + 分四层 (L1–L4) 递进式视觉」，对外用于产品宣传、对内承接后续数字孪生数据流。

本 spec 同时冻结四项跨章节生效的决策：①「8 件套模板库」作为硬件视觉的最小复用单元；② 用户可配置的范围限定在 L1（模板组合），L2（皮肤系统）非本次范围；③ 资产管线走 Blender 高模 + PBR + 烘焙 lightmap → Draco 压缩 glTF；④ 后续数据流接入点（链路 metadata、shader uniform）在 v1 预留。

背景

当前 frontend/src/components/Scene3D/ 渲染机柜、托盘、芯片为 box + 程序化纯色 + emissive 装饰，与真实超节点（NVL72 / GB300 / Rubin）的视觉差距大，且所有性能数据都在 2D TopologyGraph 视图，3D 仅承担"结构展示"。具体落差：

• 视觉不可信：Box + 纯色无法还原冷板拉丝铝、PCB 阻焊、铜缆 cartridge、Blackwell 双 die 这些"超节点辨识锚点"，宣传场景下用户辨识为示意图而非产品演示。
• 缺乏故事化：3D 仅支持自由相机 + 钻取层级切换，无开场巡游、无爆炸分解、无标注浮现的引导式交互；宣传时无法"一眼震撼 + 深入有料"。
• 硬编码无定制：节点几何在 R3F 组件里硬编码，新增"光交换托盘"或"自定义托盘布局"需改 TSX，无法对接 perfmodel/configs/ 的 YAML 配置。
• 数据流无接口：后续要叠加 G5 仿真数据（链路利用率、热点芯片）时，没有 metadata 通道（linkId / chipId）和 shader uniform 约定，需要重写资产层。

业界对标：Lusion / Active Theory 的产品级 3D 网页体验做"真实感 + 故事化"但无数据，硬件厂商（NVIDIA Omniverse / Vertiv Spectrum）有数据但不会做"产品级第一印象"。两者交集是本可视化的差异化位置。

名词定义

渲染分层

• L1 全景层：开场 12 秒的电影级巡游，承担"第一印象"。技术上是 Blender Cycles 离线 path tracing 渲染的 4K @ 30fps 视频段，浏览器播放。
• L2 结构层：机柜/托盘的爆炸分解 + 标注浮现，承担"结构清晰"。技术上是 R3F 实时 3D + react-spring 动画。
• L3 细节层：芯片封装与 die floorplan 的钻取展示，承担"内行细节"。技术上是高分辨率贴图 + 离线烘焙的 die shot 纹理。
• L4 数据层：链路实时数据流（带宽 / 利用率 / 拥塞）的可视化，本 spec 仅预留接口，不实现。

模板与配置

• 模板（Template）：一个可被实例化复用的硬件几何单元（如"通用 1U 计算托盘"），含高模 + PBR 贴图 + LOD 三档。所有模板预先建好打包进资产库。
• 8 件套：v1 资产库的最小集合——机柜骨架、计算托盘、交换托盘、电源 shelf、GPU 风格封装、CPU 风格封装、铜缆 cartridge、光纤束。
• L1 自定义配置：用户通过 YAML/JSON 配置组合模板（如"18 个计算托盘 + 9 个交换托盘"），不改模板本体。
• L2 皮肤系统：用户替换贴图（PCB 颜色 / logo / HDRI），非本 spec 范围。
• L3 模块本体：新增模板（如"光交换托盘"模板），需 Blender 建模 + 入库流程，非用户开放。

资产与管线

• glTF：本项目统一的 3D 资产格式，含几何 / 材质 / 动画。
• Draco：glTF 的几何压缩格式，bound 在 R3F 加载器支持。
• 烘焙 lightmap：Blender Cycles 离线计算的间接光 / AO 烘焙到纹理，运行时直接采样，绕开 WebGL 缺间接光的局限。
• PBR：基于物理的材质 = albedo + metalness + roughness + normal + AO 五张贴图组成。
• LOD（Level of Detail）：同一模板的三档简化几何，按相机距离切换。

故事线

• 封面镜头：可被截图用于 PPT / 推特的标志性 3D 画面。本 spec 定义其视觉目标作为资产打磨基准。
• 巡游脚本：L1 视频的相机路径与时长规划。
• 爆炸序列：L2 机柜分解的层级、节奏、标注顺序。

目标与非目标

目标

1. 冻结 8 件套模板的视觉规格——每件含几何要点、PBR 参数、标志性细节清单、尺寸量级、LOD 三档的多边形预算。覆盖 NVL72 / GB300 / Rubin 风格的视觉设计语言。
2. 冻结 L1 自定义配置 schema——能用 YAML/JSON 表达"任意自定义超节点 = 8 件套模板的组合"，对接 perfmodel/configs/topologies/ 现有结构。新增字段必须显式标注为"视觉 metadata"，不影响性能仿真语义。
3. 冻结资产管线规范——Blender 工程组织、烘焙流程、glTF 导出参数、Draco 压缩参数、资产命名约定、版本化策略。任意美术按此规范能产出可被 R3F 直接消费的 glTF。
4. 冻结 L1→L2→L3 故事线脚本——三层的时长、相机姿态、标注节奏、交互触发点；定义视频段与实时 3D 衔接的相机参数对齐方式。
5. 冻结封面镜头视觉目标——明确构图、光照、被摄主体、目标渲染质量参考；所有资产打磨围绕此帧的目标质量推进。
6. 预留 L4 数据流接入接口——每个模板实例携带 metadata.linkId / chipId / trayId；shader uniform 约定 uUtilization / uBandwidth / uCongestion 三个通道；约定数据从 backend 推送到前端的消息信封字段。

非目标

• 不做 L2 皮肤系统：用户运行时改色 / 换 logo / 切 HDRI 非 v1 范围。
• 不做 L3 模块本体扩展：新增模板类型（除 8 件套外）需走 Blender 入库流程，不作为 v1 用户能力。
• 不实现 L4 数据流的具体渲染：v1 只预留 metadata 与 shader uniform 接口，粒子流动 / 时间轴 scrub / 热点呼吸的具体实现归后续 spec。
• 不改 G5 / Math 仿真后端：本 spec 是纯前端可视化设计，后端仅在 L4 接入时新增数据推送，不改建模语义。
• 不覆盖 2D TopologyGraph 视图：2D 视图保留作为分析工具，本 spec 不涉及。
• 不做拓扑生成器：拓扑数据由拓扑生成器设计规格产出，本 spec 消费其结果。
• 不冻结 8 件套以外的具体硬件类型支持：CXL switch、光交换托盘等后续模板归 v2。

用例说明

用例 1：客户演示开场。销售在 demo 时打开页面，0–12 秒自动播放电影级巡游——远景一排深色机柜在数据中心冷光下，相机推近、绕过铜缆墙、停在某个机柜斜俯视半爆炸状态。目标观感：用户第一眼建立视觉可信度，识别为产品演示而非示意图。

用例 2：工程师讲解机柜结构。点击"爆炸视图"，机柜的 18 计算 board / 9 交换 board / 6 电源 shelf 沿 Y 轴展开，每层错峰浮现标注（"计算 board × 18 / Grace+Blackwell"），工程师可暂停在任意层、悬停看每个部件的功能。整体节奏参考用户提供的 Rubin 爆炸分解图视觉语法。

用例 3：硬件细节钻取。双击某个计算托盘，相机推近、托盘外壳淡化、看到内部 PCB + 冷板 + 4 个 GB200 封装；再双击某颗封装，看到双 die + 8 颗 HBM3e + CoWoS 硅桥 + 银色 IHS 盖；继续钻取看 die floorplan 上 SM 阵列、cache 块、IO PHY 的着色高亮。

用例 4：自定义超节点配置。研究员在 perfmodel/configs/topologies/my_pod.yaml 里写"32 计算托盘 + 4 交换托盘 + 液冷"，前端读到配置后用模板库实时组装 3D 场景，无需任何 TSX 改动。

用例 5：后续数据流接入（L4，非本 spec）。G5 仿真完成后推送链路数据，前端读 linkId → utilization 映射，沿对应铜缆 cartridge 跑发光粒子流；热点芯片的 emissive 强度绑利用率。本 spec 仅在 L2/L3 阶段把 metadata 和 uniform 通道预留好。

详细设计

概念模型

可视化由四层正交概念构成：

概念	职责	状态
模板库（Template Library）	定义"硬件长什么样"——8 件套 glTF 资产 + PBR 贴图 + LOD	设计时冻结，运行时只读
配置 schema（Topology Config）	定义"组合成什么超节点"——YAML 描述模板的实例化与排布	用户可改
组装引擎（Scene Composer）	把 Config 实例化成 R3F scene graph，挂载 metadata	运行时执行
故事线控制器（Story Director）	编排 L1→L2→L3 的相机、动画、标注、衔接	运行时执行

@tbl-sn3d-concept-model 概念模型四层职责

四层关系：模板库 + 配置 → 组装引擎 → R3F 场景 → 故事线控制器在场景上叠加交互。L4 数据流将来挂在组装引擎产出的 metadata 通道上，不影响其他三层。

设计原理

为什么 8 件套是最小集合而不是 4 件或 16 件。超节点的视觉骨架 = 容器（机柜/托盘）+ 填充（封装/芯片）+ 互联（线缆）+ 配套（电源/液冷）。每类至少 1–2 件才能组合出可信场景——4 件不够（缺互联和电源会"假"），16 件冗余（光交换 / 存储托盘等 v1 用不到）。8 件覆盖 NVL72 / GB300 / 通用机柜 99% 的视觉，且每件可通过参数化（U 高 / 芯片数 / 颜色）支持自定义。

为什么模板视觉是"半虚构"而不是严格还原 NVL72。严格还原会绑死品牌和具体配置，自定义灵活性丧失；完全原创设计需工业设计师投入且失去"看起来像真硬件"的杠杆。半虚构 = 视觉语言（深色机柜 + 金色把手 + 铜缆墙 + 银色冷板）严格抄业界，但不带品牌标识 + 不绑特定配置 + 关键尺寸参数化。

为什么 L1 用预渲染视频而不是实时 3D。WebGL 单帧上限是高质量 archviz 水平，path tracing 离线渲染可达到接近实拍的目标质量（量化以盲测和 SSIM 指标度量，见 验收标准 节）。宣传场景接受"开场固定相机路径"的约束，正好可以走视频。视频最后一帧的相机姿态 = L2 实时 3D 接管的初始相机姿态，用户感知是连续 3D 体验。Apple iPhone 产品页就是这套架构。

为什么 L2/L3 用实时 3D 而不全用视频。L2 爆炸图 + L3 钻取必须响应用户交互（点击哪层、钻到哪颗芯片），视频无法分支。这里牺牲部分真实感（实时缺间接光），靠烘焙 lightmap + HDRI 反射 + 高质量 PBR 补偿，差距以验收标准中的盲测维度度量。

为什么 L4 仅预留接口不实现。L4 要等 G5 仿真数据接入与回放控制系统就位，依赖 G5 trace 出口与时间轴控件（见前置仿真洞察工作台 spec），并行做风险高。预留 metadata 通道与 shader uniform 协议，等数据通路稳定后再补 L4 实现 spec。

为什么用 Blender + glTF + Draco 而不是 USD / FBX。glTF 是 R3F 原生格式（@react-three/drei 的 useGLTF 直接消费）+ Draco 压缩比 FBX 高 + Blender 开源免许可费 + 资产文件可入 git（带 LFS）。USD 是 NVIDIA Omniverse 主力但浏览器生态弱。

8 件套视觉规格

每件按统一格式：几何要点 / PBR 参数 / 标志性细节 / 尺寸量级 / LOD 三档。完整参数表见 附录 C。本节给概念要点。

模板 1：机柜骨架（Rack Frame）。深色金属框架 + 前/后门 + 底座 + 顶盖。标志性细节：顶部铭牌位（可参数化贴 logo）、底部脚轮、后部 1400A 铜母排（竖向）。PBR：高金属度低粗糙度漆面 + 边缘磨损法线贴图。尺寸：48U 标准（≈ 2.1m 高）、可参数化 32U/42U/48U。LOD：远景 box + 法线贴图骗细节 / 中景 + 门板分模 / 近景 + 铆钉 + 散热缝隙。

模板 2：计算托盘（Compute Tray）。1U/2U 托盘外壳 + 内部 PCB + 1–8 个芯片位 + 冷板覆盖 + 前面板。标志性细节：银/铜色冷板拉丝纹理（金属各向异性反光）、前面板 InfiniBand 笼口阵列、E1.S 抽屉。PBR：冷板高金属度低粗糙度 + 拉丝 anisotropy；PCB 深绿/黑阻焊 + 金色焊盘 + 丝印贴图。芯片位数量参数化（1/2/4/8）。LOD：远景仅外壳 + 前面板贴图 / 中景显冷板 / 近景显电容电感法线。

模板 3：交换托盘（NVSwitch Tray）。1U 托盘 + 内部 PCB + 中央交换 ASIC + 前面板金色把手横排（NVL72 标志性特征）。标志性细节：镀金色把手反光、前面板 LED 状态条、后部高密度连接器。PBR：把手高金属度极低粗糙度（镜面级反射）。LOD：远景仅前面板贴图显示把手 / 中近景显 ASIC 与冷板。

模板 4：电源 shelf（Power Shelf）。1U 高密度 PSU 阵列 + 前面板风扇格栅 + 输入接口。标志性细节：风扇可旋转动画、PSU 状态 LED、后部 busbar 接入。LOD：远景 box / 中近景显风扇与 PSU 模块。

模板 5：GPU 风格封装（GPU Package）。半虚构 GB200 风格——基板 + 中央双 die 区 + 每侧 4 个 HBM 黑色矩形（默认 2 die × 每侧 4 HBM = 共 8 HBM，对应 GB200 拓扑）+ 银色 IHS 顶盖 + 基板四周电容阵列。标志性细节：IHS 镜面反射环境、HBM 堆叠侧面层数纹理、中缝硅桥可见线（IHS 关闭态不可见，仅在 L3 钻取打开 IHS 后显示）。参数化：die 数量（1/2）、每侧 HBM 数量（4/6/8）、封装尺寸。PBR：IHS 高金属度低粗糙度；HBM 中等金属度中等粗糙度（半镜面陶瓷）。LOD：远景仅顶视贴图 / 中景显 HBM 立体 / 近景显基板电容 + 顶盖反射高分辨。

模板 6：CPU 风格封装（CPU Package）。半虚构 Grace 风格——中央方形 die + 金属 IHS + 周围 LPDDR 颗粒方阵（上下两面，参数化 8–16 颗）。PBR 同 GPU 封装但 IHS 反光更钝。LOD 三档同上。

模板 7：铜缆 cartridge（Copper Cable Cartridge）。NVL72 后部标志性特征——竖向密集铜色同轴线缆束 + 上下连接器 + 浮动咬合机构。视觉关键：让人远看就识别"铜色线缆墙"。实现：高密度法线贴图 + alpha 卡片骗细节，不真建几千根缆。标志性细节：缆束密度参数化（每 cartridge 1000+ 缆）、连接器面板。LOD：远景平面贴图 / 中景 instanced 圆柱 / 近景几何 + 缆扣。

模板 8：光纤束（Fiber Bundle）。CloudMatrix 384 风格——多色光纤线缆束 + LC/MPO 接头。参数化：束粗（几十到上千根）、走线路径（贝塞尔曲线）。PBR：光纤透明 + 接头金属。LOD：远景 spline 几何 / 中近景多股 instanced 圆柱。

配置 schema

L1 自定义配置在 configs/topologies/ 现有 YAML 上新增 visual 命名空间，不污染性能仿真字段。现有 schema 是 pods[].racks[].boards[].chips[] 四层 count 分组结构（见 configs/topologies/_template.yaml），本 spec 不改这个结构，只在每层旁挂可选 visual_template 字段，并在文件顶层加一段 visual 全局节：

# configs/topologies/my_pod.yaml
name: "my_custom_pod"

pods:
- count: 1
  visual_template: standard_pod      # ← 新增,可选
  racks:
  - count: 8
    visual_template: rack_48u_liquid # ← 新增,可选 (机柜骨架模板)
    boards:
    - count: 18
      visual_template: compute_1u_4chip  # ← 新增,可选 (托盘模板,对应 8 件套之一)
      chips:
      - name: "GB200"
        preset_id: "gb200"
        count: 4
        visual_template: gpu_2die_8hbm  # ← 新增,可选 (封装模板)

network:
  # ... 现有字段不变 ...
  # 新增:线缆视觉
  visual_cables:                     # ← 新增,可选
    - link_type: r2r                  # 绑现有 link_type
      template: copper_cartridge
      count: 4

visual:                              # ← 新增全局节,可选
  theme: dark                        # v1 仅 dark
  show_labels: true
  explode_default: false

字段语义：①visual_template 全部可选——缺失时前端按节点类型选默认模板（如 pods → standard_pod / racks → rack_48u_dark）。②新增字段不影响仿真——后端 perfmodel/ 不读 visual_template / visual_cables / visual 任何字段，前端 Scene3D 组装引擎独占消费。③枚举受限——visual_template 取值必须在 v1 模板库注册表中，前端启动时校验，未注册值报错（遵循 config-loading.md 禁默认值兜底规则）。

合规说明：新增字段为可选不构成"格式变更"——现有 YAML 不动可直接渲染（前端组装时缺字段走默认模板，属 UI 层默认而非 config-loading 层 fallback）。不违反 no-backward-compat.md（无格式分支判断 / 无 if-old-else-new 代码路径）和 config-loading.md（默认值是渲染层 UX 选择，不是配置必须字段的兜底）。同时按 sync-templates.md 要求，本 spec Implemented 时必须同步更新 configs/topologies/_template.yaml 加入 visual_template / visual 字段注释示例。

资产管线

Blender 工程组织：

assets-src/                          # 源工程,入 git LFS
├── modules/
│   ├── 01-rack-frame.blend
│   ├── 02-compute-tray.blend
│   ├── 03-nvswitch-tray.blend
│   ├── 04-power-shelf.blend
│   ├── 05-gpu-package.blend
│   ├── 06-cpu-package.blend
│   ├── 07-copper-cartridge.blend
│   └── 08-fiber-bundle.blend
├── textures/                        # PBR 贴图源（4K PNG）
│   └── shared/                      # 跨模板共享纹理（金属 / PCB / 漆面）
└── scenes/
    └── cover-shot.blend             # 封面镜头工程

frontend/public/assets/3d/           # 编译产物,入 git
├── modules/
│   ├── rack-frame.glb              # Draco 压缩 glTF
│   └── ...
└── textures/                        # 压缩 KTX2 / Basis

烘焙流程（每模板）：①Blender 设置场景光照（HDRI + key light）；②对模板烘焙 lightmap（间接光 + AO）到第二 UV 通道；③导出 glTF 时合并 lightmap 到 albedo（multiply）或独立通道（取决于运行时是否还要叠光）；④用 gltf-pipeline 跑 Draco 压缩（位置 14 位 / 法线 10 位）；⑤用 KTX-Software 把 PBR 贴图压成 KTX2 / Basis。

资产命名约定：<module-id>-<variant>-<lod>.glb，如 compute-tray-1u-4chip-lod1.glb。

版本化：模板版本随 spec 版本一起升。Breaking change（删字段/改语义）走 spec major bump。资产文件存 frontend/public/assets/3d/v1/ 目录隔离，未来 v2 资产并存。

性能预算：单个模板最高 LOD 不超过 100k 三角形；单贴图集压缩后不超过 4 MB；首屏 8 件套总下载不超过 30 MB（参考 Apple 产品页 20–40 MB 区间）。

故事线脚本

L1 巡游视频（12 秒，4K @ 30fps，预渲染）：

段	时长	相机	画面
0	0–2s	远景	数据中心冷光 + 一排深色机柜阵列
1	2–5s	推近	镜头穿过冷通道、看到机柜后部铜缆墙微微发光
2	5–9s	绕行	绕过单个机柜、相机抬升
3	9–12s	停止	停在"封面镜头"姿态（斜俯视、半爆炸、铜缆墙发光）

@tbl-sn3d-l1-script L1 巡游视频分镜表

L2 爆炸序列（用户交互触发，7 秒动画，按 NVL72 标准 33 部件——18 计算托盘 + 9 交换托盘 + 6 电源 shelf 设计节奏）：

段	时长	内容
0	0–1s	机柜外壳淡化（opacity 1→0.3）
1	1–4s	33 部件沿 Y 轴拉开，缓动 ease-out
2	4–5s	哑节奏（不弹标注，留 1 秒看结构）
3	5–7s	标注分批浮现：从上到下错峰 60ms × 33 部件 ≈ 2s（按部件数自适应 60–100ms 间隔，确保总时长 ≤ 2s）

@tbl-sn3d-l2-script L2 爆炸动画节奏表

L3 钻取（用户双击触发，2 秒动画）：相机推近到目标 → 上层外壳淡化 → 下层细节淡入 → 高分辨率贴图加载（带 loading 指示）。

衔接：L1 视频的最后一帧相机姿态硬编码到代码常量 COVER_SHOT_CAMERA，L2 实时 3D 接管时 R3F <PerspectiveCamera> 初始化用同一参数，过渡用 <video> 元素的 ended 事件触发实时层 mount + 视频元素 fade out。

封面镜头

视觉目标定义为一帧 4K 静态图，所有资产打磨围绕此帧的目标质量推进：

维度	规格
构图	斜俯视 30° + 偏左 20°，机柜占画面 70%，背景冷通道纵深
主体	单个 NVL72 风格机柜，处于半爆炸状态（托盘拉开 50%）
光照	HDRI 数据中心环境 + key light 从右上 + rim light 从左
焦点	铜缆墙微微发光（emissive 0.3）+ Blackwell 顶盖反射环境 + 金色把手镜面反光
后期	bloom（金缆与 LED，强度 0.3）+ ACES tone mapping + 胶片颗粒 0.05
质量参考	联合基准——Apple iPhone 16 Pro 产品页 hero 图（管整体调性 / 光影质感）+ NVIDIA GB200 官方渲染图（管硬件细节真实度），盲测按两维度评
客观验收	Blender Cycles 4K 渲染产出 assets-src/scenes/cover-shot.blend 对应的 PNG 入 docs/refs/cover-shot-target.png，作为构图 / 光照 / 主体三维度的对照基准

@tbl-sn3d-cover-shot 封面镜头视觉目标规格

此帧作为 Blender 工程 assets-src/scenes/cover-shot.blend 落地，导出 4K PNG 入 docs/refs/cover-shot-target.png 作为视觉验收基准。

L4 接口预留

v1 阶段仅预留三类接口，不实现渲染：

Metadata 通道：组装引擎产出 R3F scene graph 时，每个互联线缆实例挂 userData.linkId（对接 network 节 links[] 中 {from, to, type} 三元组派生 ID），每个芯片实例挂 userData.chipId（对接 expander 产出的 short chip ID c0..cN），每个 board 挂 userData.boardId。

Shader uniform 协议：所有可被数据驱动的材质（emissive 部件）暴露统一 uniform：

• uUtilization: float（0–1）→ 控制 emissive 强度
• uBandwidth: float（0–1）→ 控制粒子流密度（v1 静态）
• uCongestion: float（0–1）→ 控制颜色 hue 偏移（蓝→红）

v1 阶段三个 uniform 写死 0.0，L4 阶段由控制器按数据驱动。

消息信封约定：后续 L4 数据从 backend 推送时走 WebSocket，复用前端仿真洞察工作台 spec 定义的消息信封格式，新增 type: "viz.linkflow" 子类型，payload 字段 {linkId, utilization, bandwidth, congestion, timestamp}。

集成点

与现有系统的衔接：

上游	数据	形式
configs/topologies/	拓扑结构 + 视觉 metadata	YAML → 后端 expand → JSON
frontend/src/utils/topologyGenerator/expander.ts	节点层级结构	TS 对象
backend services/api/topologies	拓扑查询接口	HTTP /api/topologies/:id

@tbl-sn3d-integration-upstream 上游数据来源

下游	数据	形式
L4 数据流（后续 spec）	链路实时数据	WebSocket viz.linkflow
2D TopologyGraph 视图	共享同一数据源	不互相依赖

@tbl-sn3d-integration-downstream 下游数据流向

替换关系：v1 上线即替换现有 Scene3D/，旧组件不保留并存，git history 备查。理由：并存会维护两套渲染逻辑、双倍 picking/钻取代码、bundle 翻倍，无对应业务收益。

引用

• 实拍参考：refs/superpod-hardware/ 18 张 NVL72/GB300/TPU Ironwood 实拍
• 视觉语法参考：用户提供 3 张 Rubin 机柜信息图（爆炸分解 / 全景 / BOM）
• 业界对比详见 附录 A

备选方案

维度	方案 A：Blender+glTF+R3F（选定）	方案 B：USD+Omniverse	方案 C：纯程序化升级
真实感上限	8–9 成（烘焙补偿）	9–10 成（实时 path tracing）	6 成（无外部贴图）
浏览器兼容	全平台 WebGL	需 Omniverse 客户端或重做 web 端	全平台 WebGL
工作量	2–3 月 v1	6 月以上 + 客户端分发	1–2 月但效果差
自定义灵活性	模板组合 + 参数化	模板组合 + 参数化	完全自由但效果有限
与现有栈契合	沿用 R3F	重做前端	沿用 R3F
数据流接入难度	metadata + uniform 预留	NVIDIA 工具链原生支持	uniform 预留

@tbl-sn3d-alternatives 方案对比

选择理由：方案 A 是浏览器内"真实感 / 工作量 / 灵活性"的最优解。方案 B 真实感上限最高但要求客户端、放弃 web 部署的现实约束，不可接受。方案 C 工作量看似最低但效果天花板低，达不到"宣传级"目标，等于不做。

非功能性需求

维度	本 spec 的考虑
性能（Performance）	桌面端 60fps @ 1080p（中等场景）/ 30fps @ 4K（封面帧场景）。首屏 LCP < 3s（不含巡游视频）。模板总包体 ≤ 30 MB
兼容性（Compatibility）	YAML 配置向后兼容：旧 YAML 缺 visual 节时按默认主题渲染；新增字段不影响 perfmodel 仿真。glTF v2.0 + Draco + KTX2，需 WebGL2，不支持 WebGL1（2026 年浏览器覆盖率 > 99%）
可观测性（Observability）	资产加载耗时 / 渲染帧率 / WebGL 上下文丢失次数上报（沿用现有 frontend 监控）
可靠性（Reliability）	WebGL 上下文丢失自动重载（现有逻辑保留）；glTF 加载失败退化到 box placeholder + warning
安全性（Security）	N/A——前端可视化，不涉及鉴权 / 数据加密 / 敏感字段
隐私（Privacy）	N/A

@tbl-sn3d-nfr 非功能性需求

局限与后续工作

局限

风险 / 局限	影响	缓解措施
WebGL 实时部分缺间接光	L2/L3 真实感 8–9 成而非 10 成	烘焙 lightmap + HDRI 反射补偿
L1 视频固定相机路径	用户无法自由探索全景	仅用于开场，5–15 秒后切实时层放开相机
8 件套覆盖不到所有硬件	光交换 / 存储等需 v2 扩展	v2 spec 立项前固定枚举范围
模板视觉"半虚构"	不严格等于 NVL72 / Rubin	用户配置可自定义但视觉骨架统一
视频文件占带宽	巡游视频 4K ≈ 20–40 MB	提供 1080p 降级版本；首次加载用 CDN
L4 接口未经实际数据验证	后续 L4 接入可能改协议	v1 仅预留接口，L4 spec 时回头确认

@tbl-sn3d-limitations 设计局限与缓解

后续工作

方向	优先级	前置
L4 实时数据流 spec + 实现	高	G5 trace 出口稳定 + 本 spec Implemented
L2 皮肤系统（颜色 / logo / HDRI）	中	本 spec Implemented + 用户反馈
模板库 v2 扩展（光交换 / 存储 / CXL）	中	业务需求触发
移动端 / VR 支持	低	本 spec Implemented
Gaussian Splatting 真实机房素材接入	低	真机房拍摄素材可获取

@tbl-sn3d-future-work 后续工作方向与优先级

验收标准

场景	指标	目标值	测试方法
封面帧渲染质量	主观盲测加权评分	≥ 3.5/5（10 名非项目工程师，4 维度评分）	混排 5 张参考图（Apple + NVIDIA）+ 5 张本 spec 输出 + 5 张干扰组（低质量 CG），4 维度（光影 / 材质 / 构图 / 细节真实度）各 1–5 分，加权平均
封面帧客观对照	实时 R3F 渲染 vs Blender Cycles 4K 离线 PNG	SSIM ≥ 0.85 / LPIPS ≤ 0.20	相机姿态固定，封面相机参数下采样对比 docs/refs/cover-shot-target.png
封面构图/光照/主体对齐	与 docs/refs/cover-shot-target.png 对照	三维度全部符合规格表	spec 评审者人工对照构图角度 / 光源方向 / 主体位置
8 件套覆盖度	能用模板组合还原	NVL72 / GB300 / 通用 32U 机柜三类	三个配置 YAML 跑通可视化无 placeholder
配置 schema 兼容	现有 YAML 直接可用	100%	configs/topologies/ 下所有 YAML 加载无报错
L1 视频→L2 衔接	相机姿态对齐	视频末帧与实时层首帧相机参数差异 < 1°	自动化截图对比
L2 爆炸动画	节奏符合脚本	0–1s 外壳淡化 / 1–4s 拉开 / 4–5s 哑节奏 / 5–7s 标注错峰浮现	录屏检查
资产管线可独立产出	任意美术按 spec 文档独立产出 1 个 glTF	通过 R3F useGLTF 加载无报错且材质正确显示	找 1 名外部美术按 spec 复现 1 个模板
L3 钻取深度	至少 4 层	Pod → Rack → Board → Package → die	交互测试
L4 接口预留	metadata + uniform 完整	抽样检查 10% 节点都挂 userData.{linkId/chipId/boardId}	自动化 R3F scene 遍历
性能	桌面 1080p 中等场景帧率	≥ 60fps	启动 Chrome DevTools Performance 测
性能	首屏 LCP（不含视频）	< 3s	Lighthouse
包体	8 件套 v1 总下载	≤ 30 MB	webpack-bundle-analyzer

@tbl-sn3d-acceptance 验收标准表

关键测试场景：

1. 加载 NVL72 风格默认配置 → 播放 L1 视频 → 用户点击进入 L2 爆炸 → 双击钻取到 die → 返回 → 修改 YAML 某层 chips.count → 重新组装无错。
2. 在禁用 GPU 加速的环境下打开 → 优雅降级到 placeholder + warning，不崩。
3. 加载现有 configs/topologies/P1-R1-B16-C32-ring.yaml（不带 visual_template 字段）→ 正常渲染默认模板，不报错。

---

附录

附录 A：业界调研

工具 / 系统	性质	真实感	自定义	数据流	浏览器内
NVIDIA Omniverse	工业级数字孪生	极高（path tracing）	高（USD）	强	需客户端
Vertiv Spectrum	DCIM 平台	中（box + 贴图）	中	强（环境监控）	是
Lusion / Active Theory 作品	创意工作室项目	极高	低（一事一做）	弱	是
Apple 产品页	产品宣传	极高（视频+实时混合）	无	无	是
ASTRA-sim 可视化插件	学术仿真器	低	中	强（trace）	是
本 spec 方案	仿真平台前端	中高	中（模板组合）	后续接	是

@tbl-sn3d-industry 业界同类方案对比

链接：

• NVIDIA Omniverse：https://www.nvidia.com/en-us/omniverse/
• Vertiv Spectrum：https://www.vertiv.com/
• Lusion：https://lusion.co/
• Apple iPhone 产品页（公开访问任意 iPhone 页面参考）

差异化结论：本 spec 在"模板化 + 浏览器内 + 后续可接仿真数据"三个维度交集的位置目前无对应工具——Omniverse 强但要客户端，Vertiv 浏览器但视觉粗糙，Apple 视觉极致但无数据，Lusion 视觉极致但无定制。

项目内引用：

• 前端仿真洞察工作台设计规格
• 拓扑生成器设计规格
• G5事件trace出口与事件时间线设计规格

附录 B：实现说明

Spec Accepted 后实现完成时回填。

附录 C：完整接口签名与数据结构

8 件套 PBR 与 LOD 参数表

模板	LOD0 三角面	LOD1 三角面	LOD2 三角面	主贴图 (4K)	metalness	roughness	特殊材质
rack-frame	≤ 80k	≤ 20k	≤ 5k	albedo + normal + roughness + AO	0.85（漆面）/ 0.95（铜母排）	0.45 / 0.20	边缘磨损 normal 贴图
compute-tray	≤ 100k	≤ 25k	≤ 6k	albedo + normal + metallic + roughness + AO	0.95（冷板）/ 0.10（PCB）	0.18（拉丝 anisotropy 0.7）/ 0.65	PCB 阻焊 + 金焊盘 + 丝印
nvswitch-tray	≤ 100k	≤ 25k	≤ 6k	albedo + normal + metallic + roughness	1.0（金把手）/ 0.95（冷板）/ 0.10（PCB）	0.05（镜面把手）/ 0.18 / 0.65	把手 anisotropy 0
power-shelf	≤ 60k	≤ 15k	≤ 4k	albedo + normal + roughness + AO	0.6（PSU 外壳）	0.55	风扇旋转 alpha
gpu-package	≤ 90k	≤ 22k	≤ 5k	albedo + normal + metallic + roughness + AO	0.95（IHS）/ 0.45（HBM）/ 0.10（基板）	0.12（IHS）/ 0.55（HBM）/ 0.50	IHS clear coat 0.2
cpu-package	≤ 70k	≤ 18k	≤ 4k	albedo + normal + metallic + roughness	0.85（IHS）/ 0.10（基板）	0.25 / 0.50	LPDDR 颗粒法线
copper-cartridge	≤ 60k	≤ 12k	≤ 3k	albedo + normal + roughness	0.92（铜缆）	0.32	高密度法线骗细节 + alpha 卡片
fiber-bundle	≤ 40k	≤ 10k	≤ 2k	albedo + roughness	0.0（光纤）/ 0.7（接头）	0.85 / 0.30	光纤透明度 0.6 + 接头金属

@tbl-sn3d-pbr-lod 8 件套 PBR 参数与 LOD 三角面预算

切换距离约定（统一）：LOD0 < 8m / LOD1 8–30m / LOD2 > 30m（相机距离单位 = Blender 米）。

接口签名

模板元数据（每个 glTF 资产配套 JSON）：

interface TemplateManifest {
  id: string;                       // "compute-tray-1u-4chip"
  version: string;                  // "v1.0.0"
  type: "rack-frame" | "compute-tray" | "nvswitch-tray"
      | "power-shelf" | "gpu-package" | "cpu-package"
      | "copper-cartridge" | "fiber-bundle";
  lods: { distance: number; gltf: string }[];  // 三档 LOD
  parameters: {                     // 模板可参数化字段
    [key: string]: { type: "int" | "enum" | "color"; range?: any; default: any };
  };
  bbox: { min: [number, number, number]; max: [number, number, number] };
  triangles: { lod0: number; lod1: number; lod2: number };
  metadata_anchors: {               // L4 接口预留:metadata 锚点位置
    linkId?: string[];              // 哪些子 mesh 挂 linkId
    chipId?: string[];              // 哪些子 mesh 挂 chipId
    uniforms?: string[];            // 哪些材质暴露 uUtilization 等 uniform
  };
}

配置 schema（拓扑 YAML 扩展）：

interface VisualConfig {
  theme?: "dark" | "light";         // v1 仅 dark
  show_labels?: boolean;
  explode_default?: boolean;
}

// 现有拓扑 YAML 结构 pods[].racks[].boards[].chips[]
// 每层旁挂可选 visual_template,不改原结构
interface PodNode {
  count: number;
  visual_template?: string;
  racks: RackNode[];
}
interface RackNode {
  count: number;
  visual_template?: string;
  boards: BoardNode[];
}
interface BoardNode {
  count: number;
  visual_template?: string;
  chips: ChipNode[];
}
interface ChipNode {
  name: string;
  preset_id?: string;
  count: number;
  visual_template?: string;
}

interface VisualCableEntry {
  link_type: "c2c" | "b2b" | "r2r" | "p2p";
  template: "copper_cartridge" | "fiber_bundle";
  count: number;
  color?: string;
}

组装引擎接口：

interface SceneComposer {
  loadTemplates(): Promise<TemplateRegistry>;
  composeScene(topology: TopologyData, visual: VisualConfig): R3FSceneGraph;
}

故事线控制器接口：

interface StoryDirector {
  playIntro(onComplete: () => void): void;           // L1
  explodeRack(rackId: string): Promise<void>;        // L2
  drillTo(targetId: string): Promise<void>;          // L3
  resetCamera(): void;
}

L4 预留消息信封（消费方在后续 spec 实现）：

interface VizLinkflowMessage {
  type: "viz.linkflow";
  payload: {
    linkId: string;
    utilization: number;   // 0-1
    bandwidth: number;     // 0-1, 相对峰值归一化
    congestion: number;    // 0-1
    timestamp: number;     // ms
  };
}