Soar API Setup
将 Electron 连接到兼容 Unified Platform 宿主：主进程配置、宿主环境、Session 与验证。
本页是 Unified Mode 版的 Supabase Setup： 让桌面应用对着一个兼容 Web 宿主（而不是 Supabase 项目）运行所需的全部配置。 还没确定模式的话，先看后端模式。
不按框架名称给予宿主特权——Next.js、Nuxt、TanStack Start 都可以；是否符合 冻结契约才是兼容边界。
1. 部署兼容宿主
把任意一个 Web 模板部署为 Unified Platform Host，并完成其宿主侧配置 （数据库、Better Auth URL 与密钥、App API）：
先在 Web 端注册并确认 /api/auth/get-session 正常，再动桌面侧。跨模板的
整体流程见平台 Unified 快速开始。
2. 配置客户端构建
Unified Mode 需要构建时的两个环境值：
# .env
SOAR_BACKEND_MODE=soarApi
# 宿主部署的服务根地址；本地开发宿主可用 http://localhost:3000。
# 只供主进程消费——永远不给 Renderer。
SOAR_API_BASE_URL=https://your-web-app.example.comSUPABASE_* 键可以留空——这个模式下永远不会加载 Supabase 后端图。请求
Origin 是固定的桌面 scheme：soar://。
配置错误会终止所选路径。SOAR_API_BASE_URL 缺失或格式不对会以可诊断的
错误失败——绝不会转而初始化另一个后端。
3. 为这个应用配置宿主
服务端（所选宿主的部署环境）需要 原生认证 所描述的原生支持：
| 服务端变量 | 桌面应用为什么需要它 |
|---|---|
APP_SCHEME=soar:// | 主进程在每个请求上发送 Origin: soar://；Better Auth 会用 403 拒绝不受信任的 Origin。 |
STORAGE_PROVIDER（生产另加 R2_*） | 支撑上传服务的 presigned 直传对象存储。 |
| 支付 Provider 配置（Creem/Stripe） | 宿主签发桌面端要打开的订阅快照、Checkout URL 与管理门户。 |
Electron Unified 刻意不实现 OAuth、设备 Token 和测试推送——这些能力保 持缺失而非近似模拟，因此桌面端不需要 OAuth audience 或推送凭据。
4. Session 存在主进程加密存储里
Unified Mode 下应用使用 Better Auth 的 Bearer token（set-auth-token
响应 header）认证，而不是 Cookie：
- Token 只持久化在主进程持有的 safeStorage 加密存储里，命名空间由应用 ID、API Origin 和构建 Channel 组成——开发会话绝不会被生产构建恢复。
- Renderer 通过类型化 IPC 只拿到脱敏后的 Session；Bearer Token、
Authorizationheader 和 presigned URL 永远不跨越 IPC 边界。 - 重启后恢复会话并向服务端校验；退出登录会同时清理存储的 Token 和内存状态。
- Session 存于数据库、可撤销：在 Web 端撤销会话会让桌面 Token 立即失效，
应用把
401视为「需要重新登录」——不会无限重试，也不会回退到 Supabase 认证。
5. 计费经由宿主
桌面计费跟随宿主的订阅状态：应用读取共享的 订阅快照，Checkout 与门户流程打开由宿 主签发的 Provider URL。主进程会先校验这些 URL 再对外打开。
验证配置
在两端跑一遍共享冒烟测试：
- 在桌面端注册或登录（邮箱/OTP），然后在 Web 端打开同一个账户。
- 在一端更新 Profile，从另一端读取。
- 跨两端创建、编辑、排序、删除 Todo。
- 上传头像并确认其完成 URL 可读。
- 从 Web 端撤销桌面会话，确认应用回到登录页。
- 从桌面端完成一次测试 Checkout，确认两端出现同一份权益。
- 从桌面端删除账户，确认宿主侧完成级联删除。
想要一组具体宿主+客户端的端到端流程，跟 Next.js + Swift Unified Setup 走—— 步骤同样适用于桌面端（去掉 OAuth 与推送部分）。