# Sprint 5 — API 變更規格

> 後端 Dashboard API 的擴充欄位定義

---

## 現有 API (不動)

```
GET  /api/v1/dashboard          → DashboardResponse (聚合資料)
GET  /api/v1/dashboard/stream   → SSE (每30秒推送)
GET  /api/v1/dashboard/hosts    → 4主機概覽
GET  /api/v1/stats/disposition  → Sprint 4 處置統計
GET  /api/v1/approvals/pending  → 待核准列表
```

---

## 擴充: DashboardResponse 新增欄位

```python
# apps/api/src/api/v1/dashboard.py

class DashboardResponse(BaseModel):
    # ─── 現有欄位 (不動) ───
    timestamp: datetime
    environment: str
    mock_mode: bool
    overall_status: str
    hosts: list[HostStatusResponse]
    alerts_count: int
    pending_approvals: int
    
    # ─── Sprint 5 新增 ───
    k8s_pods: list[PodStatusBrief] = []
    ai_diagnosing: list[str] = []         # OpenClaw 正在分析的服務名稱
    topology_metadata: TopologyMetadata | None = None


class PodStatusBrief(BaseModel):
    """K8s Pod 簡要狀態 (不需要完整 Pod spec)"""
    name: str                    # "awoooi-api-7b8f4c-x9k2p"
    deployment: str              # "awoooi-api"
    namespace: str               # "awoooi-prod"
    status: str                  # "Running" | "Pending" | "CrashLoopBackOff"
    restart_count: int = 0
    ready: bool = True


class TopologyMetadata(BaseModel):
    """拓撲圖元資料"""
    total_entities: int          # 67
    healthy_count: int           # 65
    warning_count: int           # 1
    critical_count: int          # 0
    ai_active: bool              # OpenClaw 是否正在分析
```

---

## 擴充: SSE 新事件類型

```python
# 現有事件:
# - HOST_UPDATE: 每30秒推送主機狀態

# Sprint 5 新增:
# - AI_DIAGNOSING: OpenClaw 開始/結束分析時推送
{
    "type": "AI_DIAGNOSING",
    "data": {
        "service_name": "awoooi-worker",
        "incident_id": "INC-20260407-5E0B84",
        "action": "start",          # "start" | "complete" | "failed"
        "confidence": 0.91,         # 分析完成時
        "playbook_matched": "restart_worker.yml"  # 匹配到的 Playbook
    },
    "timestamp": "2026-04-08T10:03:42+08:00"
}
```

---

## 資料來源

| 新欄位 | 來源 | 檔案 |
|--------|------|------|
| `k8s_pods` | `k3s_monitor_service.py` 已有的 Pod 查詢 | `services/k3s_monitor_service.py` |
| `ai_diagnosing` | Redis working memory 中 active incidents | `services/incident_service.py` |
| `topology_metadata` | 從 hosts 聚合計算 | `api/v1/dashboard.py` 內計算 |

---

## 不需要的新 API

| 之前提過的 | 是否需要 | 原因 |
|-----------|---------|------|
| `POST /topology/execute` | ❌ 不需要 | 現有 `/approvals/{id}/sign` 已涵蓋 |
| `GET /topology/service/{host}/{name}` | ❌ 不需要 | 現有 `/dashboard` 已有服務資料 |
| `GET /topology/events?host={ip}` | ❌ 不需要 | 現有 `/incidents` + SSE 已涵蓋 |

**結論: 後端只需擴充 DashboardResponse (+3 欄位) + SSE 新事件 (+1 類型)，不需要新 API 端點。**