SlideStage Pro API 参考

本页是 SlideStage Pro v0 的公开 API 速查。它面向前端维护者、集成脚本作者和部署者，用来理解 Pro 的 HTTP 边界。

所有业务接口都挂载在 /api 下。认证使用 Better Auth session cookie。

错误格式

API 错误统一返回：

{
  "error": {
    "code": "STRING_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

客户端应依赖 error.code 做分支，而不是解析 message。

Auth 状态

接口分三类：

• Public：不需要登录。
• Authenticated：需要有效 session。
• Admin：需要有效 session，且 user.role === "admin"。

Health

GET /api/health

Public。用于 liveness/readiness 检查。

成功响应：

{
  "status": "ok",
  "version": "0.1.0",
  "uptimeSeconds": 1234,
  "checks": {
    "db": "ok",
    "storage": "ok"
  }
}

如果数据库或存储不可用，返回 503，并把 status 设为 degraded。

Auth

Better Auth 挂载在 /api/auth/*。

常用接口：

方法	路径	权限	说明
POST	/api/auth/sign-in/email	Public	邮箱密码登录。
POST	/api/auth/sign-out	Authenticated	退出登录。
POST	/api/auth/sign-up/email	Public + invite	使用邀请 token 注册。
GET	/api/auth/get-session	Public	获取当前 session 或 null。

注册必须带 inviteToken。缺失或无效时返回 INVITE_REQUIRED。

Decks

GET /api/decks

Authenticated。列出当前用户可见的 deck。管理员可见全部 deck。

Query：

• limit：分页大小。
• cursor：游标。

响应：

{
  "items": [
    {
      "id": "ck...",
      "title": "Q3 Roadmap",
      "fingerprint": "sha256-...",
      "currentVersionId": "ver_...",
      "visibility": "private",
      "ownerId": "usr_...",
      "createdAt": "2026-05-20T10:00:00Z",
      "updatedAt": "2026-05-20T10:05:00Z",
      "slideCount": 23
    }
  ],
  "nextCursor": null
}

POST /api/decks

Authenticated。上传新的 .stage 并创建 deck。

请求类型：multipart/form-data。

字段：

• file：必填，.stage zip。
• title：可选，覆盖 manifest title。

服务端处理顺序：

1. 检查上传大小。
2. 计算 SHA-256。
3. 使用 @slidestage/core 读取 .stage。
4. 校验 manifest。
5. 校验包内路径安全。
6. 写入对象存储。
7. 在 Prisma transaction 中创建 deck 和版本记录。

GET /api/decks/:id

Authenticated。读取 deck 详情。

GET /api/decks/:id/blob

Authenticated。下载或播放当前版本 .stage blob。

DELETE /api/decks/:id

Authenticated。删除当前用户拥有的 deck；管理员可删除任意 deck。

Notes 与 Annotations

Pro 保存服务端笔记和批注，让同一份 deck 在团队环境中保持状态。

常见形态：

• GET /api/decks/:id/notes
• PUT /api/decks/:id/notes/:slideIndex
• GET /api/decks/:id/annotations
• PUT /api/decks/:id/annotations/:slideIndex

笔记是纯文本。批注是平台定义的 JSON payload，客户端应把它视为不透明结构。

Admin Invites

管理员可以创建邀请 token，用来控制注册。

常见形态：

• GET /api/admin/invites
• POST /api/admin/invites
• DELETE /api/admin/invites/:id

邀请 token 只能使用一次。注册成功后，Pro 会把邀请标记为已使用，并设置新用户角色。

兼容性规则

Pro 不重新实现 .stage 解析规则。上传、播放和校验都应通过 Lite 发布的 @slidestage/core / @slidestage/spec 能力完成。

如果 API 行为需要改变，优先检查是否涉及 .stage 格式契约；格式契约变更应先在 Lite/spec 侧提出。