# 在 SlideStage Pro 上传第一份 Deck

本教程面向第一次使用 SlideStage Pro 的团队成员。你会上传一份 `.stage` 文件，打开详情页，并完成基本验收。

## 前提条件

你需要：

- 一套可访问的 SlideStage Pro。
- 一个已经登录的账号。
- 一份通过校验的 `.stage` 文件。

如果你还没有 `.stage`，先用 `slidestage-pack` 或 SlideStage Lite 转换器生成。

## 1. 登录 Pro

打开 Pro 的登录页：

```text
https://decks.example.com/login
```

输入邮箱和密码登录。

如果你还没有账号，请让管理员创建邀请链接。Pro 默认关闭开放注册，没有邀请 token 的注册请求会被拒绝。

## 2. 进入上传页面

登录后进入 deck 上传入口。

上传表单通常包含：

- `.stage` 文件。
- 可选标题覆盖。

如果没有填写标题，Pro 会使用 manifest 中的 `title`。

## 3. 选择 `.stage`

选择本地 `.stage` 文件并提交。

上传时，Pro 会按固定顺序处理：

1. 检查文件大小。
2. 计算 SHA-256。
3. 使用 `@slidestage/core` 读取 zip。
4. 校验 `manifest.json`。
5. 校验包内路径安全。
6. 写入对象存储。
7. 在数据库事务中创建 deck 和版本记录。

如果任一步失败，上传会中止，并返回结构化错误。

## 4. 打开详情页

上传成功后，Pro 会跳转到 deck 详情页。

在这里检查：

- 标题是否正确。
- slide 数量是否正确。
- 当前版本是否显示。
- deck 是否可以打开播放。

## 5. 播放验收

点击播放或打开 deck viewer。

检查：

- 第一页是否正确显示。
- 上一页/下一页是否正常。
- speaker notes 是否出现。
- 批注工具是否可用。
- 刷新页面后笔记或批注是否保留。

如果播放失败，先确认 `.stage` 能否在 SlideStage Lite 中打开。Lite 也失败时，问题通常来自包本身；Lite 成功但 Pro 失败时，再检查 Pro API 日志和上传限制。

## 6. 邀请他人查看

如果你的部署启用了团队共享或管理员可见范围，邀请其他成员登录后查看这份 deck。

管理员可以创建邀请 token。普通用户使用邀请注册后，即可访问自己有权限的 deck。

## 常见错误

### `INVALID_STAGE_ZIP`

文件不是合法 zip，或缺少根目录 `manifest.json`。重新打包并校验。

### `INVALID_MANIFEST`

Manifest 不符合 `slidestage@1.0` schema。使用 `@slidestage/spec` 或 packer verify 检查字段。

### `UNSAFE_PATH`

包内路径包含 `..`、绝对路径、反斜杠或控制字符。修复源文件路径后重新打包。

### 文件过大

检查 `UPLOAD_MAX_BYTES`。如果 deck 本身过大，先压缩资源或降低媒体大小；如果业务确实需要更大包，再调整服务端配置。