From 876aa9a441e67c9bbf3dd8300afd0c3484feab27 Mon Sep 17 00:00:00 2001
From: OG T <ogt@WOOOMacMiniM4.local>
Date: Wed, 8 Apr 2026 11:56:58 +0800
Subject: [PATCH] =?UTF-8?q?docs(adr):=20ADR-060=20React=20Flow=20+=20elkjs?=
 =?UTF-8?q?=20=E6=8B=93=E6=92=B2=E5=9C=96=E5=BC=95=E6=93=8E=E6=8A=80?=
 =?UTF-8?q?=E8=A1=93=E9=81=B8=E5=9E=8B=20(=E6=96=B9=E6=A1=88=20D+=20?=
 =?UTF-8?q?=E6=89=B9=E5=87=86)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...DR-060-react-flow-elkjs-topology-engine.md | 81 +++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 docs/adr/ADR-060-react-flow-elkjs-topology-engine.md

diff --git a/docs/adr/ADR-060-react-flow-elkjs-topology-engine.md b/docs/adr/ADR-060-react-flow-elkjs-topology-engine.md
new file mode 100644
index 00000000..924954a0
--- /dev/null
+++ b/docs/adr/ADR-060-react-flow-elkjs-topology-engine.md
@@ -0,0 +1,81 @@
+# 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，無顯著優勢
+
+## 安裝
+
+```bash
+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) |