在 SlideStage Pro 上传第一份 Deck

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

前提条件

你需要：

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

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

1. 登录 Pro

打开 Pro 的登录页：

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 本身过大，先压缩资源或降低媒体大小；如果业务确实需要更大包，再调整服务端配置。