From fa3e0884ade0ee17dc74fc6ff83ef1416389beec Mon Sep 17 00:00:00 2001
From: OoO <ooo@MacBook-Pro.local>
Date: Tue, 5 May 2026 14:59:45 +0800
Subject: [PATCH] =?UTF-8?q?docs(observability):=20=E8=A3=9C=E9=BD=8A=20UI?=
 =?UTF-8?q?=20=E6=B2=BB=E7=90=86=E8=A6=8F=E7=AF=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/guides/observability_ui_governance.md | 50 ++++++++++++++++++++++
 docs/memory/README.md                      |  3 ++
 static/css/observability-system.css        | 10 ++++-
 3 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 docs/guides/observability_ui_governance.md

diff --git a/docs/guides/observability_ui_governance.md b/docs/guides/observability_ui_governance.md
new file mode 100644
index 0000000..2a88e9c
--- /dev/null
+++ b/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
+```
diff --git a/docs/memory/README.md b/docs/memory/README.md
index 5916793..5423eda 100644
--- a/docs/memory/README.md
+++ b/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、資料密集卡片/表格、空狀態時。
 
 ## 新增規則
 
diff --git a/static/css/observability-system.css b/static/css/observability-system.css
index b70e679..1390c0c 100644
--- a/static/css/observability-system.css
+++ b/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;
 }