docs: 新增完整文档体系（setup-project / setup-android / setup-ios / CLAUDE.md）

2026-05-14 13:04:51 +08:00
parent bb07828234
commit a266323905
5 changed files with 1065 additions and 169 deletions
@@ -0,0 +1,233 @@
+# 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 安装时提示"应用已安装但签名不同"
+
+设备上已安装其他签名版本，需先卸载再安装，或换测试设备。