架构

Unified 请求路径

Swift / Kotlin / Expo / Electron / Tauri
                  │
        Better Auth 签名 Bearer
        Soar App API /api/app/v1
                  │
                  ▼
      Next.js / Nuxt / TanStack Start
          Unified Platform Host
                  │
     ┌────────────┼─────────────┐
     ▼            ▼             ▼
Better Auth   PostgreSQL     存储 / 支付 / 推送

客户端 UI 依赖 Backend 无关的业务服务。Standalone adapter 调用 Supabase；Unified adapter 调用 Better Auth 与 App API。业务请求不提交所有权 userId，资源所有权由所选 Backend 的 Session 决定。

稳定边界

• /api/auth/* 是注册、登录、OTP、Session 生命周期和账户凭据使用的 Better Auth HTTP 契约。
• /api/app/v1/* 是 Profile、Todo、设备 Token、通知、订阅、上传和账户删除使用的冻结业务契约。
• 不同宿主可以使用不同框架内部实现，但必须保持可观察契约一致。
• Unified 的身份、数据、存储和订阅状态必须来自同一宿主部署。不支持把 Supabase Session 与 Unified 业务数据混用。

安全边界

原生客户端将签名 Bearer Token 保存在平台安全存储中。Electron 只在主进程保存，Tauri 只在 Rust 中保存。Token、预签名 URL 和 Authorization Header 不得进入浏览器存储、UI state、日志、Analytics 或诊断导出。