terrylee/TaiwanStar_general_size_s_Chengwai

sky121113 0637f71e34 [FIX] 優化機台鎖定防護流程與遞增版本號

1. 遞增修補版號 verPatch 至 67 以落實機台 OTA 更新規範。
2. 於 FontendActivity 的 onCreate 流程新增機台鎖定狀態檢查，若鎖定則強制跳轉至 MaintenanceActivity 並清除 Activity 棧。
3. 修正 MqttService 的鎖定命令跳轉旗標，改用 Intent.FLAG_ACTIVITY_CLEAR_TASK 確保舊 Activity 棧被完整清理。
4. 移除 AppUtils 中未使用的 MqttManager 引用。

2026-06-04 16:07:31 +08:00

5.3 KiB

Raw Permalink 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 (機器系列/機型規格)。
- S9XYU：代表中國醫現場使用的 Android 9 / 21.5 吋硬體規格；除非明確指定中國醫 10 吋或 S12XYU，中國醫 (Cmuh) 相關修正與驗證預設必須使用此硬體 flavor。

4.2 Flavor 驗證與編譯指令選擇

針對特定客戶或現場問題修改後，必須編譯對應的 Gradle variant，不可只用通用 assembleDebug 或錯誤硬體 flavor 代替。

中國醫現場版 (Cmuh) 驗證指令：./gradlew :app:assembleCmuhS9XYUDebug --no-daemon
晟崴版 (Chengwai) 預設驗證指令：./gradlew :app:assembleChengwaiS12XYUDebug --no-daemon
通用版 (General) 預設驗證指令：./gradlew :app:assembleGeneralS12XYUDebug --no-daemon

4.3 實體機台 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），以便日後追溯特定現場機台的版本程式碼。

5.3 KiB Raw Permalink Blame History Unescape Escape