---
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        _ 10       _ 08     _ 8        _ R
```

### 欄位解析：
*   **`S` (來源 / Source)**：代表程式碼與專案來源（**非螢幕尺寸**）。
*   **`12` (安卓號)**：Android 系統主版本號。
*   **`XY` (主板號)**：主板型號規格。
*   **`U` (機器系列 / 機型規格)**：例如代表 U 系列機型。
*   **`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. 單維度硬體規格 (Hardware Flavor) 與 APK 命名規範

本專案原本採用雙維度，但目前客戶專案（購買流程）已收斂為執行期 `shopping_mode`（雲端 B014 下發）動態決定，因此不再使用 flavor 分家。
目前僅保留**單一維度 `hardware`**，專門處理底層硬體規格差異。

### 4.1 硬體維度定義 (flavorDimensions)
本專案於 `app/build.gradle` 中定義了唯一的 Flavor 維度 `hardware`：

*   **`S12XYU`** (10 吋預設硬體)：代表 `S` (來源) + `12` (安卓號) + `XY` (主板號) + `U` (機器系列/機型規格)。
*   **`S9XYU`** (21.5 吋硬體)：代表中國醫現場使用的 Android 9 / 21.5 吋硬體規格。

### 4.2 Flavor 驗證與編譯指令選擇

修改後，必須編譯對應硬體規格的 Gradle variant，不可只用通用 `assembleDebug`：

*   **10 吋一般機台版 (含晟崴、通用等)**：`./gradlew :app:assembleS12XYUDebug --no-daemon`
*   **21.5 吋中國醫等大螢幕機台版**：`./gradlew :app:assembleS9XYUDebug --no-daemon`

### 4.3 實體機台 APK 命名鐵律
為了符合實體機台 OTA 平台發佈規範，打包輸出的 APK 檔名必須遵循以下格式：
`app-[格式化硬體規格]-[版本號]-[BuildType].apk`

*   **格式化規則**：`S12XYU` 會在 Gradle 打包時被自動展開格式化為 `S_12_XY_U`。
*   **輸出檔名範例**：
    *   `app-S_12_XY_U-10_08_8_R-release.apk`
    *   `app-S_9_XY_U-21_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`），以便日後追溯特定現場機台的版本程式碼。