flutter-template/CLAUDE.md

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()

常用命令

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