后端模式
Standalone（Supabase）与 Unified（Soar API）：如何选择、模式如何解析，以及哪些东西不能混用。
模板在同一套业务协议之后内置了两个完整后端。App 装配哪一个是在
Secrets.xcconfig 中做出的构建级选择——一个安装实例只会对着一个后端
认证和存取数据，不存在面向终端用户的切换开关。
| Standalone Mode | Unified Mode | |
|---|---|---|
SOAR_BACKEND_MODE | supabase（默认） | soar_api |
| 认证 | Supabase Auth | Better Auth（/api/auth/*，Bearer token） |
| 数据 | PostgREST + RLS | Soar App API（/api/app/v1/*） |
| 存储 | Supabase Storage | 对象存储（presigned 直传 API） |
| 测试推送 | Supabase Edge Function | POST /api/app/v1/notifications/test-push |
| 用户 ID | Supabase UUID | Better Auth 文本 ID（不透明字符串） |
| 与 Web 应用共享用户/数据 | 否 | 是——与兼容 Web 宿主共享同一个后端 |
Standalone Mode 是经典的单模板形态：iOS App 直连你的 Supabase 项目。 如果你只购买了 Swift 模板，用这个模式即可，它的行为没有任何变化。
Unified Mode 让 App 改为指向兼容 Web 宿主的 Soar App API。Web 和 iOS 共享同一个 Better Auth 用户、 同一张 todos 表、同一份 Profile 和同一行 订阅记录——任一端购买都会解锁另一端。 以 Web 宿主 + Swift 交付同一个产品时使用它。
从这里开始
先定模式，然后只跟一份对应的配置指南走：
Standalone：Supabase Setup
创建 Supabase 项目：Schema、认证回调、Edge Functions 与密钥。
Unified：Soar API Setup
连接兼容宿主：客户端构建键、宿主环境、Session 与验证。
还没想好选哪个？平台级的模式指南和 兼容性矩阵从产品维度逐项对比了两种部署。
模式如何解析
SOAR_BACKEND_MODE 沿常规的 xcconfig 链 进入
Info.plist，由 App/BackendMode.swift 在启动时解析一次：
soar_api（也接受soarapi、soar-api，不区分大小写）→ Unified Mode。- 其他任何值——包括未设置——→ Standalone Mode（
supabase）。
App/BackendFactory.swift 是唯一知道具体实现的地方。它按解析出的模式装配
BackendServices（auth、account、todos、profile、subscription、uploads、
device tokens、push test）；再往上的 AppEnvironment、ViewModel 和 View 只
依赖业务协议，不包含任何后端类型判断。
没有静默回退。 如果选择了 Unified Mode 但缺少 SOAR_API_BASE_URL，
每个请求都会抛出可诊断的配置错误（"Soar API backend is selected but
SOAR_API_BASE_URL is not set"）——App 绝不会悄悄退回 Supabase。错误的后端
配置应当不可能被忽视。
两种模式不能混用
每个后端都是独立的身份源。Supabase 会话无法调用 Soar App API，Better Auth 会话也读不到你的 Supabase 表——设计上不存在桥接、双写或从一个模式回退 到另一个：
- Auth、数据、存储和订阅永远来自同一个后端预设。不可能用 Supabase 登录 却经 Soar API 存 todos。
- 一个模式里创建的用户在另一个模式里不存在。同一邮箱在两边注册是两个毫 不相关的账户。
把生产 App 切换模式是一次数据迁移，不是改一行配置。 对已有安装群翻转
SOAR_BACKEND_MODE 意味着：把用户账户迁入新身份源（用户必须重新认证——
密码哈希和 OAuth 关联不会自动转移）、搬迁 todos、Profile 和已上传文件、
并把 RevenueCat appUserID 重新指向新的用户 ID。请在上线前按部署确定模式；
之后的切换要当作一个有计划的迁移项目。