171 lines
10 KiB
Markdown
171 lines
10 KiB
Markdown
# Sigma 覆盖层重构 + 性能改造 设计文档
|
||
|
||
- 日期：2026-06-25
|
||
- 分支：`feat/sigma-overlay-refactor-perf`
|
||
- 关联 issue：#64 拆分 `sigma-global-renderer.ts`、#63 第 2 条（DOM 重绘重建节点）
|
||
- 范围：本 spec 覆盖 Phase 1（#64）+ Phase 2（#63.2）两阶段。#63 第 1 条（云层签名全量遍历）与 #65（无障碍）**不在本 spec 范围内**，后续单独处理。
|
||
|
||
---
|
||
|
||
## 1. 背景与动机
|
||
|
||
全局视角的知识图谱用 Sigma 在 canvas 上画点和边，再在上面盖一层 DOM/SVG 覆盖物（社区云团、节点命中框、社区标签）。这层覆盖物的全部逻辑集中在
|
||
`packages/graph-engine/src/render/sigma-global-renderer.ts`，当前 **1386 行**，存在两个已确认的问题：
|
||
|
||
1. **单文件过大（#64）**：云层几何、SVG 渲染、凸包计算、坐标变换都堆在一个文件里。仓库已把 wash 逻辑拆到
|
||
`community-wash.ts` / `community-washes.ts`，本文件应顺势拆分。
|
||
2. **每帧重建 DOM（#63 第 2 条）**：`renderSigmaOverlays()` 绑在 Sigma 的 `afterRender` 事件上
|
||
（`sigma-global-renderer.ts:426`），**平移/缩放的每一帧**都先 `overlayRoot.replaceChildren()` 清空
|
||
（`:623`），再全量重建所有节点命中框、云层 SVG，并重新绑定 click / pointerdown / mousedown / dragstart
|
||
监听（`:621-715`）。但相机移动时节点集合并未改变，只有屏幕坐标变了——这是典型的 DOM 抖动热路径。
|
||
|
||
> 注：PR #60 的 1000 节点回归已通过，当前规模不卡。本改造目标是降低维护成本、消除架构坏味道，为更大规模做准备。
|
||
|
||
### 设计原则
|
||
|
||
- 两个 Phase 相互独立、可分别合并。**Phase 1 是纯搬迁（零行为变化），Phase 2 才动行为。**
|
||
- 先拆后优化：在 1000+ 行单文件里直接改性能热路径风险叠加；拆完后 Phase 2 改动面更小、更好测。
|
||
- 依赖单向：`sigma-coordinates` ← `community-cloud-geometry` ← `sigma-overlay-svg` ← 主文件（编排）。
|
||
- 不改对外接口（`SigmaGlobalRenderer`），workbench 侧零感知。
|
||
- 遵循 YAGNI：不做通用 diff 框架、不顺手重构无关代码。
|
||
|
||
---
|
||
|
||
## 2. Phase 1（#64）：按职责拆 3 个 helper
|
||
|
||
从 `sigma-global-renderer.ts` 抽出三组纯函数 / 无状态工厂。主文件只保留编排核心：
|
||
`createSigmaGlobalRenderer`、生命周期、拖拽会话、事件接线、Graphology 属性映射、hit projector、edge style。
|
||
|
||
| 新文件 | 搬入内容 | 性质 |
|
||
|---|---|---|
|
||
| `render/sigma-coordinates.ts` | `sigmaWorldPointToScreenPoint`、`sigmaScreenPointToWorldPoint`、`overlayPointerScreenPoint` | 坐标变换 |
|
||
| `render/community-cloud-geometry.ts` | `SigmaCommunityCloud` / `SigmaCommunityCloudBasis` 接口、`sigmaCommunityCloudBasisById` + `...WithReuse` + `...WithNodePoint`、`sigmaCommunityCloudSignature`、`sigmaProjectedCloudHullPoints`、`clampPointToWorldEllipse`、`clampPointToScreenEllipse`、`sigmaCommunityCloud`、`convexHull2d` | 几何 / 凸包，多为纯函数 |
|
||
| `render/sigma-overlay-svg.ts` | `SIGMA_OVERLAY_SVG_NS`、`nextSigmaCloudFilterSequence`、`sigmaSharedCloudFilterDef`、`sigmaCloudSvg`，及 overlay 元素工厂 `sigmaOverlayButton` / `sigmaOverlayPassiveElement` / `applyOverlayBox` / `createSigmaOverlayRoot` | DOM / SVG 构造 |
|
||
|
||
依赖说明：`community-cloud-geometry` 中的投影函数（`sigmaProjectedCloudHullPoints`、`sigmaCommunityCloud`）
|
||
依赖坐标变换，故 import `sigma-coordinates`，单向依赖。
|
||
|
||
预计主文件从 1386 行降到约 1000 行。
|
||
|
||
### Phase 1 验收
|
||
|
||
- 行为零变化。
|
||
- 现有 8 个 graph-engine 测试全绿（`npm test`），`npm run typecheck` 通过。
|
||
- 几何纯函数补独立单测（凸包、签名、clamp、坐标往返）——这些此前埋在主文件内未单独测。
|
||
|
||
> 这些函数当前均为**模块私有、未对外导出**，搬到新 helper 后由新 helper 各自 `export`（供单测直接
|
||
> import），主文件再 import 回来使用。**公开 API（`SigmaGlobalRenderer` 等）与 `src/index.ts`
|
||
> barrel 不变**，workbench 侧零感知。模块级计数器 `sigmaCloudFilterSequence` 随 SVG 函数整组搬走，
|
||
> 仍是同一个计数器，行为不变。
|
||
|
||
---
|
||
|
||
## 3. Phase 2（#63.2）：拆"结构更新"与"位置更新"
|
||
|
||
把唯一的 `renderSigmaOverlays()`（每帧 `replaceChildren` 全量重建）拆成两条路径。
|
||
|
||
### `rebuildSigmaOverlays()` — 仅数据 / 选中变化时调用
|
||
|
||
- 按 id 做 diff：复用已存在元素，新增缺失的、移除多余的；维护三张
|
||
`Map<id, element>`（节点命中框、社区云层 region、社区标签各一张）。
|
||
- 监听器（click / pointerdown / mousedown / dragstart）**只在元素创建时绑一次**。
|
||
- 处理由数据决定的状态：selected / dim / searchHit / pinned、label 文本等。
|
||
|
||
> 覆盖层只渲染**这 3 类** DOM 元素。aggregation 容器画在 Sigma canvas 上（走 Graphology
|
||
> 属性），不属于本覆盖层，本改造不涉及。
|
||
|
||
### `repositionSigmaOverlays()` — 绑 `afterRender` / resize / 拖拽移动，每帧调用
|
||
|
||
- 遍历已存在元素，只更新屏幕坐标（`applyOverlayBox`）与云层 SVG 的 `points` 属性。
|
||
- **绝不** `replaceChildren` / `createElement` / `addEventListener`。
|
||
|
||
### 调用点改造
|
||
|
||
| 位置 | 现状 | 改为 |
|
||
|---|---|---|
|
||
| 初始渲染（`:336`） | `renderSigmaOverlays()` | `rebuildSigmaOverlays()` |
|
||
| 数据更新（`:382`） | `renderSigmaOverlays()` | `rebuildSigmaOverlays()` |
|
||
| `afterRender` 相机移动 | `renderSigmaOverlays()` | `repositionSigmaOverlays()` |
|
||
| resize raf | `renderSigmaOverlays()` | `repositionSigmaOverlays()` |
|
||
| 拖拽提交/取消（`applyNodeDragPoint` 终态） | `renderSigmaOverlays()` | `rebuildSigmaOverlays()` |
|
||
|
||
选中变化走数据更新路径（触发 rebuild），因此 dim / selected 不进每帧热路径。
|
||
|
||
> 实现修正（TDD 发现）：原以为"拖拽 → reposition"。实际上拖拽**过程中**的每帧位置更新由
|
||
> `sigma.refresh()` → `afterRender` → reposition 负责；而 `applyNodeDragPoint` 里那处直接调用是
|
||
> 拖拽**提交/取消的终态**，此时 pin 状态与永久坐标已变（数据变化），必须 rebuild 才能刷新
|
||
> `dataset.pinned` 等属性。
|
||
|
||
### 状态归属与不变量（防止双路径打架）
|
||
|
||
覆盖层完全自封闭：生产代码里只有本文件操作 `overlayRoot` 与几何/SVG 函数，无第二处
|
||
监听 `afterRender`。因此冲突风险只在文件内部的 rebuild / reposition 之间，必须守住以下不变量：
|
||
|
||
- **rebuild 是元素生命周期的唯一权威**：只有它能增删元素、维护三张 `Map<id, element>`、绑监听。
|
||
- **reposition 对结构只读、且幂等**：只改已存在元素的位置/box 与云 hull 投影；遇到表里有、
|
||
但当前 `adapterData` 已无的 id，安全跳过（不报错、不创建）。
|
||
- **reposition 每帧从 `cloudBasisByCommunityId` 重新投影云 hull**：拖拽中 basis 冻结、松手才重算，
|
||
reposition 必须每次重投影才能让云层跟手（与现有行为一致）。
|
||
- **`update()` 的执行顺序安全前提**：现状 `sigma.refresh()`（`:381`）→ 真实 Sigma 触发 `afterRender`
|
||
→ reposition，**早于** 紧随其后的 rebuild（`:382`）。因 reposition 满足"只读+容忍不同步+幂等"，
|
||
这次提前的 reposition 至多对旧元素做一次无害定位，rebuild 随后纠正为准。
|
||
- **`afterRender` 与 `cameraUpdated` 都绑同一处理器**（`:425-426`），reposition 一帧可能跑 2 次；
|
||
因幂等无害，暂不做 rAF 去重（YAGNI，后续按需）。
|
||
|
||
### 关键风险点
|
||
|
||
云层每帧的 hull 投影点会变，所以 reposition 必须更新 polygon 的 `points` 属性和容器 box，
|
||
同时保留同一个 shape 元素及其 click 监听。这是整个改造里最需要小心的一处，测试需专门覆盖。
|
||
|
||
---
|
||
|
||
## 4. 错误处理与边界
|
||
|
||
- 两条路径都保留 `destroyed` 守卫。
|
||
- 销毁时清空三张 `Map<id, element>`，避免悬挂引用。
|
||
- diff 按 id 增删；id 不变但内容变（如 label 文本）在 rebuild 内更新属性。
|
||
- 不改对外接口 `SigmaGlobalRenderer`。
|
||
|
||
---
|
||
|
||
## 5. 测试方案
|
||
|
||
### Phase 1
|
||
|
||
- 现有回归全绿 + 几何纯函数新单测（凸包、签名、clamp、坐标往返）。
|
||
|
||
### Phase 2（验收标准：可量化性能基线）
|
||
|
||
在 `test/sigma-global-renderer.test.ts` 复用现有 `fakeContainer()` / `fakeRuntime()` / `sigma.emit()`
|
||
基础设施（fake 元素内部已用 Map 记录子节点与监听，无需引入 jsdom）：
|
||
|
||
1. **量化基线断言**（核心）：渲染后记录元素引用与 createElement / addEventListener 调用计数 →
|
||
多次 `sigma.emit("afterRender")` → 断言**元素实例不变、createElement 计数不增、监听计数不增、
|
||
`replaceChildren` 在 reposition 路径未被调用**。
|
||
2. **行为保持**：点击云层 → 社区选中、点击节点 → 节点选中、拖拽仍生效（沿用现有 emit 用例）。
|
||
3. **结构 diff**：数据更新增 / 删节点后，元素表正确增删。
|
||
4. **需更新的现有断言**：现有 resize 测试（`test/sigma-global-renderer.test.ts:574`）当前断言
|
||
resize 后覆盖层元素被**新建**（`assert.notEqual`）。Phase 2 后元素改为**复用**，这条须改成
|
||
`assert.equal`。这是**预期内的行为变更，不是回归**——它恰好验证了"reposition 不再重建元素"。
|
||
5. **第三层手动回归**：在 codex 跑 1000 节点平移 / 缩放，主观确认不卡 + 基线测试通过
|
||
（按 CLAUDE.md 推送前测试规则）。
|
||
|
||
---
|
||
|
||
## 6. 分 Phase 推进计划
|
||
|
||
- **Phase 0（本次 spark）**：写本 spec，分支 `feat/sigma-overlay-refactor-perf`。
|
||
- **Phase 1**：拆 3 个 helper → 跑回归 → 分步 commit → 可单独开 PR 合入（纯重构、低风险）。
|
||
- **Phase 2**：基于 Phase 1 改双路径 + 量化基线测试 → codex 回归 → commit → PR。
|
||
- **文档**：每个含功能改动的 Phase，按 CLAUDE.md 更新 CHANGELOG / README / 版本号。
|
||
|
||
---
|
||
|
||
## 7. 验收清单（汇总）
|
||
|
||
- [ ] Phase 1：主文件显著瘦身、行为零变化、现有测试与 typecheck 全绿、几何函数有独立单测。
|
||
- [ ] Phase 2：`afterRender` 路径不再销毁 / 重建 DOM、不重绑监听（量化测试断言通过）。
|
||
- [ ] Phase 2：点选社区 / 点选节点 / 拖拽行为与改造前一致。
|
||
- [ ] Phase 2：1000 节点 codex 手动回归平移缩放不卡。
|
||
- [ ] 对外接口 `SigmaGlobalRenderer` 无变化，workbench 无需改动。
|