跳至主要内容

ADR-005: Application Launcher 導航架構

狀態​

已接受 (2025-12-19)

背景 (Context)​

問題陳述​

原有的靜態側邊欄（Sidebar）導航模式在應用程式模組（Applet）數量增加時面臨多項挑戰：

  1. 擴展性不足 - 側邊欄垂直空間有限，無法容納大量 Applet
  2. 角色權限管理複雜 - 各 Applet 需獨立處理權限過濾邏輯
  3. 分類不清 - 隨著 Applet 增加，用戶難以快速找到目標應用
  4. 搜尋功能缺失 - 無法透過關鍵字快速定位 Applet

限制條件​

  • 需保持響應式設計（桌面與移動端）
  • 需支援多語言
  • 需與現有 RBAC 權限系統整合
  • 需最小化對現有路由架構的影響

關鍵利害關係人​

  • 前端團隊
  • UX 設計團隊
  • 產品團隊

決策 (Decision)​

選擇的方案​

採用 Application Launcher 取代靜態側邊欄，設計參考 macOS Launchpad。

實施細節​

1. 集中式應用註冊表​

建立 src/config/applet-registry.ts 作為所有 Applet 的單一配置來源：

export interface AppletMetadata {
  id: string;
  name: string;              // 顯示名稱
  description?: string;      // 描述
  icon: LucideIcon;          // 圖示組件
  iconColor: string;         // 圖示背景色（DaisyUI 語義化顏色）
  category: AppletCategory;  // 分類
  path: string;              // 路由路徑
  requiredRole?: RoleName;   // 最低所需角色
  keywords?: string[];       // 搜尋關鍵字
}

export const APPLET_REGISTRY: AppletMetadata[] = [
  // 所有 Applet 配置
];

2. 分類系統​

定義標準化的 Applet 分類：

分類說明
sales-marketing銷售與行銷
operations營運管理
finance財務會計
hr人力資源
utilities工具程式
other其他

3. 輔助函數​

提供三個核心輔助函數：

  • filterAppletsByRole(applets, userRole) - 根據用戶角色過濾可見 Applet
  • groupAppletsByCategory(applets) - 按分類分組
  • searchApplets(applets, query) - 搜尋名稱、描述、關鍵字

4. UI 組件​

Application Launcher 組件位於 src/components/application-launcher/：

  • Modal 形式呈現（覆蓋整個畫面）
  • 頂部搜尋欄
  • 分類標籤過濾
  • 網格式 Applet 圖示顯示
  • ESC 鍵關閉

5. 觸發入口​

透過 Header 中的 Grid 圖示按鈕觸發開啟。

考慮的替代方案 (Alternatives Considered)​

方案 A: 繼續使用 Sidebar​

描述: 維持原有的靜態側邊欄設計，增加折疊功能。

優點:

  • 無需大幅改動現有架構
  • 用戶無需學習新操作

缺點:

  • 擴展性問題未解決
  • 需額外處理權限過濾邏輯
  • 移動端體驗不佳

為何未採用: 無法根本解決擴展性問題。

方案 B: Dock 模式​

描述: 類似 macOS Dock 的固定工具列，僅顯示最常用的 Applet。

優點:

  • 視覺簡潔
  • 快速訪問常用應用

缺點:

  • 可顯示的 Applet 數量有限
  • 需要額外的「更多應用」入口
  • 自定義機制增加複雜度

為何未採用: 仍需要輔助機制處理大量 Applet。

方案 C: Command Palette​

描述: 類似 VS Code 的命令面板（Ctrl/Cmd + K），透過鍵盤快速導航。

優點:

  • 對熟練用戶效率極高
  • 不佔用畫面空間

缺點:

  • 學習曲線較高
  • 新用戶難以發現可用 Applet
  • 無視覺化預覽

為何未採用: 目標用戶群不熟悉此操作模式。

決策後果 (Consequences)​

正面影響 (Positive)​

  • ✅ 統一導航入口 - 所有 Applet 透過單一介面訪問
  • ✅ 角色感知 - 自動過濾用戶無權訪問的 Applet
  • ✅ 可搜尋 - 支援多語言關鍵字搜尋
  • ✅ 分類清晰 - 按業務領域分組，便於瀏覽
  • ✅ 易於擴展 - 新增 Applet 只需在 Registry 添加配置

負面影響 (Negative)​

  • ⚠️ 需要額外點擊 - 相比側邊欄需多一步操作打開 Launcher
    • 緩解：提供快捷鍵支援（未來）
  • ⚠️ 首次使用需適應 - 用戶需了解新的導航方式
    • 緩解：提供簡單的引導提示

風險 (Risks)​

  • 🚨 效能風險（機率: 低，影響: 低）- Applet 數量極大時可能影響渲染效能
    • 緩解：使用虛擬化列表（如需要）

需要注意的事項 (Notes)​

  • 📌 確保所有新增 Applet 都在 Registry 註冊
  • 📌 圖示顏色使用 DaisyUI 語義化顏色以保持主題一致性
  • 📌 關鍵字應包含中英文以支援雙語搜尋

影響範圍 (Impact)​

受影響的系統/模組​

  • src/layouts/header.tsx - 添加 Launcher 觸發按鈕
  • src/layouts/sidebar.tsx - 已刪除
  • src/layouts/sidebar-context.tsx - 已刪除
  • src/data/applets.ts - 已刪除，由 src/config/applet-registry.ts 取代

需要的變更​

  1. 建立 src/config/applet-registry.ts
  2. 建立 src/components/application-launcher/
  3. 修改 src/layouts/header.tsx 添加觸發入口
  4. 刪除舊的 Sidebar 相關檔案

遷移策略​

  1. 先建立新架構與舊架構並存
  2. 測試新導航功能正常
  3. 移除舊的 Sidebar 組件與相關狀態管理

參考資料 (References)​

後續行動 (Follow-up Actions)​

  • 建立 Applet Registry
  • 實作 Application Launcher 組件
  • 整合至 Header
  • 移除舊 Sidebar
  • 添加鍵盤快捷鍵支援 (Cmd/Ctrl + K)

最後更新: 2026-01-03 決策者: Development Team