本章把邊界拆成四個方向，每個方向由一個實際踩過的 case 支撐。排查判準收成三問：這個變化是 provider 圖上某個節點的狀態變化嗎？在哪個容器的圖上？節點還活著嗎？

心智模型：配方、廚房、圖

provider 的全域宣告是配方——描述狀態怎麼建、怎麼變化；狀態本身活在容器（ProviderContainer／ProviderScope）裡，同一份配方在兩個容器裡煮出兩份互不相干的狀態。容器內的 provider 依 ref.watch 的依賴關係連成圖：節點是 provider 的狀態、邊是 watch 依賴，狀態變化沿著邊傳播、觸發下游重建。

reactive 的全部機制都建立在這張圖上。四個邊界各是圖的一個面向：圖屬於誰（空間）、圖上有什麼（涵蓋）、圖外的變化怎麼進來（接入）、節點活多久（時間）。

空間邊界：狀態屬於容器、不屬於宣告

main() 自建 ProviderContainer 觸發初始化、UI 跑在 runApp 的 ProviderScope 裡——兩個容器各持一份狀態，初始化改的是外部容器那份、UI 監聽的是 Scope 那份，App 永遠停在載入畫面。跨容器操作不報錯、只是安靜地作用在預期之外的地方，每段程式碼單獨看都正確。

判準：一個 App 裡活著的容器數量應該是一，每多一個都要能說出它為什麼必須隔離（測試的 ProviderContainer(overrides:) 是正當隔離）。全專案搜 ProviderContainer(、逐一問「它跟 UI 的 Scope 是同一個嗎」。確實需要在 runApp 前操作 provider 時（如讀取啟動設定），用 UncontrolledProviderScope 讓兩邊共用同一個容器。完整機制與修法：App 永遠卡在載入畫面。

涵蓋邊界：圖上只有 provider 的狀態

ref.watch(bookRepositoryProvider) 對單例 Provider<BookRepository> 建立的依賴永遠不觸發——這個 provider 的狀態是「repository 物件參考」、整個生命週期不變；SQLite 寫入了一百本書，物件參考一動不動。資料庫的變化不在圖上，於是刷新被推到圖外解決：導航返回點補 loadData()、EventBus 橋接、多個視圖各自維護 load 時機——補償刷新的出現就是涵蓋缺口的訊號。

判準：要讓畫面對某個變化反應，那個變化本身必須是圖上某個節點的狀態變化。修法方向一致——把資料變更做成一級節點（repository 補 stream 出口、StreamProvider 包成 provider），視圖回到純 ref.watch。三段補償演進與判讀訊號表：ref.watch 觀察的是 provider 圖、不是資料庫。

接入邊界：圖外的變化要立節點才進圖

把 repository 的 stream 接成圖上節點、是涵蓋缺口的結構性修法，接入處有自己的實作契約。三個問題各有一個會靜默失效的預設答案：訂閱模型（多個視圖同時聽、StreamController() 預設單訂閱、第二個訂閱者執行期 throw）、初始值（broadcast 不補送歷史、不處理的話畫面空到下一次寫入）、dispose（controller 的關閉責任跟著持有者走）。三個實作點的完整落地：StreamProvider 包 repository watch stream。

其中訂閱模型的選擇值得單獨記：StreamController() vs .broadcast() 是零成本差異，選限制更高的單訂閱版本、限制在只有一個訂閱者期間完全沉默、第二個訂閱者出現才爆。在零成本差異下把「會有多個觀察者」的領域先驗寫死成單訂閱，是設計缺陷、不是需求演化。單訂閱與 broadcast 的行為差異全表（buffer、pause、重新訂閱）：StreamController single vs broadcast。

時間邊界：節點的生命有兩頭界線

async 函式的每個 await 都是一個 gap：等待期間使用者可能離開頁面、Notifier 被 dispose，await 回來再碰 ref 就炸 UnmountedRefException。修法可機械化——每個 await 之後、第一次碰 ref 之前檢查 ref.mounted；而且刻意不抽成 helper：guard 的價值在「它在哪」，明確的檢查點讓 review 用眼睛掃就能驗證每個 gap 有沒有守。長流程、可離開的頁面（匯入、同步、批次處理）風險最高。完整機制與「評估必跑、可決定不重構」的技術債處置：await 回來的時候、頁面已經關了。

生命週期的另一頭是 build 期間：widget tree 建置中直接改 provider 狀態同樣是非法時機，觸發點要用 addPostFrameCallback 延到首幀之後。ref 的合法視窗兩頭都有界——await 之後可能太晚、build 之中太早。

排查判準

reactive 失靈時沿三問走，每一問對應一個邊界：

三問都過、reactive 仍不對時，回到接入層的實作契約查：訂閱模型（Bad state = 單訂閱撞多訂閱）、初始值（畫面空到下次寫入 = broadcast 沒補當前值）、mock 與真實實作的 stream 契約對齊。

邊界

本章處理 Riverpod 這個框架的 reactive 機制邊界，是實作層知識。「觀測能力該放哪一層」（契約歸 domain、機制歸 infrastructure、框架訂閱歸組裝層）是理論層的歸屬判準、與框架無關，見 觀測出口的職責三分；「事件與狀態流哪個當通知載體」的選擇也在理論層，見 domain event 與狀態流。本章假設載體與分層已定、只管 Riverpod 端怎麼把它接對。

下一步

圖的邊界都守住之後，剩下的深化方向各有一篇 case 可讀：容器與作用域的空間問題在 雙容器狀態脫節、涵蓋缺口的補償演進在 ref.watch 觀察的是 provider 圖、接入實作在 StreamProvider 包 repository watch stream 與 StreamController single vs broadcast、生命週期在 await 回來的時候、頁面已經關了。理論地基從 DDD 指南的讀側與觀測路線 進。

這條判準值得成章，因為它跟一個直覺衝突：觀測出口的需求完全來自消費端——是 UI 框架想觀察、domain 自己沒有這個需要。「誰需要就放誰那層」的直覺會把 Stream 出口做進 presentation 的某個 service，讓 domain 保持「純淨」；本章論證這個直覺用錯了判準的位置。

案例：六個視圖、兩種補償、一個缺口

一個書庫管理 App 的 repository 是純 Future pull 介面。盤點 presentation 層讀書庫資料的六個衍生視圖，只有一個有 reactive 機制（且僅涵蓋部分路徑），其餘全靠命令式載入加補償：

根因是同一個：repository 沒有變更通知出口，六個視圖各自在圖外解「怎麼知道資料變了」這一題，解出兩種補償策略（導航返回點重載、經 EventBus——行程內的發布／訂閱事件匯流排——的 domain event 橋接）、職責交叉且涵蓋不完整。補償演進的完整記錄在 ref.watch 觀察的是 provider 圖、不是資料庫；本章從這個案例抽三層歸屬的判準。

契約層：歸屬由介面語言決定、不由需求來源決定

契約是那一行介面宣告：

1Stream<List<Book>> watchBooks();

它該放 domain repository 介面、還是該為了「不污染 domain」放外層？判準是逐一檢查簽名裡的型別屬於哪種語言：

語言標準庫的非同步原語跟 domain 的關係、和 Future 完全等價：repository 介面回 Future<List<Book>> 從來沒人覺得是洩漏，Stream 是同一個標準庫裡「多值版的 Future」、地位等同。watchBooks() 全句只用標準庫加 domain entity——它說的是 domain 的語言，放 port 所在的 domain 介面，跟 getAllBooks() 形成 pull／push 對稱。

這裡就是與直覺衝突的位置。需求從消費者出發、決定介面該不該存在；介面放哪一層、由表達語言決定。兩個問題常被壓成一個：

• 「UI 想觀察資料」是消費端需求——它回答「要不要有 watchBooks()」。介面設計本來就該從消費者需求出發，port 的形狀由呼叫方的需要定義。
• 「watchBooks() 歸誰」是歸屬問題——它由簽名語言回答。簽名說 domain 的語言，介面就是 domain 的；哪天簽名裡出現 AsyncValue<List<Book>>（框架型別），才是把消費端的語言帶進了 domain、才需要擋。

用需求來源判歸屬會兩頭錯：把說 domain 語言的介面推到外層，domain 的資料能力（「我管理的資料變了、我能告訴你」）散落到 infrastructure 或 presentation 的 service 裡；或者反過來，以「需求是 domain 相關」為由把帶框架型別的介面塞進 domain。

契約層還有一個二擇：放既有 repository 介面、還是抽獨立的查詢 port？本案放既有介面——讀需求只有「完整書單流」一條、六個視圖都能從書單流投影，為一個方法抽 port 是介面碎片化。這個「何時該抽」的判準有自己的一章：讀模型的升級判準。讀 port 一旦抽出，仍屬契約層的延伸——簽名同樣只用 domain 語言，機制層與組裝層的三分模型對它同樣適用。

語言歸屬判準處理的是「詞彙是否洩漏」這一種反對意見。DDD 文獻裡存在另一派更根本的立場：即使簽名純淨，Repository 模式在 Evans / Vernon 的原始定義裡是集合式存取，reactive 訂閱能力本質上服務查詢端、屬於讀側的關注點，不論詞彙是否純淨都不該掛在寫側 aggregate 的 repository 介面上。這個立場涉及讀寫分離的組織方式（讀 port 何時值得獨立、CQRS 階梯的升級判準），跟詞彙判準各自回答不同的問題：詞彙判準回答「語言有沒有洩漏」，讀寫分離判準回答「職責該不該分離」。本章只處理前者；後者見 讀模型的升級判準。

機制層：變更偵測是 adapter 的實作細節

機制層回答「怎麼知道資料變了」。這層的語言是 controller、資料庫 hook、交易——全是 infrastructure 詞彙，所以歸 adapter。本案的二擇：

本案選寫入點 emit：repository 在每個實際執行寫入的方法尾端發出最新書單。它的維護成本（新增寫入方法要記得掛 emit）留在單一類別內部、被測試釘住；update hook 的 false positive 則會流出去變成消費端的雜訊。關鍵的架構事實是：這整個表格的內容都不出現在契約層——選哪個、換哪個，介面簽名一個字不動。這正是三分成立的證據：機制可替換、契約穩定。

組裝層：框架型別止步的位置

組裝層把 domain 的 Stream 翻譯成框架的觀察原語。本案是 Riverpod 的 StreamProvider：

1final watchBooksProvider = StreamProvider<List<Book>>((ref) async* {
2  final repository = ref.watch(bookRepositoryProvider);
3  yield await repository.getAllBooks(); // 訂閱當下先給當前值
4  yield* repository.watchBooks();       // 再轉接後續變更
5});

StreamProvider、Ref、AsyncValue 這些框架型別在這層第一次出現、也只在這層出現。組裝層同時吸收「呈現需求」性質的行為——訂閱當下要先看到當前值，是消費端的需要、不是「變更通知」語意的一部分，所以那兩行 yield 住在這裡而非 repository 裡。組裝層的其他責任（誰插上誰、插上了沒有的證言）見 組裝層的可達性；本案的 Flutter 實作細節見 StreamProvider 包 repository watch stream。

三分總表

三列共用同一條判準：看那一層的產出用什麼語言說話。這條判準的機械性有明確範圍——它機械地回答「一個已寫好的簽名該歸哪一層」：打開簽名、逐型別問「這是誰的詞彙」，答案不依賴對「純淨」的品味爭論。它不回答「一段新行為該寫進哪一層」（如初始值那兩行 yield）——那是語意歸屬決策，要判斷行為屬於誰的語意，跟機制層選 emit 時機一樣是設計判斷、不是型別檢查。把兩者混為一談、以為整篇的歸屬都能靠型別自動判定，正是這條判準最容易被過度推廣的地方。

邊界

觀測出口通知的是「資料現在長什麼樣」；domain event 記錄的是「發生過什麼業務事實」。兩者正交、互不取代——本案落地觀測出口時，既有的事件發布點零改動。這個正交性有一個架構前提：狀態存在獨立的資料庫、事件只是旁支通知。event-sourced 架構下狀態由事件重建、沒有獨立持久化的當前值，機制層要生出 watchBooks() 只能訂閱同一條事件流做投影——那時變更偵測與 domain event 不再是兩條獨立管線、「零改動」的論證不成立。把 event 借用成刷新訊號的代價、以及兩種載體的選用判準，見 domain event 與狀態流。

下一步

三分的判準確定之後，下一個問題通常是「要不要抽讀 port」——先讀 讀模型的升級判準 再做這個決策。還沒建觀測出口、仍在用事件或導航補償的話，回頭讀 domain event 與狀態流 先確認載體選擇，確認要用狀態流再進本章。

• 補償演進與 Riverpod reactive 邊界的案例全文 → ref.watch 觀察的是 provider 圖、不是資料庫
• 機制層與組裝層的實作點（broadcast、初始值、dispose）→ StreamProvider 包 repository watch stream

兩種載體的語意對照

「錯過的代價」那一列是實務上最好用的分辨器。畫面剛好沒訂閱時漏掉一次書單更新，下一次更新全額補償——狀態流語意。稽核系統漏掉一筆「書籍已刪除」，那筆事實永遠消失——事件語意。同一個資料變更常常兩種消費者都有：刪一本書，審計要那個事實（event）、清單畫面要新的書單（狀態流）——這不是二選一，是兩條正交的出口。

事件命名的過去式約定本身就是語意宣告（展開見 Domain Event 命名的過去式）：過去式承諾「這是已發生的事實」。當事實開始被當成「請刷新」的訊號消費，這個承諾就被消費端改寫了——下面的案例走的正是這條路。

案例：一條斜坡的三步

一個書庫管理 App 的統計頁需要在資料變更後刷新。repository 是純 pull 介面、沒有狀態流出口；但專案有現成的 EventBus、也有數十個 domain event 發布點。「用既有的事件當刷新訊號」看起來是零成本的選擇——這是斜坡的入口。

第一步：橋接。用 StreamProvider 包 EventBus、ViewModel 監聽事件流、任何事件進來就重新查詢統計。上線有效：匯入完成事件、同步事件都正確觸發刷新。

第二步：斷鏈暴露枚舉本質。搜尋加書與掃描加書路徑不刷新——盤點發現這兩條寫入路徑從未發布任何 domain event。事件的發布時機由業務語意決定（「匯入完成」值得記錄；「使用者加了一本書」當時沒有下游流程需要它），而刷新的涵蓋面要求「每條寫入路徑都有事件」。兩個需求的形狀本質不同：事件的涵蓋面是業務事實的集合、狀態流的涵蓋面是寫入操作的集合。用前者服務後者，缺的部分只能靠枚舉補——為了刷新而補發事件。

第三步：語意綁架成形。補發事件的修法一旦開始，事件系統的演進被刷新需求綁住：新增寫入路徑的檢查清單多了「記得發事件、否則某頁不刷新」；想移除一個再無業務消費者的事件、要先確認沒有畫面靠它刷新；監聽端則因為「不知道哪些事件代表資料變了」而全事件監聽、任何無關事件都觸發一次重新查詢。每一步都合理、加總起來是兩個系統互相持有對方的隱含契約。

這個專案在第三步前停下，把問題拉回載體選擇：統計頁的問題是「現在是什麼」（當前書庫統計）、不是「發生了什麼」。正確載體是狀態流——repository 補 Stream<List<Book>> 觀測出口、畫面 ref.watch 訂閱，涵蓋面天然等於寫入操作的集合（每個寫入方法尾端 emit），沒有「記得發」這個動作。演進全記錄在 ref.watch 觀察的是 provider 圖、不是資料庫、分層落地在 觀測出口的職責三分。

正交性：加了狀態流、事件一個不動

載體分清楚之後最有力的驗證是改動面：狀態流落地時，既有事件發布點零改動。事件仍然記錄業務事實、服務審計與跨 domain 通知；狀態流負責「資料變了」的觀測。兩者正交、互不取代：

「結構性涵蓋」與「逐事實設計」的差異就是兩種載體不可互換的原因。狀態流的 emit 掛在寫入方法上、新路徑必然經過、涵蓋不靠任何人記得；事件的發布點是設計決策、每個事件都該有業務理由——被迫「為涵蓋而發」的事件是沒有事實語意的雜訊，反過來稀釋整個事件系統的可信度（事件多到沒人知道哪些重要時，跨 domain 通訊的成本問題見 用事件做同步查詢等於手工重建 RPC——同一族的載體誤用、方向相反：那篇是拿事件做請求回應、本篇是拿事件做狀態通知）。

判讀訊號

斜坡的每一步都有可觀察的訊號，出現任何一個就回到載體判準重新選：

第四個訊號值得單獨說明：事實的 payload 是「這件事的內容」（哪本書、什麼時間），快照的 payload 是「現在的全貌」。事件開始攜帶全量狀態、通常是因為消費者拿到事件後只想要最新值——那正是狀態流一次 emit 就給完的東西。這個訊號有適用邊界：它假設消費者與事件來源在同一進程、同一信任邊界內。跨服務情境下，刻意讓事件攜帶足量當前狀態是 event-carried state transfer 這個正當設計——目的是讓下游服務不必回頭查詢來源、避免同步耦合，那時「payload 帶全量狀態」是設計選擇、不是載體錯位。本案是單一 App、同進程，沒有跨服務查詢成本，才適用「該補的是狀態流」的判讀。

四個訊號量的不是同一種東西。訊號一、二、四直接檢驗「消費者現在問的是哪種問題」；訊號三（移除事件前要先查有沒有畫面靠它刷新）量的是選錯載體之後累積的耦合成本——它是後果訊號（lagging indicator），等綁架已經長出來才觀察得到。把它跟前三個並列，是因為它同樣觸發「回到載體判準」，但它遲到、指向的是已經發生的綁架而非正在發生的誤用。

以上訊號都指向同一個方向：把事件當成狀態流用。反方向的誤用同樣存在、訊號相反——消費者需要的是逐筆離散事實（每一次庫存調整、每一筆退款），系統卻只給得到最新快照。症狀是稽核回頭找「中間發生過什麼」時只有結果沒有過程、或下游流程因為錯過中間狀態而少觸發。此時該補的是 event、而不是把狀態流的快照硬拆成假事件。兩個方向共用同一條判準：問「發生了什麼」給事件、問「現在是什麼」給狀態流——判準對稱，誤用可以往兩邊倒。

邊界

本章的判準處理「資料變更通知」這一種需求的載體選擇。事件對另外兩種離散訊息（命令、查詢）的責任結構分界在 domain event 與命令、查詢；狀態流的實作選型（broadcast、初始值、生命週期）在 StreamProvider 包 repository watch stream。另外，CQRS 階梯頂端「以事件同步讀模型」是事件的合法消費——那裡的消費者問的確實是「發生了什麼」（用事實重建投影），與把事件當刷新鈴聲不同層；階梯全貌見 讀模型的升級判準。這也標出本章「兩者正交」論述的架構前提：狀態存在獨立儲存、事件只是旁支通知。event-sourced 架構把這個前提拿掉——狀態流成為事件的投影、由同一條事件流重建，兩條管線不再獨立，正交性讓位給「讀模型由事件同步」的第四階語意。

下一步

決定用狀態流之後，先讀 觀測出口的職責三分 搞清楚契約、機制、組裝分別放哪一層，再進 ref.watch 觀察的是 provider 圖、不是資料庫 看案例從導航補償到狀態流的完整演進。事件命名的過去式約定（為什麼叫 BookAdded 而不是 AddBook）展開在 Domain Event 命名的過去式。讀側若走到階梯高處、要用事件同步投影的代價評估，見 讀模型的升級判準。

概念位置

狀態流是 觀測出口 的載體形態：觀測出口定義「資料變了、我能告訴你」這個能力歸屬哪一層、狀態流定義這個通知的語意——連續快照、不是離散事實。它的涵蓋面是寫入操作的集合：emit 掛在每個寫入方法尾端、新路徑必然經過、涵蓋不靠任何人記得發——與 domain event「業務語意決定發布點、逐事實設計」的涵蓋方式正交。

可觀察訊號

系統缺狀態流出口時，補償的形狀是訊號：導航返回點出現手動 reload、為了讓某頁刷新而補發事件、監聽端掛全事件過濾器。事件被誤用成狀態流的完整判讀訊號表在 domain event 與狀態流。

設計責任

狀態流承擔「畫面、快取、衍生視圖對資料當前值的觀測」，錯過的代價為零是它跟 event 不可互換的原因——需要逐筆事實（審計、下游流程）的消費者拿快照會斷檔。載體選用判準展開見 domain event 與狀態流、實作選型（broadcast、初始值、dispose）見 StreamProvider 包 repository watch stream。

概念位置

觀測出口的契約層是一種 port：簽名只用語言標準庫與 domain entity、放 domain repository 介面，與 pull 方法形成對稱。機制層（broadcast controller、寫入點 emit）歸 adapter；組裝層（框架 provider 包裝）歸 DI／presentation。三層歸屬的完整判準與「需求來源不決定歸屬」的推導見 觀測出口的職責三分。

可觀察訊號

repository 缺觀測出口時，每個衍生視圖各自解「怎麼知道資料變了」：導航返回點補 reload、EventBus 橋接刷新、多個視圖各自維護 load 時機。補償策略的交叉與涵蓋缺口是這個能力該補的訊號。

設計責任

觀測出口讓「資料變更」成為可訂閱的一級節點，涵蓋面等於寫入操作的集合——emit 掛在寫入方法尾端、新路徑自動涵蓋。它通知「現在是什麼」、不記錄「發生了什麼」——後者是 domain event 的責任，兩者正交。落地的實作點（broadcast、初始值、dispose）見 StreamProvider 包 repository watch stream。