后端模式
Standalone（Supabase）与 Unified（Soar API）：如何选择、模式如何解析，以及哪些东西不能混用。
模板在同一套业务接口之后内置了两个完整后端。App 装配哪一个是在
local.properties 中做出的构建级选择——一个安装实例只会对着一个后端
认证和存取数据，不存在面向终端用户的切换开关。
| Standalone Mode | Unified Mode | |
|---|---|---|
SOAR_BACKEND_MODE | supabase（默认） | soarApi |
| 认证 | Supabase Auth | Better Auth（/api/auth/*，Bearer token） |
| 数据 | PostgREST + RLS | Soar App API（/api/app/v1/*） |
| 存储 | Supabase Storage | 对象存储（presigned 直传 API） |
| 推送 | FCM（经 Supabase Edge Function） | FCM Token 注册；v1 测试推送端点仅支持 APNs |
| 用户 ID | Supabase UUID | Better Auth 文本 ID（不透明字符串） |
| 与 Web 应用共享用户/数据 | 否 | 是——与兼容 Web 宿主共享同一个后端 |
Standalone Mode 是经典的单模板形态：Android App 直连你的 Supabase 项目。 如果你只购买了 Kotlin 模板，用这个模式即可，它的行为没有任何变化。
Unified Mode 让 App 改为指向兼容 Web 宿主的 Soar App API。Web 和 Android 共享同一个 Better Auth 用户、同一张 todos 表、同一份 Profile 和同一行 订阅记录——任一端购买都会解锁另一端。 以 Web 宿主 + Android 交付同一个产品时使用它。
从这里开始
先定模式，然后只跟一份对应的配置指南走：
Standalone：Supabase Setup
创建 Supabase 项目：Schema、认证回调、Edge Functions 与密钥。
Unified：Soar API Setup
连接兼容宿主：客户端构建键、宿主环境、Session 与验证。
还没想好选哪个？平台级的模式指南和 兼容性矩阵从产品维度逐项对比了两种部署。
模式如何解析
SOAR_BACKEND_MODE 从 local.properties 进入 BuildConfig，由
core/backend/BackendMode.kt 在启动时解析一次：
soarApi（不区分大小写）→ Unified Mode。supabase或留空 → Standalone Mode。- 其他任何值都会让启动失败，抛出
BackendConfigurationException（"Invalid SOAR_BACKEND_MODE"）——写错值不可能悄悄选中某个后端。
core/backend/BackendConfig.kt 会在启动时立刻校验 Unified 键：
SOAR_API_BASE_URL 必须是绝对 HTTP(S) 服务根地址（Release 构建强制
HTTPS；不要带 /api/app/v1——客户端会自行拼接），SOAR_API_ORIGIN 必须
是以 :// 结尾的裸 scheme。DI 图只装配解析出的模式对应的仓库；ViewModel
与 Composable 只依赖业务接口，不包含任何后端类型判断。
没有静默回退。 如果选择了 Unified Mode 但某个 SOAR_API_* 值缺失或
格式不对，启动会直接失败并给出可诊断的配置错误——App 绝不会悄悄退回
Supabase。错误的后端配置应当不可能被忽视。
两种模式不能混用
每个后端都是独立的身份源。Supabase 会话无法调用 Soar App API，Better Auth 会话也读不到你的 Supabase 表——设计上不存在桥接、双写或从一个模式回退 到另一个：
- Auth、数据、存储和订阅永远来自同一个后端预设。不可能用 Supabase 登录 却经 Soar API 存 todos。
- 一个模式里创建的用户在另一个模式里不存在。同一邮箱在两边注册是两个毫 不相关的账户。
把生产 App 切换模式是一次数据迁移，不是改一行配置。 对已有安装群翻转
SOAR_BACKEND_MODE 意味着：把用户账户迁入新身份源（用户必须重新认证——
密码哈希和 OAuth 关联不会自动转移）、搬迁 todos、Profile 和已上传文件、
并把 RevenueCat appUserID 重新指向新的用户 ID。请在上线前按部署确定模式；
之后的切换要当作一个有计划的迁移项目。