Files

OG T 83e9d3eef8 docs(specs): Sprint 5 四份技術文檔 — Tab 規格/路由對照/元件抽取/API 變更

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>

2026-04-08 16:03:58 +08:00

3.0 KiB

Raw Blame History

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 新增欄位

# 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 新事件類型

# 現有事件:
# - 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 端點。

3.0 KiB Raw Blame History

Sprint 5 — API 變更規格

現有 API (不動)

擴充: DashboardResponse 新增欄位

擴充: SSE 新事件類型

資料來源

不需要的新 API

3.0 KiB

Raw Blame History