ewoooc/docs/memory/observability_ui_qa_guardrails_20260505.md

AI 觀測台 UI QA Guardrails（2026-05-05）

背景

Claude Code Phase 38→55 完成 AI 觀測台 10 頁，但前端曾出現以下問題：

• 側欄第二/三層字色太暗，看不清楚。
• 側欄背景回退成近純黑，偏離暖咖啡設計規範。
• 觀測台頁面 typography / spacing / button / table / chart 容器不一致。
• observability-system.css 在 template 有 link，但 production /static/css/observability-system.css 曾 404。
• 前端互動曾外露 Error: ...、unknown、SQL/Jinja raw error 類文案。

現行治理入口

• UI 規範 guide：docs/guides/observability_ui_governance.md
• 部署 SOP：docs/guides/deployment_sop.md
• 頁面契約 SOT：scripts/observability_contract.py
• 靜態 UI guard：scripts/check_observability_ui.py
• Production smoke：scripts/check_observability_pages.py
• 一鍵 QA：scripts/check_observability_suite.sh
• CSS mirror sync：scripts/sync_observability_css.py

必跑指令

修改觀測台 template、route、shell、topbar、CSS 後：

./scripts/quick_review.sh --sync-observability-css
./scripts/quick_review.sh --observability-qa

指定環境或只跑靜態 guard：

./scripts/quick_review.sh --observability-smoke --base-url https://mo.wooo.work --timeout 12
./scripts/quick_review.sh --observability-qa --base-url https://mo.wooo.work
./scripts/quick_review.sh --observability-qa --skip-production
./scripts/quick_review.sh --observability-help

等效直接指令：

python3 scripts/sync_observability_css.py
bash scripts/check_observability_suite.sh

重要陷阱

• static/css/observability-system.css 是 canonical CSS。
• web/static/css/observability-system.css 是 Flask production static route 實際服務用 mirror。
• 兩者必須 byte-identical；guard 會檢查，不一致時跑 sync_observability_css.py。
• Production smoke 必須看到 觀測台 CSS: HTTP 200, markers=ok。
• 觀測台頁面清單、URL、active_page、內容 marker 不要分散維護，先改 scripts/observability_contract.py。
• quick_review.sh --observability-qa 預設打 production https://mo.wooo.work；測 staging/localhost 時要明確帶 --base-url。
• Gitea CD 會偵測觀測台 template/CSS/route/QA script/guide 變更：deploy 前跑 CSS sync + static QA，deploy 後跑 production smoke。

已鎖住的回歸

• Times / Georgia / serif 標題字型。
• 超大 hard-coded clamp title。
• 圖表 inline style="height:..."。
• 靜態 inline width。
• 純白 hover/card surface。
• raw SQL/Jinja exception 外露。
• raw alert('Error: ...') / unknown 前端文案。
• 側欄純黑背景。
• 側欄第二/三層低對比文字。
• 觀測台 URL 有側欄連結但 Flask route 不存在。
• 觀測台頁面 200 但內容 marker 缺失。
• CSS link 存在但 production static asset 404。