15 事故分流
15 事故分流與畫面除錯
事故第一步判斷、畫面異常分流與升級條件。
出事時先看這份。它不是完整 runbook，也不取代 repo README；它只幫你在第一時間分清楚問題類型，然後跳到 03、04、05、07、08 或 09。
敏感資料交付提醒：本文件中的 05 或 05-environment-variables 指 05-environment-variables_環境變數與金鑰；該文件含 env value / secret 線索，僅做本地交付，不做雲端交付。
這裡確認
- 事故第一步先判斷什麼
- 畫面異常先分流到哪一類文件
- 先回哪份文件
- 哪個情況應該升級
這裡不處理
- 不重寫逐專案 debug 步驟
- 不重寫 deploy 指令
- 不重列 env、integrations、CMS 技術知識
先去哪裡
| 情境 | 先看哪裡 |
|---|---|
| 站掛了、5xx、白畫面 | 看這份的 事故導航表 |
| 內容有發但前台沒變 | 先看這份，再跳 07 或 04 |
| OAuth、表單、第三方串接出錯 | 先看這份，再跳 08 與 05 |
| 平台登入不進去 | 先看這份，再跳 03 |
靜態站部署（next "export"）後 _next / 圖片 / 字型路徑壞掉 | 先看這份，再跳 04 的靜態輸出部署注意事項 與 05 |
| reload 後停在中段，首屏動畫、ScrollTrigger 或鎖滾動流程錯亂 | 先看這份，再跳 09 的 scroll restoration 初始化防護文件 |
| macOS / Retina 上字重看起來比 Figma 粗 | 這屬於低風險視覺 QA 分流，先查 09 的 Figma 字重與瀏覽器顯示差異文件，不要直接當成一般站台事故 |
第一反應原則
- 先確認是哪個專案、哪個環境。
- 先打開該 repo
README。 - README 不夠，再回對應 handoff 主文件。
- 只要涉及權限、2FA、billing、owner 不明，就不要硬處理，直接升級。
事故導航表
| Incident Type | First Check | Primary Doc | Fallback Doc | Escalate When |
|---|---|---|---|---|
mahjong-system 會員 / 後台 / 桌台 / 付款異常 | 先分清是前端頁面、外部後端 API、LINE、LIFF、JKOPay、還是實體機桌台設備問題 | mahjong-system repo README 的 Troubleshooting | 05-environment-variables、08-integrations-and-api、03-access-and-accounts、04-deployment | 需要後端 API owner、LINE / JKOPay owner、正式站或 rollback 權限 |
| 網站掛掉 / 5xx / 白畫面 | 先分清是剛部署後、特定頁面還是整站都掛 | repo README 的 Deploy / Troubleshooting | 04-deployment、03-access-and-accounts | 需要 hosting / DNS / rollback 權限 |
Next.js export 靜態輸出路徑壞掉 / 資產 404 / 破圖 | 先分清是 basePath、assetPrefix 還是 build 後補寫沒生效 | repo README 的 Deployment / Troubleshooting | 04 靜態輸出部署注意事項、05-environment-variables | 需要調整部署路徑、重新打包，或缺 hosting / rollback 權限 |
| reload 後沿用舊 scroll 位置，動畫或鎖滾動狀態錯亂 | 先確認是否有 GSAP ScrollTrigger、首屏動畫、pin / scrub 或 scroll-control logic | repo README 的 animation / scroll 說明 | 09 scroll restoration 初始化防護 | 需要改 _document、調整初始化順序，或無法確認正式站 reload 行為 |
| Figma 字重與瀏覽器顯示不一致 / macOS 字偏粗 | 先確認字型名稱、字型版本、實際載入字重與驗收平台 | repo README 的 styles / fonts 說明 | 09 Figma 字重與瀏覽器顯示差異 | 字型檔版本不明、品牌頁高敏感版位無法驗收，或需設計師重新定義驗收平台 |
| 內容已更新但前台沒變 | 先確認 CMS 是否真的已發布，再判斷是 cache、revalidate 還是部署問題 | repo README 的 CMS / cache 說明 | 07-cms-content-operations、04-deployment、策略文件 | 需要 CMS owner 或 hosting owner |
| Build / deploy 失敗 | 先看 build log、最近變更、是否缺 env | repo README 的 Build / Deploy | 04-deployment、05-environment-variables | 缺 secret、缺 rollback approver、平台入口不明 |
| 表單 / API / 第三方整合失敗 | 先分清是哪個整合、哪個 endpoint、哪個 callback | repo README 的 Integrations / Troubleshooting | 08-integrations-and-api、05-environment-variables | 需要第三方 owner、callback 管理權或 token 重發 |
| 無法登入 CMS / 平台 | 先確認是哪個平台與缺哪種驗證 | repo README 的 Admin / Entry | 03-access-and-accounts | 需要 owner、2FA holder、billing owner |
升級原則
- 可以自己處理：
- repo README 已有明確路徑
- 不需要額外平台權限
- 不涉及高風險 rollback
- 應升級給主管或 owner：
- 不確定是否影響正式營運
- 牽涉帳號、2FA、billing、callback、whitelist
- owner 不明，或你無法確認變更風險