# 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，不携带任何历史迁移负担