API 契约
以冻结的 Soar App API v1 和独立 Better Auth HTTP 契约作为平台事实来源。
SoarStarter 有两个分别维护、分别版本化的公开 HTTP 边界。
Soar App API v1
market/pilot/openapi.yaml 是规范 OpenAPI 3.1 契约，覆盖 /api/app/v1 业务 Operation：
- Profile 读取与更新。
- Todo 列表、创建、更新、删除、清理与排序。
- 原生设备 Token 注册与删除。
- 当前用户 APNs 测试推送。
- 订阅快照、支付和管理入口行为。
- 预签名上传创建与完成。
- 级联账户删除。
成功响应使用 { "success": true, "data": ... }。错误使用 { "success": false, "error": { "code", "message", "requestId" } }。v1 只接受向后兼容的增量变更；破坏性变更必须使用 v2。
Better Auth HTTP
market/pilot/auth-http.md 定义独立的 /api/auth/* 原生契约，覆盖签名 Bearer 传输、可信 Origin、set-auth-token、邮箱密码、OTP、原生 ID Token 登录、Session 查询、撤销和凭据修改。
认证端点有意不属于 OpenAPI 业务契约。不要把它们复制到 /api/app/v1，也不要发明第二种 Session 传输。
宿主文档解释框架专属接线，客户端文档解释安全存储与配置；端点 Schema 不在每个模板中重复维护。