白板核心概念

Room / Scene / Appliance / Member / Camera / Operation / Replay 的字段与不变量。

版本 v1.0.0 · 更新于 2026-10-28 · 修订 1

白板的领域模型很小，但每条不变量都直接影响客户端体验。这一页把这些概念讲清楚，后面的 REST 与 SDK 页面都复用同一套术语。

房间（Room）#

房间是白板内容的最小隔离单位。每个房间有全局唯一的 uuid、所属项目的 appUUID、房主账号的 teamUUID，以及：

• phase：active（可读写）、banned（封禁，拒绝写入与签发 Token）、closed（永久关闭，仅只读）。
• limit：同时持有 writer / admin 角色的成员上限，0 表示不限制。
• version：房间版本号，每次变更 +1；客户端用它判断自己是否落后。
• currentScenePath：当前场景路径，默认 /init。

房间 Token 绑定到具体房间；项目凭证（Basic）拥有该项目的全部房间。

场景（Scene）#

场景是白板的一页，路径形如 /deck/page1：/deck 是目录，page1 是页面名。约定：

• 路径必须以 / 开头，不能包含 // 或 ..。
• 同一目录内页面名唯一，页面名不含 /，长度 1..64。
• 页面可以带一个背景图（ppt：src、width、height）。
• 切换场景只改 currentScenePath，不修改任何内容。

工具与笔迹（Appliance / Stroke）#

工具由 appliance 枚举：pencil、pencilEraser、eraser、rectangle、ellipse、shape、selector、hand、clicker、laserPointer。

一条笔迹包含：工具、颜色（#rrggbb）、线宽（1..64）、点序列（最多 4096 点）、作者 memberId、序号 seq。擦除不会删除记录，而是把 erased 置为 true，保证回放可以重建当时画面。

成员（Member）#

成员由客户端在加入房间时登记（memberId 由客户端提供，房间 Token 授权的是场景而不是固定身份）。成员记录角色、当前工具、颜色和线宽，以及可撤销/可重做的步数。

视口（Camera / Viewport）#

视口是相机在世界坐标中的可见区域：x、y、width、height、scale。视口属于房间状态而不是某个成员，新加入的成员和回放起点都从房间视口开始。

操作日志与撤销/重做#

每次变更追加一条操作，seq 单调递增，包含类型、成员、场景、房间版本与负载。撤销/重做按成员隔离：

• 撤销：找到该成员在当前场景中最近一条未撤销、未擦除的笔迹，标记 undone。
• 重做：仅当该成员此后没有追加新笔迹时，恢复最近一次撤销。
• 记录不会被物理删除，因此回放与审计能看到完整过程。

回放（Replay）#

回放接口把操作日志按时间排序，返回 offset（相对第一条保留操作的毫秒偏移）与操作本身。播放器据此实现播放、暂停、定位、结束；快照接口则返回与回放同源的完整状态，便于离线渲染。

Token 角色#

Project 凭证等价于 admin，只应存在于服务端。