# Android 配置指南

本文档覆盖 Android 端从 Flavor 验证到正式签名发布包所需的全部配置步骤。

---

## 前提

- Android Studio Meerkat (2024.3) 或更高版本
- Android SDK：API 34（compileSdk）/ API 21（minSdk）
- JDK 17（Android Gradle Plugin 要求）
- 已完成 [setup-project.md](setup-project.md) 的 Step 1–4

---

## 1. 验证 Flavor 构建

脚手架预配置了三个 Flavor：`dev` / `staging` / `prod`，对应三套应用名和包名后缀。

```bash
# 确认三个 Flavor 都能构建（debug 模式，速度最快）
make build-apk-dev          # com.example.sunny_mochi.dev

flutter build apk --flavor staging --debug \
  --dart-define-from-file=dart-defines/staging.json
# com.example.sunny_mochi.staging

flutter build apk --flavor prod --debug \
  --dart-define-from-file=dart-defines/prod.json
# com.example.sunny_mochi
```

若构建失败，检查 `android/app/build.gradle.kts` 中的 `flavorDimensions` 和 `productFlavors` 配置。

---

## 2. 修改包名（业务项目必须）

编辑 `android/app/build.gradle.kts`，找到 `productFlavors` 和 `defaultConfig`：

```kotlin
defaultConfig {
    applicationId = "com.your_company.your_app"   // ← 修改
    // ...
}

productFlavors {
    create("dev") {
        applicationIdSuffix = ".dev"
        // applicationId 实际为 com.your_company.your_app.dev
        resValue("string", "app_name", "YourApp Dev")  // ← 修改应用名
    }
    create("staging") {
        applicationIdSuffix = ".staging"
        resValue("string", "app_name", "YourApp Beta") // ← 修改应用名
    }
    create("prod") {
        resValue("string", "app_name", "YourApp")      // ← 修改应用名
    }
}
```

同步修改 `android/app/src/main/AndroidManifest.xml` 确认使用 `@string/app_name`（脚手架默认已使用）。

---

## 3. 配置 Release 签名

### 3.1 生成 Keystore（首次）

```bash
mkdir -p android/keystore
keytool -genkey -v \
  -keystore android/keystore/release.jks \
  -alias your-key-alias \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000
```

> ⚠️ **Keystore 丢失无法找回，必须妥善保管。** 建议：
> - 备份到加密云存储（1Password / Bitwarden Vault）
> - CI/CD 系统通过 secret 变量注入，不放在仓库中
> - `android/keystore/` 目录已在 `.gitignore` 中

### 3.2 填写 key.properties

```bash
cp android/key.properties.template android/key.properties
```

编辑 `android/key.properties`（相对于 `android/app/` 目录）：

```properties
storePassword=your-keystore-password
keyPassword=your-key-password
keyAlias=your-key-alias
storeFile=../keystore/release.jks
```

> `key.properties` 已在 `android/.gitignore` 中，不会被提交。

### 3.3 验证签名配置

```bash
# 构建 staging release APK（使用 release 签名）
make build-staging

# 查看签名信息
apksigner verify --print-certs \
  build/app/outputs/flutter-apk/app-staging-release.apk
```

---

## 4. 配置 Firebase（可选）

若业务项目使用 Firebase（推送通知 / Analytics）：

1. 在 [Firebase Console](https://console.firebase.google.com) 为每个 Flavor 创建应用（不同包名）
2. 下载各包名对应的 `google-services.json`，放置到对应 Flavor 目录：

```
android/app/src/
├── dev/google-services.json
├── staging/google-services.json
└── main/google-services.json        # prod 用 main
```

3. 在 `android/app/build.gradle.kts` 添加 Google Services 插件：

```kotlin
plugins {
    // ...
    id("com.google.gms.google-services")
}
```

4. 将 `google-services.json` 加入 `.gitignore`（含 API key，勿提交）：

```
# 在根 .gitignore 中添加
**/google-services.json
```

> `google-services.json` 已在 `android/.gitignore` 中有注释行，取消注释即可。

---

## 5. 配置 ProGuard / R8（Release 混淆）

脚手架的 `android/app/build.gradle.kts` 已预启用 R8：

```kotlin
buildTypes {
    release {
        isMinifyEnabled = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
    }
}
```

`android/app/proguard-rules.pro` 中已预留 Drift / Sentry / Riverpod 保留规则注释，按需取消注释。

---

## 6. SQLCipher 注意事项

脚手架已在 `build.gradle.kts` 中处理 SQLCipher 的 native library 冲突：

```kotlin
packaging {
    jniLibs {
        pickFirsts += setOf("**/libsqlite3.so")
    }
}
```

若后续新增包时出现 `libsqlite3.so` 重复错误，在此处追加相同模式即可。

---

## 7. CI/CD 构建（示例：GitHub Actions）

以下为生产包构建的 workflow 关键步骤：

```yaml
- name: Decode keystore
  run: |
    echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 --decode \
      > android/keystore/release.jks

- name: Write key.properties
  run: |
    cat > android/key.properties <<EOF
    storePassword=${{ secrets.KEYSTORE_PASSWORD }}
    keyPassword=${{ secrets.KEY_PASSWORD }}
    keyAlias=${{ secrets.KEY_ALIAS }}
    storeFile=../keystore/release.jks
    EOF

- name: Write prod.json
  run: |
    echo '${{ secrets.PROD_DART_DEFINES }}' > dart-defines/prod.json

- name: Build AAB
  run: make build-prod
```

Secrets 清单：`KEYSTORE_BASE64`、`KEYSTORE_PASSWORD`、`KEY_PASSWORD`、`KEY_ALIAS`、`PROD_DART_DEFINES`

---

## 常见问题

### Gradle sync 失败，报找不到 compileSdk

确认 Android SDK Platform 34 已安装（Android Studio → SDK Manager → Android 14）。

### `libsqlite3.so` duplicate 错误

在 `build.gradle.kts` 的 `packaging.jniLibs.pickFirsts` 中追加冲突的 .so 路径。

### Release APK 运行时崩溃，Debug APK 正常

通常是 ProGuard 混淆了不应混淆的类。查看 `build/outputs/mapping/` 下的 `seeds.txt` 和 Logcat，在 `proguard-rules.pro` 添加对应的 `-keep` 规则。

### 签名 APK 安装时提示"应用已安装但签名不同"

设备上已安装其他签名版本，需先卸载再安装，或换测试设备。