From ce7dd6068c16f9731eb9512394cc3e21e417fa1a Mon Sep 17 00:00:00 2001
From: OoO <ooo@MacBook-Pro.local>
Date: Tue, 5 May 2026 23:24:33 +0800
Subject: [PATCH] docs(deploy): require observability QA for frontend changes

---
 docs/guides/deployment_sop.md | 39 ++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/docs/guides/deployment_sop.md b/docs/guides/deployment_sop.md
index 43d945b..028571e 100644
--- a/docs/guides/deployment_sop.md
+++ b/docs/guides/deployment_sop.md
@@ -1,6 +1,6 @@
 # 🚀 EwoooC 部署標準作業程序 (SOP)
 
-> **版本日期**: 2026-04-18 (依 ADR-008 修訂)
+> **版本日期**: 2026-05-05 (依 ADR-008 / ADR-011 修訂)
 > **目標主機**: `ollama@192.168.0.188` (經 `192.168.0.110` 跳板)
 
 ## 🛠️ 開發同步流程
@@ -22,15 +22,48 @@ scp -o ProxyJump=wooo@192.168.0.110 -r services/ ollama@192.168.0.188:/home/olla
 ### 3. 重啟容器
 檔案進入掛載目錄後，重啟容器以加載變更：
 ```bash
-ssh -J wooo@192.168.0.110 ollama@192.168.0.188 "docker restart momo-pro-system"
+ssh -J wooo@192.168.0.110 ollama@192.168.0.188 \
+  "cd /home/ollama/momo-pro && docker compose up -d --no-deps --force-recreate momo-app"
 ```
 
+注意：
+- 禁止使用 `docker compose ... --remove-orphans`。
+- 禁止影響 `momo-db` 的資料與容器生命週期。
+- 若只同步文件、QA script、非 runtime 檔案，不需要重啟容器。
+
 ## 🏗️ 重大變更 (Rebuild)
 若修改了 `Dockerfile` 或新增了 `requirements.txt` 套件：
 ```bash
-ssh -J wooo@192.168.0.110 ollama@192.168.0.188 "cd /home/ollama/momo-pro && docker compose build momo-app && docker compose up -d momo-app"
+ssh -J wooo@192.168.0.110 ollama@192.168.0.188 \
+  "cd /home/ollama/momo-pro && docker compose build momo-app && docker compose up -d --no-deps --force-recreate momo-app"
 ```
 
+## 🎛️ AI 觀測台前端變更驗收
+若修改以下任一類檔案，必須跑 AI 觀測台 QA 套件：
+- `templates/admin/*observability*` 或任何 `/observability/*` 頁面 template。
+- `templates/ewoooc_base.html` 或 `templates/components/_ewoooc_shell.html`。
+- `static/css/observability-system.css` 或 `web/static/css/observability-system.css`。
+- `routes/admin_observability_routes.py`。
+
+本地先跑：
+```bash
+python3 scripts/sync_observability_css.py
+bash scripts/check_observability_suite.sh
+```
+
+部署後再跑：
+```bash
+bash scripts/check_observability_suite.sh
+```
+
+QA 套件會檢查：
+- `/health` 必須 HTTP 200 且包含 healthy marker。
+- 10 個觀測台頁面必須 HTTP 200。
+- 每頁必須包含自己的內容 marker。
+- 不得外露 `Traceback`、`ProgrammingError`、`UndefinedError`、`relation "`、`查詢失敗:`。
+- `observability-system.css` 必須線上 HTTP 200，且包含核心 token/class。
+- `static/css/observability-system.css` 與 `web/static/css/observability-system.css` 必須一致。
+
 ## 🔍 維運指令
 - **查看日誌**: `docker logs -f momo-pro-system --tail 100`
 - **進入資料庫**: `docker exec -it momo-db psql -U momo -d momo_analytics`