---
description: 自動編譯正式發行 Release APK、升級 Patch 版本號、並產出公司 OTA 平台必備之 Keyin 參考資料
---

# 生產環境發版打包工作流 (release-apk)

這個 Workflow 專門為應用程式「生產環境上線/發版」設計。當您準備好將特定客戶的最新功能派送至實體販賣機時，呼叫 `/release-apk` 將自動為您完成嚴格的發行檢查、版號遞增、Release 簽章打包與發版資訊生成。

> [!TIP]
> **支援參數化指定編譯變體：**
> * 預設（不帶參數）：打包 **`Chengwai` (晟崴客製正式版)**。
> * 您可以呼叫 `/release-apk General`（或 `general`）打包 **`General` (通用正式版)**。
> * 您可以呼叫 `/release-apk Cmuh`（或 `cmuh`）打包 **`Cmuh` (中國醫客製正式版)**。

---

## 步驟零：發行檢查與版號自動遞增 (OTA 鐵律)
為了確保實體機台能夠順利觸發 OTA 自動下載覆蓋安裝，新編譯的 `versionCode` 必須嚴格大於現場的舊版號：
1. AI 助手將讀取 `app/build.gradle` 並自動將 `verPatch`（修補版號）**遞增 1**（例如從 `8` 自動升級為 `9`），確保 versionCode 順利變大。
2. 自動在 terminal 呈報即將打包的最新版本號資訊。

## 步驟一：清理快取並進行正式簽章編譯
採用單次 JVM 進程強制重新編譯，以確保代碼 100% 乾淨，並執行 Release 模式下的**代碼優化、混淆、與嚴格的 `lintVital` 審查**。

```bash
// turbo
# 終止殘留的 Gradle Daemon 程序，避免多個 Daemon 互搶資源，同時避免誤殺 VS Code Gradle 擴充功能
./gradlew --stop 2>/dev/null; pkill -9 -f "org.gradle.launcher.daemon.bootstrap.GradleDaemon" 2>/dev/null; sleep 3

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
cd /home/mama/projects/TaiwanStar_general_size_s_Chengwai

# 取得目標 Flavor 參數（預設為 Chengwai，支援 General, Chengwai, Cmuh）
TARGET_FLAVOR="Chengwai"
if [ -n "$1" ]; then
    TARGET_FLAVOR=$(echo "$1" | awk '{print toupper(substr($0,1,1))tolower(substr($0,2))}')
fi

# 安全防護：檢查是否為支援的客製項目
if [ "$TARGET_FLAVOR" != "General" ] && [ "$TARGET_FLAVOR" != "Chengwai" ] && [ "$TARGET_FLAVOR" != "Cmuh" ]; then
    echo "❌ 不支援的 Flavor: $TARGET_FLAVOR，請使用 General, Chengwai 或 Cmuh。"
    exit 1
fi

# 根據專案 Flavor 判定硬體 Flavor（中國醫 Cmuh 使用 S9XYU，其餘使用 S12XYU）
HW_FLAVOR="S12XYU"
if [ "$TARGET_FLAVOR" = "Cmuh" ]; then
    HW_FLAVOR="S9XYU"
fi

echo "📦 [Release] 開始編譯正式版變體: ${TARGET_FLAVOR}${HW_FLAVOR}Release"

# 使用 clean 確保完整重新編譯，避開 incremental 快取問題
./gradlew clean :app:assemble${TARGET_FLAVOR}${HW_FLAVOR}Release --no-daemon
```

## 步驟二：導出正式 APK 並產出後台 Keyin 派送參考資料
將封裝完畢、具備正式簽章的 APK 導出至最外層 `outputs/` 資料夾，並自動計算產出公司 OTA 派送後台所需的全部對照資料。

```bash
// turbo
cd /home/mama/projects/TaiwanStar_general_size_s_Chengwai
mkdir -p outputs

# 取得 Flavor 參數
TARGET_FLAVOR="Chengwai"
if [ -n "$1" ]; then
    TARGET_FLAVOR=$(echo "$1" | awk '{print toupper(substr($0,1,1))tolower(substr($0,2))}')
fi

HW_FLAVOR="S12XYU"
if [ "$TARGET_FLAVOR" = "Cmuh" ]; then
    HW_FLAVOR="S9XYU"
fi

# 動態尋找編譯產出的最新正式版 APK 檔案
APK_SOURCE=$(find app/build/outputs/apk/${TARGET_FLAVOR}${HW_FLAVOR}/release/ -name "app-S_*_${TARGET_FLAVOR}-*-release.apk" | head -n 1)

if [ -n "$APK_SOURCE" ]; then
    APK_NAME=$(basename "$APK_SOURCE")
    APK_DEST="outputs/$APK_NAME"
    cp "$APK_SOURCE" "$APK_DEST"
    echo "=================================================="
    echo "✅ 正式版 APK 封裝成功，已導出至：$APK_DEST"
    echo "=================================================="
    
    # 提取與計算版本資訊
    MINOR=$(grep "def verMinor" app/build.gradle | awk '{print $4}')
    PATCH=$(grep "def verPatch" app/build.gradle | awk '{print $4}')
    
    # 根據硬體規格決定 Major (S9XYU 為 21 吋，S12XYU 為 10 吋)
    if [ "$HW_FLAVOR" = "S9XYU" ]; then
        MAJOR=21
    else
        MAJOR=10
    fi
    
    VERSION_NAME="${MAJOR}_0${MINOR}_${PATCH}_R"
    VERSION_CODE=$((MAJOR * 10000 + MINOR * 100 + PATCH))
    FLAVOR="${TARGET_FLAVOR}${HW_FLAVOR}"
    
    echo "🚀 實體販賣機 OTA 後台新增版本 Keyin 參考資料："
    echo "--------------------------------------------------"
    echo "1. 專案/客戶風味 (Flavor)     : $FLAVOR"
    echo "2. 版本代碼 (versionCode)     : $VERSION_CODE"
    echo "3. 版本名稱 (versionName)     : $VERSION_NAME"
    echo "4. 螢幕吋數 (Screen Size)     : ${MAJOR} 吋"
    echo "5. 正式版 APK 檔名             : $APK_NAME"
    echo "--------------------------------------------------"
    echo "📢 [溫馨提醒] 請將此 APK 上傳至 OTA 平台，並設定為對應機型的強迫升級。"
    echo "=================================================="
else
    echo "❌ 找不到編譯產出的正式版 APK 檔案，封裝失敗！"
    exit 1
fi
```

## 步驟三：自動化 Git 發版標記引導
為了落實公司發版規範第 5 條「必須在主分支合併節點打上 Git Tag，以利日後追溯特定現場機台的版本程式碼」，AI 助手會自動為您計算出對應的版本 Tag 標籤與提示：

```bash
// turbo
MAJOR=$(grep "def verMajor" app/build.gradle | awk '{print $4}')
MINOR=$(grep "def verMinor" app/build.gradle | awk '{print $4}')
PATCH=$(grep "def verPatch" app/build.gradle | awk '{print $4}')
TAG_NAME="v${MAJOR}.${MINOR}.${PATCH}"

echo "=================================================="
echo "🔔 Git 發版追溯標記指南"
echo "--------------------------------------------------"
echo "請在專案合併回 main 分支後，執行以下指令打上發版 Tag："
echo "git tag -a $TAG_NAME -m \"TaiwanStar 發版 - 版本 $TAG_NAME\""
echo "git push origin $TAG_NAME"
echo "=================================================="
```
