❯❯ spec 凍結下的正式覆寫：issue #90 拆 UI、留 API 實錄

📍 流水線位置｜入口 → 【flow】 → 型別 → mock → 測試 → UI → vibe → 上線（規格層的治理）

在婚禮系統的賓客名單頁面底端，原先設計了一個名為「已移除的賓客」折疊區塊，專門顯示被軟刪除的賓客清單，並提供「恢復」按鈕供管理者進行資料復原。

從軟體流程角度檢視，該功能具備完整的規格描述、自動化測試覆蓋與程式碼實作，於 CI/CD 流水線中全數呈綠燈通過。

然而在真實的婚禮籌備場景中，經多次名單整理與異動，這個回收區介面的使用頻率極低。被移除的賓客資料多屬確定不出席的名單，在 UI 頁面底端常駐這個折疊視圖對使用者體驗毫無效益，反而憑空製造了視覺干擾。

但當我評估將該區塊從前端介面移除時，卻撞上了最棘手的工程牆：該功能已白紙黑字凍結於主規格（Specification）中。
在 03-guests.flow.md 的 Business Invariant 3 中，早已明確立下了這條不可變的規矩：

3. 管理員能軟刪除賓客並能恢復已軟刪除的賓客；
   已移除賓客預設不顯示於畫面（經展開「已移除」分區才可見、可恢復）

同時，自動化 E2E 測試套件中包含「成功恢復賓客」的測試案例，每次執行均會模擬 DOM 操作展開該區塊並發起復原請求。這個 UI 區塊絕非隨意加上去的新功能，而是一份預先簽署、且被自動化測試死死保護著的實體合約。

兩種快速處置方案的工程風險評估

本流水線的核心原則在於：

當主 Specification 處於凍結狀態時，測試套件就是硬性合約，程式碼實作絕對不允許偏離合約規範。

如果為了圖一時方便採行常見的快捷處置，將面臨以下工程風險：

• 方案一：直接移除 UI 介面，暫不更新 Spec 與測試
  自動化測試會因為找不到「已移除」的 DOM 節點而立刻爆掉。此時若為了讓 CI 綠燈通過而跳過測試，或是隨意修改斷言條件，只會徹底破壞測試合約的權威性，導致未來面對測試失敗時，容易演變為修改測試而非修正程式碼的壞習慣。

• 方案二：連同後端 API 完全移除，改採實體刪除（Hard Delete）
  若直接廢棄 restore 端點並將資料庫操作改為硬刪除，雖能迅速清空介面與 API 邏輯，但將失去資料救援機制。一旦使用者發生誤刪操作，關聯的喜餅、飲食與桌次設定將無法復原。「前端介面沒有展示需求」並不等於「後端系統無資料安全需求」。

這兩種偷懶的捷徑都不符合工程規範，唯一合宜的解法為：

正式進行規格解凍，並依架構層級進行解構與調整。

正解：分層解構與決策拍板

針對此需求開立 Issue #90，於 Context 中說明：「移除回收區 UI 將侵犯凍結之主 Spec，故需同步進行 Spec 變更與層級修訂。」

接著，針對五個工程層級進行獨立評估與異動：

• UI 層（刪除）：
  移除回收區折疊元件、恢復按鈕與確認 Modal，並同步修正提示文案（刪除「可從回收區恢復」之描述，避免留下一套給出不實指引的介面）。

• API 層（保留）：
  HTTP DELETE 端點維持軟刪除邏輯（設定 deletedAt 時間戳記），後端 restore 端點完全保留，作為資料庫極端異常或後台維護時的資料修復管道。

• Flow 層（改寫）：
  將 03-guests.flow.md 中的 Business Invariant 3 修正為新版本（如後述）。

• 測試層（層級轉移）：
  保留「成功恢復賓客」的測試邏輯，但將驗證層級從「前端 UI 點擊操作」轉移為「直接呼叫後端 API 端點」，持續覆蓋端點合約並驗證軟刪除機制。

• Gherkin 層（維持原狀）：
  RestoreGuest.feature 檔案保持不變。該檔案屬於上游 Codegen 的產物，且領域層中的「恢復（Restore）」行為依然成立：本次異動只是將行為從前端 UI 隱藏，而不是刪除領域行為本身。這精確遵循了 Day 03 所確立的職能邊界：流水線僅變更授權範疇內的檔案，上游規格保持唯讀。

修訂後的 Business Invariant 3 定義如下：

3. 管理員能軟刪除賓客；已移除賓客不顯示於畫面
   （無回收區、UI 無恢復入口——恢復僅存在於 API 層作為資料修復途徑）

於 Flow 文件對應場景中補充歷史紀錄：「恢復為領域命令且端點保留，但不對管理員 UI 曝光（使用者決策，2026-07-15）」。
這行記錄明確留下了決策背景與時間節點，使後續維護者能清楚理解 API 端點與 UI 介面設計不對稱的架構原委。

凍結機制的本質

「規格解凍」從來就不是隨意拆除程式碼的通行證；相反地，它要求開發者必須將「功能廢棄」精細地拆解至系統的各個層級，並針對每一層單獨評估保留或刪除的必要性。在本案例中，五個層級最終分別採行了：刪除、保留、改寫、層級轉移與維持原狀五種不同的工程處置。

凍結機制的目的從來不是阻止系統演進，而是防止未經審查與紀錄的隱蔽變更。 只要具備明確的決策紀錄與分層審查機制，團隊完全可以合理地演進規格與測試架構。這套機制能徹底杜絕「先改程式碼、出事再補規格」的隨意開發習慣，確保系統長期的可維護性。

規格是系統行為的最終依歸，而規格的演進則取決於開發團隊嚴謹的決策過程。

搞定規格解凍後，下一篇將討論流水線中的關鍵課題：當規格與程式碼散落於多個層級時，如何透過自動化機制，確保各層級之間不會發生隱性的邏輯偏離？

🎒 最小一步｜ 當未來需要廢棄一項既有功能時，請列出五個架構層級（UI / API / DB / 測試 / 文件），針對每一層級單獨評估「刪除或保留」的理由。
📎 本篇證據｜ issue #90（賓客名單移除回收區：凍結 spec 的正式覆寫與分層修訂紀錄）