AI 儀表板（AI Dashboard）

功能群：報表與儀表板｜兩類產出先讀 功能群總覽

事實基準：2026-07-05 從 FE（views/dynamic-dashboard/、composables/useDashboardGenerator.js）/ BE（api/ai_dashboard、app/ai_dashboard、infra/ai_dashboard）code 掃出；error code 對 common/code/error_code.py；模型 ID 對 infra/ai_dashboard/ai_client/claude_client.py

1. 功能描述

AI 儀表板讓使用者用自然語言 prompt 生成一份動態儀表板：後端跑五階段管線（AI 選資料 API → 取資料 → 統計 → AI 設計版面 → 組裝 JSON），前端渲染成 Ultima UI 元件並抽出圖表。生成結果 per-request、不落 DB（無專屬儀表板表）。

主要使用者：需快速視覺化 GRC 資料的人（全域工具，任何登入者皆可用）。

角色速覽：

1.1 功能總覽（本頁全部功能）

UC（§2）展開 生成主流程（健康檢查 → prompt → 生成 → 渲染 / 重試）。

2. Use Case

角色速覽：

流程圖視覺慣例：菱形 = 判斷、橘底 = AI 步驟 / 例外、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-AID-01 生成 AI 儀表板

3. 權限矩陣

生成時以 JWT 帶出 DashboardContext（user_uid / user_id / tenant_id / org_unit_id / locale）注入資料 API——查詢受 RLS / tenant 隔離（見 §11）。

4. 狀態機與前置條件

本頁無持久狀態機（無儲存）。生成前置與 gate：

5. UI 設計

📸 實際畫面截圖待補（一律亮色模式拍攝；截圖另有專責 session）。預計補到 assets/img/： ① 空狀態（PromptBar + 範本） aid-empty.png ② 生成中 loading aid-loading.png ③ 生成結果（儀表板 + 戰情室圖表） aid-result.png ④ 錯誤訊息 aid-error.png

版面骨架與區塊職責：

狀態呈現：PromptBar 狀態徽章由 health 決定（在線 success / 離線 danger）；生成鈕在 loading 或離線時停用；未生成且未載入顯示 Templates；生成後主區 DynamicPrimeComponent 渲染 Ultima 結構，chartsFromAI > 0 才顯示戰情室（抽最多 3 圖表、以指紋去重）。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"error_code": "AI_DASHBOARD_…", "msg": "…"}。

6.1 總清單（本頁呼叫的全部 endpoint）

6.2 核心 endpoint（欄位對照 route / service，出處標段末）

[GET] /ai-dashboard/health

免 JWT。回靜態健康狀態 + 可用供應商（claude / openai / google）+ 速度（fast / balanced / powerful）。出處：api/ai_dashboard/routes/ai_dashboard_route.py::health。

[POST] /ai-dashboard/auto-generate

Request：

{
  "prompt": "string",     // 必，1–2000 字
  "provider": "claude",   // 預設 claude
  "speed": "balanced"     // 預設 balanced
}

（FE 送 speed:'fast'）。以 JWT 組 DashboardContext(user_uid, user_id, tenant_id, org_unit_id, locale)。五階段管線（見 §10）。Response data：

{
  "object": {},           // <Ultima Container JSON>
  "query_plan": {},
  "data_count": 0,
  "tokens_used": {
    "input": 0,
    "output": 0,
    "cache_creation": 0,
    "cache_read": 0
  },
  "auto_generated": true
}

出處：api/ai_dashboard/routes/ai_dashboard_route.py::AiDashboardAutoGenerateRoute、app/ai_dashboard/service/ai_dashboard_app_service.py::generate_dashboard_auto。

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本頁核心鏈路）

DDD 提醒：資料查詢透過 data_api_service 動態路由到既有服務方法（api_registry 映射），注入 DashboardContext 保留 RLS / tenant 隔離；不繞過既有 domain service 直接查 DB。LLM client 在 infra 層（ClaudeClient / OpenAIClient / GoogleClient）。

9. DB

9.1 資料表總清單

main_app.py 曾有「AI Dashboard schema analyzer」啟動初始化，目前已註解不執行（見 §11）。無 _trans / 專屬 dump 表。

10. 頁面邏輯與資料對應

生成管線（五階段）：

1. AI 選 API（_ask_ai_to_select_api）：LLM 從 api_registry（~40 服務方法目錄）選最合適的 main_api（附理由），用 prompt 快取。
2. 取資料（data_api_service.call_api）：動態呼叫該服務方法，注入 DashboardContext（RLS / tenant）。
3. 統計（analyze_data_stats）：算分布 / 計數（project_name / group_name / control_no / job_status 等維度）。
4. AI 設計版面（_ask_ai_to_design_layout）：LLM 依統計 + 樣本產出 analysis_blocks（stat / status-breakdown / category-breakdown）+ table。
5. 組裝（build_dashboard_from_design）：組成 Ultima UI Container / Card / DataTable JSON 樹回傳。

前端渲染：dashboardStructure（object）→ DynamicPrimeComponent 遞迴渲染；extractChartsFromStructure 走訪樹抽出 type==='chart' 節點、指紋去重、限 3 張 → 戰情室。

錯誤對應：AI_DASHBOARD_400001（API Key 未設）/ 400002（不支援供應商）/ 400003（查詢計畫格式錯）/ 400004（AI 解析失敗）/ 500001（生成失敗）/ 404001（服務映射找不到）/ 404002（服務方法不存在）→ ErrorMessage（含建議 + 可重試判斷）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 不持久化：生成結果只在記憶體、回傳即渲染；重整頁面 / 重新生成即失，無「我的儀表板」清單可回讀。要保留需另外截圖 / 匯出（本頁未提供匯出）。
2. health 免 JWT：健康檢查端點公開；auto-generate 才要 JWT。
3. 兩層 AI 呼叫成本：一次生成含兩次 LLM 呼叫（選 API + 設計版面）+ 一次資料查詢；tokens_used 有回報但不落 DB / 不計費追蹤——高頻使用需注意 token 成本。
4. FE 速度硬編 fast：前端送 speed:'fast'（→ haiku 模型），BE 預設值是 balanced（sonnet）——實際跑哪個模型看 FE 送的值，勿只看 BE 預設。
5. AI 選 API 可能選錯：第①階段由 LLM 從 api_registry 選資料來源，選錯 / 選到不存在服務會擋 AI_DASHBOARD_404001/404002；prompt 與可用 API 目錄的匹配品質決定結果。
6. RLS 靠 context 注入：資料查詢注入 DashboardContext（tenant / org），依賴既有 domain service 的 RLS——若某 API 未正確吃 context，可能跨租戶（設計上應由 data_api_service 統一注入）。
7. 模型 ID 是程式碼現況：§11 模型 ID 取自 claude_client.py 當前值；升級模型需改該檔 MODEL_MAP，spec 同步更新。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。需設 ANTHROPIC_API_KEY（或對應供應商 key）於環境變數，否則生成擋 AI_DASHBOARD_400001。BE 改 service code 後必須重啟（無 hot reload）
• 測試帳號：dev 環境登入帳號密碼見 .env / 部署文件
• 導航路徑：側邊選單「儀表板 / AI 儀表板」（/dashboard/ai-dashboard）
• 前置資料：需有可查詢的 GRC 資料（專案 / 任務 / 控制），且 AI API Key 已設；先看 health 徽章是否在線
• E2E：compliance-manager-test/ repo；以 AI 儀表板 / ai dashboard 搜尋 feature 檔（注意：LLM 回應非決定性，E2E 宜驗流程而非固定內容）
• 相關文件：摘要報表見 專案摘要報表、GRC 內建儀表板見 專案儀表板；Claude API 用法見 CLAUDE.md / claude-api 參考；DB / API 全量見 GAI-SD-02/03