---
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 維度：

1.  **`project` 維度 (客戶/銷售場景區隔)**：
    *   **`General`** (通用主幹)：預設顯示付款方式選單（彈出 `BuyDialog`）。未來新客戶最常用此通用主幹。
    *   **`Chengwai`** (晟崴客製)：直接跳出員工卡刷卡畫面（彈出 `MemberCardPickupDialog`），不顯示付款選單。
    *   **`Cmuh`** (中國醫客製)：支援 QR Code 掃碼、處方籤醫令離線 AES 解密與解析領藥流程。
2.  **`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 發版配合流程

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