chore: 初始化脚手架 — sunny_mochi 企业级 Flutter 模板

Core 基础设施：Flavor 三包体系、Drift+SQLCipher 加密数据库 7 拦截器 Dio 网络栈、CrashReporter 崩溃日志、Sealed Failure 错误体系 5 色板主题系统、Auth 认证骨架（Clean Architecture）、Dev Panel、Mock Adapter 通过验证：flutter analyze（0 errors）、flutter test（全绿）、staging APK 74.8MB
2026-05-14 12:51:05 +08:00
commit 61017f1c39
204 changed files with 15386 additions and 0 deletions
@@ -0,0 +1,89 @@
+# CLAUDE.md — sunny_mochi 脚手架项目规范
+
+## 项目简介
+
+`sunny_mochi` 是企业级 Flutter APP 脚手架模板，包含：
+- Flavor 三包体系（dev/staging/prod）
+- 完整 Core 基础设施层（网络/存储/崩溃/主题/观测性）
+- 认证骨架（Auth Feature）
+- 开发者工具面板（Dev Panel）
+- 本地错误日志 + 上报
+
+## 目录结构
+
+```
+lib/
+├── main.dart              # 6 步启动序列
+├── app.dart               # AppRoot → MaterialApp.router
+├── i18n/                  # Slang 翻译文件
+├── core/
+│   ├── config/            # Env / ApiConfig / ApiPaths
+│   ├── router/            # GoRouter + TypedRoutes
+│   ├── network/           # Dio 7 拦截器 + MockAdapter
+│   ├── storage/           # Drift + SQLCipher + SecureStorage
+│   ├── crash/             # CrashReporter 3 步生命周期
+│   ├── error/             # sealed Failure 层级
+│   ├── theme/             # 5 色板 + 深色模式
+│   ├── observability/     # Talker + Sentry
+│   ├── sync/              # Offline-First 同步框架
+│   ├── crypto/            # RSA 加密工具
+│   ├── extensions/        # BuildContext / String / num / DateTime
+│   ├── utils/             # 验证器 / 密码强度 / SMS 倒计时
+│   ├── data/              # FreshnessPolicy 缓存策略
+│   └── widgets/           # 通用 UI 组件库
+└── features/
+    ├── auth/              # 认证 Feature（完整 Clean Architecture）
+    ├── dev_panel/         # Talker 调试面板（Internal 包）
+    └── error_report/      # 本地错误日志查看 + 上报
+```
+
+## 新项目初始化清单
+
+1. **替换包名**：`sunny_mochi` → 你的包名（android/app/build.gradle.kts + pubspec.yaml + import）
+2. **填入 API 路径**：`lib/core/config/api_paths.dart` 中所有空字符串
+3. **配置 Flavor**：`android/app/build.gradle.kts` applicationId + 签名配置
+4. **填入 Sentry DSN**：`dart-defines/prod.json`
+5. **填入 RSA 公钥**：`dart-defines/dev.json` 的 `rsaPublicKey` 字段
+6. **替换 i18n 字符串**：`lib/i18n/strings_zh_CN.i18n.json` 按需扩展
+7. **添加业务路由**：`lib/core/router/routes.dart` 新增 TypedGoRoute
+8. **实现 Tab 页面**：替换 HomeRoute / MineRoute 的 placeholder build
+
+## 零容忍规则
+
+| 规则 | 正确 | 禁止 |
+|------|------|------|
+| API 路径 | `ApiPaths.xxx` | 字面量字符串 |
+| 错误处理 | `ExceptionMapper.fromUnknown()` | 散落的 `catch(e)` 直接显示 |
+| Token 存储 | `SecureStorage`（SoT） | 普通 SharedPreferences |
+| DB 加密 | SQLCipher（默认） | 无加密 sqflite |
+| 日志 | `appTalker.xxx()` | `print()` / `debugPrint()` |
+| 路由跳转 | `LoginRoute().go(context)` | `Navigator.push()` |
+
+## 常用命令
+
+```bash
+# 代码生成
+make gen
+
+# i18n 生成
+make gen-i18n
+
+# 运行（dev 包）
+make run-dev
+
+# 构建 staging APK
+make build-staging
+
+# 静态分析
+flutter analyze
+
+# 测试
+flutter test --coverage
+```
+
+## 关键技术决策
+
+- **SQLCipher**：企业合规要求加密存储，部署后无法无损迁移到无加密
+- **7 拦截器栈**：Token 刷新互斥（Completer）+ 证书绑定是安全基础，不可简化
+- **sealed Failure**：统一错误分类，UI / 日志 / Sentry 三层复用同一模型
+- **schemaVersion=1**：脚手架全新 DB，不携带任何历史迁移负担