❯❯ 從人工記憶到機器驅動：route-map.yaml 的 Drift 防衛機制

📍 流水線位置｜入口 → flow → 型別 → mock → 測試 → UI → vibe → 上線（今日：flow 與程式碼之間的對照層）

當專案規模還小時，「哪條路由對應哪份規格」這種問題，單靠腦袋就能輕鬆回答。但當專案規模擴展、業務模組增加後，人工閱覽便再也無法確保規格與程式碼實作是否隨時保持一致；模組一多，這件事就變成了工程師的幻覺：「我以為我還記得😱。」

「這支端點是從哪份 flow 生出來的？」「規格改了這一條，程式碼有幾個地方要跟著動？」這些問題雖然硬翻檔案都查得到，但每次都要浪費好幾分鐘。更致命的是，就算記錯了、查漏了，系統也不會發出任何警報，規格和程式碼就這樣安靜地分岔下去，無形中增加系統維護與架構追溯的成本。

這正是為什麼流水線需要這一層防護：

把路由與規格的對應關係寫成實體對照檔，直接交給機器來對帳。

route-map.yaml：路由與規格的對帳單

這份對照表放在 spec/report/route-map.yaml，由 /feature-to-api 的第一階段（Phase 0）解析生成，記錄專案裡所有前端路由、API 端點與原始規格之間的對應關係。

它的檔頭定義如下：

# 由 /feature-to-api Phase 0 自動產生
# ⚠️ 可手動修改，修改後以此為準

generated_at: 2026-06-20

第二行註解可以思考一下：「可手動修改，修改後以此為準」。這直接劃清了檔案的權限天花板：腳本雖然負責初始化產生它，但只要人類手動微調過，人的版本就是最終真理（SSoT）。後續所有的自動化流水線一律以檔案的最終狀態為準，完全不在意那個狀態是機器產生的、還是人類改出來的。

檔案裡也留下了當初的架構決策脈絡：

# - 來源：spec/e2e-flows/*.flow.md 一致使用 /api/v1
# - 無 api-spec.yml、無既有 server/api/ → 採 flow 文件約定
path_prefix: /api/v1

這段註解記的是 Day 05 提到的開局背景：專案啟動時，既沒有後端交付的 api-spec.yml，也沒有現成的 server 端點可循，因此 API 前綴就照 flow 文件的約定統一走 /api/v1。

漂移偵測：用 content_hash 為規格建立「對帳機制」

route-map.yaml 可不只是給人類查閱的靜態目錄，它更是後面整條工具鏈的解析基準：從型別自動生成、Mock Server 設定，到自動化測試套件的腳本，全都要仰賴它提供真實資料。

在這份對照表裡，每筆路由與 feature 的對應都帶一個 content_hash 校驗碼。只要規格有任何變動，腳本在 Phase 0 重算 Hash 時就會立刻發現「對帳不符」，自動啟動兩道防線：

1. 攤開差異與影響判定：
精確標示出哪些 feature 檔動過。不過，Hash 只負責回答「你有沒有動」；至於動的幅度是否大到需要修改程式碼，則交由下一關判定。

腳本隨後會跑一份機械式的檢查清單：端點路徑改了嗎？出現全新的 Command 嗎？欄位增減超過兩個嗎？新增的 Scenario 是新功能，還是新增欄位的驗證？再依據檢查結果，精確判斷這支 feature 該走「局部修補」還是「整段重生」。即便只是純措辭或數值的微調，雖然同樣會觸發 Hash 變動，但判定機制能確保它只走最輕量的局部修修補補。

2. 主動攔截與人工介入：
一旦碰到高風險的敏感變動（例如 API 路徑前綴發生漂移），腳本會立刻硬性中斷，主動提示開發者介入定案，絕不擅自作主繼續往下改。

這層機制的設計，防的就是規格與程式碼之間的「隱性分岔（Drift）」。它從不寄望於開發者的自律與警覺性，而是直接把「對帳與審查」鎖進每一次自動化的生成流程中。

（至於後端規格更新後的增量差異追蹤與 Sync 模式，則是另一個精彩的故事，留到 Day 13 再聊。）

為什麼不寫一份「架構說明文件」就好？

傳統工程最常見的做法，就是寫一份 Wiki 或 Markdown 掛在專案裡。但這類文件最大的命門在於：沒有任何機制強制它保持更新。經歷幾輪產品迭代後，文件寫的與程式碼做的漸行漸遠，隨著時間過去，根本沒人知道這兩者之間到底已經隱形漂移了多遠。

route-map.yaml 與傳統文件最根本的差別，在於它是自動化工具鏈的必經輸入。
每次系統構建時，機器都會強制解析這份檔案並校驗 hash；一旦資料對不上，就必須執行一輪完整的變更程度判定，並將判定依據白紙黑字寫進變更報告。只有天天被機器即時讀取與校驗的文件，才有資格說自己隨時保持最新。

當需要修改規格時，再也不用憑記憶去全域搜尋哪些程式碼會受影響。對應關係全都明明白白攤在 YAML 檔裡，且每一次構建都在為你默默驗證一致性。即便未來系統遇到了潛在的隱性漂移，開發者也永遠擁有一份單一真理來源（Single Source of Truth）。

回頭看看你的專案：「這條路由對應哪些業務需求」的知識，現在是妥善地寫在機制裡，還是依然只藏在某個人的腦袋裡？

規格層的對帳到這裡告一段落。明天開始，讓我們正式進入「型別先行」的階段：先立好合約，再來蓋房子！

🎒 最小一步｜建立一份 YAML 格式對照檔，列出當前專案中三個核心路由所對應的需求文件；若發現有無法精確對應的路由，該處就是你的專案中已經發生「規格漂移（Drift）」的警戒節點。
📎 本篇證據｜spec/report/route-map.yaml（包含檔頭標示與 path_prefix 決策紀錄之實體內容）