chore(observability): centralize QA page contract

2026-05-05 22:19:25 +08:00
parent 346e9672a6
commit cdcbcf1d80
4 changed files with 164 additions and 98 deletions
--- a/scripts/observability_contract.py
+++ b/scripts/observability_contract.py
@@ -0,0 +1,125 @@
+"""Single source of truth for AI observability QA contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ObservabilityPage:
+    template: str
+    active_page: str
+    url: str
+    label: str
+    short_label: str
+    markers: tuple[str, ...]
+
+    @property
+    def route_suffix(self) -> str:
+        return self.url.replace("/observability", "", 1) or "/"
+
+
+@dataclass(frozen=True)
+class AssetCheck:
+    url: str
+    label: str
+    markers: tuple[str, ...]
+
+
+OBSERVABILITY_PAGES = (
+    ObservabilityPage(
+        "templates/admin/observability_overview.html",
+        "obs_overview",
+        "/observability/overview",
+        "觀測台總覽",
+        "總覽",
+        ("觀測台總覽", "主機健康", "AI 呼叫"),
+    ),
+    ObservabilityPage(
+        "templates/admin/agent_orchestration.html",
+        "obs_agent_orchestration",
+        "/observability/agent_orchestration",
+        "Agent 編排矩陣",
+        "Agent",
+        ("Agent 編排矩陣", "LLM", "MCP", "RAG"),
+    ),
+    ObservabilityPage(
+        "templates/admin/business_intel.html",
+        "obs_business_intel",
+        "/observability/business_intel",
+        "商業面 × AI",
+        "商業",
+        ("商業面 × AI", "AI", "競品"),
+    ),
+    ObservabilityPage(
+        "templates/admin/host_health.html",
+        "obs_host_health",
+        "/observability/host_health",
+        "主機健康",
+        "主機",
+        ("主機健康", "Ollama", "AutoHeal"),
+    ),
+    ObservabilityPage(
+        "templates/admin/ai_calls_dashboard.html",
+        "obs_ai_calls",
+        "/observability/ai_calls",
+        "AI 呼叫",
+        "AI 呼叫",
+        ("AI 呼叫", "Provider", "RAG"),
+    ),
+    ObservabilityPage(
+        "templates/admin/budget.html",
+        "obs_budget",
+        "/observability/budget",
+        "預算控管",
+        "預算",
+        ("預算控管", "force", "throttle"),
+    ),
+    ObservabilityPage(
+        "templates/admin/promotion_review.html",
+        "obs_promotion_review",
+        "/observability/promotion_review",
+        "RAG 晉升審核",
+        "晉升",
+        ("RAG 晉升審核", "Promotion", "ai_insights"),
+    ),
+    ObservabilityPage(
+        "templates/admin/rag_queries.html",
+        "obs_rag_queries",
+        "/observability/rag_queries",
+        "RAG 召回詳情",
+        "RAG",
+        ("RAG 召回詳情", "最近 50", "hits"),
+    ),
+    ObservabilityPage(
+        "templates/admin/quality_trend.html",
+        "obs_quality_trend",
+        "/observability/quality_trend",
+        "反饋趨勢",
+        "品質",
+        ("反饋趨勢", "Caller", "蒸餾"),
+    ),
+    ObservabilityPage(
+        "templates/admin/ppt_audit_history.html",
+        "obs_ppt_audit",
+        "/observability/ppt_audit_history",
+        "PPT 視覺審核",
+        "PPT",
+        ("PPT 視覺審核", "AiderHeal", "audit"),
+    ),
+)
+
+
+CSS_ASSET_CHECKS = (
+    AssetCheck(
+        "/static/css/observability-system.css",
+        "觀測台 CSS",
+        (
+            "--obs-title-size",
+            "--obs-value-size",
+            ".momo-observability-mode",
+            ".obs-chart-frame",
+            ".obs-modal-preview",
+        ),
+    ),
+)