docs: 新增完整文档体系（setup-project / setup-android / setup-ios / CLAUDE.md）

2026-05-14 13:04:51 +08:00
parent bb07828234
commit a266323905
5 changed files with 1065 additions and 169 deletions
@@ -1,123 +1,156 @@
 # 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 备用） |
+基于 Flutter 3.x 的企业级 APP 模板底座，涵盖开发 / 测试 / 生产三包共存体系、加密本地数据库、完整网络安全栈、崩溃与错误日志、主题系统和认证骨架，让新项目从第一天就拥有生产级基础设施。

 ---

-## 克隆后首次设置
+## 已实现的基础设施
+
+### 构建体系
+- **Flavor 三包**：dev（Mock 可开）/ staging（连测试服）/ prod（正式签名）
+- **dart-defines JSON**：环境变量与代码完全解耦，CI/CD 通过 secret 注入 prod 配置
+- **Android productFlavors + iOS xcconfig**：三套应用名、ID、签名互不干扰
+
+### 网络层（Dio，7 拦截器固定顺序）
+| 顺序 | 拦截器 | 作用 |
+|------|--------|------|
+| 1 | CertPinning | SSL 证书绑定，防 MITM |
+| 2 | Auth | 注入 sa-token 动态 header（tokenName 从 SecureStorage 读取）|
+| 3 | TokenRefresh | 401 时静默刷新，Completer 互斥防并发重复消耗 |
+| 4 | Retry | 网络超时 / 5xx 指数退避重试（最多 3 次）|
+| 5 | Error | DioException → sealed Failure 映射 |
+| 6 | AuthLogout | AuthFailure(unauthorized/refreshFailed) → 清 token + 跳登录 |
+| 7 | Log | TalkerDioLogger（仅 dev/Internal 包输出）|
+
+### 本地存储
+- **Drift 2.31.0 + SQLCipher**：AES-256 加密 SQLite，密钥由 `DbKeyProvider` 派生并存入 Keychain
+- **SecureStorage**：token / refreshToken / tokenName / userId 的唯一真源（Keychain on iOS，EncryptedSharedPreferences on Android）
+- **Offline-First 同步框架**：`SyncService` + `SyncColumns` mixin，4 字段脏数据追踪骨架
+
+### 错误体系
+```
+Failure (sealed)
+├── NetworkFailure  → 超时 / 无网络 / 证书错误 / 请求取消
+├── AuthFailure     → 未授权 / token 过期 / 刷新失败 / 无权限 / 加密失败
+├── ServerFailure   → HTTP 4xx/5xx / 业务码非 00000
+├── CacheFailure    → Drift / IO 异常
+└── UnknownFailure  → 兜底
+```
+
+### 崩溃日志
+三步生命周期：`preInit()` → 启动 → `consumePending()`（读取上次崩溃）→ `installHooks()`（接管 Flutter/Zone 全局异常）。崩溃数据同步写文件（不依赖异步），重启后弹窗展示并提供上报入口。
+
+### 主题系统
+5 套色板（blue / red / green / purple / teal）× 浅色/深色模式，通过 `ThemeNotifier`（SharedPreferences 持久化）+ Riverpod 全局响应式切换。
+
+### 认证骨架（Clean Architecture）
+```
+domain/entities/UserEntity          ← 纯 Dart，无框架依赖
+domain/repositories/AuthRepository  ← abstract interface
+data/models/UserModel               ← Freezed + JSON，含 toEntity()
+data/datasources/AuthRemoteDatasource ← Dio 调用
+data/repositories/AuthRepositoryImpl ← 接口实现
+presentation/notifiers/AuthNotifier  ← @riverpod，generation 计数防竞态
+presentation/notifiers/AuthStatusController ← ValueNotifier<bool?> 三态门面
+presentation/pages/LoginPage        ← 手机号 + SMS/密码双模式骨架
+```
+
+### 可观测性
+- **Talker**：全局 `appTalker`，dev/Internal 包输出，Release 编译期关闭
+- **Sentry**：`SentrySetup.init()` 包裹 `runApp`，空 DSN 时自动跳过，Release 才上报
+- **DevPanel Feature**：Internal 包内 TalkerScreen 入口，方便调试网络 / 状态变化
+
+### 通用 Widget 库
+`AppToast`（Overlay 动画条）、`AppButton`（带 loading）、`AppTextField`、`EmptyView`、`ErrorView`、`LoadingOverlay`、`ConfirmDialog`、`SectionCard`、`SectionTitle`、`Skeleton`、`InfoRow`、`CountDownButton`、`AvatarWidget`、`TagChip`
+
+---
+
+## 技术栈版本
+
+| 技术 | 版本 | 说明 |
+|------|------|------|
+| Flutter | ≥ 3.41.0 | |
+| Dart | ≥ 3.7.0 | |
+| flutter_riverpod | ^3.3.0 | |
+| go_router | ^17.0.0 | TypedRoutes + StatefulShellRoute |
+| drift | 2.31.0 | **锁定**，2.32+ analyzer 冲突 |
+| sqlcipher_flutter_libs | ^0.6.0 | |
+| freezed_annotation | ^3.0.0 | |
+| json_serializable | 6.13.0 | **锁定**，6.13.1+ analyzer 冲突 |
+| dio | ^5.9.0 | |
+| flutter_secure_storage | ^10.0.0 | |
+| slang | ^4.0.0 | i18n，zh-CN 基准 |
+| talker_flutter | ^5.0.0 | |
+| sentry_flutter | ^9.0.0 | |
+| flutter_screenutil | ^5.9.0 | 设计基准 375×812pt |
+| pointycastle + asn1lib | ^4.0.0 / ^1.5.0 | RSA PKCS#1 v1.5 |
+
+---
+
+## 快速开始
+
+**前提**：已安装 Flutter ≥ 3.41.0、Android Studio（Android SDK）、Xcode 16+（iOS 开发）。

-### 1. 安装依赖
 ```bash
+# 1. 克隆（替换为业务项目实际地址）
+git clone https://gitea.example.com/your-org/your-project.git
+cd your-project
+
+# 2. 安装依赖
 flutter pub get
+
+# 3. 代码生成
+make gen        # 生成 .g.dart / .freezed.dart
+make gen-i18n   # 生成 lib/i18n/strings.g.dart
+
+# 4. 运行（dev 包，Mock 模式）
+make run-dev
 ```

-### 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`）
+> 首次运行前请阅读 [docs/setup-project.md](docs/setup-project.md) 完成环境配置。

 ---

 ## 项目结构

 ```
-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 中，勿提交）
+├── android/
+│   ├── app/build.gradle.kts        # Flavor 三包 + SQLCipher + 签名配置
+│   ├── key.properties.template     # 签名配置模板（复制为 key.properties 并填入密码）
+│   └── keystore/                   # 存放 .jks 文件（gitignore，勿提交）
+├── ios/
+│   ├── Flutter/flavors/            # dev / staging / prod xcconfig
+│   └── Podfile                     # iOS 15.0+，pod install 后生成 Pods/
+├── dart-defines/
+│   ├── dev.json                    # 开发环境（占位符，可提交）
+│   ├── staging.json                # 测试环境（占位符，可提交）
+│   ├── prod.json.template          # 生产模板（复制为 prod.json 并填入真实值）
+│   └── prod.json                   # 生产真实配置（gitignore，勿提交）
+├── assets/
+│   ├── fonts/                      # HarmonyOS Sans SC（4 字重）
+│   ├── fixtures/                   # Mock JSON（dev 调试用）
+│   └── themes/                     # 主题图片（业务项目按 AppColorScheme 放置）
+├── lib/                            # 详见 CLAUDE.md 目录结构
+├── docs/
+│   ├── setup-project.md            # 完整项目配置指南
+│   ├── setup-android.md            # Android Flavor / 签名详细配置
+│   └── setup-ios.md                # iOS Scheme / CocoaPods / 签名详细配置
+├── CLAUDE.md                       # AI 辅助开发上下文（技术栈 / 规范 / 零容忍规则）
+├── Makefile                        # 常用命令
+├── pubspec.yaml                    # 依赖（含版本锁定 dependency_overrides）
+└── slang.yaml                      # i18n 配置（base_locale: zh-CN）
 ```
+
+---
+
+## 文档导航
+
+| 文档 | 适用人群 | 内容 |
+|------|---------|------|
+| **本文（README.md）** | 所有成员 | 项目概述、技术栈、快速开始 |
+| [docs/setup-project.md](docs/setup-project.md) | 所有开发者 | 环境配置、API 路径、dart-defines 填写 |
+| [docs/setup-android.md](docs/setup-android.md) | Android / 全栈 | Flavor、签名、keystore、构建 |
+| [docs/setup-ios.md](docs/setup-ios.md) | iOS / 全栈 | Scheme、CocoaPods、证书、Archive |
+| [CLAUDE.md](CLAUDE.md) | AI 辅助开发 | 架构规范、零容忍规则、开发范式 |