terrylee/TaiwanStar_general_size_s_Chengwai

sky121113 3409f93f07 [REFACTOR] 重構銷售流程至雙維度 Flavor 架構、統一忙碌狀態並修正版本規範

1. 引進 SaleFlowHandler 與 SaleFlowCallback 介面，分離通用版 (General)、晟崴版 (Chengwai) 與中國醫版 (Cmuh) 的前台銷售進入點，降低 FontendActivity 耦合度。
2. 建立 src/Chengwai/、src/Cmuh/、src/General/ 目錄，將客製 dialog（如 FontendPickupCodeDialog、TakeMedicineDialog）與 layout 移入對應的專屬目錄。
3. 統一狀態檢查機制，將全專案背景排程、定時重啟與日誌備份中的舊 isShowDialog() 替換為更安全的 isMachineBusy()；於 NFC 交易與鍵盤 Enter 防誤觸中特意保留原 isShowDialog() 以守護安全性防線。
4. 修正英文 values-en/strings.xml 缺漏與預設 locale 對齊的 sync_product/sync_product_warning，解決 lintVital 報告的 ExtraTranslation 錯誤，使 Release 打包 100% 成功。
5. 微調 app/build.gradle，將起點版號重置為 10_01_1，自動連動 versionCode 100101 與 versionName 10_01_1_R。
6. 修正 .agents/rules/versioning.md 規範，將 S 修正為「來源 (Source)」，將 verMajor 修正為「螢幕大小」，並補齊官方命名規範對照圖表與欄位解析。
7. 升級一鍵編譯 /compiler-apk（新增中文與英文別名智慧防呆映射）與新建發版 /release-apk 工作流。

2026-05-27 14:48:22 +08:00

4.6 KiB

Raw Blame History

trigger
always_on

TaiwanStar 專案版號與發版規範

本規範定義了本專案（販賣機機台 App）的版號命名、自動化計算、實體機台 OTA 更新原則，以確保後續開發與發版時版本管理高度穩定。

1. 雙版號動態計算機制 (Double Versioning Scheme)

本專案採用三段式版號變數進行自動化計算，所有配置皆於 app/build.gradle 頂部定義。

Important

開發人員與 AI 助手在修改版號時，嚴禁直接寫死 versionCode 或 versionName，必須透過修改 Gradle 頂部的變數來進行。

verMajor (螢幕大小)：代表實體機台的螢幕吋數（例如 10 代表 10 吋螢幕）。
verMinor (次版號)：代表新增商業功能、硬體支援，但向下相容（例如 8）。
verPatch (修補版號)：代表 Bug 修復、小優化（例如 5）。

計算公式：

versionCode = verMajor * 10000 + verMinor * 100 + verPatch
versionName = "${verMajor}_0${verMinor}_${verPatch}_R"

2. 公司官方命名規範對照

依據公司標準規範，實體機台發佈之 APK 與版本名稱需嚴格符合以下欄位對照：

來源 _ 安卓號 _ 主板號 _ 機器系列 _ 專案名稱 _ 螢幕大小 _ 次版號 _ 修補版號 _ 環境
S    _ 12    _ XY    _ U        _ Chengwai _ 10       _ 08     _ 8        _ R

欄位解析：

S (來源 / Source)：代表程式碼與專案來源（非螢幕尺寸）。
12 (安卓號)：Android 系統主版本號。
XY (主板號)：主板型號規格。
U (機器系列 / 機型規格)：例如代表 U 系列機型。
Chengwai (專案名稱)：客戶/銷售場景專案代碼（如 General, Chengwai, Cmuh）。
10 (螢幕大小)：對應 Gradle 中的 verMajor。
08 (次版號)：對應 Gradle 中的 verMinor（格式化為雙位數）。
8 (修補版號)：對應 Gradle 中的 verPatch。
R (環境)：環境代碼，例如 R 代表 Release 生產環境。

3. 實體機台 OTA 自動更新鐵律

因為本 App 部署於實體販賣機，更新主要透過後台進行遠端自動下載覆蓋安裝 (OTA)。

Caution

每次釋出任何新版 APK 至生產環境，versionCode 必須嚴格大於前一次發佈的數值！

若 versionCode 相同，即便 versionName 不同（例如從 10_08_2_R 改為 10_08_5_R），機台下載後也會因 INSTALL_FAILED_ALREADY_EXISTS 錯誤而拒絕覆蓋安裝，導致遠端自動升級完全失效。

4. 雙維度產品風味 (Product Flavors) 與 APK 命名規範

本專案採用雙維度 Flavor 架構，以完美分離「客戶銷售場景」與「底層硬體規格」，方便後續快速擴充。

4.1 雙維度定義 (flavorDimensions)

本專案於 app/build.gradle 中定義了兩個 Flavor 維度：

project 維度 (客戶/銷售場景區隔)：
- General (通用主幹)：預設顯示付款方式選單（彈出 BuyDialog）。未來新客戶最常用此通用主幹。
- Chengwai (晟崴客製)：直接跳出員工卡刷卡畫面（彈出 MemberCardPickupDialog），不顯示付款選單。
- Cmuh (中國醫客製)：支援 QR Code 掃碼、處方籤醫令離線 AES 解密與解析領藥流程。
hardware 維度 (硬體與系統規格區隔)：
- S12XYU：代表 S (來源) + 12 (安卓號) + XY (主板號) + U (機器系列/機型規格)。

4.2 實體機台 APK 命名鐵律

為了符合實體機台 OTA 平台發佈規範，打包輸出的 APK 檔名必須嚴格連動雙維度，並遵循以下格式： app-[格式化硬體規格]_[專案名稱]-[版本號]-[BuildType].apk

格式化規則：S12XYU 會在 Gradle 打包時被自動展開格式化為 S_12_XY_U。
輸出檔名範例：
- app-S_12_XY_U_General-10_08_8_R-release.apk
- app-S_12_XY_U_Chengwai-10_08_8_R-release.apk
- app-S_12_XY_U_Cmuh-10_08_8_R-release.apk
注意：此檔名轉換規則已完全由 app/build.gradle 頂部 Gradle 變數與 applicationVariants.all 自動連動生成，嚴禁手動修改輸出檔名。

5. Git 發版配合流程

自 develop 拉出 release/10.8.5 發版分支。
遞增 app/build.gradle 中的 verPatch 變數並 Commit。
測試無誤後，合併回 main 與 develop。
必須在 main 合併節點打上 Git Tag，格式為 v[Major].[Minor].[Patch]（例如 v10.8.5），以便日後追溯特定現場機台的版本程式碼。

4.6 KiB Raw Blame History Unescape Escape