# 项目配置指南（所有开发者必读）

本文档覆盖从克隆脚手架到可以运行第一个 dev 包所需的全部步骤。  
Android 和 iOS 的平台专属配置请分别参阅 [setup-android.md](setup-android.md) 和 [setup-ios.md](setup-ios.md)。

---

## 前提条件

| 工具 | 最低版本 | 安装方式 |
|------|---------|---------|
| Flutter SDK | 3.41.0 | [flutter.dev](https://docs.flutter.dev/get-started/install) |
| Dart SDK | 3.7.0 | 随 Flutter 一起安装 |
| Android Studio | Meerkat (2024.3) | [developer.android.com](https://developer.android.com/studio) |
| Xcode | 16.0 | Mac App Store（仅 iOS 开发需要）|
| CocoaPods | 1.15+ | `sudo gem install cocoapods` |
| make | 系统内置 | macOS/Linux 自带；Windows 用 Git Bash 或 WSL |

验证安装：
```bash
flutter --version   # 应显示 ≥ 3.41.0
flutter doctor      # 确认 Android toolchain + Xcode 全绿
```

---

## Step 1 — 克隆与初始化

```bash
git clone https://gitea.example.com/your-org/your-project.git  # TODO: 替换实际地址
cd your-project

flutter pub get          # 拉取所有依赖
make gen                 # 生成 .g.dart / .freezed.dart（约 1 分钟）
make gen-i18n            # 生成 lib/i18n/strings.g.dart
```

> **注意**：如果 `make gen` 报错 `build_runner` 找不到，请先确认 `dart` 在 PATH 中：
> ```bash
> dart --version
> ```

---

## Step 2 — 填入项目 API 路径

编辑 `lib/core/config/api_paths.dart`，将所有空字符串替换为实际后端路径：

```dart
// 示例（sa-token + Spring Boot）
static const String authLoginSms  = '/sys/auth/sms-login';
static const String authLoginPwd  = '/sys/auth/password-login';
static const String authSmsSend   = '/sys/auth/send-sms';
static const String authLogout    = '/sys/auth/logout';
static const String authRefresh   = '/sys/auth/refresh-token';
static const String userProfile   = '/sys/sys-user/app/userInfo';
// ... 其余路径按业务填写
```

所有 datasource 文件通过 `ApiPaths.xxx` 引用路径，**严禁字符串字面量散落**。

---

## Step 3 — 配置环境变量（dart-defines）

### 3.1 开发环境（dev.json）

```bash
# 直接编辑，此文件可提交（含占位符，无真实密钥）
nano dart-defines/dev.json
```

需填入的字段：

```json
{
  "ENV": "dev",
  "USE_MOCK": "true",          // true = 使用 Mock Adapter（不调真实服务）
  "INTERNAL_BUILD": "true",    // true = 显示 Dev Panel 入口
  "SENTRY_DSN": "",            // dev 通常留空
  "PINNED_FINGERPRINTS": "",   // 证书指纹（dev 可留空跳过 SSL 绑定）
  "API_BASE_URL": "http://192.168.1.100:8080",  // TODO: 实际 dev 服务器
  "RSA_PUBLIC_KEY": "MIIBIjANBg..."              // TODO: 后端 RSA 公钥（Base64 DER）
}
```

### 3.2 测试环境（staging.json）

```json
{
  "ENV": "test",
  "USE_MOCK": "false",
  "INTERNAL_BUILD": "true",
  "SENTRY_DSN": "",
  "PINNED_FINGERPRINTS": "",
  "API_BASE_URL": "https://staging.your-domain.com",  // TODO
  "RSA_PUBLIC_KEY": "MIIBIjANBg..."                    // TODO
}
```

### 3.3 生产环境（prod.json）

```bash
cp dart-defines/prod.json.template dart-defines/prod.json
nano dart-defines/prod.json
```

```json
{
  "ENV": "prod",
  "USE_MOCK": "false",
  "INTERNAL_BUILD": "false",
  "SENTRY_DSN": "https://xxx@sentry.io/yyy",   // TODO: Sentry 项目 DSN
  "PINNED_FINGERPRINTS": "AA:BB:CC:...",        // TODO: 服务器证书 SHA-256 指纹
  "API_BASE_URL": "https://api.your-domain.com",// TODO
  "RSA_PUBLIC_KEY": "MIIBIjANBg..."             // TODO
}
```

> **prod.json 已在 .gitignore 中**，不会被提交。CI/CD 系统通过 secret 变量注入。

### 获取 RSA 公钥

后端一般提供 RSA 公钥的 Base64 DER 编码。若后端使用 sa-token + RSA：

```bash
# Java 后端：从 public.key 文件提取（去掉 PEM header/footer，拼接成单行）
cat public.key | grep -v "BEGIN\|END" | tr -d '\n'
```

### 获取证书 SHA-256 指纹

```bash
# 方法 1：openssl（推荐）
echo | openssl s_client -connect api.your-domain.com:443 2>/dev/null \
  | openssl x509 -fingerprint -sha256 -noout \
  | sed 's/SHA256 Fingerprint=//'

# 方法 2：Chrome → 锁图标 → 证书 → 指纹
```

---

## Step 4 — 验证首次运行

```bash
# 方式 1：使用 Mock（推荐首次验证，不需要后端服务）
# 确保 dart-defines/dev.json 中 USE_MOCK=true
make run-dev

# 方式 2：连接真实后端
# 确保 dart-defines/dev.json 中 USE_MOCK=false + API_BASE_URL 已填入
make run-dev
```

**期望结果：**
- APP 启动，显示登录页（手机号 + SMS/密码双模式）
- 右上角（或侧滑）可进入 Dev Panel（Talker 日志面板）
- `flutter analyze` 输出 `103 issues found`（均为 info 级别，0 errors）

---

## Step 5 — 更新包名（业务项目必须）

脚手架默认包名为 `com.example.sunny_mochi`，接手后必须替换：

### Android
编辑 `android/app/build.gradle.kts`：
```kotlin
// dev Flavor
applicationId = "com.your_company.your_app.dev"

// staging Flavor
applicationId = "com.your_company.your_app.staging"

// prod / release
defaultConfig {
    applicationId = "com.your_company.your_app"
}
```

### iOS
在 Xcode 中修改 Bundle Identifier（见 [setup-ios.md](setup-ios.md) Step 3）。

### pubspec.yaml + Dart 导入路径
```yaml
name: your_app_name   # 修改后所有 import 路径也需要更新
```

批量替换导入：
```bash
# macOS / Linux
find lib -name "*.dart" -exec sed -i '' 's/package:sunny_mochi/package:your_app_name/g' {} \;

# Windows PowerShell
Get-ChildItem -Path lib -Recurse -Filter "*.dart" |
  ForEach-Object { (Get-Content $_.FullName) -replace 'sunny_mochi', 'your_app_name' |
  Set-Content $_.FullName }
```

运行 `make gen` 重新生成后确认无编译错误。

---

## Step 6 — 平台专属配置

- **Android**（签名 / Flavor 验证 / 发布包构建）→ [setup-android.md](setup-android.md)
- **iOS**（Xcode Scheme / CocoaPods / 证书 / Archive）→ [setup-ios.md](setup-ios.md)

---

## 常见问题

### `build_runner` 生成失败，报 analyzer 版本冲突

确认 `pubspec.yaml` 中的 `dependency_overrides`：
```yaml
dependency_overrides:
  drift: 2.31.0
  json_serializable: 6.13.0
```
若被修改，恢复后重跑 `flutter pub get && make gen`。

### App 启动后 token 丢失 / 每次重启都跳登录

SecureStorage 在 iOS Simulator 上可能行为异常。请在真机测试，或检查 `Keychain Sharing` 是否开启。

### Mock 模式下请求崩溃 `Unable to load asset`

检查 `assets/fixtures/` 下是否有对应的 JSON 文件，且 `pubspec.yaml` 中的 `assets:` 包含了对应子目录。

### `flutter analyze` 报错（非 info 级别）

先运行 `make gen` 确保生成文件是最新的，再重新 analyze。