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
• 渲染後視覺契約：scripts/check_observability_visual_contract.sh

必跑指令

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

./scripts/quick_review.sh --sync-observability-css
./scripts/quick_review.sh --check-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-visual --base-url http://127.0.0.1:5016 --timeout 20
./scripts/quick_review.sh --observability-help

等效直接指令：

python3 scripts/sync_observability_css.py
python3 scripts/sync_observability_css.py --check
bash scripts/check_observability_suite.sh
bash scripts/check_observability_visual_contract.sh --base-url http://127.0.0.1:5016 --timeout 20

重要陷阱

• 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。
• quick_review.sh --observability-visual 也預設打 production；驗證尚未部署的本機變更時，必須先啟 Flask local server 並明確帶 --base-url http://127.0.0.1:<port>。若打 production 失敗，先確認正式端是否已部署該版，不要把舊版正式站結果誤判成本機 diff 失敗。
• Gitea CD 會偵測觀測台 template/CSS/route/QA script/guide 變更：deploy 前跑 CSS mirror check + static QA，deploy 後跑 production smoke。QA script 範圍包含 quick_review.sh、check_observability_*、observability_contract.py、sync_observability_css.py。CD 不會偷偷修 mirror；若 check fail，先本地跑 sync 後提交。
• CD 觸發判斷集中在 scripts/check_observability_deploy_gate.py；不要在 .gitea/workflows/cd.yaml 另維護一份長 regex。
• check_observability_suite.sh 會跑 deploy gate self-test，確認觀測台相關檔案會觸發 QA、一般 backend/docs 檔案不會誤觸發。

已鎖住的回歸

• 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。