驗證、發布與維護紀錄

本篇適用於已完成目標評估與必要合併之後。暫時沒有更新需求時，保留既有專案即可，不需要執行發布、建立標籤或資料庫操作。

一、先明確訂出驗收範圍

驗證應圍繞本次變更及其實際影響進行，不能只看首頁，也不需要在修改無關文案後，一律測試所有第三方功能。

開發模式的郵件會顯示在終端機預覽，不能將預覽成功當作實際投遞驗證。使用 Stripe 測試模式時，也要確認連線、Price 和 Webhook 屬於同一測試環境。

二、完成本機檢查

程式碼變更完成後，執行：

npm run verify

範本會依序執行 ESLint、TypeScript 型別檢查、應用程式與指令碼等測試，以及正式環境建置。檢查過程中產生的內容或型別錯誤，也需要處理，不能只留下最後一次建置成功的螢幕截圖。

如需在本機檢查打包後的頁面，可以使用：

npm run preview

本機預覽不能證明正式環境資源、郵件服務或第三方回呼可用。需要線上整合驗證時，先準備隔離資源與明確的測試設定，目前範本並未自動提供一套完整的 staging 環境。

三、發布前核對實際執行目標

記錄準備發布的提交、網站網址、Worker、資源 ID、遷移檔案及設定變更。確認恢復所需的原始主金鑰和其他驗證資訊，仍儲存在安全位置。紀錄中僅填寫儲存位置或更新狀態。

涉及正式環境資料變更時，請確認備份或還原點可用，並評估發布期間是否需要限制相關寫入操作。僅建立 Git 標籤，無法保護資料庫和外部服務狀態。

一般更新使用：

npm run deploy:update

這個指令發布的是目前工作目錄，不會下載或合併範本。執行順序包含正式環境檢查、產生型別、完整驗證、遠端遷移、發布 Worker、同步 KV，以及頁面健康狀態檢查。

由於它已包含 verify，發布前不需要只為了完成流程，立刻再重複相同檢查。不過，若先前驗證後又修改了程式碼，就不能將舊驗證結果當作目前版本的證明。

發布步驟請見首次部署與後續更新。

四、失敗後先確認發生了什麼

不要看到指令失敗，就刪除資源、清空資料庫或重複首次部署。更詳細的排查請見部署、資源與網域。

回復舊版程式碼，不等於系統已恢復

如果僅修改應用程式碼，且未改變資料格式、設定含義和外部狀態，可以評估重新發布已驗證的舊程式碼。如果遷移已刪除舊欄位，或新版本已寫入舊版本無法辨識的資料，就不能直接採用這個方法。

還原資料庫可能撤銷還原點之後的合法資料。Stripe 已付款、郵件已寄送、Queue 已處理的效果，也不會隨 Git 版本回復一併消失，需要另外對帳。

專案沒有自動將整個系統回復原狀的指令。恢復方案應依本次變更制定，寫清楚恢復對象、依據、執行順序，以及恢復後需要補做的業務處理。

五、上線後驗證實際受影響的功能

頁面健康狀態檢查通過後，使用發布前準備的代表案例驗證。請核對舊帳號和歷史資料，不要只建立一個新帳號，看到正常結果就結束。

涉及背景工作時，繼續檢查 Event、Command 和取用者結果。涉及付款時，核對交易與權益是否一致。首次觀察到正常結果後，也應配合實際業務週期，留意延遲回呼或排程工作，不要將短時間內未出現錯誤，解讀為所有路徑都已驗證。

確認穩定後，清理本次確實不再需要的暫時邏輯、測試設定和舊參照。未使用的資源，不要只因名稱相似就刪除，應先確認沒有讀取或寫入者，也沒有恢復用途。

六、保留一份內部維護紀錄

內部紀錄說明如何實作和恢復，公開更新頁面則說明使用者獲得了什麼，兩者用途不同。

以下是日後有實際更新時，可以複製使用的紀錄範本。其中的預留內容需依實際情況填寫，不代表本次已發生升級：

# 更新紀錄：<本次變更名稱>

- 狀態：評估中 / 待發布 / 已發布 / 已恢復
- 更新原因：
- 應用程式原提交與版本：
- 範本原來源與目標來源：
- 本次採用的修改：
- 保留或未採用的範本變更及原因：
- 資料庫遷移檔案與驗證結果：
- 設定、變數和資源變更：
- 第三方平台手動操作：
- 自動檢查與業務驗收結果：
- 實際發布提交、時間和目標 Worker：
- 失敗時的恢復條件、對象與步驟：
- 發布後的觀察結果：
- 尚未解決的問題：

請勿在紀錄中儲存 Secret、Cookie、權杖、完整的正式環境資料或電子郵件驗證碼。資料庫備份也應另外安全儲存，不應隨文件提交至儲存庫。

即使決定暫緩更新，也可以記錄目標版本和暫緩原因，下次評估時就不必從頭猜測。

七、維護公開更新說明

目前範本的更新頁面會讀取 src/components/server/Changelog/entries.ts 中的靜態陣列，不會自動將 Git 提交或 package.json 版本轉換為公告。

目前的更新條目使用以下欄位：

更新條目的內文目前直接使用陣列中的英文字串，只有頁面框架文案會透過 pages.changelog 等語言索引鍵讀取。僅修改語言 JSON，不會自動翻譯 entries.ts 的標題和清單內容。如果日後需要多語言更新內文，應依專案既有的國際化機制，串接對應資源。

初始化後的產品，不應自動將範本歷史紀錄當作自己的產品發布歷史。有實際發布時，再記錄自己已提供給使用者的變更。沒有變更時，不需要為了填滿頁面而虛構新版本。

文案應描述具體結果，例如「修正變更電子郵件地址後，舊地址仍收到後續通知的問題」，比「優化電子郵件模組」更有意義。內部資源 ID、還原點、敏感資料和具體安全性控制細節，請保留在受控的維護紀錄中。

八、標籤、原始碼套件與部署各自獨立

npm run release:tag 會建立標籤並推送至 origin，不是本機唯讀操作，也不會部署 Worker。release:archive 會從指定的 Git Tree 產生原始碼套件，不會包含尚未提交的變更。

範本維護者的 commit script 已從發布的原始碼套件移除，不能假設初始化後的專案提供相同的一鍵提交方式。

是否使用這些發布指令，應由自己的版本管理流程決定。目前沒有發布需求時，不需要先建立標籤或封存檔，只需保留能夠追溯專案狀態的紀錄。