Template
SkyJourney
b8b63282ee
P0 代码修复：删除 imSdkAppId、清除内网 IP 与原项目域名、修正 USE_MOCK 默认值 P1 CLAUDE.md 重组：零容忍规则前置，新增 dart-defines 字段对照表 P2 文档优化：先跑再配的 setup 流程，新增 architecture.md 架构图
226 lines
7.4 KiB
Markdown
226 lines
7.4 KiB
Markdown
# 项目配置指南
|
||
|
||
> **阅读顺序建议**：先跑起来（Step 1–2），再按需配置后续步骤。
|
||
> Android / iOS 平台专属配置见 [setup-android.md](setup-android.md) / [setup-ios.md](setup-ios.md)。
|
||
|
||
---
|
||
|
||
## 前提条件
|
||
|
||
| 工具 | 最低版本 | 说明 |
|
||
|------|---------|------|
|
||
| Flutter SDK | 3.41.0 | [flutter.dev/get-started](https://docs.flutter.dev/get-started/install) |
|
||
| Android Studio | Meerkat 2024.3 | 含 Android SDK API 34 |
|
||
| Xcode | 16.0 | 仅 iOS 开发需要（macOS 专属）|
|
||
| CocoaPods | 1.15+ | `sudo gem install cocoapods` |
|
||
|
||
```bash
|
||
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 # 拉取所有依赖（约 1 分钟）
|
||
make gen # 生成 .g.dart / .freezed.dart（约 1 分钟）
|
||
make gen-i18n # 生成 lib/i18n/strings.g.dart（秒级）
|
||
```
|
||
|
||
> 如果 `make gen` 报错，确认 `dart` 在 PATH 中：`dart --version`
|
||
|
||
---
|
||
|
||
## Step 2 — 立即运行（无需后端）
|
||
|
||
`dart-defines/dev.json` 默认开启 Mock 模式（`USE_MOCK=true`），App 使用 `assets/fixtures/` 下的预设 JSON 响应，**不需要任何后端服务**即可运行。
|
||
|
||
```bash
|
||
make run-dev
|
||
```
|
||
|
||
**期望结果：**
|
||
- ✅ App 启动，显示登录页（手机号 + SMS/密码双模式）
|
||
- ✅ 点击"发送验证码"→ 自动填入 `123456`（Mock 响应）
|
||
- ✅ 输入任意手机号 + `123456` 登录 → 跳转 Home 占位页
|
||
- ✅ 进入 Dev Panel（Talker 日志面板可正常显示请求日志）
|
||
|
||
> `flutter analyze` 输出约 103 条 `info` 提示，**这是正常的**（全为风格建议，0 errors）。
|
||
|
||
---
|
||
|
||
## Step 3 — 填入 API 路径
|
||
|
||
编辑 `lib/core/config/api_paths.dart`，将所有空字符串替换为实际后端路径：
|
||
|
||
```dart
|
||
// 示例（sa-token 后端）
|
||
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/user/profile';
|
||
static const String crashReport = '/sys/crash-report';
|
||
static const String errorReport = '/sys/error-report';
|
||
// ... 其余路径按业务填写
|
||
```
|
||
|
||
---
|
||
|
||
## Step 4 — 配置环境变量（连接真实后端）
|
||
|
||
### dart-defines 字段说明
|
||
|
||
| JSON 键 | 作用 | dev 默认 | 必须填写时机 |
|
||
|---------|------|---------|------------|
|
||
| `ENV` | 环境名（dev/test/release）| `dev` | 通常不改 |
|
||
| `API_BASE_URL` | 临时覆盖 baseUrl | 空 | 见下方说明 |
|
||
| `USE_MOCK` | 开启 Mock 模式 | `true` | 连真实后端时改 `false` |
|
||
| `INTERNAL_BUILD` | 显示 Dev Panel | `true` | 通常不改 |
|
||
| `SENTRY_DSN` | Sentry 上报地址 | 空 | prod 上线前 |
|
||
| `PINNED_FINGERPRINTS` | SSL 证书指纹 | 空 | 正式上线前 |
|
||
| `RSA_PUBLIC_KEY` | 密码加密公钥 | 空 | 登录加密时 |
|
||
|
||
### 方式 A：修改 api_config.dart（推荐，永久生效）
|
||
|
||
编辑 `lib/core/config/api_config.dart`：
|
||
|
||
```dart
|
||
return switch (Env.name) {
|
||
'dev' => 'http://192.168.1.100:8080', // ← 改为 dev 服务器
|
||
'test' => 'https://staging.your-domain.com', // ← 改为 staging 服务器
|
||
'release' => 'https://api.your-domain.com', // ← 改为生产服务器
|
||
_ => 'http://192.168.1.100:8080',
|
||
};
|
||
```
|
||
|
||
同时将 `dart-defines/dev.json` 中的 `USE_MOCK` 改为 `false`。
|
||
|
||
### 方式 B：临时覆盖（调试私有环境）
|
||
|
||
```bash
|
||
flutter run --flavor dev \
|
||
--dart-define-from-file=dart-defines/dev.json \
|
||
--dart-define=API_BASE_URL=http://192.168.1.200:8080 \
|
||
--dart-define=USE_MOCK=false
|
||
```
|
||
|
||
### 配置 RSA 公钥（密码加密）
|
||
|
||
若后端使用 RSA 加密传输密码，从后端获取公钥后填入各环境 JSON：
|
||
|
||
```bash
|
||
# 从 Java 后端 PEM 文件提取 Base64 DER（去掉 header/footer，合并为单行）
|
||
cat server-public.key | grep -v "BEGIN\|END" | tr -d '\n'
|
||
```
|
||
|
||
将结果填入 `dart-defines/dev.json` / `staging.json` / `prod.json` 的 `RSA_PUBLIC_KEY` 字段。
|
||
|
||
若后端**不需要** RSA 加密，修改 `auth_repository_impl.dart` 的 `loginWithPassword` 方法，将明文密码直接传入（或使用 HTTPS 保护）。
|
||
|
||
### 配置 SSL 证书指纹（生产必须）
|
||
|
||
```bash
|
||
# 获取服务器证书 SHA-256 指纹
|
||
echo | openssl s_client -connect api.your-domain.com:443 2>/dev/null \
|
||
| openssl x509 -fingerprint -sha256 -noout \
|
||
| sed 's/SHA256 Fingerprint=//'
|
||
```
|
||
|
||
将结果填入 `dart-defines/prod.json` 的 `PINNED_FINGERPRINTS` 字段（多个指纹用逗号分隔）。
|
||
|
||
### 配置生产环境（prod.json）
|
||
|
||
```bash
|
||
cp dart-defines/prod.json.template dart-defines/prod.json
|
||
# 编辑 prod.json，填入 Sentry DSN / 证书指纹 / RSA 公钥
|
||
```
|
||
|
||
> **prod.json 已在 .gitignore 中**，不会被提交。CI/CD 通过 secret 注入。
|
||
|
||
---
|
||
|
||
## Step 5 — 修改包名（业务项目必须）
|
||
|
||
### Android
|
||
|
||
`android/app/build.gradle.kts` → `defaultConfig.applicationId`：
|
||
|
||
```kotlin
|
||
defaultConfig {
|
||
applicationId = "com.your_company.your_app" // ← 修改
|
||
}
|
||
productFlavors {
|
||
create("dev") {
|
||
applicationIdSuffix = ".dev"
|
||
resValue("string", "app_name", "YourApp Dev") // ← 修改
|
||
}
|
||
create("staging") {
|
||
applicationIdSuffix = ".staging"
|
||
resValue("string", "app_name", "YourApp Beta") // ← 修改
|
||
}
|
||
create("prod") {
|
||
resValue("string", "app_name", "YourApp") // ← 修改
|
||
}
|
||
}
|
||
```
|
||
|
||
### iOS
|
||
|
||
打开 Xcode（必须用 `.xcworkspace`）：
|
||
```bash
|
||
open ios/Runner.xcworkspace
|
||
```
|
||
Runner Target → General → Bundle Identifier → 修改为实际 ID。
|
||
|
||
### pubspec.yaml + Dart 导入路径
|
||
|
||
```yaml
|
||
# pubspec.yaml
|
||
name: your_app_name # ← 修改
|
||
```
|
||
|
||
批量替换代码中的 package 名：
|
||
|
||
```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` 重新生成，确认 `flutter analyze` 无错误。
|
||
|
||
---
|
||
|
||
## Step 6 — 平台专属配置
|
||
|
||
| 需求 | 文档 |
|
||
|------|------|
|
||
| Android 签名 / Flavor 验证 / 发布包 | [setup-android.md](setup-android.md) |
|
||
| iOS Scheme / CocoaPods / 证书 / Archive | [setup-ios.md](setup-ios.md) |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
| 症状 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| `make gen` 报错 `dart: command not found` | Dart 不在 PATH | `export PATH="$PATH:/path/to/flutter/bin"` |
|
||
| `build_runner` 报 analyzer 版本冲突 | dependency_overrides 被修改 | 恢复 `drift: 2.31.0` 和 `json_serializable: 6.13.0` |
|
||
| App 启动后立即跳登录页 | 正常（未配置 token）| 用 Mock 登录验证，或连后端后正式登录 |
|
||
| Mock 登录后 Home 显示占位文字 | 正常（脚手架默认）| 实现 `routes.dart` 中 HomeRoute 的 build |
|
||
| `flutter analyze` 显示 103 issues | 正常（全为 info 级别）| 0 errors 即通过，info 为风格建议 |
|
||
| 连接后端但请求无响应 | api_config.dart 仍是占位 URL | 修改 api_config.dart 三套 baseUrl |
|
||
| iOS 真机崩溃，模拟器正常 | SecureStorage Keychain 权限 | 确认 Signing & Capabilities 配置正确 |
|