# 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 後：

```bash
./scripts/quick_review.sh --sync-observability-css
./scripts/quick_review.sh --check-observability-css
./scripts/quick_review.sh --observability-qa
```

指定環境、渲染後視覺契約或只跑靜態 guard：

```bash
./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
```

等效直接指令：

```bash
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。