Template
SkyJourney
61017f1c39
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
90 lines
3.4 KiB
Markdown
90 lines
3.4 KiB
Markdown
# 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，不携带任何历史迁移负担
|