操作盤點的覆蓋範圍

BDD 操作盤點通常包含：

• 使用者操作（When）：「使用者點擊連線按鈕」
• 前端引導（Then）：「顯示連線進度指示」
• 後端回應：「WebSocket 連線建立」

「前端引導」描述的是畫面的顯示內容 — 對應狀態矩陣的「顯示」欄。但操作盤點通常不會展開：連線中的畫面除了顯示進度指示，使用者能做什麼？如果連線失敗，使用者怎麼離開失敗畫面？

app_tunnel 的操作盤點在「前端引導」欄寫了「連線失敗顯示無法連線」，覆蓋了 error 狀態的顯示。但是「顯示無法連線之後使用者能做什麼」和「使用者怎麼離開這個畫面」都沒有描述。實作出來的 error 狀態有重連按鈕但沒有 back 按鈕 — 重連失敗時使用者被困在 error → retry → error 循環裡（U.C1）。

展開步驟

步驟一：從操作盤點抽出所有畫面

每個 BDD 情境至少涉及一個畫面。列出所有情境提到的畫面名稱，去重後得到畫面清單。

例：app_tunnel 的操作盤點涉及三個畫面 — 首頁、配對畫面、終端機畫面。

步驟二：每個畫面列出狀態

從操作盤點的 Given / When / Then 條件中抽出狀態。「Given 連線已建立」暗示有 connected 狀態；「Then 顯示無法連線」暗示有 error 狀態。

同時檢查程式碼中的狀態 enum — 操作盤點可能遺漏了某些狀態（如 idle、disconnected），程式碼裡有但操作盤點沒提到的狀態同樣需要設計 UI。

步驟三：每個狀態填「顯示」欄

從操作盤點的「前端引導」直接填入。這一步通常不缺資料，因為操作盤點的強項就是描述顯示內容。

步驟四：每個狀態填「可用操作」和「退出路徑」欄

這一步是關鍵 — 操作盤點通常不提供這些資訊，需要主動補上。

對每個狀態問兩個問題：

• 使用者在這個狀態下想做什麼？（可用操作）
• 使用者怎麼離開這個狀態？（退出路徑）

開發者容易假設 connected 狀態下使用者只想打字，不會想返回首頁。但使用者可能想切換到配對畫面重新配對、想暫時離開做其他事、想結束當前操作。把這些可能性列出來，判斷哪些需要提供操作按鈕。

步驟五：檢查矩陣的空白格

退出路徑欄為空的狀態是 UX 死胡同，需要補上退出路徑。可用操作欄為空的狀態需要判斷是否合理 — loading 狀態操作欄為空可能合理，但建議至少提供取消操作。

操作盤點的「描述顯示」偏差

操作盤點的「前端引導」傾向描述顯示（What the user sees）而非描述互動（What the user can do）。這個偏差的根源在 BDD 的 Then 語法 — Then 通常描述可觀察的結果，而「畫面顯示 X」比「使用者可以做 Y」更容易寫成可觀察的斷言。

app_tunnel 的操作盤點就是這個模式。四個操作情境的「前端引導」都寫了顯示內容（「顯示終端機畫面」「顯示連線中」「顯示無法連線」），沒有一個寫了操作（「使用者可以取消」「使用者可以返回」）或退出路徑（「使用者可以回到首頁」）（U.C1）。

畫面狀態矩陣的四欄結構強制補上這兩個面向。從 BDD 操作盤點到畫面狀態矩陣的展開步驟，就是把「只描述顯示」擴展成「顯示 + 操作 + 退出」的過程。

下一步路由

• 畫面狀態矩陣的完整定義 → 畫面狀態矩陣的定義與填寫方法
• 路由可達性檢查 → 路由可達性檢查
• 想知道什麼是「假設只走 happy path」的反模式 → 反模式：假設使用者只走 happy path

57 個 unit test 全綠，但沒有任何機制能回答「這些測試覆蓋了哪些 UseCase 場景」。

monitor 專案 v0.1.0 從需求文件系統（Proposal → Spec → UseCase）一路走到 Collector 實作，中間經過 BDD 測試設計、紅燈測試撰寫、骨架實作讓綠。流程表面上順暢——10 個根 Ticket 全部完成、Collector 可啟動、所有 unit test 通過。但回頭檢視發現：需求→測試的銜接是單向管道，沒有反向追溯，也沒有邊界回補流程。

本文記錄 v0.1.0 的完整流程、發現的五個結構性差異、和落地的解決方案。

實際走過的流程

1saas 選型訪談
2  → Proposal（MVP 範圍界定）
3    → Spec（14 份，涵蓋 schema/ingestion/query/storage/rule-engine/SDK）
4      → UseCase（5 個，UC-01 端到端事件流 ~ UC-05 Web 監控）
5        → BDD 測試設計 ANA（全專案 26 個行為場景 → 整合/單元/協議測試清單）
6          → 紅燈測試（9 個 Ticket 並行，72 個測試 FAIL）
7            → 骨架實作（1 個 Ticket，57 個 unit test GREEN）

每個箭頭都有對應的框架機制：saas→doc 有 Stage 6 銜接、doc→TDD 有 doc-handoff 映射表。但箭頭只往右——沒有任何箭頭往左。

五個結構性差異

差異 1：「全專案 BDD 設計」不在 TDD Phase 模型中

TDD Skill 定義 Phase 0→1→2→3→4 的逐功能流程。v0.1.0 做的是「全專案 UseCase 一次性展開為 BDD 測試設計」，跨越 Phase 1 和 Phase 2 的邊界，粒度是專案級不是功能級。

這不是 Phase 設計的錯——Phase 模型適合增量開發（每次加一個功能）。新專案起手是不同的工作模式：批量設計、模組群組粒度。

解法：在 doc-handoff 新增「新專案起手模式」章節，描述批量 BDD 設計流程、Phase 0 豁免條件、模組群組粒度。

差異 2：紅燈測試需要存根（stub）

Go 是靜態語言，go test 必須編譯通過才能執行。紅燈測試引用的 type/interface 不存在時直接編譯失敗，不是「測試 FAIL」。

TDD Skill 的 Phase 2 說「設計測試」、Phase 3b 說「讓測試綠」，但中間的「建存根讓測試可紅」沒有定義。

實作驗證：v0.1.0 的每個紅燈 Ticket 都自帶建立存根（空 function return nil / 空 struct / 回 501 的 HTTP handler），存根讓 go test 編譯通過，合法測試 PASS、非法測試 FAIL = 紅燈狀態。

解法：Phase 3 rules 新增「存根策略」章節，涵蓋靜態語言（Go/Dart）和動態語言（Python/JS）的不同處理。

差異 3：測試→UseCase 沒有反向追溯

寫完 57 個 unit test 後，問「UC-01 的替代場景 01a（批次部分失敗 → 207）被哪些測試覆蓋？」——沒有任何機制能回答。

doc test-map UC-01 工具存在但回傳 0 個測試——因為它搜尋 UC frontmatter 的 ticket_refs，和測試檔案沒有連結。Spec 的「三方交叉比對」是建 Ticket 時的一次性動作，不是持續追溯。

解法：建立 docs/traceability.yaml 追溯矩陣，三層追溯（UC 場景 → 整合測試 IT-* → 單元測試 UT-* → Spec FR）。每個 entry 標記 covered / gap / deferred。

差異 4：邊界條件發現後沒有回補 UC 的流程

寫 Ingest Handler 測試時發現：「如果 POST body 不是 JSON 怎麼辦？」「如果 Content-Type 是 text/plain（sendBeacon）怎麼辦？」這些邊界在 UC-01 的場景描述中不存在。

測試設計的 BDD ANA 有涵蓋這些邊界場景，但 UC 文件本身沒有更新。邊界條件「住」在測試設計文件而非 UseCase——下次有人讀 UC 不會知道這些邊界存在。

解法：追溯矩陣增加 boundaries: 區段，測試撰寫者發現新邊界時加 gap entry，PM 建 DOC Ticket 回補 UC/Spec。Phase 4d 掃描所有 gap 確認無遺漏。

差異 5：Ticket 拆分邊界未對齊測試變綠驗收點

Collector 實作被拆為 4 個 Ticket：骨架（interface 定義）/ Storage / Ingestion Handler / Query Handler。骨架 Ticket 指派做「main.go + Config + Storage interface」，代理人完成了所有模組實作——57 個 unit test 從紅全部變綠，其餘 3 個 Ticket 的 acceptance 全被涵蓋。

初看像是「代理人超額完成」，回頭用判讀三問檢查骨架 Ticket：完成後有測試變綠嗎？→ 沒有（只定義 interface）。能獨立跑測試嗎？→ 不能（其他模組引用骨架的 type）。共用 type？→ 是。三問全部指向「不應獨立拆」。根因是 Ticket 拆分設計，不是代理人行為——按 Spec FR 拆（輸入驅動）導致骨架 Ticket 完成後 0 個測試狀態改變，不是有意義的驗收點。

判讀規則：實作 Ticket 的拆分邊界必須對齊「測試從紅變綠」的驗收點。一個 Ticket 完成後若沒有任何測試狀態改變，它不應該是獨立 Ticket。

判讀三問：

1. 這個 Ticket 完成後，有測試從 FAIL 變 PASS 嗎？
2. 拆出的各部分能獨立跑測試嗎？
3. 不同部分共用同一組 type/error/constant 嗎？

反模式：按 Spec FR 拆（輸入驅動）。正確做法：按「哪組測試變綠」拆（輸出驅動）。

追溯矩陣的設計

追溯矩陣是三個問題（向上追溯 + 覆蓋驗證 + 邊界回補）的統一解法。

結構

 1UC-01:
 2  title: 端到端事件流
 3  scenarios:
 4    main:
 5      integration_tests: [IT-01-01]
 6      unit_tests: [UT-COL-01-01, UT-COL-02-01, UT-COL-04-01]
 7      spec_frs: [SPEC-002-FR-01, SPEC-003-FR-01]
 8      status: covered
 9    alt-01a:
10      integration_tests: [IT-01-02]
11      unit_tests: [UT-COL-01-03, UT-COL-02-03]
12      spec_frs: [SPEC-002-FR-02]
13      status: covered
14
15boundaries:
16  batch-limit:
17    discovered_during: "ingestion-handler-red-tests"
18    status: gap  # 需回補 UC/Spec

三個問題的對應

整合點

附帶發現：並行派發的 Git 隔離問題

5 個代理人以 worktree 並行派發時，commit 內容交叉混入——A 代理人的 commit 包含 B 代理人的檔案。根因：主 repo 不在 main 分支，多個 worktree 共用同一分支 ref，git add + commit race condition。

防護：派發前確保主 repo 在 main + 已 push。單一代理人和正確條件下的多代理人都驗證通過。

結論

v0.1.0 的流程不是失敗——Collector 可用、57 個 test GREEN。問題在於「走到終點後沒有辦法回頭驗證起點」。需求→測試的管道是單向的：Proposal 說了什麼、Spec 定了什麼 FR、UC 描述了什麼場景，和最終的測試之間沒有結構化連結。

追溯矩陣不增加任何程式碼——它是一個 YAML 檔案，記錄「每個測試為什麼存在」。維護成本是每次寫測試多填一行映射。回報是：任何時候都能回答「這個 UC 場景有沒有被測試保護」。

方法論要解的問題

這套方法論的核心命題是成本不對稱：設計問題拖到開發中途才浮現，修正的代價遠高於在訪談階段多問十題。沒想清楚的操作、沒切清楚的領域邊界、沒被告知的防護缺口，最後都會在開發中途以重工的形式收費。訪談協議的責任是逼這些設計問題在寫第一行程式之前、於已知需求的範圍內浮現——因此訪談問題的數量刻意不設上限，問漏才是成本；節奏上每輪三到五題讓受訪者好消化，輪數跟著覆蓋率走。

協議同時內建「產品名攔截」：受訪者開口指定產品（「我要用 MongoDB」「直接上 k8s」）時，先回到需求確認背後動機（schema 變動頻繁？團隊熟悉度？），需求成立後產品可以直接採納。產品名是選型的輸出，由需求與領域模型推導出來，而非訪談的輸入。

推導鏈：從定錨到決策記錄

整條推導鏈的設計邏輯是：每一站的產出都是下一站的輸入，技術問題永遠錨在前面站點的具體產物上，避免「對空氣選型」。

1定錨 → 交付形態 gate → 操作盤點（BDD）→ domain / event 切分（DDD）
2    → 核心問題與維度展開（每個維度就地過防護底線）→ 決策記錄 + scaffold

定錨。訪談從建立規模假設開始，定錨問題覆蓋七個面向：

• 產品形態（B2B / B2C / 內部工具）——決定合規壓力與流量不確定性的預設方向
• 動機（營收、學習、解決自己的營運問題）——決策記錄理由欄的錨點，「自建換學習」「託管換速度」的權重都從這裡來
• 租戶模型——多租戶把租戶隔離升級成儲存與安全維度的第一級問題
• 預期規模（首年用戶與資料量級）——決定容量維度是否展開
• 團隊能力（人數、production on-call 經驗）——維運經驗低時預設 managed 服務，每個自管元件都要回答「誰半夜處理它」
• 每週可投入時數——一週十小時跟全職的選型分母不同
• 上線時程與迭代節奏——時程緊時選型偏保守，團隊熟悉度的權重高於技術新穎度

定錨答案是後續每個推薦的合法依據——「因為團隊兩人且無維運經驗，推薦 managed 資料庫」這類理由都要能回指到定錨。

交付形態 gate。定錨之後、進入任何技術討論之前，先誠實回答「這個產品現在值得自建嗎」。需求落在現成平台的標準域時，訪談走縮減流程：完整推導跳過，但仍產出託管縮減記錄——平台選擇與理由、可遷出保險狀態、升級自建的 tripwire、防護底線總表的適用項，託管結論同樣留下可追溯的決策記錄。這一站的判讀邏輯單獨成節，見「交付形態 gate」。

操作盤點（BDD）。自建成立後，枚舉所有操作主體（含管理者、客服、訪客、機器角色）與其全部操作，每個操作寫行為情境——Given / When / Then 至少一條主情境加一條失敗情境。誤操作風險成對設計：前端引導（確認對話框、預設值、防呆）與後端防護（驗證、權限、idempotency）一一對應，從介面一路串到伺服器側。行為情境寫不出來，代表那個操作的需求還沒成形——在盤點階段攔下，比開發中途才發現便宜得多。

Domain / event 切分（DDD）。操作清單沿固定方向轉成領域骨架：operation → command → 唯一歸屬 domain → event。推導從操作出發而非資料表出發——從資料表出發會切出 CRUD 式的偽領域（UserManager、OrderManager），從操作出發才會浮現真正的業務領域與領域間需要交換的事實。切分只用兩個原則：

• SRP：一個 domain 一個變更理由、一個 event 一個事實。判讀問題包括「這兩個概念會因為同一個業務原因一起改嗎」「這個規則改變時誰說了算」——組織的決策邊界是領域邊界最誠實的線索。
• OCP：每個 domain 區分公開面（別的 domain 需要知道的：event schema、查詢介面）與內部面（表結構、狀態機、內部規則）。公開面是 contract、變更要盤點訂閱者；內部面可自由改。判讀問題是「Order domain 的表加一個欄位，要通知誰」——理想答案是「不用通知任何人」。

LSP / ISP / DIP（里氏替換、介面隔離、依賴反轉）三個原則刻意留給實作階段：初始化階段還沒有 class 階層、沒有 interface 簇、沒有依賴注入結構，提前套用會把訪談拖進實作細節，模糊掉「邊界在哪」這個此階段的核心問題。

核心問題與維度展開。領域骨架立好後，依序確認需求類型、流量形狀、資料生命週期、失敗代價、成本模型、定位與備援、安全邊界。每題附答案路由：訊號決定哪些技術維度要展開（快取、非同步佇列、容量），哪些維度任何 production 服務都逃不掉（儲存、部署、安全、觀測、可靠性）。

展開時問題錨在領域骨架上——「Order domain 的不可丟 event 用什麼機制送」，而非抽象的「要不要 queue」。每站也帶反向問，因為受訪者描述的是想要的功能，沒想到的東西藏在失敗面：「使用者做完馬上後悔怎麼辦」「凌晨三點服務掛了誰會知道」。

防護底線。每個維度附一份防護底線清單——底線的定義是「缺了它、第一次事故的代價會遠超過 day one 建立它的成本」的項目，例如 secret 管理、備份加至少一次還原驗證、物件層級授權、部署可回滾。底線跟選型的差別在答案空間：選型問題容許多個合理答案並存，底線項目只有「已納入」「已告知後延後」「不適用」三種合法狀態，每一項的狀態都要寫進決策記錄。延後必須轉成記錄：告知代價、記下延後理由、附具體的重評條件（「上線前」「第一個付費客戶前」），「之後再說」這種無期限的口頭妥協會被協議擋下。目的是讓六個月後接手的人能回答「當初為什麼沒做」，把口頭妥協變成可追溯的決策。底線在訪談中經過兩次——維度展開時就地逐項過，決策記錄的總表再核對一次；雙重核對是刻意設計，防止任何一條在長流程中被沉默跳過。

決策記錄。訪談收斂成一份決策記錄：操作風險表、domain map、event catalog、每項技術選型的理由 / 防護狀態 / tripwire 三欄齊備、防護底線總表、規模成長 tripwire 總表。被淘汰的次選項留名字——淘汰原因消失（例如團隊長出維運能力）就是重評入口。scaffold 建議是決策記錄的下游：先確認決策、再產生檔案，決策改了 scaffold 跟著重生。

交付形態 gate：先勸退不必要的自建

一套為自建選型而生的訪談協議，第一個正式任務是勸退不必要的自建。自建的前提是差異化在軟體本身；差異化在商品、內容或服務品質的業務，託管平台、BaaS、垂直 SaaS 可能是成本上更誠實的起點。跳過這個判斷，等於用整套自建流程回答一個本來就該用現成平台解的需求。交付形態光譜的完整論述（各形態的能力邊界、遷出代價、可遷出保險）見 交付形態選型：託管平台、BaaS 與自建的邊界，訪談協議把它操作化成 gate。

gate 的第一個澄清問是身分問題：這個軟體是要賣的產品，還是經營業務的工具？「給健身教練用的課表系統」有兩種身分——要賣給眾多教練的產品（市場上的垂直 SaaS 是競爭對手，走自建），或教練管理自己學員的工具（同一批垂直 SaaS 正是該優先評估的託管候選）。同一句需求描述，兩種身分的結論相反。

回答「先自用、之後想賣」的雙重身分，用時間判準裁決：付費外部用戶離現在多遠。協議把裁決寫成兩條規則：外部買家已有承諾或近期有交付時程的，按「要賣的產品」走完整訪談，自家使用記為首租戶（dogfooding）；外部用戶還停在想像、目前唯一用戶是自己的，託管先行，平台野心轉成升級自建的 tripwire——協議給的觸發例是第一個付費外部用戶出現，或客製需求超出託管平台 API 的承載範圍。

gate 的收尾原則是尊重知情決定：受訪者聽完託管對照後仍選自建時，訪談照常繼續，勸退只做一次；選自建的動機（練手、控制權、長期成本）原樣記進決策記錄，讓未來重評者能還原當時的權重。

用合成 dry-run 驗證協議

方法論本身也需要驗證。這套協議以一組結構化文件存在——訪談流程、各站的判讀表、決策記錄模板都是 agent 可直接執行的文件，驗證因此可以採用合成 dry-run：讓 agent 同時扮演訪談者與 persona 受訪者，從定錨到決策記錄完整走一遍協議，過程中記錄機械性斷點。斷點分五類：

• 路由斷裂：協議指向的段落不存在，或前後站接不上
• gate 矛盾：兩條判讀規則同時命中且結論相反，協議沒給裁決方式
• 重複提問：同一風險在不同階段被當成新問題重新開放問
• 資訊斷流：前站的產出（操作清單、event catalog）沒被後站引用
• 判準缺席：協議要求做判讀，但沒給可操作的判讀條件

dry-run 收尾時實際試填決策記錄模板，量測每個欄位填得出來的比例——填不出來的欄位就是協議在某一站漏問了。

第一輪驗證跑了兩個 persona：一個雙重身分的健身房管理 SaaS（自用兼想賣），一個 solo 開發者的付費電子報（最該被勸退自建的案例）。合計記錄 13 個斷點，在兩個 persona 覆蓋的路徑上路由斷裂為零——協議的檔案結構與觸發路由都接得起來；決策記錄試填率約 85-90%，缺口集中在交付形態相關欄位：gate 判讀依據寫不出來、混合形態的記錄格式沒有規格、自建動機沒有欄位可放。影響最大的斷點是兩個 persona 從不同方向撞上同一個 gate 矛盾：判讀表兩列規則同時命中且方向相反——健身房的「都是」讓垂直 SaaS 列與自建列並立，付費電子報既符合「託管平台標準域」也符合「產品本身是軟體」——協議當時沒有 tie-breaker，在最該被勸退的案例上這個斷點被評為阻斷級；前文的時間判準正是這次修復補上的。矛盾發生在協議最核心的判斷上，且在真實使用者撞到之前被攔下。兩場 dry-run 最終收斂出 8 項修復回寫協議，包括雙重身分的時間判準、混合形態的決策記錄規格、訪談問句去重、跨 domain 寫入的一致性判讀條件。

合成 dry-run 的邊界也要誠實：它抓得到機械性斷點，抓不到真實受訪者的不耐與理解斷層。agent 扮演的 persona 永遠有耐心答完所有問題、永遠聽得懂術語；真實使用者在第四輪提問時的疲乏、對「event catalog」一詞的困惑，要等真人訪談才會浮現。另一層盲點是同源：persona 由產生協議的同一個模型扮演，回答分布偏向協議作者想像得到的案例，超出這個想像的需求形態，結構上不會出現在合成驗證裡。合成驗證的定位是上線前的結構檢查，取代不了真實使用回饋。

適用邊界與下一步

完整協議的固定成本是數輪訪談加一份決策記錄，值得跑的情境有明確輪廓：

• 產品會進 production，有真實使用者與失敗代價——失敗代價是核心問題階段的主要輸入，沒有它整條推導鏈失去分水嶺
• 團隊規模或交接需求讓「當初為什麼這樣選」值得被記錄——決策記錄的三種讀者（確認結論的現在使用者、回溯理由的未來維護者、等訊號的重評者）至少存在兩種
• 領域邊界有切分價值——操作主體超過一種、跨領域協作存在，domain / event 切分的產出才有承載對象

反過來，快速原型與純內部腳本跑完整協議是過度設計——原型的目的是丟棄式驗證假設，設計決策活不過原型本身；這類情境取協議的最小子集就夠：定錨（確認規模假設）加防護底線裡的 secret 管理一條。另一類邊界是需求不可知：產品會進 production、但要提供哪些操作得靠市場驗證才知道的探索型產品，協議能整理的只有已知部分——它解「已知需求沒想清楚」的成本，解不了「需求本身未知」；這類情境先走薄切片迭代，需求穩定後再回來補完整訪談。

判讀方式可以收成一個問題：這個專案的設計決策，六個月後有人需要回答「當初為什麼這樣選」嗎？需要，完整協議的固定成本就划算；無此需求，取子集。

下一步路由：

• 交付形態光譜與各形態的遷出代價：交付形態選型
• 判定自建後的服務選型順序：後端需求分類地圖
• 不可丟 event 的執行層機制：idempotency 與 outbox pattern 知識卡

這不是測試該有的樣子。問題根源在於測試耦合了實作細節，而非行為。

BDD 的核心定位

BDD 是 TDD 的演進，它要求測試描述系統的「行為」而非「實作」。

行為是使用者視角觀察到的系統反應；實作是程式內部的技術細節。這個區別看起來簡單，實際撰寫測試時卻很容易模糊。

BDD 解決三個問題：

測試維護成本高。傳統單元測試緊密耦合實作細節，重構時即使行為沒變，測試仍需大量修改。BDD 讓重構時測試保持穩定。

需求追溯困難。測試充滿技術細節，無法對應業務需求。Given-When-Then 場景即是需求文件，測試即規格。

溝通成本高。開發、測試和業務人員用不同語言描述系統行為。BDD 統一使用業務語言，建立共通溝通基礎。

我們的分工是：Clean Architecture 定義架構分層，TDD 四階段流程定義開發節奏，BDD 定義測試內容和撰寫規範。

Given-When-Then 結構

Given 描述系統的初始狀態，必須明確完整，只包含與此場景相關的資料。常見錯誤是前置條件模糊，或包含大量無關測試資料。

When 描述使用者執行的操作，必須是單一動作，使用業務語言。「呼叫 Repository 的 save 方法」是技術術語；「使用者提交訂單」是業務語言。一個 When 不能包含多個動作。

Then 描述執行後的狀態變化或結果，必須是可觀察的行為。「Repository 的 save 方法被呼叫一次」是實作細節；「訂單成功儲存並回傳訂單編號」是可觀察的行為。

判斷行為還是實作的方法很簡單：使用者能否觀察到？改變實作會影響這個結果嗎？產品經理需要關心嗎？都是「能觀察、不影響、需要關心」就是行為，反之是實作細節。

行為測試和實作測試的差異

測試實作：

1test('OrderRepository.save should call database.insert', () {
2  repository.save(order);
3  verify(database.insert('orders', order.toJson()));
4});

這個測試關注「如何儲存」，替換資料庫或重構儲存邏輯就會失敗。

測試行為：

 1test('使用者提交訂單 - 訂單成功儲存', () async {
 2  // Given: 使用者已選擇商品並填寫完整資訊
 3  final order = validOrder;
 4
 5  // When: 使用者提交訂單
 6  final result = await submitOrderUseCase.execute(order);
 7
 8  // Then: 系統確認訂單已儲存
 9  expect(result.isSuccess, true);
10  expect(result.orderId, isNotEmpty);
11});

這個測試關注「訂單是否成功儲存」，重構儲存機制不會影響結果。

測試描述的視角同樣重要。從技術元件角度：

1test('當 Repository 回傳 null 時 UseCase 拋出例外', () { ... });

從使用者視角：

1test('使用者提交訂單失敗 - 商品庫存不足', () {
2  // Given: 商品庫存為 0
3  // When: 使用者嘗試提交訂單
4  // Then: 系統回應「庫存不足」錯誤
5});

分層測試策略

BDD 不適用所有架構層級，每層特性不同，測試策略也不同。

UseCase 層是 BDD 的核心應用層，代表完整的使用者操作流程，必須使用 Given-When-Then 結構，涵蓋所有業務場景。

Domain 層包含核心業務規則、值物件驗證和實體不變量，需要細緻的邊界條件測試，單元測試更適合。

Behavior 層負責 ViewModel 轉換和事件處理，只有複雜轉換邏輯需要獨立測試，簡單轉換由 UseCase 層覆蓋即可。

UI 層測試成本高，只測試關鍵互動路徑，使用整合測試。

Interface 層只定義契約，沒有實作邏輯，不需要測試。

Mock 策略

核心原則：只 Mock 外層依賴，不 Mock 內層邏輯。

外層依賴（Repository、Service、Event Publisher）透過 Interface 進行 Mock，隔離外部系統。內層邏輯（Domain Entity、Value Object）必須使用真實物件，確保測試涵蓋真實業務邏輯。

正確寫法：

 1test('使用者提交訂單成功', () async {
 2  // Mock Repository（外層依賴）
 3  final mockRepository = MockOrderRepository();
 4  when(mockRepository.save(any))
 5      .thenAnswer((_) async => SaveResult.success('order-123'));
 6
 7  // 使用真實的 Domain Entity（內層邏輯）
 8  final order = Order(
 9    amount: OrderAmount(100),
10    userId: UserId('user-001'),
11  );
12
13  final useCase = SubmitOrderUseCase(repository: mockRepository);
14  final result = await useCase.execute(order);
15
16  expect(result.isSuccess, true);
17  expect(result.orderId, 'order-123');
18});

錯誤寫法是 Mock Domain Entity：

1test('使用者提交訂單成功', () {
2  final mockOrder = MockOrder();
3  when(mockOrder.validate()).thenReturn(true);
4  // 沒有測試到任何真實業務邏輯
5});

與 TDD 階段整合

階段一（功能設計）：從需求識別使用者行為場景。「使用者可以提交訂單」需要提取多個場景：成功提交、庫存不足失敗、金額無效失敗等，每個場景涵蓋正常流程、異常流程和邊界條件。

階段二（測試設計）：將行為場景轉換為可執行的測試程式碼，先建立結構，設置 Mock，再依 Given-When-Then 填入邏輯。

階段三（實作策略）：測試先行。先完成所有測試場景並確認失敗（Red），才開始實作 UseCase 讓測試通過（Green）。

階段四（重構優化）：重構時，行為測試必須保持穩定。重構導致測試需要修改，代表測試耦合了實作。

判斷重構品質的標準很清楚：替換 Repository 實作、改變演算法，不應讓測試失敗；改變業務規則、調整可觀察的錯誤訊息，才應讓測試失敗。

常見挑戰

測試覆蓋率盲點

BDD 強調測試「重要行為」，可能讓某些程式碼未被覆蓋。混合策略解決這個問題：UseCase 層 100% BDD 測試，Domain 層複雜邏輯 100% 單元測試，整體維持 80% 程式碼覆蓋率目標。

學習曲線

從「測試實作」轉向「測試行為」需要思維轉換，初期容易寫出「假行為測試」（實際上還是在測試實作）。建立範例庫和測試模板很有幫助：

 1test('[業務場景描述] - 成功', () async {
 2  // Given: [前置條件]
 3  final input = [準備測試資料];
 4  [設置 Mock 行為];
 5
 6  // When: [觸發動作]
 7  final result = await useCase.execute(input);
 8
 9  // Then: [預期結果]
10  expect(result.isSuccess, true);
11  expect([驗證業務結果]);
12});

邊界條件容易被忽略

業務場景描述容易遺漏技術性的邊界條件（null、異常、極端值）。每個 UseCase 最少需要：一個正常流程、兩個異常流程、三個邊界條件。建立技術性測試檢查清單並在 Code Review 重點確認。

測試設置複雜度

UseCase 層的 BDD 測試需要 Mock 多個依賴，建立 Test Helper 和 Builder Pattern 減少重複：

 1class UseCaseTestHelper {
 2  static MockOrderRepository createMockRepository({
 3    required SaveResult saveResult,
 4  }) {
 5    final mock = MockOrderRepository();
 6    when(mock.save(any)).thenAnswer((_) async => saveResult);
 7    return mock;
 8  }
 9}
10
11class OrderBuilder {
12  int _amount = 100;
13  String _userId = 'user-001';
14
15  OrderBuilder withAmount(int amount) {
16    _amount = amount;
17    return this;
18  }
19
20  Order build() => Order(
21    amount: OrderAmount(_amount),
22    userId: UserId(_userId),
23  );
24}

行為粒度

粒度太粗，失敗時難以定位；太細則接近單元測試，失去 BDD 優勢。採用「一個 UseCase 等於一個核心行為」的原則：UseCase 代表完整業務流程，名稱以動詞開頭（Submit, Cancel, Query），所有測試場景屬於同一個業務流程。

業務需求變更

需求變更時測試場景仍需更新。集中管理業務規則常數減少影響範圍：

1class OrderBusinessRules {
2  static const int freeShippingThreshold = 1000;
3  static const int maxOrderAmount = 100000;
4  static const int minOrderAmount = 1;
5}

完整範例

以「使用者提交訂單」為例：

  1group('SubmitOrderUseCase', () {
  2  late MockOrderRepository mockRepository;
  3  late MockInventoryService mockInventoryService;
  4  late MockEventPublisher mockEventPublisher;
  5  late SubmitOrderUseCase useCase;
  6
  7  setUp(() {
  8    mockRepository = MockOrderRepository();
  9    mockInventoryService = MockInventoryService();
 10    mockEventPublisher = MockEventPublisher();
 11    useCase = SubmitOrderUseCase(
 12      repository: mockRepository,
 13      inventoryService: mockInventoryService,
 14      eventPublisher: mockEventPublisher,
 15    );
 16  });
 17
 18  group('正常流程', () {
 19    test('使用者提交訂單成功', () async {
 20      // Given: 使用者已選擇商品且填寫完整資訊
 21      final order = Order(
 22        amount: OrderAmount(100),
 23        userId: UserId('user-001'),
 24        items: [OrderItem(productId: 'prod-001', quantity: 2)],
 25        shippingAddress: Address(city: '台北市', district: '信義區'),
 26      );
 27      when(mockInventoryService.checkStock('prod-001'))
 28          .thenAnswer((_) async => StockStatus.available);
 29      when(mockRepository.save(any))
 30          .thenAnswer((_) async => SaveResult.success('order-123'));
 31
 32      // When: 使用者點擊「提交訂單」
 33      final result = await useCase.execute(order);
 34
 35      // Then: 系統確認訂單已儲存並回傳訂單編號
 36      expect(result.isSuccess, true);
 37      expect(result.orderId, 'order-123');
 38      verify(mockEventPublisher.publish(any.having(
 39        (e) => e.type, 'event type', EventType.orderCreated,
 40      ))).called(1);
 41    });
 42  });
 43
 44  group('異常流程', () {
 45    test('使用者提交訂單失敗 - 商品庫存不足', () async {
 46      // Given: 選擇的商品庫存為 0
 47      final order = Order(
 48        amount: OrderAmount(100),
 49        userId: UserId('user-001'),
 50        items: [OrderItem(productId: 'prod-001', quantity: 2)],
 51      );
 52      when(mockInventoryService.checkStock('prod-001'))
 53          .thenAnswer((_) async => StockStatus.outOfStock);
 54
 55      // When: 使用者點擊「提交訂單」
 56      final result = await useCase.execute(order);
 57
 58      // Then: 系統回應庫存不足錯誤，不儲存訂單
 59      expect(result.isSuccess, false);
 60      expect(result.error, ErrorType.outOfStock);
 61      verifyNever(mockRepository.save(any));
 62    });
 63
 64    test('使用者提交訂單失敗 - Repository 儲存失敗', () async {
 65      // Given: Repository 無法儲存（網路錯誤）
 66      final order = Order(
 67        amount: OrderAmount(100),
 68        userId: UserId('user-001'),
 69        items: [OrderItem(productId: 'prod-001', quantity: 1)],
 70      );
 71      when(mockInventoryService.checkStock(any))
 72          .thenAnswer((_) async => StockStatus.available);
 73      when(mockRepository.save(any))
 74          .thenAnswer((_) async => SaveResult.failure('網路連線失敗'));
 75
 76      // When: 使用者點擊「提交訂單」
 77      final result = await useCase.execute(order);
 78
 79      // Then: 系統回應訂單提交失敗
 80      expect(result.isSuccess, false);
 81      expect(result.error, ErrorType.saveFailed);
 82    });
 83  });
 84
 85  group('邊界條件', () {
 86    test('使用者提交訂單失敗 - 訂單金額為 0', () async {
 87      final order = Order(
 88        amount: OrderAmount(0),
 89        userId: UserId('user-001'),
 90        items: [],
 91      );
 92      final result = await useCase.execute(order);
 93      expect(result.isSuccess, false);
 94      expect(result.error, ErrorType.invalidAmount);
 95    });
 96
 97    test('建立負數金額訂單拋出例外', () {
 98      expect(
 99        () => Order(amount: OrderAmount(-100), userId: UserId('user-001')),
100        throwsA(isA<InvalidAmountException>()),
101      );
102    });
103
104    test('使用者提交訂單失敗 - 訂單金額超過上限', () async {
105      final order = Order(
106        amount: OrderAmount(1000001),
107        userId: UserId('user-001'),
108        items: [OrderItem(productId: 'prod-001', quantity: 10000)],
109      );
110      final result = await useCase.execute(order);
111      expect(result.isSuccess, false);
112      expect(result.error, ErrorType.amountExceedsLimit);
113    });
114  });
115});

結論

回頭看最初那個重構週期，二十幾個因為替換 Repository 實作而失敗的測試，問題很清楚：測試在監視實作細節，而不是守護業務行為。

切換到 BDD 之後，同樣的重構只需確認業務行為沒有改變，測試套件就能保持穩定。

但 BDD 不是萬靈丹。它需要思維轉換，需要建立明確規範，需要持續 Code Review 維持品質。混合策略（UseCase 層 BDD、Domain 層單元測試、UI 層整合測試）才能真正發揮效果。

追求覆蓋率，會寫出大量測試 getter 和直接欄位映射的測試，維護成本高，保護力低。不管覆蓋率，又很難有信心說業務邏輯正確。

答案是：測試策略跟著架構走。

問題的根源

全面單元測試的問題是，重構 ViewModel 內部實作時，大量測試跟著壞掉，但行為根本沒變。全面 BDD 的問題是，Domain 層邊界條件很難透過業務語言的場景完整覆蓋。

不同層級的程式碼，用不同的測試方法。

五層架構的測試分工

Layer 1（UI/Presentation） 只針對關鍵互動流程撰寫整合測試。判斷標準：流程失敗是否影響核心業務、是否需要多步驟操作、是否涉及金流或敏感資料。靜態展示頁面、簡單列表交給人工測試。

Layer 2（Application/Behavior） 只針對複雜轉換邏輯撰寫單元測試。判斷標準：轉換是否包含條件判斷、計算邏輯、多個來源資料，或邏輯超過十行。簡單的 DTO 欄位直接映射，不需要獨立測試，由 UseCase 層間接覆蓋。

Layer 3（UseCase） 所有業務場景都必須撰寫 BDD 測試，沒有例外。每個 UseCase 至少涵蓋一個正常流程、兩個異常流程、三個邊界條件。格式使用 Given-When-Then，只 Mock 外層依賴，使用真實的 Domain Entity。

Layer 4（Interface） 不測試。介面只定義合約，沒有可測試的行為。

Layer 5（Domain Implementation） 複雜業務規則必須撰寫單元測試。判斷標準：是否包含業務規則驗證、計算邏輯、狀態轉換、不變量檢查。Email 格式驗證、金額範圍、訂單狀態轉換都需要完整的單元測試。純資料容器的 Entity 不需要獨立測試。

做決策的流程

確定程式碼屬於哪一層（目錄結構直接反映架構層級），然後問一個問題：

• UI 層：這是關鍵互動流程嗎？
• Behavior 層：這裡有複雜轉換邏輯嗎？
• UseCase 層：直接寫 BDD 測試。
• Interface 層：不測試。
• Domain 層：這裡有複雜業務規則嗎？

答案是就寫，不是就跳過讓上層覆蓋。

技術性測試項目

不分層級都要納入：

• Null 值和空集合
• 邊界值（零、負數、最大值）
• 異常處理（網路錯誤、儲存失敗）
• 資料驗證（格式、範圍、必填欄位）

這些容易被忽略，但往往是上線後出問題的地方。

覆蓋率的意義

這套策略讓覆蓋率指標更有意義。UseCase 層要求行為場景覆蓋率 100%，是所有業務場景都有測試，不是追求程式碼行數百分比。Domain 層複雜邏輯要求分支覆蓋率 100%，每個分支都代表一個業務決策。整體新增程式碼維持 80% 以上。

數字背後有實際意義，不是為了報告好看。

測試的穩定性

UseCase 層的 BDD 測試關注行為，重構內部邏輯只要業務行為沒變，測試就不需要動。Domain 層只有規則本身改變才需要更新。Behavior 層只測複雜的轉換邏輯，重構簡單映射不影響測試。

測試應該是開發的保護網，不是阻力。測試因為業務改變而失敗，那很好；因為重構而大量失敗，那是設計問題。