如何使用本章
目標是辨別工具鏈、process、依賴、登入、資料與契約問題。前置條件是知道目前工作目錄、使用的版本及操作的環境；沒有這些資料時，先記錄，不急著重啟或清除快取。
基本步驟： 記錄重現操作 → 確認程序與版本 → 檢查對應層 → 以相同條件重測。只有重現條件一致，前後結果才有比較價值。
為什麼 healthz 正常，功能仍不可用？
/healthz 只回報程序存活；/readyz 才執行 readiness checks。非 critical 的 check 失敗時 /readyz 仍回 200，只把該項標為 degraded；就緒成功也不保證帳號角色、租戶資料或每個外部系統都正確。
- 確認實際 API 位址與程序版本。
- 檢查
/readyz的 HTTP status 與 checks。 - 使用已授權帳號重現實際業務操作。
驗證結果應分開記錄： 存活、就緒、特定端點成功，不用一個「正常」概括全部。
Compose 提示需要原本的密碼
觸發條件是根 .env 缺少或清空 COMPOSE_POSTGRES_ADMIN_PASSWORD，而 Compose 專案 nexus-pro-be-plus 的 new-nexus-pro-data volume 已存在：已有資料，但本機設定不足以安全沿用它。compose-env 會在修改 .env 前停止，這是保護機制，不是應繞過的障礙。
預期的恢復結果是原有資料仍在、正確角色可以連線，再驗證 API 就緒。未做到這些，不宣稱恢復完成。
另一種相近症狀是 password authentication failed：根 .env 的 COMPOSE_* 是 compose-env 為根目錄 Compose stack 產生的，與日常開發 stack 的 deploy/dev-local/.env 是兩組不同的秘密值，混用就會認證失敗。先確認正在使用哪一套 stack，不要互相覆寫。
前端只有登入頁，或 API 回 401
先確認本次使用真實登入還是 dev:mock。dev:mock 不會自動登入：先開啟 /api/auth/dev-login 寫入假會話，否則 proxy.ts 仍會導向 /login。MSW 沒有 handler 的 /v1/** 會照常經 proxy.ts 送出，若設定了後端位址，假 token 得到 401 是正確行為。
真實模式需要有效的 session、相符的 Keycloak 設定及租戶上下文。proxy.ts 只檢查 cookie 是否存在；沒有 token 時照樣轉發 /v1/**，由後端回 401（10100）。若 /v1/** 回 503、code 10500，且訊息指出後端位址未設定，是前端缺少 NEXUS_API_BASE_URL，不是登入問題。使用 dev-local 時，Keycloak issuer 固定為 http://127.0.0.1:38081；改了 Keycloak 埠卻沒同步 KC_HOSTNAME 與根 .env 的 KEYCLOAK_BASE_URL，或 KEYCLOAK_PUBLIC_BASE_URL 與 KEYCLOAK_BASE_URL 不一致，都會得到 401，細節見後端 deploy/dev-local/README.md。登入轉址本身代表頁面驗收被擋住，不代表目標功能不存在。
不要硬編碼 token 或繞過 PageGate 來讓截圖成功。經授權恢復登入後，重新執行原本操作，核對 API status、response 與畫面資料。
已修改程式，為什麼還是舊行為？
依序核對：listener 所屬目錄 → branch／commit 與工作區 diff → 執行的 binary／image → 是否重新 build → 實際命中的環境。
不要先假設是瀏覽器快取，也不要直接殺掉佔用 port 的程序。若是文件站，確認讀取的是 127.0.0.1:3210，而非業務前端的服務。
預覽為什麼顯示填寫後決定？
草稿預覽只使用已保存值。條件所需欄位尚未保存時，該關卡回 undetermined、整體 complete: false，並附 condition_undetermined warning；這是合法結果，不是把空值判成條件不成立（skipped／condition_false）。條件所指的員工找不到，或該員工沒有職等資料時，也會以 undetermined 結束，warning 分別是 workflow_subject_employee_not_found、workflow_applicant_level_missing。
先保存必要欄位，觀察 revision 是否前進，再核對新預覽的 revision。若回應仍落後，前端只重取一次，仍落後就回報錯誤。詳見實戰教學。
Apifox 全綠就能交付嗎？
不能只看 CLI success。先確認命中的環境、場景集合與斷言數；斷言數為零不是有效驗證。
平常以 make apifox-isolated 執行：它需要 Docker 與已登入的 Apifox CLI，會建立隔離的 Compose stack、準備已知 fixture、建立暫時的 Apifox 環境，結束後只清理自己建立的 stack 與環境，並清除繼承的 NEXUS_DEV_PASSWORD 等共用覆寫。手動 make apifox-test 需要 APIFOX_RUNTIME_VARS（場景 fixture 變數）與指向同一套 stack 的 APIFOX_ENV（預設 48657657）；缺少 fixture 變數時會在送出任何請求前以 exit 2 結束，這是設定不足，不代表被測系統有 bug。
make ci-local 與 make apifox-test 各有不同責任。文件站建置、前端 fixture 測試以及本地聚焦測試，都不能冒充這兩道業務交付門。
文件與實作不同，以哪個為準？
以目前程式碼及已凍結契約核實行為，文件作為索引。記錄檔案路徑、工作區或 commit 與差異，再修正文稿。不能因為指南寫「規劃中」就忽略已經存在的實作，也不能因為架構圖畫了它就宣稱已上線。
新增文件要改頁面元件嗎？
不需要。在本站 content/docs/ 新增 MDX，填寫 metadata；category 使用既有七類 ID，order 決定導航與前後篇順序。以下是 metadata 示例，不是已發布文章：
title: 新的開發手冊
description: 說明這一章能解決的問題。
category: backend
order: 100
reviewed: 'YYYY-MM-DD'
sources: []
related: ['/backend']reviewed 必須填實際內容核對日期；不把檔案複製時間當作來源更新時間。補上正文後執行 typecheck、內容測試與 build，確認路由、分類和全文搜尋都有收錄。新文章不需要改 React 頁面。