awoooi/docs/superpowers/plans/2026-04-08-sprint5-ia-restructure.md

Sprint 5 — 前端資訊架構重組 + 指令中心拓撲圖

建立: 2026-04-08 (台北) 狀態: 📋 待統帥最終審核 範圍: 導航精簡 (25→6+2) + 多頁籤整合 + React Flow 拓撲圖 原則: 零功能遺失 — 所有現有頁面功能必須保留，只改變呈現方式

---

第一章：現有資產完整清單 (不可遺失)

1.1 現有 26 個頁面路由

#	路由	頁面名稱	程式碼行數	功能摘要
1	/	AI 中心 (首頁)	1200+	Metrics Strip + Incident Feed + OpenClaw Panel + HostGrid
2	/alerts	告警	183	告警列表 + 嚴重度篩選
3	/authorizations	授權中心	25	批准/拒絕授權 (佔位頁)
4	/monitoring	服務監控	269	監控工具狀態 (Grafana/Prometheus/SigNoz)
5	/apm	APM	128	應用效能監控 (SignOz 連結)
6	/errors	錯誤追蹤	164	Sentry 錯誤列表 + AI 分析
7	/topology	拓撲圖	103	簡單 host list (待升級)
8	/security	安全	137	安全掃描狀態
9	/compliance	合規	124	合規報告 + 嚴重度分佈
10	/auto-repair	自動修復	460	Playbook 管理 + 評估 + 執行
11	/neural-command	神經指揮	209	SSH 指揮權鏈 (4 Tab 元件)
12	/drift	Drift 偵測	324	Config Drift 報告
13	/deployments	部署管理	113	部署歷史
14	/tickets	工單	120	工單管理
15	/cost	成本分析	95	AI 效能統計
16	/action-logs	行動日誌	551	操作記錄 + 時間軸
17	/reports	報表	317	處置統計儀表板 (Sprint 4)
18	/knowledge-base	知識庫	532	KB 搜尋 + 語義搜尋
19	/terminal	終端	36	Omni-Terminal
20	/apps	應用	103	主機服務狀態
21	/services	服務目錄	120	服務清單
22	/settings	設定	245	系統設定
23	/users	用戶	136	用戶管理
24	/notifications	通知	97	通知中心
25	/billing	計費	113	計費資訊
26	/help	幫助	57	幫助文檔
—	/demo	Demo	189	開發用 (環境變數保護)

1.2 現有 62 個前端元件

(完整清單見附錄 A)

核心元件群組:

• layout/: AppLayout, Header, Sidebar (4 檔, 719 行)
• incident/: IncidentCard, FlowPipeline, ThinkingTerminal (3 檔, 1172 行)
• approval/: ApprovalCard, LiveApprovalPanel, ConversationalView 等 (6 檔, 2402 行)
• ai/: OpenClawPanel, ThinkingStream, HITLSection 等 (6 檔, 1883 行)
• neural-command/: NeuralPreFlight, NeuralLiveCenter, NeuralStats, NeuralApprovalPanel (4 檔, 1032 行)
• dashboard/: LiveDashboard, HostCard, ConnectionStatus (4 檔, 1217 行)
• errors/: ErrorOverview, ErrorTrend, RecentIssues, UXAudit (4 檔, 1083 行)

---

第二章：重組對照表 — 每個頁面的去向

2.1 導航重組：25 項 → 6 主項 + 2 固定項

舊導航 (25項)                    新導航 (6+2項)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🏠 AI 核心 (3項)
├─ 儀表板 ─────────────────→  🏠 AI 指令中心
├─ 授權中心 ───────────────→     └─ [Tab] 告警 & 授權
└─ 告警 ───────────────────→     └─ [Tab] 告警 & 授權

📊 監控安全 (6項)
├─ 服務監控 ───────────────→  📊 可觀測性
├─ APM ────────────────────→     └─ [Tab] APM
├─ 錯誤追蹤 ───────────────→     └─ [Tab] 錯誤追蹤
├─ 拓撲圖 ─────────────────→  🏠 AI 指令中心 [Tab] 戰情總覽
├─ 安全 ───────────────────→  🛡️ 安全合規
└─ 合規 ───────────────────→     └─ [Tab] 合規

🔧 維護管理 (8項)
├─ 自動修復 ───────────────→  🔧 自動化
├─ 神經指揮 ───────────────→     └─ [Tab] 神經指揮
├─ Drift ──────────────────→     └─ [Tab] Drift
├─ 部署管理 ───────────────→  📦 營運
├─ 工單 ───────────────────→     └─ [Tab] 工單
├─ 成本分析 ───────────────→     └─ [Tab] 成本
├─ 行動日誌 ───────────────→     └─ [Tab] 日誌
└─ 報表 ───────────────────→  🏠 AI 指令中心 [Tab] 處置統計

📚 知識工具 (4項)
├─ 知識庫 ─────────────────→  📚 知識
├─ 終端 ───────────────────→  💻 終端 (底部固定)
├─ 應用 ───────────────────→  📊 可觀測性 [Tab] 應用
└─ 服務目錄 ───────────────→  📊 可觀測性 [Tab] 服務

⚙️ 底部 (5項)
├─ 用戶 ───────────────────→  ⚙️ 設定 (底部固定)
├─ 通知 ───────────────────→  🏠 AI 指令中心 (通知 bell icon)
├─ 計費 ───────────────────→  📦 營運 [Tab] 計費
├─ 幫助 ───────────────────→  ⚙️ 設定 [Tab] 幫助
└─ 設定 ───────────────────→  ⚙️ 設定 (底部固定)

2.2 新導航結構

━━━━━━━━━━━━━━━━━━
🏠 AI 指令中心        ← 首頁/戰情室
📊 可觀測性           ← 監控/APM/錯誤/應用/服務
🔧 自動化             ← 修復/SSH/Drift/Playbook
📦 營運               ← 部署/工單/成本/日誌/計費
🛡️ 安全合規           ← 安全/合規
📚 知識               ← 知識庫/服務目錄
━━━━━━━━━━━━━━━━━━
💻 終端               ← 固定底部
⚙️ 設定               ← 固定底部 (含用戶/幫助)
━━━━━━━━━━━━━━━━━━

---

第三章：每個新頁面的 Tab 結構與元件整合

3.1 🏠 AI 指令中心 (路由: /)

整合來源: 現有首頁 + /alerts + /authorizations + /topology + /reports

Tab	名稱	整合的現有元件/頁面	新增元件
T1	戰情總覽	HostGrid, MetricsStrip, IncidentCard, OpenClawPanel	ServiceTopology (React Flow)
T2	告警 & 授權	/alerts 完整頁面 + LiveApprovalPanel + ApprovalCard	合併為左右佈局
T3	活動串流	SSE /dashboard/stream + ActionTimeline	即時事件時間軸
T4	處置統計	/reports 完整儀表板 (Sprint 4)	直接嵌入

實作方式:

// apps/web/src/app/[locale]/page.tsx
// 改為 Tab 容器，每個 Tab 載入對應內容

const TABS = [
  { id: 'overview',    label: t('tabs.overview'),    icon: LayoutDashboard },
  { id: 'alerts',      label: t('tabs.alerts'),      icon: Bell, badge: alertsCount },
  { id: 'stream',      label: t('tabs.stream'),      icon: Activity },
  { id: 'disposition', label: t('tabs.disposition'),  icon: BarChart3 },
]

// Tab 1: 戰情總覽
//   - 保留: MetricsStrip (7指標)
//   - 保留: IncidentCard + FlowPipeline
//   - 保留: OpenClawPanel
//   - 新增: ServiceTopology (React Flow, 收合模式)
//   - 保留: HostGrid (嵌入拓撲圖下方)

// Tab 2: 告警 & 授權
//   - 移入: /alerts/page.tsx 的完整內容 (183行)
//   - 移入: LiveApprovalPanel (484行)
//   - 左右佈局: 告警列表(左) + 授權面板(右)

// Tab 3: 活動串流
//   - 移入: ActionTimeline (245行)
//   - SSE 即時事件
//   - AI 推理鏈視覺化

// Tab 4: 處置統計
//   - 移入: /reports/page.tsx 完整內容 (317行)
//   - Sprint 4 四色統計 + 堆疊條 + 明細表

影響的現有檔案:

檔案	動作	說明
app/[locale]/page.tsx	重寫	改為 Tab 容器
app/[locale]/alerts/page.tsx	保留路由但內容抽取	抽取為 AlertsPanel 元件
app/[locale]/authorizations/page.tsx	保留路由但內容抽取	合併入 Tab 2
app/[locale]/topology/page.tsx	保留路由但升級	完整版拓撲 (全展開)
app/[locale]/reports/page.tsx	保留路由但內容抽取	抽取為 DispositionPanel 元件

重要: 所有原有路由保留，確保舊連結/書籤不失效。只是內容同時在 AI 中心也能看到。

---

3.2 📊 可觀測性 (路由: /observability 新建)

整合來源: /monitoring + /apm + /errors + /apps + /services

Tab	名稱	整合的現有頁面	行數
T1	服務監控	/monitoring/page.tsx	269
T2	APM	/apm/page.tsx	128
T3	錯誤追蹤	/errors/page.tsx	164
T4	應用	/apps/page.tsx	103
T5	服務目錄	/services/page.tsx	120

實作方式: 新建 /observability/page.tsx，5 Tab 容器 保留舊路由: /monitoring → redirect to /observability?tab=monitoring

---

3.3 🔧 自動化 (路由: /automation 新建)

整合來源: /auto-repair + /neural-command + /drift

Tab	名稱	整合的現有頁面	行數
T1	自動修復	/auto-repair/page.tsx	460
T2	神經指揮	/neural-command/page.tsx	209 + 4元件(1032)
T3	Drift 偵測	/drift/page.tsx	324

保留舊路由: /auto-repair → redirect to /automation?tab=repair

---

3.4 📦 營運 (路由: /operations 新建)

整合來源: /deployments + /tickets + /cost + /action-logs + /billing

Tab	名稱	整合的現有頁面	行數
T1	部署管理	/deployments/page.tsx	113
T2	工單	/tickets/page.tsx	120
T3	成本分析	/cost/page.tsx	95
T4	行動日誌	/action-logs/page.tsx	551
T5	計費	/billing/page.tsx	113

---

3.5 🛡️ 安全合規 (路由: /security-compliance 新建)

整合來源: /security + /compliance

Tab	名稱	整合的現有頁面	行數
T1	安全掃描	/security/page.tsx	137
T2	合規報告	/compliance/page.tsx	124

---

3.6 📚 知識 (路由: /knowledge 新建)

整合來源: /knowledge-base

Tab	名稱	整合的現有頁面	行數
T1	知識庫	/knowledge-base/page.tsx	532

(單一內容暫不需 Tab，但預留未來擴充)

---

3.7 底部固定項

項目	路由	說明
💻 終端	/terminal	保持獨立，因為需要全螢幕
⚙️ 設定	/settings	整合 /users + /help + /notifications

---

第四章：舊路由向後兼容 (Backward Compatibility)

原則: 所有現有 URL 必須繼續有效 (書籤/Telegram 連結不失效)

舊路由	處理方式	目的地
/alerts	redirect	/?tab=alerts
/authorizations	redirect	/?tab=alerts
/topology	保留	完整版拓撲 (React Flow 全展開)
/reports	redirect	/?tab=disposition
/monitoring	redirect	/observability?tab=monitoring
/apm	redirect	/observability?tab=apm
/errors	redirect	/observability?tab=errors
/apps	redirect	/observability?tab=apps
/services	redirect	/observability?tab=services
/auto-repair	redirect	/automation?tab=repair
/neural-command	redirect	/automation?tab=neural
/drift	redirect	/automation?tab=drift
/deployments	redirect	/operations?tab=deployments
/tickets	redirect	/operations?tab=tickets
/cost	redirect	/operations?tab=cost
/action-logs	redirect	/operations?tab=logs
/billing	redirect	/operations?tab=billing
/security	redirect	/security-compliance?tab=security
/compliance	redirect	/security-compliance?tab=compliance
/knowledge-base	redirect	/knowledge
/users	redirect	/settings?tab=users
/help	redirect	/settings?tab=help
/notifications	redirect	/settings?tab=notifications

實作: Next.js redirects in next.config.js 或各頁面加 redirect()

---

第五章：共用 Tab 容器元件

所有新頁面共用同一個 Tab 元件，確保一致性：

// apps/web/src/components/layout/page-tabs.tsx (新建)

interface TabConfig {
  id: string
  labelKey: string       // i18n key
  icon: React.ElementType // Lucide icon
  badge?: number          // 數字徽章 (如告警數)
  component: React.LazyComponent // lazy load 內容
}

interface PageTabsProps {
  tabs: TabConfig[]
  defaultTab?: string
  // URL query 同步: ?tab=alerts
  syncWithUrl?: boolean
}

// 設計規範:
// - Tab Bar 高度: 40px
// - Tab 間距: 0px (緊貼)
// - Active Tab: 底部 2px accent (#d97757) + 文字加粗
// - Inactive: text-text2 (#87867f)
// - Icon: 16px Lucide, 與文字間距 4px
// - Badge: 紅色圓形 (#cc2200), 8px 字體
// - Tab Bar 邊框: 0.5px solid #e0ddd4

---

第六章：新導航 Sidebar 結構

// apps/web/src/components/layout/sidebar.tsx (修改)

const NAV_SECTIONS: NavSection[] = [
  {
    sectionKey: 'main',
    sectionLabel: '',
    items: [
      { id: 'command-center',     href: '/',                    labelKey: 'commandCenter',      Icon: LayoutDashboard },
      { id: 'observability',      href: '/observability',       labelKey: 'observability',      Icon: Monitor },
      { id: 'automation',         href: '/automation',          labelKey: 'automation',         Icon: Wrench },
      { id: 'operations',         href: '/operations',          labelKey: 'operations',         Icon: Package },
      { id: 'security-compliance',href: '/security-compliance', labelKey: 'securityCompliance', Icon: Shield },
      { id: 'knowledge',          href: '/knowledge',           labelKey: 'knowledge',          Icon: BookOpen },
    ],
  },
]

const BOTTOM_NAV: NavItemConfig[] = [
  { id: 'terminal', href: '/terminal', labelKey: 'terminal', Icon: Terminal },
  { id: 'settings', href: '/settings', labelKey: 'settings', Icon: Settings },
]

// 從 25 項 → 8 項 (6 主項 + 2 底部)

---

第七章：互動模式完整規範

7.1 Tab 頁籤

場景	行為
點擊 Tab	切換內容，URL query 同步 (?tab=alerts)
瀏覽器後退	回到上一個 Tab
Tab 有 badge	顯示數字 (如告警數 2)
Tab 內容載入中	骨架屏 (Skeleton)
Tab 內容無資料	空狀態 (Inbox icon + 文字)

7.2 Drawer 側邊抽屜

場景	行為
點擊拓撲節點	右側滑出服務詳情 Drawer (300px)
點擊告警列表項	右側滑出告警詳情
Drawer 外點擊	關閉 Drawer
ESC 鍵	關閉 Drawer

7.3 Modal 彈出視窗

場景	行為
批准修復操作	彈出確認 Modal (風險等級 + URI + 按鈕)
拒絕操作	彈出理由輸入 Modal
危險操作 (scale down)	彈出雙重確認 Modal

7.4 Toggle 開關

場景	行為
「顯示拓撲圖」	切換 拓撲圖 / HostGrid 視圖
「只看異常」	篩選只顯示 warning/critical
「顯示數據流」	開啟/關閉 SSE 即時串流
「自動刷新」	開啟/關閉 30 秒輪詢

---

第八章：細化實施步驟

Phase 0: 基礎建設 (Day 1)

Step	動作	影響檔案	驗證
0.1	安裝 @xyflow/react + elkjs	package.json	import 成功
0.2	建立 PageTabs 共用元件	components/layout/page-tabs.tsx (新建)	渲染 3 個 Tab
0.3	建立 ServiceDrawer 共用元件	components/layout/service-drawer.tsx (新建)	滑出/關閉

Phase 1: AI 指令中心重構 (Day 2-3)

Step	動作	影響檔案	驗證
1.1	首頁 page.tsx 改為 4-Tab 結構	app/[locale]/page.tsx (重寫)	4 Tab 切換
1.2	Tab 1: 保留現有 MetricsStrip + IncidentCard + OpenClaw	複用現有元件	不丟功能
1.3	Tab 1: 嵌入 ServiceTopology (React Flow 收合)	topology/ 元件 (新建)	拓撲圖渲染
1.4	Tab 2: 從 /alerts 和 /authorizations 抽取內容	alerts/page.tsx → AlertsPanel 元件	告警列表+授權
1.5	Tab 3: 建立活動串流 Tab	複用 SSE + ActionTimeline	即時事件
1.6	Tab 4: 從 /reports 抽取處置統計	reports/page.tsx → DispositionPanel	四色統計

Phase 2: React Flow 拓撲圖 (Day 3-4)

Step	動作	影響檔案	驗證
2.1	ServiceNode.tsx (memo + Tailwind + Lucide)	topology/nodes/ (新建)	節點渲染
2.2	GroupNode.tsx (展開/收合)	topology/nodes/ (新建)	群組切換
2.3	TopologyEdge.tsx (漸層 + CSS 動畫)	topology/edges/ (新建)	邊線動畫
2.4	useElkLayout.ts (elkjs 嵌套佈局)	topology/hooks/ (新建)	自動佈局
2.5	useTopologyData.ts (store → nodes)	topology/hooks/ (新建)	資料轉換
2.6	ServiceTopology.tsx (主元件)	topology/ (新建)	完整拓撲

Phase 3: 其他整合頁面 (Day 4-5)

Step	動作	影響檔案	驗證
3.1	新建 /observability 頁 (5 Tab)	app/[locale]/observability/page.tsx (新建)	5 Tab
3.2	新建 /automation 頁 (3 Tab)	app/[locale]/automation/page.tsx (新建)	3 Tab
3.3	新建 /operations 頁 (5 Tab)	app/[locale]/operations/page.tsx (新建)	5 Tab
3.4	新建 /security-compliance 頁 (2 Tab)	app/[locale]/security-compliance/page.tsx (新建)	2 Tab
3.5	/knowledge 指向 knowledge-base	app/[locale]/knowledge/page.tsx (新建)	內容一致

Phase 4: 導航重構 + 舊路由 Redirect (Day 5-6)

Step	動作	影響檔案	驗證
4.1	sidebar.tsx 改為 6+2 結構	components/layout/sidebar.tsx (修改)	導航正確
4.2	建立 20+ 個 redirect	next.config.js 或各舊頁面	舊 URL 跳轉正確
4.3	i18n 新增所有 Tab/Section key	messages/zh-TW.json, en.json	零硬編碼

Phase 5: 後端擴充 (Day 6)

Step	動作	影響檔案	驗證
5.1	dashboard.py 加 K8s Pod + AI 狀態	api/v1/dashboard.py (修改 +30行)	curl 新欄位
5.2	靜態依賴關係定義	topology/dependency-map.ts (新建)	邊線正確

Phase 6: 視覺調校 + 驗收 (Day 7-8)

Step	動作	驗證
6.1	TypeScript 編譯	tsc --noEmit 零錯誤
6.2	生產建置	pnpm build 成功
6.3	所有舊 URL redirect 測試	20+ URL 全部跳轉正確
6.4	所有 Tab 切換測試	每個 Tab 內容正確載入
6.5	拓撲圖互動測試	展開/收合/hover/click
6.6	統帥視覺驗收	確認設計

---

第九章：檔案影響完整清單

新增檔案 (15 個)

#	檔案	行數	功能
1	components/layout/page-tabs.tsx	80	共用 Tab 容器
2	components/layout/service-drawer.tsx	60	共用側邊抽屜
3	components/topology/index.ts	10	匯出
4	components/topology/ServiceTopology.tsx	150	React Flow 主元件
5	components/topology/nodes/GroupNode.tsx	120	群組節點
6	components/topology/nodes/ServiceNode.tsx	80	服務節點
7	components/topology/edges/TopologyEdge.tsx	60	邊線
8	components/topology/hooks/useTopologyData.ts	100	資料轉換
9	components/topology/hooks/useElkLayout.ts	80	佈局引擎
10	components/topology/topology.css	30	動畫
11	app/[locale]/observability/page.tsx	100	可觀測性頁
12	app/[locale]/automation/page.tsx	80	自動化頁
13	app/[locale]/operations/page.tsx	100	營運頁
14	app/[locale]/security-compliance/page.tsx	60	安全合規頁
15	app/[locale]/knowledge/page.tsx	40	知識頁

新增總計: ~1,150 行

修改檔案 (5 個)

#	檔案	改動
1	app/[locale]/page.tsx	重寫為 4-Tab 結構
2	components/layout/sidebar.tsx	25→8 導航項
3	apps/web/tailwind.config.ts	+3 動畫
4	apps/api/src/api/v1/dashboard.py	+30 行 K8s/AI 狀態
5	messages/zh-TW.json + en.json	+40 i18n key

不刪除的檔案 (保留舊路由做 redirect)

所有 26 個現有頁面路由檔案 全部保留，內容改為 redirect 或共用元件。

---

第十章：技術文檔清單

為避免溝通落差，以下文檔需要產出：

#	文檔名稱	用途	格式
1	頁面路由對照表	每個舊 URL 對應到哪個新位置	本文件第四章
2	Tab 結構規格書	每個新頁面的 Tab 配置	本文件第三章
3	元件抽取計畫	哪些頁面需要抽取為獨立元件	見下方
4	React Flow PoC	嵌套群組互動 demo	HTML 部署到內網
5	設計稿 (3+ 版本)	AI 指令中心多頁籤視覺設計	HTML 部署到內網
6	Sidebar 設計稿	新 6+2 導航視覺設計	HTML 部署到內網
7	i18n Key 清單	所有新增的翻譯 key	JSON
8	API 變更規格	dashboard.py 新增欄位定義	Pydantic model

元件抽取計畫 (文檔 #3)

現有頁面	抽取為元件	用途
/alerts/page.tsx	AlertsPanel.tsx	AI 中心 Tab 2 + 獨立路由
/reports/page.tsx	DispositionPanel.tsx	AI 中心 Tab 4 + 獨立路由
/monitoring/page.tsx	MonitoringPanel.tsx	可觀測性 Tab 1
/apm/page.tsx	APMPanel.tsx	可觀測性 Tab 2
/errors/page.tsx	ErrorsPanel.tsx	可觀測性 Tab 3
/auto-repair/page.tsx	AutoRepairPanel.tsx	自動化 Tab 1
/neural-command/page.tsx	NeuralCommandPanel.tsx	自動化 Tab 2
/drift/page.tsx	DriftPanel.tsx	自動化 Tab 3

---

第十一章：風險與緩解

風險	等級	緩解
舊 URL 失效	高	全部保留做 redirect
Tab 切換效能	中	React.lazy + Suspense 按需載入
元件抽取改壞現有功能	中	抽取時只移動，不修改邏輯
Sidebar 變更影響所有頁面	中	先測試再部署
i18n key 遺漏	低	build 時 next-intl 會報錯
工期超出預估	中	Phase 1-2 優先，Phase 3-4 可分批

---

第十二章：時程預估

Phase	天數	內容	優先級
0	1	安裝 + 共用元件	P0
1	2	AI 指令中心 4-Tab	P0
2	2	React Flow 拓撲圖	P0
3	2	其他整合頁面	P1
4	1	導航重構 + redirect	P1
5	1	後端擴充	P1
6	1	視覺調校 + 驗收	P0
總計	~10 天

可分批交付:

• 第一批 (Day 1-5): Phase 0-2 → AI 指令中心 + 拓撲圖可用
• 第二批 (Day 6-8): Phase 3-4 → 其他頁面整合 + 導航精簡
• 第三批 (Day 9-10): Phase 5-6 → 後端 + 驗收