# GRC Dashboard API 規格

> **Blueprint prefix**：`/api/1.0/grc`
> **File**：`api/grc/routes/dashboard_route.py`
> **Auth**：JWT Required（Header：`Authorization: Bearer <token>`）

---

## API 列表

| Method | URL | 說明 |
|--------|-----|------|
| `GET` | `/api/1.0/grc/dashboard/summary` | 取得 GRC 儀表板彙總資料 |

---

## 1. GET `/api/1.0/grc/dashboard/summary`

> **Route class**：`DashboardSummaryResource`
> **用途**：取得 GRC 儀表板彙總資料，包含指標數字、專案狀態分佈、近 7 天完成率趨勢。

### Request

無 Request Body。

```
GET /api/1.0/grc/dashboard/summary
```

### Response `200`

```json
{
  "status": true,
  "data": {
    "metrics": {
      "active_project_count": 3,
      "total_controls": 120,
      "avg_completion_rate": 42,
      "my_pending_task_count": 7
    },
    "status_distribution": {
      "pending": 2,
      "in_progress": 3,
      "completed": 1,
      "suspended": 0,
      "archived": 0
    },
    "completion_trend": [
      {
        "date": "2026-02-25",
        "projects": [
          { "project_uid": "uuid-A", "project_name": "CMMC 評鑑", "completion_rate": 30 },
          { "project_uid": "uuid-B", "project_name": "ISO 27001",  "completion_rate": 15 }
        ]
      },
      {
        "date": "2026-02-26",
        "projects": [
          { "project_uid": "uuid-A", "project_name": "CMMC 評鑑", "completion_rate": 35 },
          { "project_uid": "uuid-B", "project_name": "ISO 27001",  "completion_rate": 15 }
        ]
      }
    ]
  }
}
```

> `completion_trend` 共 7 筆（今天 - 6 天 → 今天），由舊到新排列。

### Response 欄位說明

#### `metrics`

| 欄位 | 型別 | 說明 |
|------|------|------|
| `active_project_count` | integer | 狀態為 `in_progress` 的專案數 |
| `total_controls` | integer | 所有 `in_progress` 專案的控制項總數 |
| `avg_completion_rate` | integer | 所有 `in_progress` 專案的平均完成率（%，四捨五入） |
| `my_pending_task_count` | integer | 當前登入使用者尚未完成的 Job 數（`job_executions.status != COMPLETED`） |

#### `status_distribution`

key 固定為以下 5 個，value 為該狀態的專案數：

| Key | 說明 |
|-----|------|
| `pending` | 待啟動 |
| `in_progress` | 進行中 |
| `completed` | 已完成 |
| `suspended` | 暫停 |
| `archived` | 已封存 |

#### `completion_trend`

近 7 天（含今天）每天的累積完成率快照，時間範圍：`today-6` ～ `today`，**共 7 筆**，由舊到新排列。

取當前 `in_progress` 且最早建立的前 5 個專案。

| 欄位 | 型別 | 說明 |
|------|------|------|
| `date` | string `YYYY-MM-DD` | 日期 |
| `projects` | array | 該日各專案的累積完成率 |
| `projects[].project_uid` | string | 專案 UUID |
| `projects[].project_name` | string | 專案名稱 |
| `projects[].completion_rate` | integer | 截至該日已完成任務數 / 總任務數 × 100（%） |

> **累積邏輯**：`completion_rate` 為「截至該日（含）已完成的 AO 任務數」÷「該專案總 AO 任務數」× 100。
> 完成時間以 `oscal.assessment_plan_tasks.updated_at` 為準。

### 無資料情境

| 情境 | 行為 |
|------|------|
| 無 `in_progress` 專案 | `completion_trend: []` |
| 某專案無任務 | 該專案每天 `completion_rate: 0` |
| 非 admin 且非 owner / participant | 只看得到自己有權限的專案 |