# 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) |