awoooi/docs/adr/ADR-060-react-flow-elkjs-topology-engine.md

ADR-060: React Flow + elkjs 拓撲圖引擎技術選型

項目	內容
狀態	✅ 已批准
日期	2026-04-08
決策者	統帥 + 首席架構師
觸發	Sprint 5 指令中心重設計 — 需呈現 67→150+ 個監控實體的服務拓撲

背景

AWOOOI 監控系統已涵蓋 67 個實體 (K8s Pods 15 + Docker 17 + 主機 5 + API 8 + AI 4 + 外部 6 + 其他)，未來預計擴展至 120-150+ 個。需要在前端呈現「神經拓撲圖」— 即時服務依賴 + AI 介入狀態 + 嵌套群組展開/收合。

候選方案評估

方案	組合	優點	缺點	評分
A	React Flow + AntV X6	各取所長	維護兩套、設計語言分裂	60
B	React Flow + dagre	輕量統一	dagre 不支援嵌套群組	70
C	AntV X6 統一	內建佈局強	React 整合非原生、Tailwind 穿透困難	55
D+	React Flow + elkjs	原生 React + 嵌套群組 + 正交路由	elkjs API 較複雜	90

決策

選擇方案 D+: React Flow (@xyflow/react) + elkjs

核心理由

1. DOM 渲染 — 節點是 HTML 元素，Tailwind/Lucide/自定義字型 100% 原生支援
2. elkjs 嵌套群組 — 支援 Compound Graph，可實現 Macro→Drill-down 層級視圖
3. 單一技術棧 — 一套 API、一份節點元件、一個設計語言
4. 未來 150+ 節點 — elkjs 正交邊線路由 + 子群組摺疊，避免認知超載
5. 社群 — React Flow 155K/週下載、35K stars，問題好查

否決方案 A 的理由

• 同一專案維護兩套圖形引擎違反 SSOT (Single Source of Truth)
• 設計系統更新需同步兩處，增加漂移風險
• Bundle Size +330KB vs +270KB，無顯著優勢

安裝

npm install @xyflow/react elkjs

架構

apps/web/src/components/topology/
├── ServiceTopology.tsx     # React Flow 主元件
├── GroupNode.tsx            # 可展開/收合的群組節點
├── ServiceNode.tsx          # 服務節點 (memo + areEqual)
├── TopologyEdge.tsx         # 漸層邊線 + CSS 動畫
├── useTopologyData.ts       # API → nodes/edges
├── useElkLayout.ts          # elkjs 嵌套佈局
└── topology.css             # 邊線動畫

各頁面使用

頁面	模式	節點數
/ 首頁	收合群組 (~4-6 節點)	低
/topology	完整展開 (100+) + 篩選	高
/neural-command	SSH 指揮鏈 (8-12)	低

效能策略

• React.memo + 自定義 areEqual (只比 status/cpu/memory)
• 收合群組：預設 Macro View (~6 節點)
• 動態篩選：只顯示 Warning/Critical 節點
• elkjs Web Worker (避免阻塞主線程)

風險

風險	緩解
elkjs API 複雜	封裝在 useElkLayout.ts，業務層不接觸
elkjs 異步佈局	顯示 loading 骨架屏
節點數 500+	評估虛擬化 (viewport culling)