Template
124 lines
4.8 KiB
Markdown
124 lines
4.8 KiB
Markdown
# sunny_mochi — Flutter 企业级脚手架
|
||
|
||
基于 Flutter 3.x 的企业级 APP 脚手架，开箱即用的基础设施底座。
|
||
|
||
## 包含能力
|
||
|
||
| 模块 | 说明 |
|
||
|------|------|
|
||
| Flavor 三包 | dev / staging / prod 环境共存 |
|
||
| 加密数据库 | Drift + SQLCipher AES-256 |
|
||
| 网络层 | 7 拦截器 Dio（Token 刷新互斥、证书绑定、错误映射） |
|
||
| 崩溃日志 | 同步写文件 + 启动时弹窗上报 |
|
||
| 错误分类 | Sealed Failure 体系（Network / Auth / Server / Cache） |
|
||
| 主题系统 | 5 套色板 + 深色模式 + Riverpod 持久化 |
|
||
| 开发者面板 | Talker UI（Internal 包可见，Release 编译期关闭） |
|
||
| 认证骨架 | Clean Architecture：手机号 + 短信 / 密码双模式登录 |
|
||
| 本地错误日志 | 查看 + 一键上报 |
|
||
| i18n | Slang 4.x（zh-CN 基准 + en 备用） |
|
||
|
||
---
|
||
|
||
## 克隆后首次设置
|
||
|
||
### 1. 安装依赖
|
||
```bash
|
||
flutter pub get
|
||
```
|
||
|
||
### 2. 代码生成
|
||
```bash
|
||
make gen # build_runner → .g.dart / .freezed.dart
|
||
make gen-i18n # slang → lib/i18n/strings.g.dart
|
||
```
|
||
|
||
### 3. 填入项目 API 路径
|
||
编辑 `lib/core/config/api_paths.dart`，将所有空字符串替换为实际路径。
|
||
|
||
### 4. 配置 Android 签名（发布版必须）
|
||
```bash
|
||
cp android/key.properties.template android/key.properties
|
||
# 编辑 key.properties，填入 keystore 路径和密码
|
||
```
|
||
|
||
### 5. 配置生产环境变量
|
||
```bash
|
||
cp dart-defines/prod.json.template dart-defines/prod.json
|
||
# 编辑 prod.json，填入 Sentry DSN、RSA 公钥等
|
||
```
|
||
|
||
### 6. iOS（首次或 Pod 变更后）
|
||
```bash
|
||
cd ios && pod install && cd ..
|
||
```
|
||
|
||
---
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
make run-dev # 开发版调试运行
|
||
make run-staging # 测试版 Release 运行
|
||
make build-staging # 打测试包 APK
|
||
make build-prod # 打正式版 AAB（需先配置 prod.json + key.properties）
|
||
make gen # 代码生成
|
||
make gen-i18n # i18n 生成
|
||
flutter analyze # 静态分析（目标 0 errors）
|
||
flutter test # 单元测试
|
||
```
|
||
|
||
---
|
||
|
||
## 新项目初始化清单
|
||
|
||
- [ ] 替换包名 `com.example.sunny_mochi` → 项目包名（`android/app/build.gradle.kts` + `pubspec.yaml`）
|
||
- [ ] 填入 API 路径（`lib/core/config/api_paths.dart`）
|
||
- [ ] 配置 `android/key.properties`（从 `key.properties.template` 复制）
|
||
- [ ] 配置 `dart-defines/prod.json`（从 `prod.json.template` 复制）
|
||
- [ ] 替换 App 名称（`android/app/build.gradle.kts` `resValue`、`ios/Runner/Info.plist`）
|
||
- [ ] 替换 App Icon（`android/app/src/main/res/mipmap-*/`、`ios/Runner/Assets.xcassets/AppIcon.appiconset/`）
|
||
- [ ] 实现 Tab 页面（替换 `lib/core/router/routes.dart` 中的 placeholder build）
|
||
- [ ] 添加业务路由（`lib/core/router/routes.dart` 新增 `@TypedGoRoute`）
|
||
- [ ] 配置 Sentry DSN（`dart-defines/prod.json`）
|
||
- [ ] 配置 RSA 公钥（`dart-defines/dev.json`、`staging.json`、`prod.json`）
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
lib/
|
||
├── main.dart # 6 步启动序列
|
||
├── app.dart # AppRoot → MaterialApp.router
|
||
├── i18n/ # Slang 翻译
|
||
├── core/
|
||
│ ├── config/ # Env / ApiConfig / ApiPaths（填入 API 路径）
|
||
│ ├── router/ # GoRouter + TypedRoutes（添加业务路由）
|
||
│ ├── network/ # Dio 7 拦截器 + MockAdapter
|
||
│ ├── storage/ # Drift + SQLCipher + SecureStorage
|
||
│ ├── crash/ # CrashReporter 生命周期
|
||
│ ├── error/ # Sealed Failure 分类
|
||
│ ├── theme/ # 5 色板 + 深色模式
|
||
│ ├── observability/ # Talker + Sentry
|
||
│ ├── sync/ # Offline-First 同步框架骨架
|
||
│ ├── crypto/ # RSA 加密
|
||
│ ├── extensions/ # BuildContext / String / num / DateTime
|
||
│ ├── utils/ # 验证器 / 密码强度 / SMS 倒计时
|
||
│ └── widgets/ # 通用 UI 组件库
|
||
└── features/
|
||
├── auth/ # 认证（完整 Clean Architecture，替换登录 UI 品牌）
|
||
├── dev_panel/ # Talker 调试面板（Internal 包）
|
||
└── error_report/ # 本地错误日志 + 上报
|
||
|
||
android/
|
||
├── app/build.gradle.kts # Flavor 三包 + SQLCipher + 签名配置
|
||
├── key.properties.template # 签名配置模板（复制为 key.properties 并填入密码）
|
||
└── keystore/ # 放置 .jks 文件（.gitignore 中，勿提交）
|
||
|
||
dart-defines/
|
||
├── dev.json # 开发环境变量（占位符，可提交）
|
||
├── staging.json # 测试环境变量（占位符，可提交）
|
||
├── prod.json.template # 生产环境变量模板
|
||
└── prod.json # 生产真实配置（.gitignore 中，勿提交）
|
||
```
|