# SlideStage Pro API 参考

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

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

## 错误格式

API 错误统一返回：

```json
{
  "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 检查。

成功响应：

```json
{
  "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`：游标。

响应：

```json
{
  "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 侧提出。