Soar API Setup
将 Kotlin 连接到兼容 Unified Platform 宿主：客户端构建、宿主环境、Session 与验证。
本页是 Unified Mode 版的 Supabase Setup： 让 Android App 对着一个兼容 Web 宿主（而不是 Supabase 项目）运行所需的全部 配置。还没确定模式的话，先看后端模式。
不按框架名称给予宿主特权——Next.js、Nuxt、TanStack Start 都可以；是否符合 冻结契约才是兼容边界。
1. 部署兼容宿主
把任意一个 Web 模板部署为 Unified Platform Host，并完成其宿主侧配置 （数据库、Better Auth URL 与密钥、App API）：
先在 Web 端注册并确认 /api/auth/get-session 正常，再动 Android 侧。跨模板
的整体流程见平台 Unified 快速开始。
2. 配置客户端构建
Unified Mode 需要 local.properties 里的三个键：
# local.properties
SOAR_BACKEND_MODE=soarApi
# 宿主部署的服务根地址。不要带 /api/app/v1——客户端会自行拼接。
# Release 构建强制 HTTPS；Android 模拟器访问宿主机用 10.0.2.2（不是
# localhost），例如 http://10.0.2.2:3000
SOAR_API_BASE_URL=https://your-web-app.example.com
# Better Auth 请求携带的原生 Origin：以 `://` 结尾的裸 scheme。
# 必须与宿主的 APP_SCHEME / trustedOrigins 白名单一致，同时它也会生成
# AndroidManifest.xml 里 App 的 deep-link scheme。
SOAR_API_ORIGIN=soar://SUPABASE_* 键可以留空——这个模式下永远不会构建 Supabase 客户端。两种模式
下 Google 登录都通过设备上的 Credential Manager 完成；audience 在服务端校验
（见下一步）。
配置错误会终止当前构建。任何 SOAR_API_* 值缺失或格式不对都会让启动失败
并给出可诊断的错误——不存在静默 Supabase 回退。
3. 为这个 App 配置宿主
服务端（所选宿主的部署环境）需要 原生认证 所描述的原生支持：
| 服务端变量 | Android App 为什么需要它 |
|---|---|
APP_SCHEME=soar:// | App 在每个请求上发送 Origin: soar://；Better Auth 会用 403 拒绝不受信任的 Origin。必须与客户端的 SOAR_API_ORIGIN 一致。 |
GOOGLE_ANDROID_CLIENT_ID | 经 Credential Manager 的原生 Google ID Token 登录的 audience 白名单条目。 |
REVENUECAT_WEBHOOK_AUTHORIZATION + REVENUECAT_PRODUCT_* | 把 Google Play 购买同步到共享的订阅行。 |
STORAGE_PROVIDER（生产另加 R2_*） | 支撑上传仓库的 presigned 直传对象存储。 |
4. Session 存在 Android Keystore 里
Unified Mode 下 App 使用 Better Auth 的 Bearer token（set-auth-token
响应 header）认证，而不是 Cookie：
- Token 只持久化在 Keystore 加密的安全存储（
SecureTokenStore）—— 绝不进日志，也被排除在备份之外。 - 重启后恢复会话并向服务端校验；退出登录会同时清理存储的 Token 和内存状态。
- 任何响应带来新的
set-auth-token时，存储的 Token 都会被替换。 - Session 存于数据库、可撤销：在 Web 端撤销会话会让 Android Token 立即失效，
App 把
401视为「需要重新登录」——不会无限重试，也不会回退到 Supabase 认证。
5. RevenueCat appUserID
购买层始终用当前用户 ID 登录 RevenueCat——Unified Mode 下即 Better Auth 用户
ID。正是它让服务端的 RevenueCat Webhook
能把 app_user_id 解析回同一个 Better Auth 用户，并更新 Web 端也在读取的
同一行共享订阅。
保持 RevenueCat 的 Restore Behavior 为禁用 Transfer：收据已绑定其他账户 时应当出现面向支持的明确错误，而不是在用户之间悄悄转移权益。
6. 推送通知
Unified Android 通过设备 Token 端点注册 FCM Token。冻结的 v1 测试推送 端点仅支持 APNs，因此 App 会把测试发送显示为「不支持」而不去调用它——真实 的 FCM 送达不受影响。
验证配置
在两端跑一遍共享冒烟测试：
- 在 Android 注册或登录（邮箱与 Google），然后在 Web 端打开同一个账户。
- 在一端更新 Profile，从另一端读取。
- 跨两端创建、编辑、排序、删除 Todo。
- 上传头像并确认其完成 URL 可读。
- 从 Web 端撤销 Android 会话，确认 App 回到登录页。
- 沙盒购买后，确认两端出现同一份权益。
- 注册 FCM 设备 Token，并确认它出现在宿主的 Token 注册表里。
想要一组具体宿主+客户端的端到端流程，跟 Next.js + Swift Unified Setup 走—— 步骤与 Android 一一对应。