项目结构
了解 Kotlin 模板的文件夹、功能模块和职责边界。
Android 模板是一个 Gradle app module，package 代码位于 com.soarstarter.kotlin。
主要分层是：core/ 放可复用应用服务，data/ 放持久化和网络边界，feature/ 放屏幕族，
nav/ 放类型安全 routes 和图组合。
模板的 AGENTS.md / CLAUDE.md 目录树略有过期。当前代码有 core/showcase/，没有
feature/test/，没有 AuthGate.kt，也没有独立 MainNavGraph.kt；MainNavGraph 是
AppNavGraph.kt 内的 private composable。
项目地图
local.properties 被 git ignore，位于 repo root。Android Studio 也会在这里写入 sdk.dir。
Firebase client config 放在 app/google-services.json；只有该文件存在时 Gradle 才应用 Google
Services plugin。
App 入口
| 文件 | 职责 |
|---|---|
SoarApp.kt | @HiltAndroidApp；进程启动时启动 Sentry、PostHog 和 update controller |
MainActivity.kt | @AndroidEntryPoint；处理 deep-link intent、edge-to-edge、主题、语言、gates、root nav 和 ToastHost |
app/build.gradle.kts | Android SDK 版本、BuildConfig 字段、条件式 Google Services plugin、签名配置 |
AndroidManifest.xml | 权限、FCM service、launcher activity、custom scheme、App Links |
core/
core/ 是可复用应用基础设施。feature code 可以依赖它；core/ 不应依赖 feature screens。
| Folder | 职责 |
|---|---|
analytics/ | PostHog 的 AnalyticsController 和 typed AnalyticsEvent |
auth/ | SessionController 和 Google Sign-In controller |
biometric/ | Biometric app-lock controller 和 gate |
deeplink/ | DeepLinkHandler、DeepLinkResolver、DeepLinkDestination |
di/ | DataStore、repositories、session flow、coroutines、biometric binding 的 Hilt modules |
error/ | AppErrorBus、ErrorBoundary、SentryReporter |
haptics/ | toast 和 demo 使用的 Android vibrator wrapper |
legal/ | 法律文档模型、consent controller、LEGAL_VERSION |
locale/ | AppLanguage、LocaleController、LocalizedAppHost |
onboarding/ | Onboarding completion controller |
purchases/ | RevenueCat lifecycle、entitlement reader、PremiumGate |
rating/ | Play In-App Review controller |
result/ | AppResult、AppError、友好错误映射 |
showcase/ | removable Showcase leaf 共享的 capability catalog model |
ui/components/ | 可复用 Compose 控件和状态 |
ui/theme/ | Material 3 color schemes、typography、theme controller |
ui/toast/ | SharedFlow toast controller 和 root overlay |
update/ | Play In-App Updates controller 和 gate state |
data/
data/ 用来把平台和 backend 细节从 screens 隐藏起来。
| Folder | 职责 |
|---|---|
local/ | AppPreferences，提供 theme、locale、gates、rating、biometrics 的 typed DataStore flows |
model/ | Todo、Profile、Subscription、profile/user DTOs 等 serializable models |
network/ | 基于 ConnectivityManager.NetworkCallback 的 NetworkObserver |
notifications/ | FCM service、token table data source、内存 inbox、test-push function client |
remote/ | SupabaseClientProvider 和 Supabase plugin setup |
repository/ | Auth、todos、profile、subscription、upload repositories 及 Supabase remote data sources |
添加 backend-backed feature 时，沿用现有形状：
data/model/NewThing.kt
data/repository/NewThingRemoteDataSource.kt
data/repository/SupabaseNewThingRemoteDataSource.kt
data/repository/NewThingRepository.kt
core/di/RepositoryModule.kt binding
feature/newthing/NewThingViewModel.kt
feature/newthing/NewThingScreen.kt
nav/Routes.kt + graph mountfeature/
每个 feature folder 拥有一个 screen family、对应 ViewModel 和私有 UI。
| Folder | 职责 |
|---|---|
auth/ | Login、signup、verification、forgot/reset password、纯 validators |
component/ | 数据驱动 UI component gallery 和交互 demos |
guide/ | purchase-gated developer-guide 示例内容 |
home/ | Home tab 和 entitlement-aware license card |
legal/ | Consent gate UI 和 legal document screens |
main/ | Main shell、bottom tabs、drawer、sign-out state |
notifications/ | Push setup、FCM token 展示、内存 inbox、test push button |
onboarding/ | 四页 onboarding pager |
paywall/ | Paywall、subscription management、redeem-code screen |
permissions/ | Permission priming screen |
profile/ | Me tab、personal info、account security、biometric toggle |
refer/ | Android share-sheet referral 示例 |
showcase/ | removable demo catalog 和 capability demos |
todos/ | Home stack 上的示例 CRUD feature |
update/ | UpdateGate 使用的 update dialogs |
upload/ | Supabase Storage 图片上传示例 |
当前没有 feature/test/ folder。如果需要手动 observability triggers，请使用 Showcase demos 或添加自己的 debug-only screen。
nav/
当前文件：
| 文件 | 职责 |
|---|---|
Routes.kt | object AppRoutes 中的类型安全 @Serializable app routes |
AppNavGraph.kt | Root gates、outer nav destinations、auth graph、private MainNavGraph |
OnboardingGate.kt | 在 consent/main content 之前显示 onboarding 的 gate |
Tab graph 挂载在 feature/main/MainShellScreen.kt 中，每个 tab 都有 nested destination graph，
tab navigation 会保留 back stacks。
测试
Unit tests 位于 app/src/test。当前测试覆盖 controllers、repositories、validators、model rules、
component catalogs、entitlement gates 和 view models，并使用 fakes 与 kotlinx-coroutines-test。
Instrumented tests 位于 app/src/androidTest。当前包含 smoke instrumented test 和
nav/NavRouteTest.kt。只有连接设备或模拟器后才运行：
./gradlew connectedDebugAndroidTest