專案儀表板（Project Dashboard）

功能群：專案管理｜狀態機與共用概念先讀 功能群總覽

事實基準：2026-07-05 從 FE / BE code 掃出（FR-038 v2）；endpoint 對照 routes.json，response 對照 marshmallow serializer，表結構取自 db_schema.json

變更紀錄：2026-07-09 FR-047 —— ① 專案狀態機 B 案：專案建立即 in_progress（「未開始 pending」語意取消），落地頁「進行中專案」卡改只判 in_progress（DashboardView 篩選對齊輪次驅動真相）；② 進行中專案卡進度條接上真值（list_projects 補 completion_rate，原恆 0%）

1. 功能描述

專案儀表板是登入後的全域落地頁（route /project/dashboard）——聚合「我有份的」跨專案資訊：四張指標卡、我的待辦任務、我的稽核、進行中專案卡片、兩張圖表（各專案完成度 / 狀態分佈）。

與專案總覽頁的區別：本頁是跨專案的個人落地頁（無專案 id）；專案總覽頁（/project/projects/:id/round/:roundUid）是單一專案單一輪次的儀表板。兩者不同頁、不同資料源，勿混淆。

主要使用者：所有登入者（各區塊以 hasCap() 能力個別 gate；本頁無 route 層權限，缺能力則該區塊隱藏而非整頁擋）。

角色速覽：本頁無專案層角色概念，改以全域能力（capability）gate 個別區塊。

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

UC（§2）展開一條核心路徑 UC-PD-01（載入聚合資料並導航到各明細頁）。§12 記錄兩處已確認失效的 UI 元素（專案卡進度條恆 0%、SSP 迷你件不顯示），本頁如實描述現況、不當作正常功能寫。

2. Use Case

角色速覽：本頁無專案層角色概念，改以全域能力（capability）gate 個別區塊。

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外 / 擋下、綠框 = 成功終點、虛線 = 可選路徑。

UC-PD-01 檢視儀表板並導航到明細

3. 權限矩陣

本頁無 route 層權限（無 pagePermission meta），控制在 UI 組成層以 hasCap() 個別 gate；BE 各 endpoint 另有可見性強制：

⚠️ 本頁權限是「區塊級隱藏」而非整頁擋——缺 project.read 只是專案相關區塊消失，「我的待辦任務」仍顯示（對落地頁合理）。各 endpoint 的 BE 可見性各自獨立，三種身分判定不同（專案成員資格 / 稽核角色 / 任務指派），勿假設一致。

4. 狀態機與前置條件

本頁不推進任何狀態，僅呈現跨專案彙總。狀態分佈甜甜圈的 7 態桶對應輪次狀態機（見 _overview §2）；completion_trend 欄位恆 []（v2 無歷史快照表，見 §12）。

5. UI 設計

版面骨架與區塊職責（本頁為落地儀表板，區塊以全域 capability gate；彩色區塊可點跳本頁小節錨點，API 僅標代表性）：

實機截圖（STG，亮色模式，2026-07-05，帳號 blsadmin）：

狀態呈現：全頁 spinner 於並行 fetch；MetricCard / StatusBadge / FrameworkBadge / GrcProgressBar 共用元件；兩圖為 PrimeVue Chart（Chart.js v4）橫條 + 甜甜圈，甜甜圈附自訂圖例。注意：進行中專案卡的進度條已接上真值（2026-07-07 修，§12 坑 2）；SSP 完成度迷你件仍不顯示（§12 坑 1，未接 follow-up）。

6. API 規格

Envelope：成功 {"status": true, "data": …}（清單類帶 meta）、失敗 {"error_code": "…", "msg": "…"}。

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

6.2 核心 endpoint

[GET] /grc/dashboard/summary

無參數。Response data（DashboardSummaryResponseSchema）：

存取控制：route 強制 is_admin=False（admin 不繞專案成員資格）。出處：api/grc/serializers/dashboard.py、infra/grc/repository/grc_dashboard_repo_impl.py

[POST] /grc/jobs/my/list

Request：

{
  "pager": { "page": 1, "page_size": 8, "with_total": false },
  "sort": [],
  "filters": { "exclude_status": "COMPLETED" }
}

Response data（MyJobResponseSchema[]，每項一筆待辦任務）：

來源 = ORM view public.vw_user_job_queue。出處：api/grc/serializers/job.py:235、infra/participant/repository/task_assignee_repo_impl.py

[POST] /grc/audits/my/list

Request（無分頁，回 flat items）：

{ "filters": { "status": "auditing" } }

Response data.items（AuditorDashboardItemSchema[]）：

SQL 內建 role IN ('auditor','manager') + 輪次狀態白名單守門。出處：api/grc/serializers/auditor_dashboard.py、infra/grc/repository/auditor_dashboard_query.py

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

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

DDD 提醒：auditor_dashboard_query 是 query-object pattern（raw SQL），非標準 entity 鏈——讀取聚合場景刻意繞 entity 提效，別當一般 CRUD 樣板。

9. DB

9.1 資料表總清單（本頁讀取的全部表 / 視圖）

9.2 ER 圖（本頁讀取範圍）

9.3 核心表 / 視圖

大多數表欄位見規劃頁 §9.3 與 GAI-SD-03。本頁特有：

public.vw_user_job_queue — 使用者任務佇列（VIEW）

非基底表，是 view（定義 scripts/sql/view/vw_user_job_queue.sql），由 compliance.task_assignees / job_executions / projects / workflow_executions / public.users / workflow_execution_control_mapping / project_extensions + catalog 表組成；供「我的待辦任務」按 user_id 撈。欄位：job_id / user_id / job_status / job_name / project_uid / project_name / group_name / control_no / ap_task_* / workflow_execution_uid。

10. 頁面邏輯與資料對應

載入時序：見 §2 UC-PD-01（2~4 支並行，依能力）。歡迎列 nickname / 日期來自 user store 與本地時間，非 API。

關鍵欄位對應：

導航：待辦列 → project-my-tasks?job=；稽核列 → project-audit-review-round；專案卡 → project-ap-list；「檢視全部」→ 對應列表頁。

錯誤對應：各 fetch 失敗個別 catch，不整頁 fail；能力不足的區塊直接不渲染。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. ⚠️ 進行中專案卡的「SSP 完成度迷你件」永不顯示（已驗證死碼）：卡片 v-if="sspStatsMap[project.id]"，但填充它的 fetchSspStats 依賴 p.ssp?.id，而 POST /grc/projects/list 的 list_projects 不 wire ssp（mapper 預設 ssp_uid=None，只有 detail endpoint 才帶）→ SSP 迷你件在本頁任何情況都不會 render
2. 進行中專案卡進度條已接上真值（2026-07-07 修，FR-047 R1）：原本 list_projects 不傳 completion_rate、mapper 預設 0 → 進度條恆 0%，與同頁「各專案完成度」圖表（summary 真值）矛盾。已在 list_projects 加 _completion_rates() 批次 helper（公式與 summary project_completion 同源）餵 mapper，進度條與圖表同源。註：SSP 完成度迷你件（坑 1）仍未接（ssp 仍不 wire），屬另一 follow-up
3. evidence_ready_count / evidence_total_count 恆 0：auditor_dashboard_query 硬寫 0（v2 證據統計 follow-up）；本頁我的稽核表不消費這兩欄，暫無害，但未來若有 UI 讀它是不完整值
4. completion_trend 恆 []：v2 無歷史快照表，刻意棄用；FE 改用 project_completion，此欄僅 schema back-compat 保留（非 bug）
5. id 欄位是 uid 字串非數字：ProjectResponseSchema / MyJobResponseSchema 的 id 是 Method 回 uid，別誤當數字主鍵
6. 我的稽核無分頁：POST 帶 filters 但回 flat items 全量；FE 只 .slice(0,5)。稽核輪次爆量時整包傳輸
7. 待辦數兩處來源可能分歧：待辦表抓 page_size:8 顯示 5 筆；「檢視全部」條件用 metrics.my_pending_task_count > 5（summary 的 distinct count）而非 myPendingTasks.length——兩者不同查詢，理論上可能不一致
8. 無 route 層權限：本頁無 pagePermission meta；缺能力是「區塊消失」而非整頁擋。這對落地頁合理（待辦任務對所有人有用），但與其他頁的 route-guard 模式不同
9. 與專案總覽頁易混：本頁是全域跨專案落地頁；專案總覽頁 是單專案單輪。名稱都含「儀表板 / dashboard」但完全不同

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟
• 測試帳號：dev 環境 blsadmin（密碼見 .env / 部署文件）
• 導航路徑：登入 → 側邊選單「專案儀表板」（/project/dashboard）
• 前置資料：需自己有份的專案 + 指派給自己的任務 / 稽核，各區塊才有資料；驗能力 gate 需有 / 無 project.read / audit.read 兩種帳號
• E2E：compliance-manager-test/ repo；以 儀表板 / dashboard 搜尋（注意與 AI 儀表板 ai-dashboard 區分）
• 相關文件：單專案儀表板見 專案總覽頁、專案清單見 專案列表頁、我的任務見稽核執行群 project-my-tasks；FR-038 docs/features/FR-038-2606-oscal-redesign/