版本編號規範

AppFuse 依產物是否被其他模組依賴，採用兩套版本策略：

層級	產物	策略	版本回答的問題
框架層	appfuse-web、appfuse-server	SemVer	升級會不會影響相容性？
參考實作層	所有 app-* 模組	CalVer	這是哪一次應用釋出？

目前實際版號會在文檔站導覽列顯示。該徽章於建置時分別讀取 appfuse-web/package.json 與 appfuse-server/gradle.properties，不由本頁手動維護。

框架層：SemVer

appfuse-web 跟隨 React 主版本，appfuse-server 跟隨 Spring Boot 主版本：

MAJOR.MINOR.PATCH[-alpha.N|-beta.N|-rc.N|-SNAPSHOT]

段位	正式版的演進規則
PATCH	修正缺陷，不新增、deprecate 或移除 public API
MINOR	新增 API、deprecate API，或移除已 deprecated 至少兩個 minor 的 API
MAJOR	跨底層框架主版本，或進行重大架構變更

日常發布使用不可變 pre-release

框架發展期的日常通道是精確版號的不可變 pre-release，例如 19.0.0-alpha.N、4.0.0-alpha.N：

• 發布到 release registry，不覆寫既有版本。
• 消費端必須 pin 精確版號，不使用 ^、~ 或浮動版本。
• SNAPSHOT 僅保留給 Server 的本機或實驗用途，不是 fleet 的日常消費通道。
• pre-release 可有 breaking change，不受正式版的 deprecation cycle 約束；但所有移除與 migration 仍必須寫入 Changelog。

Deprecation cycle

正式版 API 從 deprecated 到移除，至少跨兩個 minor：

Deprecated	最早移除
4.1.0	4.3.0
19.2.0	19.4.0

Java API 使用 @Deprecated(since = "...", forRemoval = true)；TypeScript API 使用 @deprecated JSDoc，並同時在 Changelog 的 Deprecated 區段記錄 replacement 與預計移除版本。

Changelog 與版本的關係

框架 Changelog 是升級合約，不是發布摘要：

• Web Changelog
• Server Changelog

正式版發布時，[Unreleased] 會改名為該正式版本；pre-release 發布則不消費 [Unreleased]。因此：

升級目標	應讀區段
正式版，例如 19.0.0	## [19.0.0]
Pre-release，例如 19.0.0-alpha.N	## [Unreleased]

pre-release 的 [Unreleased] 會涵蓋整條開發線，可能大於單次版本差異。升級工具會以 Removed 清單掃描消費端實際使用處，因此這種保守涵蓋是刻意設計。

完整操作流程見框架升級指南。

參考實作層：CalVer

所有帶版本檔的 app-* 模組共享同一個純 CalVer：

YYYY.N.P

欄位	意義
YYYY	發布年份
N	該年第幾個里程碑 release
P	該 release 內的修補序

參考實作不帶 -SNAPSHOT。Web、server family 是版本 bump 的驅動集；mockup、host、docs 等支援模組在切版時被動 stamp 成同一版號。切版由 release-app workflow 原子完成， 並建立 app-v{version} tag。

版本的事實來源

產物	事實來源
appfuse-web	appfuse-web/package.json
appfuse-server	appfuse-server/gradle.properties
參考實作整體	release.json，並同步到各 app-* 的版本檔
文檔站框架徽章	建置時讀取上述 Web／Server 版本檔

不要在指南中另外維護「當前版本」表格。需要查詢最新可用版本時，應使用 registry、 文檔站版本徽章與對應 Changelog。

常見問題

為什麼 Web 與 Server 的主版本不同？

它們跟隨不同的底層框架：Web 跟隨 React，Server 跟隨 Spring Boot。兩者各自發布與升級， 不要求版號一致。

為什麼 alpha 也必須 pin 精確版號？

pre-release 允許 breaking change。若使用範圍版本，自動安裝到下一個 alpha 可能在未審閱 Changelog 的情況下破壞建置；精確 pin 讓升級成為明確、可驗證的動作。

文檔站為什麼同時顯示兩個框架版本？

同一站點同時服務 Web 與 Server，而兩套框架獨立發布。雙徽章比讓文檔站假裝只有一個版本 更能準確表達內容基線。