❯❯ feature-to-flow：business invariant 與 UX 無關的 flow 層

📍 流水線位置｜入口 → 【flow】 → 型別 → mock → 測試 → UI → vibe → 上線

進入流水線後的第一個步驟，並非急著撰寫元件程式碼或繪製 UI 介面，而是先對規格進行解構與萃取。

在導入 AI 輔助前端開發時，最常遇到的瓶頸莫過於：請 AI 調整按鈕樣式或進行元件重構時，模型往往在修改視覺層的同時，不小心「順手」改掉了 API 請求的 Payload 欄位結構或是刪除了特定業務邏輯的預設值。

這種現象是源於元件檔中通常混雜了視覺呈現、DOM 結構與業務邏輯。當 AI 模型接收到調整 UI 的指令時，容易將整個元件都當成可以任意覆寫的範疇，最終導致業務邏輯隨著視覺重構一起被抹除。

為了解耦視覺呈現與業務邏輯，本流水線在規格層與實作層之間引入了 Flow 層 （spec/e2e-flows/）。它的核心使命，就是精確劃清「不隨 UI 變更而破壞的業務條件」與「允許自由調整的視覺範疇」。

萃取核心：業務不變量（Business Invariants）

具體來說，Flow 層會從規格中拆解出系統的 「業務不變量（Business Invariants）」 ，指的是不論 UI 介面如何變換，系統都必須死守的硬性約束。這些約束主要體現在三個維度：

1. 實體識別性：
業務實體必須能被精確識別。
例如：賓客實體呈現為「陳大明」，而非抽象代號 guest-001。

2. 狀態語意保留：
業務狀態的文本語意絕不可遺失。
例如：「男方」、「葷食」等關鍵標籤必須可被讀取，不能被簡化成無標籤、純靠顏色識別的視覺圓點。

3. 操作路徑可達性：
關鍵業務功能必須具備對應的操作途徑。
例如：「取消座位」不論被實作為獨立按鈕、右鍵選單，還是拖曳互動，這些功能本身都必須保持可被執行。

這些範疇嚴格地只定義系統「應具備何種業務行為（What）」，從而將「視覺介面該如何呈現（How）」完全釋放出來，交給前端自由發揮。

Flow 文件（flow.md）的結構解剖

透過 /feature-to-flow 這支 Skill，系統能自動讀取原始 .feature 規格，並生成標準化的 flow.md 文件。以婚禮專案為例，目前已收錄了 19 份 Flow 文件（00–18）。每份文件均遵循標準化結構：

06-cakebox.flow.md
├── 對應規格               #標註來源 .feature 檔與對應頁面（確保溯源性）
├── Background            #定義前置狀態與情境
├── Business Invariants   #定義合約核心之不變量清單
├── Flow: 各場景
│   ├── 業務脈絡           #描述該場景之業務背景
│   ├── E2E 驗證流程       #採用抽象動詞（如「觸發」、「填寫」）描述操作，解耦具體 UI
│   ├── Verification策略  #結合 API Spy 與 UI 語意斷言
│   └── 不再凍結           #明確列出該場景下不受合約保護之視覺與介面範疇
└── Mock 假設             #定義 Seed 資料與 API 端點之狀態碼約定

這些 Flow 文件的核心設計，在於建立一套標準化的架構規範：
1. 情境奠基：
由最上游的「對應規格」與「Background 前置情境」拉出基礎。

2. 核心防守：
透過 Business Invariants 釘死領域不變量，並以 API Spy 與 UI 語意斷言確保資料精確。

3. 語意解耦：
在 Flow 內一律使用「觸發」、「填寫」等高階抽象動詞，嚴格避開具體的 DOM 選取器。

4. 邊界與約定：
明確劃分出「不再凍結」的視覺範疇，並於尾聲補齊「Mock 假設」的 API 合約。

傳統 E2E 測試之所以維護成本高昂，痛點就在於測試邏輯與 UI 結構強耦合。當測試寫死如 page.locator('.blue-button-class').click() 時，只要介面樣式稍作調整或 Class 重新命名，測試便瞬間崩潰。這種極度脆弱的護欄，往往是工程團隊在 UI 重構時乾脆直接關閉測試的罪魁禍首。

規格萃取實務：以 AddCakeBoxType 為例

以 Day 05 提到的 AddCakeBoxType.feature 為例，規格定義了管理員送出 AddCakeBoxType 命令後，系統應發出 CakeBoxTypeAdded 事件。在領域模型中，此抽象描述相當嚴謹。

然而，在前端執行環境中，瀏覽器卻無法直接觀測或斷言領域層的抽象事件。DevTools 可以監控網路請求與 DOM 結構，但無法直接捕捉領域層的事件觸發。

因此，Flow 層的靈魂在於語意轉譯：把抽象的領域事件，轉化為自動化測試可斷言的客觀步驟。拿喜餅模組（06-cakebox.flow.md）來說，對應的 E2E 驗證流程拆解如下：

### E2E 驗證流程
說明：從進入頁面、觸發「新增喜餅款式」，到填寫表單細節與提交，全程使用解耦具體 UI 的抽象描述。
1. 進入 /weddings/wedding-001/cake-box
2. 觸發「新增喜餅款式」
3. 填寫：名稱 → 經典禮盒、設為預設 → 是（isDefault）
4. 提交

### Verification 策略
說明：同時從兩個維度雙管齊下——透過 API Spy 斷言 POST 請求被正確發送且 Payload 符合強型別合約；同時透過 UI 語意 斷言畫面列表中確實渲染出包含「經典禮盒」文本的實體節點。
- API spy：POST .../cake-box-types，payload 含 name / description / isDefault
- UI：列表新增可識別的「經典禮盒」實體

### 不再凍結
說明：明確放開表單元件型態（無論是 Checkbox、Switch 還是 Radio）與表單整體視覺呈現的修改自由。
- 是否預設的元件（checkbox / switch / radio）、表單呈現

在此過程中，抽象事件被轉化為兩項客觀驗證指標：
1. API Spy： 斷言 HTTP POST 請求被正確發送，且 Payload 符合強型別合約。
2. UI 實體： 斷言畫面列表中確實渲染出包含「經典禮盒」文本的實體節點。

透過這樣的語意轉譯，領域事件能好好留在業務邏輯層，而前端合約則緊扣可觀測的介面與網路證據。這確保了我們的測試護欄始終鎖定在真正的業務行為，而非脆弱的介面實現。

場景約定：「不再凍結」範疇

在各 Flow 場景末尾，我們都會加入「不再凍結」這段關鍵聲明，明確界定哪些介面細節不納入自動化測試與合約保護。例如在喜餅模組中，我們聲明「設為預設」不論採用 Switch 還是 Radio 元件皆可；而在座位模組（04-seating.flow.md）中，我們同樣給予了介面設計自由：：

### 不再凍結
- 位置設定方式（拖放畫布 / 數字輸入）
- 桌次呈現（畫布節點 / 列表列 / 卡片）

這項約定完美劃清了「系統防護網（不可破壞的不變量）」與「設計沙盒（可自由重構的 UI）」之間的界線。當我們後續將 UI 重構或樣式調整交付給 AI 執行時，AI 便獲得了明確且安全的修改權限；一旦它的重構過程不小心侵犯了業務不變量，自動化測試護欄就能第一時間精確觸發警報。

設計價值

導入 Flow 層在專案初期看似多了一道文件建置的工序，但它的真正價值，會在系統進行大規模 UI 重構或大版本迭代時爆發出來。

由於後續撰寫的 E2E 測試完全依循業務不變量而非 CSS 選取器撰寫，當團隊未來想翻新 UI 樣式、替換 CSS 框架，或是大規模重構 DOM 結構時，只要業務邏輯與 API 合約未受破壞，自動化測試套件就能保持綠燈無痛通過。反之，若重構時不小心漏掉了關鍵的業務欄位，測試失敗也能精準指明是哪一條業務不變量遭到了破壞，徹底告別過去令人疲憊的假警報。

我認為標準的規格定義本來就應該專注於限制「何種業務條件不可變更」，而非硬性約束「介面外觀該長怎樣」。適當的解耦才能確保系統在介面微調與架構演進時不需要支付高昂的測試重寫成本。

下一篇我將透過婚禮系統中複雜度最高的「座位（Seating）」模組，完整展示 Flow 文件的實務推導與套用流程。

🎒 最小一步｜挑選當前專案中的一項功能，於紙上列出三項「無論 UI 介面如何改版均不可破壞的業務條件」：此即為該功能的業務不變量。
📎 本篇證據｜spec/e2e-flows/（19 份 flow.md）・06-cakebox.flow.md（包含規格轉譯對照與「不再凍結」段落）