83e9d3eef8
1. Tab 結構規格書: 每個新頁面的 Tab 配置、區塊佈局、元件複用方式 2. 路由對照表: 26 個舊 URL → 新位置的精確映射 + redirect 實作方式 3. 元件抽取計畫: 17 個頁面抽取為 Panel 元件的步驟和目錄結構 4. API 變更規格: DashboardResponse +3 欄位 + SSE +1 事件 (不新增 API) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
103 lines
3.0 KiB
Markdown
103 lines
3.0 KiB
Markdown
# 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 端點。**
|