后端模式
Standalone（Supabase）与 Unified（Soar API）：如何选择、模式如何解析，以及哪些东西不能混用。
模板在同一套业务接口之后内置了两个完整后端。一个构建装配哪一个是在
环境（.env / EAS 构建 Profile）中做出的构建级选择——一个安装实例只会
对着一个后端认证和存取数据，不存在面向终端用户的切换开关。
| Standalone Mode | Unified Mode | |
|---|---|---|
EXPO_PUBLIC_SOAR_BACKEND_MODE | supabase（默认） | soarApi |
| Runtime | iOS、Android、Web | 仅 iOS 与 Android |
| 认证 | Supabase Auth | Better Auth（/api/auth/*，Bearer token） |
| 数据 | PostgREST + RLS | Soar App API（/api/app/v1/*） |
| 存储 | Supabase Storage | 对象存储（presigned 直传 API） |
| 测试推送 | Supabase Edge Function | 仅 APNs 的 v1 端点（iOS）；Android 注册 FCM Token |
| 用户 ID | Supabase UUID | Better Auth 文本 ID（不透明字符串） |
| 与 Web 应用共享用户/数据 | 否 | 是——与兼容 Web 宿主共享同一个后端 |
Standalone Mode 是经典的单模板形态：Expo App 在三个 Runtime 上都直连你 的 Supabase 项目。如果你只购买了 Expo 模板，用这个模式即可，它的行为没有任 何变化。
Unified Mode 让原生 App 改为指向兼容 Web 宿主的 Soar App API。Web 和移动端共享同一个 Better Auth 用户、同一张 todos 表、同一份 Profile 和同一行 订阅记录——任一端购买都会解锁另一端。 在 Unified 产品里，Expo 负责 iOS/Android，浏览器由 Web 宿主负责。
Expo Web 会明确拒绝 Unified。 在浏览器中打开 soarApi 构建会抛出
UnifiedWebUnsupportedError——App 绝不会把 Bearer Token 存入浏览器存储，
也不会回退 Supabase。它可以经 EXPO_PUBLIC_UNIFIED_WEB_APP_URL 展示你的
Web 部署链接。
从这里开始
先定模式，然后只跟一份对应的配置指南走：
Standalone：Supabase Setup
创建 Supabase 项目：Schema、认证回调、Edge Functions 与密钥。
Unified：Soar API Setup
连接兼容宿主：环境键、宿主环境、Session 与验证。
还没想好选哪个？平台级的模式指南和 兼容性矩阵从产品维度逐项对比了两种部署。
模式如何解析
EXPO_PUBLIC_SOAR_BACKEND_MODE 经 app.config.ts 进入构建，由
lib/backend/backend-config.ts 在启动时解析一次：
soarApi→ iOS/Android 上进入 Unified Mode；在 Web 上抛出UnifiedWebUnsupportedError。supabase或未设置 → Standalone Mode。
模式刻意独立于 APP_VARIANT——development、preview、production 构建可以
各自指向匹配的部署。lib/backend/backend-factory.ts 按解析出的模式装配服务
包（auth、account、todos、profile、subscriptions、uploads、device tokens、
push test）；页面与 Hook 只依赖业务接口，不包含任何后端类型判断。
没有静默回退。 如果选择了 Unified Mode 但
EXPO_PUBLIC_SOAR_API_BASE_URL 缺失或格式不对，启动会抛出
BackendConfigurationError——App 绝不会悄悄退回 Supabase。错误的后端配置
应当不可能被忽视。
两种模式不能混用
每个后端都是独立的身份源。Supabase 会话无法调用 Soar App API，Better Auth 会话也读不到你的 Supabase 表——设计上不存在桥接、双写或从一个模式回退 到另一个：
- Auth、数据、存储和订阅永远来自同一个后端预设。不可能用 Supabase 登录 却经 Soar API 存 todos。
- 一个模式里创建的用户在另一个模式里不存在。同一邮箱在两边注册是两个毫 不相关的账户。
把生产 App 切换模式是一次数据迁移，不是改一行配置。 对已有安装群翻转
EXPO_PUBLIC_SOAR_BACKEND_MODE 意味着：把用户账户迁入新身份源（用户必须
重新认证——密码哈希和 OAuth 关联不会自动转移）、搬迁 todos、Profile 和已
上传文件、并把 RevenueCat appUserID 重新指向新的用户 ID。请在上线前按
部署确定模式；之后的切换要当作一个有计划的迁移项目。