工作空间通知与公告
工作空间公告用于向团队发布维护通知、入组说明或共享事项。每个工作空间维护一份当前公告配置，包含公告弹窗和可以独立启用的顶部通知栏。
本页对应 v2.4.7 之后正在开发的工作空间公告实现。部署的应用需要包含这项功能；仅使用 2.4.7 镜像并不代表已支持。
打开公告编辑器
- 在侧边栏切换到目标工作空间。
- 打开工作空间菜单，选择成员。
- 在管理弹窗中切换到公告标签。
- 配置弹窗、顶部通知栏或同时启用两者，检查预览后点击保存。
- 使用成员账号进入同一工作空间，验证展示效果。
工作空间的所有者和管理员可以发布公告、上传配图。普通成员和游客可以阅读，不能编辑。平台管理员也需要具备该工作空间中的相应角色；平台管理身份本身不授予此编辑器的写入权限。
公告随当前工作空间展示。个人空间不显示工作空间公告，其他工作空间的成员也无法通过该空间的公告接口读取配置。
| 公告类型 | 管理入口 | 展示范围 |
|---|---|---|
| 全局公告 | 管理后台 → 系统 → 公告 | 整个应用，包括个人空间 |
| 工作空间公告 | 工作空间菜单 → 成员 → 公告 | 正在使用对应工作空间的成员 |
两类公告可以同时启用。启动弹窗使用共同队列，依次展示。两种顶部通知栏同时存在时，全局栏在上、工作空间栏在下，位于内容区域顶部，不覆盖侧边栏。
配置公告弹窗
| 设置 | 实际行为 |
|---|---|
| 显示公告 | 启用弹窗；标题、文字、图片至少有一项非空才会展示 |
| 必须阅读 | 5 秒内不能关闭，包括关闭按钮、Escape 和点击弹窗外部 |
| 允许用户选择不再弹出 | 提供针对当前版本的“下次不再提示”选项 |
| 标题 | 可选的纯文本标题 |
| 文字 | 支持 HTML，预览和展示时会过滤 HTML；换行可使用 <br> |
| 图片 | 可填写 URL 或上传 PNG/JPG/JPEG；桌面端图文并排，移动端上下排列 |
弹窗在用户完成首次引导及所需的密码设置后展示。关闭弹窗开关不影响独立启用的顶部通知栏。
关闭与版本更新
关闭只关闭当前弹窗，不记住后续访问的选择。启用相应选项后，下次不再提示会在当前浏览器记住此版本。以后保存产生新的版本时间戳时，弹窗可以再次展示，包括只修改顶部通知栏的保存。
这些选择保存在浏览器本地，按工作空间和版本区分，不在设备或浏览器之间同步。存储键不区分账号，因此共用同一浏览器配置文件的账号可能共用关闭记录。清除站点数据后，记住的选择也会清除。
“必须阅读”表示等待五秒再关闭。这项功能不收集服务端已读回执、未读数量或成员阅读名单，也不会发送邮件或系统推送通知。
配置顶部通知栏
启用顶部通知栏并填写简短的 HTML 内容，可以包含链接。即使弹窗关闭，通知栏也能独立展示，但内容必须非空。
- 关闭通知栏会在本浏览器记住其版本，不受弹窗“不再提示”开关控制。
- 修改通知栏内容或启用状态会更新其版本。只保存弹窗修改时，未变更的通知栏保留原版本，已经关闭的栏不会因此重新出现。
- 关闭通知栏并保存会清空其已存储的 HTML；重新启用时需要重新填写内容。
- 保存成功后，在线客户端收到更新事件并重新读取当前工作空间的公告。进入工作空间时也会读取当前配置。
内容与配图限制
工作空间接口去除首尾空白后执行以下限制。文字按 UTF-8 字节数计算，中文和表情可能在输入框的字符上限之前就触及服务端限制。
| 内容 | 服务端限制 |
|---|---|
| 标题 | 120 字节，通常约 40 个汉字 |
| 正文 HTML | 64 KiB |
| 图片 URL | 2 KiB |
| 通知栏 HTML | 8 KiB |
| 上传图片 | PNG/JPG/JPEG，默认 256 KiB，由 AIVORY_API_ADMIN_ICON_UPLOAD_SIZE 控制 |
编辑器会在上传前缩放图片，服务端校验扩展名、实际类型和图片头。此上传接口不支持 SVG、GIF 或 WebP。配图使用共享的 /api/icons/… 资源服务，已登录且持有 URL 的用户可以读取；图片 URL 本身不是工作空间专属的私密下载链接。
接口参考
三个接口均要求登录，并使用具体的工作空间 ID。
| 方法 | 路径 | 权限与结果 |
|---|---|---|
GET | /api/workspaces/:id/announcement | 工作空间成员读取当前配置；尚未保存时为未启用状态 |
PATCH | /api/workspaces/:id/announcement | 工作空间所有者或管理员保存并返回完整配置 |
POST | /api/workspaces/:id/announcement/image | 工作空间所有者或管理员上传图片；multipart 字段为 file，返回 url 与 filename |
虽然使用 PATCH，保存实际是替换完整配置，不会逐字段合并。接入时先读取当前对象，修改后提交所有需要保留的设置。updated_at 与 bar_updated_at 由服务端决定，以返回值为准；两者使用 Unix 秒，同一秒内连续保存不保证产生不同版本。
字段定义、审计记录和浏览器存储键见工作空间与成员表。
数据存储、升级与备份
启动迁移会在 SQLite 和 PostgreSQL 中创建 workspace_announcements 表。每个已配置工作空间占一行，删除工作空间时级联删除该行。每次保存会在工作空间审计日志中记录 announcement.updated。
| 备份方式 | 公告覆盖范围 |
|---|---|
| 完整备份 | 包含公告配置和审计记录 |
| 完整备份并包含文件 | 额外包含 UPLOAD_DIR/icons/ 下的本地上传配图 |
| 配置导出 | 不包含工作空间公告数据行；可能携带共享图标文件，但仅有图片不能重建公告 |
| 外部图片 URL | 只保存 URL；两种导出均不会下载外部图片 |
其他条件满足兼容要求的旧版备份，即使没有公告表条目也可以恢复。新表保持为空，保存公告后才会显示。完整恢复不会保留目标环境原有的工作空间公告。浏览器的关闭记录不属于数据库备份。
完整恢复步骤见升级、备份与恢复。
常见问题
| 现象 | 检查项 |
|---|---|
| 找不到“公告”标签 | 先选择工作空间，确认账号是其所有者或管理员，以及部署版本包含该功能 |
| 弹窗没有出现 | 检查弹窗开关、非空内容、首次引导与密码设置，以及此浏览器是否已选择不再提示当前版本 |
| 顶部通知栏没有出现 | 检查其独立开关、内容，以及单独保存的关闭记录 |
| 中文标题保存失败 | 服务端上限为 120 UTF-8 字节，可能早于输入框允许的字符上限 |
| 恢复后公告图片失效 | 检查备份是否包含文件、目标上传目录是否存在对应图标，或外部图片 URL 是否有效 |