本章目標與前置條件
在不啟動服務的情況下找到功能的 owner、契約、實作與測試。前置條件是可讀取前後端 checkout，並先確認目前分支、工作區變更與各自 AGENTS.md。
後端目錄的責任
| 目錄 | 用途 | 閱讀問題 |
|---|---|---|
cmd/ | 程式執行入口與生成工具 | API、worker 或工具由哪裡組裝？ |
api/openapi.yaml | 對外契約；沒有機器可讀的權限欄位 | 必填、可空與錯誤形狀是什麼？ |
internal/api/v1/ | Gin transport 與路由宣告（register*Routes） | 是 AuthOnly 還是具名權限？ |
internal/service/ | 依業務域分包的服務 | 狀態、交易、冪等在哪裡判斷？ |
internal/domain/ | 領域資料與詞彙 | 枚舉有沒有第二套定義？ |
internal/repository/ | 持久化契約與實作邊界 | 哪些查詢依賴租戶上下文？ |
internal/platform/ | 外部依賴 adapter | 供應商語意是否只留在邊界？ |
internal/authz/、internal/route/ | 授權判定與路由政策；全量路由快照在 internal/route/testdata/registry.golden | 拒絕理由如何回應？ |
internal/errs/、api/error-codes.md | 錯誤碼 registry 與生成的錯誤碼表 | 錯誤對應哪個 code 與 HTTP status？ |
internal/outbox/、internal/jobs/、internal/worker/ | 非同步投遞、工作與執行 | 何時重試、怎樣去重？ |
internal/wiring/、internal/startup/、internal/config/ | 組裝與啟動設定 | 哪個 flag 決定啟用？ |
db/migrations/、db/queries/ | goose 與 sqlc 來源 | schema 與查詢是否同批維護？ |
tests/ | 契約、整合及 E2E；另有 tests/unit/（表單實例單測）、tests/evaluation/（知識庫評測資產）、tests/apifox/（Apifox 場景）。多數單元測試與程式碼同目錄 | 這個測試實際證明哪一層？ |
deploy/ | dev-local 依賴 stack、Keycloak realm 與測試站部署腳本 | 本機要起哪一套 stack？ |
前端目錄的責任
app/ 使用 App Router 與 route groups（(auth)、(platform)、(public)），app/api/ 是前端自己的 BFF Route Handlers（auth、geo、healthz、readyz）。features/ 放各業務功能與各自的 api.ts，components/ 承載共用 UI，hooks/ 與 libs/ 提供 API、權限與導覽支援；store/ 只放 Jotai client state，test/ 放 MSW handlers 與 test/fixtures/routeRegistry.json 等契約 fixture。不要另起一個全站巨型 API 檔把 feature hooks 全搬進去。
真實頁面與 catch-all 的差異見功能全景。表單、考勤、人資的 schema、hook 與測試應沿 feature 目錄一起閱讀，不只看 page.tsx。
操作步驟：追蹤一次草稿預覽
- 從
api/openapi.yaml找workflow/preview，讀請求與回應。 - 在
internal/api/v1/form_runtime.go的registerFormRuntimeRoutes確認路由、權限、身分及輸入驗證：這條路由宣告為route.Point("workflow.run", "read")，綁 pageworkflow.form與formInstanceId，請求 body 是封閉的空物件。權限以這裡的宣告與internal/route/testdata/registry.golden為準，OpenAPI 只在部分 description 以文字提及。 - 進入
internal/service/form/instance/preview.go，核對狀態限制及解析結果。 - 回到
features/forms/api.ts，看 SWR key、revision 與 schema 邊界。 - 閱讀這條路徑的測試：handler 測試
internal/api/v1/form_workflow_preview_test.go、服務單測tests/unit/forminstance/preview_test.go、PostgreSQL 整合測試tests/integration/postgres/form_preview_test.go，以及前端features/forms/workflow-preview.contract.test.tsx；建立成功、拒絕、舊資料與錯誤矩陣。
以下命令是唯讀搜尋；在後端根目錄執行，不會產生 API 呼叫：
rg -n 'workflow/preview|PreviewWorkflow' api/openapi.yaml internal/api/v1 internal/service/form tests預期結果與驗證
能列出一條具體請求的五個邊界：契約、HTTP adapter、service、repository、前端資料轉換；並指出錯誤會在哪層被分類。若找不到任一層，先判斷是共用 helper、純運算或未實作，不自行補猜路徑。
變更程式碼前檢查既有測試是否走到該路徑，尤其拒絕案例全綠也不代表 happy path 正確。
常見錯誤
- 只靠檔名推斷實作：要讀呼叫與 return 分支。
- 把 adapter 的欄位直接洩漏進領域：轉換留在邊界。
- 因為功能跨模組就在同一 transaction 同步操作所有域：先讀 outbox 與編排規範。
- 在有未提交變更的目錄直接覆寫整個檔案：先讀 diff，僅修改自己負責的區段。