ewoooc/docs/guides/pchome_growth_ui_ux_guardrails.md

PChome Growth UI/UX Guardrails

本專案所有使用者可見頁面，都必須服務同一個產品目標：

讓營運者更快判斷如何提升 PChome 業績，並能直接採取下一步。

不可偏離的工作重點

1. 每個頁面都要有清楚的營運目的、目前狀態與下一步。
2. 使用者不應看到工程實作細節，例如資料庫欄位、raw caller、commit、branch、JSON、API、endpoint、模型名稱或錯誤堆疊。
3. 比價、缺貨、匯入、AI 建議、觀測與服務健康頁，都要用同一套 PChome 業績成長語言：主推、守價、補比價、供貨風險、成長缺口、建議路徑、使用情境、服務元件。
4. 資料不足時不能整段消失，要顯示可理解的空狀態與下一步。
5. 不得把工作視窗溝通、部署交接、工程判斷或維護工作摘要搬到前台。
6. 外部促銷活動、折扣、價格壓力與平台活動訊號，必須被整理成「PChome 現況對比」與「業績提升解法」，不能只顯示外部事件本身。
7. 商品型頁面必須把商品身份放在主要視覺區：商品圖、平台商品 ID、商品名稱、售價、賣場連結、可信度與下一步不得分散到難以掃描的位置。
8. 外部主流平台來源治理不得只看 PChome / MOMO；Shopee、Lazada、Amazon、Google Merchant / Shopping、TikTok Shop、LINE 購物、Rakuten、Yahoo 購物、露天、品牌官網 / Shopify、Meta Commerce、Coupang 等來源至少要有待接入契約。未接合法穩定來源前只能標示待接入，不得假裝已監控。
9. 前台頁首、導覽、CTA 與提示不得把「爬蟲」當使用者主語；應使用「商品監控、資料擷取、監控來源、價格來源」等營運語言。內部 route / key 可維持相容，但不得外露成主要文案。
10. 前台錯誤 fallback 不得直接回傳後端 raw message；未知錯誤也必須轉成「下一步怎麼處理」的營運語言，原始 exception、資料庫表名、欄位名、driver error、runtime error 只可留在內部 log 或維護介面。

每次 UI/UX 修改的驗收

至少要完成：

• 本地測試：tests/test_frontend_v2_assets.py
• 相關業務測試：tests/test_pchome_revenue_growth_service.py
• 正式 smoke：檢查 /health 版本、核心頁 HTTP 200、可見文案無 raw terms、靜態資源 HTTP 200
• 如果頁面有 PChome/MOMO 商品比較，必須能一眼看到兩平台價格與可同時開啟的外部賣場連結
• 如果頁面有商品列、AI 挑品或候選卡，必須能一眼看到商品圖、商品 ID 與可點擊賣場；缺圖只能顯示「待補圖片」等可診斷狀態，不得破圖或空白
• 如果商品表格需要橫向捲動，關鍵賣場操作欄必須固定或重複在可見區，不能讓使用者為了開兩家賣場而找不到按鈕
• 如果頁面有外部促銷或競品活動訊號，必須至少提供守價、組合、曝光或會員回饋等 PChome 可執行解法
• 如果 CSS/JS 在同一輪修正後重新部署，必須同步提升 SYSTEM_VERSION，確保正式頁的靜態資源版本參數改變，不讓使用者瀏覽器繼續使用舊樣式

判斷標準

如果頁面需要使用者理解「這是什麼欄位、哪個模型、哪個 pipeline、哪個 commit、哪個 API」才知道下一步，這個 UI 就是不合格。