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. 安装依赖

flutter pub get

2. 代码生成

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 签名（发布版必须）

cp android/key.properties.template android/key.properties
# 编辑 key.properties，填入 keystore 路径和密码

5. 配置生产环境变量

cp dart-defines/prod.json.template dart-defines/prod.json
# 编辑 prod.json，填入 Sentry DSN、RSA 公钥等

6. iOS（首次或 Pod 变更后）

cd ios && pod install && cd ..

---

常用命令

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 中，勿提交）