❯❯ Sync 模式：後端 spec 變更的增量同步，只動該動的

📍 流水線位置｜入口 → flow → 【型別】 → mock → 測試 → UI → vibe → 上線（規格更新的回路）

全新開工的專案當然好寫，麻煩的是活得夠久的專案：後端調了欄位定義、改了端點規格，一則修改的訊息過來，前端就得跟著動。

最省事的做法是全量重新生成（Full Regeneration）：
新規格進來，整套重跑一次。但這會把前端先前手工調過的細節微調、防禦性邏輯與邊界條件全部蓋掉，等於拿新規格換掉一批舊心血，之後還得自己一個一個補回來。為了不付這個代價，流水線設計了第二種運轉模式：Sync 模式。

自己改規格是一回事，別人改是另一回事

在討論 Sync 模式前，必須先區分兩種開發情境。

如果是獨立開發，規格變更純粹是我自己的內部決策，直接走 Day 08 講過的規格解凍與正式覆寫流程就夠了（婚禮專案就是這樣，至今沒有導入 Sync 模式的需求）。

但跨團隊協作就不一樣了。以後端獨立運作的公司專案為例，後端團隊有自己的交付週期，spec/api/ 目錄下放的是對方交付的介面合約。當外部規格一更迭，前端就得增量同步，而且不能把自己寫好的商業邏輯弄壞。

跨團隊的規格變更是外部影響因子，我們無法預測它何時降臨。為了把風險壓到最低，關鍵在於資訊必須絕對透通，所以在自動化腳本動手改程式碼之前，先把受影響的範圍毫無保留地攤開來。

為此，Sync 模式導入了兩階段審查機制：異動發生時，先生成 sync-report.md 變更報告，人工確認後才執行程式碼異動，最後用 Git Diff 做最終驗證。

先給我看報告，才准動手

後端交付新版 api-spec.yml 之後，執行 /feature-to-api 的 Sync 模式。它不做全量覆寫，而是分兩拍：

1. 第一階段（變更偵測與報告生成）：
   腳本會先解析新舊規格檔的差異，將受影響的端點、型別與 Mock 資料整理成變更報告，寫入 spec/report/sync-report.md。這一階段只更新報告檔案，不動程式碼。值得一提的是，報告中會特別拉出一份「孤兒項清單（Orphaned List）」，把那些「規格已經刪除，但程式碼還殘留」的項目獨立標記出來。這些項目會交給開發者研判處置方式，而不是由機器擅自抹掉。

2. 第二階段（人工審查與補強套用）：
   當我們確認過變更報告、排除了非預期的修改後，才會二次發起執行指令。此時工具腳本才會真正動手修補受影響的範圍：更新 TypeScript 型別、同步 Mock 資料、補上新增端點，同時更新 Day 09 提過的 route-map.yaml 裡的 Hash 狀態。

這套機制已經在實務專案跑過一輪：後端規格一動，它偵測到變動、先把報告丟到我面前，我檢視完再發第二次指令，讓它做範圍內的增量修復。套用完之後，用 Git Diff 驗一次邊界。假設後端這次動了三個欄位，diffstat 應該長這樣：

（示意）後端異動三個欄位， Sync 模式修復後之 diffstat
 spec/api/api-spec.yml           | 6 ++--   ← 後端交付之新版規格（輸入）
 app/types/api/players.ts        | 3 ++-   ← 型別定義同步更新
 server/mock/data/players.ts     | 2 +-    ← Mock 資料結構補齊欄位
 spec/report/sync-report.md      | 12 ++++  ← 變更範疇與原因記錄
 （其餘兩百餘個模組檔案）          |         ← 未受波及，保持原狀態

變更範圍應該精確限縮在受影響的檔案上。如果 diffstat 出現非預期的擴散（明明只改三個欄位，卻波及幾十個無關檔案），那就是警訊，這時候就需要先停下來分析，不要繼續往下走。

/feature-to-api 的增量同步做完之後，接力棒交給測試套件（/test e2e）與 UI 生成腳本（/feature-to-ui），修訂對應的 E2E 測試案例與介面元件，直到測試全數綠燈。沒被影響到的模組，完全維持原狀。

有個問題值得先回答：後端改規格、連 E2E 測試都跟著改，這不是違反凍結嗎？並不是。後端交付新規格，代表這份介面合約已經完成正式的覆寫拍板，只是拍板的人坐在對面。前端的 Sync 流程不是要阻止合約演進，而是把演進的影響範圍精確攤開，作為後續 UI 調整的依據。

全量重生比較好寫，但我不敢用

坦白說，站在工具開發的角度，「全量重新生成」反而最簡單：收進新規格、一口氣重產所有程式碼，邏輯既直白又乾淨。但 Sync 模式之所以難寫，就在於工具必須先分辨「哪些是機器生成的基底」與「哪些是人後來補上的業務邏輯」，然後只動前者。

多付這個實作成本，買到的是專案演進過程中累積的人工成果不被清洗。那些因應特定場景的樣式微調、鬼譎的邊界案例（Edge Cases），以及防禦性的業務邏輯，通通都是團隊踩坑換來的寶貴經驗，絕不能因為一次「一鍵重生」就全數化為烏有。

自動化工具鏈本來就該隨專案生命週期靈活調整。專案初期我們追求建置速度，到了迭代期，就要死守架構穩定性。

將 Sync 模式搭配 Day 08 的規格解凍機制，規格層的演進就有了明確且可控的工程路徑。聊完了規格與介面合約層，明天開始，我們將正式跨入整套自動化流水線的最核心戰場：測試驅動與驗證。

🎒 最小一步｜ 拿你專案裡最近一次後端 API 規格異動，動手改 code 之前先人工列出受影響的端點、型別與前端元件清單，這就是你的第一份 sync report。
📎 本篇證據｜ skill .claude/skills/feature-to-api/references/phase-0-sync.md（兩階段流程：步驟 8 產出變更報告、步驟 10 人工確認後才寫入）、spec/report/route-map.yaml。