房间、权限与用户偏好

两层角色模型

SyncTV 有两层角色，不能混为一谈。

层级	角色	作用范围
全局用户角色	`root`、`admin`、`user`	平台管理、用户管理、房间管理、系统设置
房间角色	`creator`、`admin`、`member`、`guest`	单个房间内的播放、成员、媒体、聊天和设置权限

全局 admin 不自动等于某个房间的 admin。房间 admin 也不等于平台管理员。

角色	能力边界
`root`	超级管理员，可以管理 root/admin/user、全局设置和所有房间
`admin`	平台管理员，可以管理普通用户和房间，但不能越权管理 root 或同级管理员的敏感设置
`user`	普通用户，按房间和业务权限使用功能

用户状态是从封禁记录派生的有效状态：

状态	影响
`active`	可以登录、创建房间、加入房间
`banned`	不能登录、创建房间或加入房间

房间角色	默认语义
`creator`	房间创建者，拥有全部房间权限，不能通过房间设置削弱
`admin`	房间管理员，默认拥有成员管理、播放控制、媒体管理、房间设置等权限
`member`	普通成员，默认可以聊天、添加/编辑/删除自己的媒体、查看播放列表和成员信息
`guest`	游客，默认只读，只能查看播放列表

房间角色提供基础权限，房间设置和成员权限覆盖会在基础权限上继续做加减。

有效权限按三层计算：

全局角色默认权限
  -> 房间设置 added/removed 权限
  -> 成员个人 added/removed 权限

规则：

权限	含义
`SEND_CHAT`	发送聊天和弹幕消息
`ADD_MEDIA`	添加媒体
`DELETE_MEDIA_SELF` / `DELETE_MEDIA_ANY`	删除自己添加的媒体 / 删除任意媒体
`EDIT_MEDIA_SELF` / `EDIT_MEDIA_ANY`	编辑自己添加的媒体 / 编辑任意媒体
`REORDER_PLAYLIST`	调整播放列表顺序
`CLEAR_PLAYLIST`	清空播放列表
`START_LIVE`	开始直播推流
`PLAY_CONTROL`	播放、暂停、seek
`CHANGE_CURRENT_MEDIA`	切换当前播放媒体
`CHANGE_PLAYBACK_RATE`	修改播放速度
`APPROVE_MEMBER`	审批加入房间请求
`KICK_MEMBER`	踢出成员
`BAN_MEMBER`	封禁或解封成员
`SET_MEMBER_PERMISSIONS`	修改成员权限
`ADD_MEMBER`	主动添加成员
`SET_ROOM_SETTINGS`	修改房间设置
`DELETE_CHAT`	删除聊天消息
`DELETE_ROOM`	删除房间，不可作为普通房间内委派权限
`VIEW_PLAYLIST`	查看播放列表
`VIEW_MEMBER_LIST`	查看成员列表
`VIEW_CHAT_HISTORY`	查看聊天历史
`USE_WEBRTC`	使用 WebRTC 语音/视频能力

权限值在 API/CLI 中通常以 u64 bitmask 表达。修改 bitmask 前应先确认目标角色和当前有效权限。

房间设置控制加入策略、显示能力和默认权限。

设置	默认值	说明
`require_password`	`false`	是否要求房间密码
`allow_guest_join`	`false`	是否允许游客加入
`max_members`	`100`	房间最大成员数，上限 `10000`
`require_approval`	`false`	加入房间是否需要审核
`allow_auto_join`	`true`	是否允许符合条件的用户自动加入
`chat_enabled`	`true`	是否启用聊天
`danmaku_enabled`	`true`	是否启用弹幕
`auto_play`	`{}`	自动播放策略，JSON 结构
`admin_added_permissions` / `admin_removed_permissions`	`0`	房间 admin 默认权限增减
`member_added_permissions` / `member_removed_permissions`	`0`	房间 member 默认权限增减
`guest_added_permissions` / `guest_removed_permissions`	`0`	房间 guest 默认权限增减

示例：

synctv room settings get <ROOM_ID>
synctv room settings update <ROOM_ID> --settings-json '{"require_approval":true}'

成员级覆盖用于处理例外，例如临时禁言、给某个成员播放控制、撤销某个管理员的封禁能力。

语义：

建议：

用户偏好是数据库中的用户级设置，不是 YAML 配置。

字段	默认值	说明
`two_factor_enabled`	`false`	是否开启用户级 2FA
`notifications.room_invitation_in_app`	`true`	房间邀请站内通知
`notifications.room_event_in_app`	`true`	房间事件站内通知
`notifications.system_announcement_in_app`	`true`	系统公告站内通知
`notifications.room_invitation_email`	`false`	房间邀请邮件通知
`notifications.room_event_email`	`false`	房间事件邮件通知
`notifications.system_announcement_email`	`true`	系统公告邮件通知
`provider_defaults.alist_instance_name`	`null`	默认 Alist 实例
`provider_defaults.emby_instance_name`	`null`	默认 Emby 实例
`provider_defaults.bilibili_instance_name`	`null`	默认 Bilibili 实例

数据库表还有一个 settings JSONB 扩展载荷，只用于低优先级实验性偏好。稳定的产品偏好应该优先设计成明确字段，不能把 secret、token、Cookie、密码或 Provider 凭据放进去。

2FA 约束：