可观测性
PostHog 分析、Sentry 崩溃上报、测试控制和同意机制。
Kotlin 模板有两层可选观测能力：PostHog 用于产品 analytics，Sentry 用于 crash reporting。
二者都从 local.properties 配置；缺少 key 时都会 no-op。
提供什么
| Surface | 状态 | 实现 |
|---|---|---|
| Product analytics | Integrated | AnalyticsController 封装 PostHog Android |
| Typed analytics events | Integrated | AnalyticsEvent sealed class |
| User identity | Integrated | 登录时 PostHog identify，退出时 reset |
| Crash reporting | Integrated | SentryReporter 初始化 Sentry Android |
| User tagging | Integrated | Sentry scope user 跟随 SessionController.currentUser |
| Error fallback | Integrated | AppErrorBus + ErrorBoundary + 应用内 feedback |
关键文件
配置
# Sentry
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
# PostHog
POSTHOG_API_KEY=phc_your_key
POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_DISABLED=false
POSTHOG_DEBUG=false缺少 SENTRY_DSN 时会跳过 Sentry SDK 初始化，capture 调用也不会发送。缺少
POSTHOG_API_KEY，或设置 POSTHOG_DISABLED=true，会让 analytics track() 和 screen()
no-op。
PostHog analytics
SoarApp.onCreate() 调用 analyticsController.start()。配置存在时，它会创建
PostHogAndroidConfig：
| 选项 | 值 |
|---|---|
| API key | BuildConfig.POSTHOG_API_KEY |
| Host | BuildConfig.POSTHOG_HOST，默认 https://us.i.posthog.com |
| Lifecycle capture | captureApplicationLifecycleEvents = true |
| Debug logging | BuildConfig.POSTHOG_DEBUG |
controller 订阅 SessionController.currentUser。登录时，它用 Supabase UUID identify 用户，并
发送 email、email domain、账号创建时间、environment 等账号属性。退出登录时调用
PostHog.reset()。
Typed app events 位于 AnalyticsEvent：
| Event | Name | 当前调用点 |
|---|---|---|
ScreenViewed | screen viewed | 可用 helper event |
OnboardingCompleted | onboarding completed | OnboardingGate |
PaywallViewed | paywall viewed | 可用 event type |
ReferralInviteShared | referral invite shared | 可用 event type |
PurchaseCompleted | purchase completed | 购买后由 PaywallViewModel 调用 |
PurchaseRestored | purchase restored | 可用 event type |
添加新事件时扩展 sealed class，并保持 property names 稳定。
Sentry crash reporting
SoarApp.onCreate() 也会调用 sentryReporter.start()。存在 SENTRY_DSN 时，reporter 用以下
选项初始化 Sentry Android：
| 选项 | 值 |
|---|---|
| Environment | debug build 是 development，其他是 production |
| Release | <applicationId>@<versionName>+<versionCode> |
| Trace sample rate | debug 是 1.0，非 debug 是 0.2 |
| Stack traces | Attached |
reporter 跟随 SessionController.currentUser，在登录时把 Supabase user id 和 email 写入
Sentry scope。
Error boundary
MainActivity 用以下结构包住应用导航：
ErrorBoundary(errorBus = appErrorBus, reporter = sentryReporter)ViewModel 和 controller 可以调用 AppErrorBus.report(throwable, boundary)。bus 会在 Sentry
已配置时 capture exception，并把当前错误保存在 StateFlow。ErrorBoundary 随后渲染应用内
fallback：
- Try again：清除当前错误。
- Send a report：发送 Sentry feedback event。
- debug-only 详情面板：显示 message 和 stack trace。
这个 boundary 处理通过 AppErrorBus 路由的错误，不替代 Sentry 对进程 crash 的常规
uncaught-exception 捕获。
隐私和 Play data safety
当前代码从 SoarApp.onCreate() 启动 PostHog，早于 legal ConsentGate 被接受。如果你的应用
必须等 consent 后才 tracking，请把 analyticsController.start() 移到
ConsentController.hasAcceptedCurrent 后面，或在用户接受前以 POSTHOG_DISABLED=true
发布。
Play Console data safety 声明应反映你实际发布的 SDK。使用模板默认组合时，通常需要考虑：
| 数据类别 | 常见来源 |
|---|---|
| User IDs 和 email | Supabase Auth、PostHog identify、Sentry user scope |
| App interactions | PostHog events 和 lifecycle capture |
| Crash logs 和 diagnostics | Sentry |
| Device identifiers | Advertising ID permission、Firebase、PostHog |
如果移除 PostHog 或 Firebase，请同步复查 AndroidManifest.xml、SDK dependencies 和 Play
data-safety form。
早期规划笔记提到 dev-only feature/test/ screen。当前 Kotlin 代码库并不存在这个 screen，
所以手动观测测试应从真实调用点完成，或你自己添加 debug-only trigger screen。
验证
- 不配置任何 observability key，确认应用启动且没有网络初始化错误。
- 添加
POSTHOG_API_KEY，登录后确认 PostHog identify Supabase user id。 - 完成 onboarding，确认捕获
onboarding completed。 - 完成测试购买，确认捕获
purchase completed。 - 添加
SENTRY_DSN，触发一个通过AppErrorBus.report()路由的错误，确认 fallback screen 和 Sentry event。 - 退出登录后确认 PostHog reset，Sentry user scope 被清空。