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