把 ZenDrip 想成一間小咖啡店：用流程圖看懂開發架構
櫃台、計時助手與筆記本，各自做什麼？用白話和流程圖，走過 iPhone、Watch、資料保存與開發驗證。
更新於
「開發架構」聽起來很大，其實可以先問一個小問題：按下開始之後，誰負責提醒我，誰負責記住這次沖煮？
把 ZenDrip 想成一間小咖啡店就好。你在櫃台選一份方案，助手陪你走過注水與等待，最後把這次的事情寫進筆記本。
以下依 2026 年 10 月 5 日的程式與開發紀錄整理。圖中的方塊表示工作角色或步驟，箭頭表示交接方向。Watch 圖以虛線標出仍待真機驗證的路徑；實際程式還有錯誤處理與保存檢查。
1. 櫃台、助手、筆記本
畫面是櫃台。 方案列表、開始按鈕、引導畫面與日誌，都在這裡和你說話。iPhone 畫面用 Apple 的 SwiftUI 製作；Swift 則是寫下 App 行為的程式語言。
引導是計時助手。 它讀取方案，知道目前在哪個階段、還剩多久，以及何時提示下一步。暫停、提前結束、切到背景，也需要有明確的處理方式。
資料管理負責照顧筆記本。 畫面把要保存的方案或紀錄交給它，它檢查資料，再寫入手機裡的檔案。保存成功後，畫面才顯示更新的內容。
這些是幫助理解的分工。現在引導畫面本身也持有計時與操作狀態；圖中的「引導」是在說明職責，並不代表它已拆成完全獨立的服務。
2. 同一張方案，兩種陪伴
一份方案像一張食譜卡：粉量、水溫、各階段水量和時間，都寫在上面。
「實際沖煮」是拿著器材，依方案操作。「內在沖煮」是在心中預演水流與等待，把注意力帶回這段節奏。
兩種模式共用方案、階段與計時規則，再用不同的文字、畫面及提示陪伴使用者。內在沖煮還可以選擇觀看引導，或透過聲音與觸覺減少看螢幕的需要。
例如調整第二段注水時間，兩種模式都會依同一份方案前進。現在的「不看螢幕」仍在 App 前景運作；鎖屏後持續引導，需要另外驗證。
3. 一次沖煮，有書籤，也有日記
進度保存像書籤：留下目前已保存的進度。App 意外中斷後，可以從最後保存的位置處理復原；不知道的中斷時間不會被當成已完成的沖煮。
完成保存後，就有這次正式留下的紀錄。回顧再補上你對這次體驗的想法。程式也保留這次使用的「方案快照」，像把當時的食譜影印一份貼進日記。明天修改方案，昨天那一杯仍保留昨天的條件。
目前主要資料以 JSON 保存。可以把 JSON 想成有固定欄位的文字筆記，程式知道哪一欄是時間、哪一欄是方案。
BrewLibrary 放方案、日誌與沖煮紀錄；active-run 是書籤；import-rollback 是匯入前後的還原資料。Sessions 另外保存 Watch 傳來的 session 紀錄。
目前沒有登入帳號與雲端同步。要留一份可自行帶走的副本，可以使用匯出；資料保留與備份的界線，在 備份文章 有更完整的說明。
4. 心率和 Watch，是另外兩條入口
iPhone 可以在使用者選擇相關功能並經過健康資料授權流程後，查詢 Apple Health 中已有的心率，再和這次沖煮的時間對照。
時間配對像把兩張時間表放在一起：找出沖煮期間有哪些已存在的心率樣本。資料可能沒有、延遲或不完整；使用者也可以略過心率。
專案另外保留 ZenDrip Watch 的技術驗證程式：在手錶端收集 session、安排觸覺提示、先存檔，再交給 iPhone。
WatchConnectivity 是 Apple 提供的手機與手錶傳檔通道。兩端共用 SessionRecord 的格式，就像約好同一張表格的欄位。
這條 Watch 路徑仍在技術驗證階段。熄幕提示、心率密度與傳輸可靠性需要真實裝置證據；開發主線目前先集中在 iPhone。iPhone 讀 Apple Health，也不會因此自動啟動 ZenDrip Watch 或手錶的心率 App。
5. 開發時，先照施工圖，再分開檢查
專案把「有哪些 App、包含哪些檔案」寫在 project.yml。XcodeGen 讀這份施工圖，產生 Xcode 專案；Xcode 再把程式組成可以執行的 App。
iPhone 開發有一個不附帶 Watch App 的 PhoneMVP 版本，方便先驗證手機功能。它和原本附帶 Watch 的 iPhone 版本共用手機程式碼；兩者的 App 資料空間分開。
檢查也分成三種，像檢查食譜、試走流程，再真的喝一杯：
- 邏輯測試：確認時間計算、方案快照、匯入與保存規則。
- 模擬器 UI 測試：真的按畫面上的按鈕，檢查保存、重開、再次查閱。
- 真機驗收：確認手機和手錶上的聲音、觸覺、健康資料與日常操作。
編譯成功只表示程式能組起來。模擬器操作通過，也只證明已測的路徑；真機體驗要留下自己的驗證結果。
6. 官網是店門口的介紹牌
最後，這篇文章所在的官網，有自己的程式與發布流程：Astro 把內容做成靜態網頁，再放到 Cloudflare Pages。
官網負責介紹、指南和開發日誌，App 負責裝置上的沖煮體驗。本機沖煮紀錄目前不會同步到官網。先前的動畫也還是獨立示意原型，尚未接入 App 的引導邏輯。
如果把整套架構帶回那間小咖啡店：櫃台讓你選擇，助手陪你走過時間，筆記本留下這次的條件。開發時，就是逐一確認這幾個角色能把事情交接好，讓下一次回顧仍然找得到上一杯。
2026 年 10 月 5 日圖示更新
依閱讀回饋，將原本八張 ASCII 文字圖換成中文流程圖，補上交接箭頭與 Watch 待驗路徑的虛線。本文描述的程式分工與驗證狀態維持原來的依據。