docs(observability): 補齊 UI 治理規範

docs/guides/observability_ui_governance.md

@@ -0,0 +1,50 @@
+# AI 觀測台 UI Governance
+
+> Scope: `/observability/*` pages using `ewoooc_base.html` and `.momo-observability-mode`.
+
+## 目標
+
+AI 觀測台是「AI 中樞控制室」，不是 Bootstrap 報表頁。任何新增或修改都必須維持：暖色焦糖系、Noto Sans TC、點陣方格、卡片化資料面、可降級空狀態。
+
+## 必守規範
+
+- 使用 `static/css/observability-system.css` 的 token 與 utility class。
+- 標題使用 `--obs-title-size`，KPI 數字使用 `--obs-value-size`。
+- 圖表容器使用 `.obs-chart-frame`、`.obs-chart-frame-tall`、`.obs-chart-frame-slim`。
+- 頁面資料缺表或 migration 未完成時，顯示安全空狀態，不得把 SQL exception 顯示給使用者。
+- 側欄必須維持暖深咖啡背景，第二/三層文字要有足夠對比。
+- 表格必須有暖色表頭、row hover、長文字換行保護。
+- 手機與中螢幕要能自動從多欄收成單欄。
+
+## 禁止事項
+
+- 不要在 template 裡新增 Times / Georgia / serif 作為主標題字型。
+- 不要新增紫色系、純黑 sidebar、純白卡片 hover。
+- 不要把整頁做成寬表格；資料密集內容優先用卡片、矩陣、可橫向 overflow 的表格。
+- 不要硬寫超大 `font-size: clamp(...)`；先調 token。
+- 不要新增 `style="height:..."` 圖表容器；使用 chart frame class。
+- 不要用 `查詢失敗: ProgrammingError...` 顯示給使用者。
+
+## 新頁 checklist
+
+1. Template 設定正確 `active_page`，讓 `observability-system.css` 載入。
+2. Hero 有清楚頁面任務，不做簡報封面式大字。
+3. 第一屏有 3 到 6 個可行動 KPI，不堆原始資料。
+4. 主資料區先呈現結論，再給明細。
+5. 空資料、缺表、外部服務未接入都要是可讀狀態。
+6. 10 頁巡檢不得出現 `Traceback`、`UndefinedError`、`ProgrammingError`、`relation "`、`查詢失敗:`。
+
+## 驗收指令
+
+```bash
+python3 - <<'PY'
+import urllib.request
+pages=[('/observability/overview','總覽'),('/observability/agent_orchestration','Agent'),('/observability/business_intel','商業'),('/observability/host_health','主機'),('/observability/ai_calls','AI 呼叫'),('/observability/budget','預算'),('/observability/promotion_review','晉升'),('/observability/rag_queries','RAG'),('/observability/quality_trend','品質'),('/observability/ppt_audit_history','PPT')]
+needles=['Traceback','UndefinedError','ProgrammingError','Internal Server Error','relation "','查詢失敗:']
+for path,label in pages:
+    with urllib.request.urlopen('https://mo.wooo.work'+path,timeout=12) as r:
+        html=r.read().decode('utf-8','ignore')
+        found=[n for n in needles if n in html]
+        print(f'{label}: HTTP {r.status}, issues={found or "none"}')
+PY
+```

docs/memory/README.md

@@ -27,6 +27,9 @@
 - `docs/guides/codex_agent_roles.md`
   用途：12 位歷史 Agent 的 Codex 化角色矩陣。
   何時閱讀：要做多角色分工、任務派工、review 流程設計時。
+- `docs/guides/observability_ui_governance.md`
+  用途：AI 觀測台 `/observability/*` 頁面的 UI/UX 設計治理、禁用事項與巡檢指令。
+  何時閱讀：新增或修改觀測台頁面、側欄、Chart.js、資料密集卡片/表格、空狀態時。
 
 ## 新增規則
 

static/css/observability-system.css

@@ -1,6 +1,12 @@
 /*
  * AI 觀測台共用視覺系統
  * 只在 ewoooc_base.html 的 .momo-observability-mode 啟用，避免污染一般後台頁。
+ *
+ * Governance:
+ * - 新增觀測頁時，優先使用本檔 token / utility class，不要在 template 內重建一套 hero/table/card。
+ * - 標題與 KPI 數字使用 --obs-title-size / --obs-value-size，不要再硬寫超大 clamp。
+ * - 圖表容器使用 .obs-chart-frame 系列；只有資料百分比 width 可保留 inline style。
+ * - 視覺語言固定為暖色焦糖系、Noto Sans TC、點陣方格；禁止回到紫色、純黑、Times/Georgia。
  */
 .momo-observability-mode {
   --obs-ink: var(--momo-ink, #302720);
@@ -70,8 +76,8 @@
     linear-gradient(135deg, rgba(255, 248, 239, 0.96), rgba(255, 255, 255, 0.76));
   box-shadow: 0 18px 42px rgba(70, 46, 28, 0.08);
   color: var(--obs-ink);
-  font-family: Georgia, 'Times New Roman', 'Noto Sans TC', serif;
-  font-size: clamp(1.65rem, 3vw, 2.65rem);
+  font-family: 'Noto Sans TC', 'Inter', sans-serif;
+  font-size: var(--obs-title-size);
   letter-spacing: -0.045em;
 }