Template
docs: 新增完整文档体系（setup-project / setup-android / setup-ios / CLAUDE.md）
This commit is contained in:
SkyJourney
@@ -0,0 +1,234 @@
|
||||
# 项目配置指南（所有开发者必读）
|
||||
|
||||
本文档覆盖从克隆脚手架到可以运行第一个 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。
|
||||
Reference in New Issue
Block a user