框架升級指南
本指南適用於消費 @appfuse/appfuse-web 或
io.leandev.appfuse.webapp:appfuse-server 的 workspace。升級的核心不是只改版號，而是：
盤點 → Changelog 預檢 → 更新依賴 → 完成 migration → build/test → 部署驗證
:::info 先取得目標版本
從自動產生的當前發布線複製精確版號，再代入
下列 workflow 參數或 REPLACE_WITH_EXACT_VERSION。
:::
1. 先讀正確的 Changelog 區段
| 目標版本 | 預檢來源 |
|---|---|
| 正式版 | 對應的 ## [{targetVersion}] |
alpha、beta、rc、SNAPSHOT | ## [Unreleased] |
pre-release 不會把 [Unreleased] 切成自己的版本區段。找不到
## [19.0.0-alpha.N] 或 ## [4.0.0-alpha.N] 是正常行為，不代表可以跳過預檢。
依序檢查：
Removed：搜尋消費端是否仍使用被移除的 API。Deprecated：記錄 replacement 與 removal version。Breaking Changes：完成每一項 Impact／Migration。Added、Changed、Fixed、Security：確認新行為與修正是否影響測試假設。
2. 建議使用 workspace 升級 workflow
在 modules/ 執行：
/upgrade-appfuse-web {webTargetVersion}
/upgrade-appfuse-server {serverTargetVersion}
升級 workflow 會掃描所有消費模組、取得 Changelog、檢查 Removed API 使用點並逐模組建置。 這能避免只升到一半，讓同一 workspace 同時存在兩個框架版本。
3. 手動升級 Web
先找出所有消費模組：
rg -l '"@appfuse/appfuse-web"' */package.json
逐一安裝精確版本：
WEB_TARGET_VERSION="REPLACE_WITH_EXACT_VERSION"
npm install --save-exact "@appfuse/appfuse-web@$WEB_TARGET_VERSION"
再查詢並比對新舊版本的 peer dependencies：
npm view "@appfuse/appfuse-web@$WEB_TARGET_VERSION" peerDependencies --json
框架本身使用精確版號；peer dependencies 依專案慣例保留 ^ 等範圍。兩者應分成不同的
npm install 指令，避免 --save-exact 把 peer dependencies 一併釘死。
驗證：
npm run build
npm run test
若 workspace 同時有 mockup 與 production Web，先驗證 mockup，再驗證 production。 使用 yalc 連結的模組應先解除連結或明確跳過，不要誤以為 registry 版本已生效。
4. 手動升級 Server
找出所有消費模組：
rg -l 'io\.leandev\.appfuse\.webapp:appfuse-server' */build.gradle.kts
將依賴 pin 到不可變版本：
dependencies {
implementation("io.leandev.appfuse.webapp:appfuse-server:REPLACE_WITH_EXACT_VERSION")
}
框架會以 Gradle api configuration 傳遞 Spring Boot starters 等公開依賴；不要為了升級而
重複宣告這些傳遞依賴。完成 Server Changelog 的 migration 後逐模組驗證：
./gradlew build
若 workspace 用 includeBuild("../appfuse-server") 做本地 composite build，版本化依賴會被
本地原始碼取代。驗證 registry artifact 前，須暫時停用 composite substitution 或在乾淨的
消費端環境重跑 build。
5. Migration 與驗證清單
- 所有
RemovedAPI 使用點已移除或替換。 - 所有
Breaking Changes的資料庫與設定遷移已完成。 - 若版本導入
persistence-encryption：保存 MailSetting credential 前已佈建 root key；若資料庫 確實有既有 credential，再依持久化資料加密指南 規劃專案專屬轉換。reference implementation 不提供 migration runner。 - Web peer dependencies 已對齊，框架版本不含
^／~。 - 所有 Web 消費模組 build/test 通過。
- 所有 Server 消費模組 build 通過，應用 context 可啟動。
- 重要 API、登入、檔案、通知與背景工作完成 smoke test。
-
/actuator/info或應用版本頁顯示預期版本與 build commit。 - 部署後重新檢查 Web Changelog 與 Server Changelog 中標記的安全與行為變更。
6. 發生問題時
| 症狀 | 優先檢查 |
|---|---|
| 找不到 pre-release 的版本區段 | 改讀 [Unreleased] |
| Web 升級後型別錯誤 | peer dependency 差異與 Removed API |
| Server 編譯失敗 | Breaking Changes、被移除類別／方法與 Maven 座標 |
| Server 啟動時 schema 失敗 | Changelog 中的 SQL migration 是否依順序執行 |
| 版號看似沒更新 | yalc、Gradle composite build 或快取是否仍取代 registry artifact |
版本政策與 pre-release 行為詳見版本編號規範。