# SlideStage Pro 的认证与邀请模型

SlideStage Pro 使用关闭注册模型。用户不能随意注册，必须通过管理员创建的邀请码进入系统。

这个设计让 Pro 可以安全地部署在小团队、内网或私有 VPS 上，而不需要先实现完整的组织、多租户和公开注册体系。

## 核心角色

Pro v0 只需要两个角色：

- `admin`：管理用户邀请、查看所有 deck、执行平台管理操作。
- 普通用户：上传和管理自己有权限访问的 deck。

角色存储在用户记录上。Better Auth 负责身份和 session，Pro 在它之上增加角色和邀请规则。

## 登录

登录使用 Better Auth 的邮箱密码接口：

```text
POST /api/auth/sign-in/email
```

成功后，浏览器持有 HttpOnly session cookie。前端通过 session 查询判断当前用户状态。

## 注册为什么需要邀请

Pro 是自托管系统。默认部署通常暴露在团队域名、内网或公网 VPS 上。如果允许开放注册，任何访问到页面的人都可能创建账号。

因此注册必须带 `inviteToken`。

注册请求缺少 token 或 token 无效时，服务端返回：

```json
{
  "error": {
    "code": "INVITE_REQUIRED",
    "message": "Invite token is required"
  }
}
```

## 邀请生命周期

1. 管理员创建邀请。
2. 系统生成一次性 token。
3. 管理员把注册链接发给新用户。
4. 用户注册时提交 token。
5. 服务端在创建用户前验证 token。
6. 用户创建成功后，服务端标记邀请已使用，并给用户分配角色。

邀请应只能使用一次。已经使用、过期或被删除的邀请不能再次注册。

## Bootstrap 管理员

首次启动时，如果数据库中还没有用户，Pro 会读取 bootstrap 环境变量创建第一个管理员。

常用变量：

- `BOOTSTRAP_ADMIN_EMAIL`
- `BOOTSTRAP_ADMIN_PASSWORD`
- `BOOTSTRAP_ADMIN_NAME`

如果系统没有任何用户，又缺少 bootstrap 配置，API 应拒绝继续服务。这样可以避免部署出一个没有管理员、但可能开放注册的站点。

## Session 与 Cookie

生产环境中，session cookie 应满足：

- HttpOnly。
- SameSite=Lax。
- HTTPS 下 Secure。
- `BETTER_AUTH_URL` 与用户实际访问地址一致。

如果登录后马上变回未登录，优先检查 `BETTER_AUTH_URL`、反向代理协议头和公开访问域名是否一致。

## 前端如何使用

前端不直接读取 cookie。它通过 Better Auth client 或 session API 获取当前用户。

常见 UI 分支：

- 无 session：显示登录页。
- 有 session：进入 deck 列表。
- `user.role === "admin"`：显示邀请管理入口。

不要在前端只靠隐藏按钮保护管理员能力。服务端接口必须再次检查 admin 权限。

## 设计边界

Pro v0 暂不处理：

- OAuth 登录。
- Passkey / WebAuthn。
- 双因素认证。
- 多租户组织。
- 公开注册。
- 邮箱找回密码。

这些能力可以后续添加，但不应改变当前原则：注册入口必须默认关闭，管理员邀请是团队准入边界。