docs: add workspace collaboration design and client demos

Document shared workspaces, realtime messaging, member handling, and source permissions. Include local interaction demos and verification scripts, and update development startup for Electron Node mode. Production collaboration services remain unimplemented.
2026-09-28 17:04:34 +08:00
parent 440d878d76
commit 599a0a6645
19 changed files with 880 additions and 22 deletions
@@ -5,8 +5,8 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中 |
-| 版本 | 0.3 |
-| 日期 | 2026-09-09 |
+| 版本 | 0.5 |
+| 日期 | 2026-09-28 |
 | 关联 PRD | [ShareServer PRD](./prd.md) |
 | 功能逻辑 | [功能逻辑设计](./logic-design.md) |
 | 共享协议 | [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) |
@@ -62,12 +62,13 @@ ShareServer 仍不得导入 Electron 的 `src/shared`，也不得依赖相邻桌
 ## 2. 技术选型约束

 - 使用与仓库一致的 TypeScript/Node.js 工具链，具体 HTTP 框架在实现前根据维护性选择。
- PostgreSQL 是组织、策略、任务元数据和审计的权威数据库。
+- PostgreSQL 是组织、策略、任务元数据和审计的权威数据库；工作空间消息、处理状态及可靠投递记录
+  也以数据库为准，具体业务表与受控正文存储在协作模块实现时增加。
 - Package、可选中继暂存和 Office 工作副本使用 S3 兼容对象存储；不开启对应功能时不要求
  对象存储，启用 Office 时对象存储是必需依赖。
 - Web 控制台与 API 同源部署，采用严格 CSP，不在浏览器保存设备凭据。
- 单实例部署可完整工作；水平扩展时再引入共享事件/连接路由组件，不为未验证规模预设复杂
-  分布式协议。
+- 单实例部署可完整工作，不为未验证规模预设复杂分布式协议。工作空间实时投递优先评估独立
+  实时组件，与是否水平扩展分开决策；第 18 节记录候选方案，尚未确定采用。

 ## 3. 服务模块

@@ -80,6 +81,8 @@ ShareServer 仍不得导入 Electron 的 `src/shared`，也不得依赖相邻桌
 | `policies` | Grant、强制策略和确定性授权计算 |
 | `approvals` | 内容绑定申请、决定、过期和通知 |
 | `tasks` | task/attempt、provider 路由、状态和取消 |
+| `workspaces`（待实现） | 共享关联、成员访问、资料同步、空间消息、线程与处理请求 |
+| `delivery`（待实现） | 事务投递记录、实时组件适配、去重、离线补收与历史查询 |
 | `relay` | 可选有界数据中继，不解释能力正文 |
 | `packages` | 不可变对象、签名目录、通道和撤销 |
 | `office` | 编辑会话、工作副本、ONLYOFFICE 配置、callback、checkpoint、保留和健康 |
@@ -163,6 +166,8 @@ revocations
  `project` 和 `automation` 种类及 Provider 验证后的本地关联 ID 摘要。Provider 执行时按该
  revision 在本地重新解析分区并检索；服务端不接收记忆文本、来源正文、Embedding 或检索
  结果。新增来源是权限扩大，移除来源是单向收紧。
+- 上述记忆限制针对 Provider 私有记忆授权。FR-18 明确发布的知识或回顾副本走独立共享内容
+  授权与存储，不借 Publication 内存策略上传私有记忆或开放记忆浏览。
 - `document_edit_sessions` 只保存组织、用户、设备、公开来源 ID、显示名、格式、对象键、摘要、
  访问模式、策略 revision、状态和保留期限，不保存 Desktop 绝对路径。
 - `document_checkpoints` 以 session 内单调 revision 保存对象键、大小、SHA-256、callback 幂等键
@@ -176,6 +181,8 @@ revocations
 - 设备在线状态允许短暂最终一致；身份、撤销、授权和任务接受必须走权威存储。
 - 重复注册挑战、联邦 offer 和 task create 使用唯一幂等键。
 - 无法确认 provider 副作用时只更新 `outcome_unknown`，不靠消息队列自动重放。
+- 工作空间消息／状态与 outbox 待投递事件在同一数据库事务提交，提交成功才确认已发送。
+  投递重试与客户端补收只传播已有事件，不重建 Task 或重放 Provider 副作用。
 - Office callback 的临时对象、checkpoint 行和审计事件在同一提交边界发布。数据库提交失败时
  临时对象保持不可下载并由清理任务删除；重复 callback 依赖会话内幂等键返回已有 revision。

@@ -377,3 +384,88 @@ Desktop 或部署脚本当作真实身份、策略、任务或审计 API。下
 初始化、本地身份、PostgreSQL 组织作用域和事务审计开始，不在 fixture 上叠加生产状态。
 当前原型没有 Office 导航、配置、会话 API、对象存储、ONLYOFFICE、callback 或 Desktop 文档
 Tab 集成；上述章节仅定义目标设计。
+
+## 17. 工作空间协作的待实现契约
+
+本节记录 FR-15 至 FR-18 对服务端的最低契约要求，尚未确定具体 API 路径、数据库迁移和协议
+包版本；跨产品网络架构继续以关联总体设计为准，进入开发前须完成 Desktop/Server 联合评审。
+
+| 对象或契约 | 服务端要求 |
+| --- | --- |
+| 共享关联 | 本地 workspace ID 与服务端共享 ID 分开；绑定 organization、owner、成员和 revision；本地未共享空间不注册到服务端 |
+| 资料同步请求 | 携带共享关联、客户端操作 ID、基准 revision 和增量游标；逐项返回接受、拒绝或冲突，不使用客户端时间决定权限 |
+| 空间消息 | 保存发送者、message ID、thread ID、提及身份、上下文版本与受众；普通消息不创建处理任务 |
+| 处理请求 | 显式意图关联一条消息，保存唯一处理人、本人确认标记和接受时的偏好版本；提及与处理人分开 |
+| 处理偏好 | 按空间和成员保存模式、分身绑定、来源授权引用及 revision；只应用于处理请求，绑定 Publication 沿用能力权限检查 |
+| 消息事件与历史 | 稳定事件身份、服务端顺序及对象 revision；支持增量补收和历史分页，资料暂停不停止消息事件 |
+| 执行与回复 | 对消息处理版本、任务关联和回复 ID 建立幂等约束；接手与发布以同一权威版本比较，防止迟到结果发布 |
+| 回顾与知识 | 引用来源身份、版本、受众和动作授权；明确共享的内容副本存入受控内容存储，原始私有分区不入库 |
+
+ShareServer 必须持久化获准共享的消息和资料，才能提供消息离线补收及资料同步。此功能使用受控
+业务内容存储，不能复用普通审计或只转发不持久化的 task relay；仅部署控制面的实例应报告
+空间协作不可用，不假装接受消息。具体正文存储介质、额度、加密与保留配置在协议实现前确定。
+管理员仅凭管理身份不能通过内容接口读取正文，备份策略须覆盖启用后的共享业务内容。
+
+授权撤销、成员状态与同步接收使用服务端当前事实。在同一事务中接受一次操作并记录幂等结果，
+重试只能获得同一结果；冲突不能静默覆盖成员名单、内容范围或回复。分身运行环境仍在
+Provider，工作空间消息不使 ShareServer 自动成为模型运行节点。草稿确认须原子消费待确认的
+处理版本；同操作重试返回原结果，不同正文的重复确认或接手后的旧确认返回版本冲突。
+
+验收须覆盖 US 中的离线发送、确认丢失、部分成功、跨空间隔离、移除成员、关闭共享后旧队列、
+同时接手与发布、不同正文的重复确认、待开启时关闭共享、新成员读取历史的限制，以及回顾
+两种权限的单独撤销。静态 demo 的 localStorage 和
+角色切换不能作为这些服务端契约的实现。
+
+## 18. 实时通信组件选型提案
+
+状态：待验证，未定版、未安装组件、未新增运行依赖。优先评估 **ShareServer + PostgreSQL +
+Centrifugo**。此处是组件职责比较，不代表已核验当前版本、许可证、部署成本或生产可靠性；
+选型须以固定版本的文档核对与端到端试验为依据。
+
+| 候选 | 采用范围 | 需要 GoodBuddy 完成的部分 | 当前判断 |
+| --- | --- | --- | --- |
+| [Centrifugo](https://centrifugal.dev/) | 实时频道、连接及恢复相关机制 | 权威消息存储、历史、权限、成员通知和协作处理 | 优先验证，可保留 ShareServer 业务模型 |
+| [Matrix / Synapse](https://matrix.org/) | 房间、成员、消息及同步体系 | 身份、空间与房间映射、界面及分身协作扩展 | 采用完整通信体系的备选 |
+| [OpenIM](https://openim.io/) | IM 服务与客户端 SDK | 组织和空间集成、协作处理及来源授权 | IM 范围扩大时比较 |
+| [Socket.IO](https://socket.io/) | 连接、事件及房间广播 | 持久化、可靠交付、历史、补收和业务权限 | 可作传输层，不按完整 IM 服务评估 |
+
+### 18.1 职责与投递流程
+
+ShareServer 接收客户端消息并执行组织、空间、受众和附件授权检查。Centrifugo 候选方案只负责
+实时传输，不能由客户端绕过 ShareServer 直接广播一条被视为权威的消息。
+
+1. 客户端携带稳定操作 ID 提交普通消息、线程回复或显式处理请求；附件版本先准备完成。
+2. ShareServer 在一个事务内写入消息／状态、必要的处理请求及 outbox 事件，提交后返回接受结果。
+3. 后台投递器读取 outbox，将已提交事件发布到实时组件；成功后记录投递结果。发布后未能记录
+   成功可能导致重复投递，因此采用至少一次投递，客户端按事件身份与对象版本合并。
+4. 在线客户端收到更新通知后，按授权读取新增消息和状态。断线后按服务端游标补收；组件的
+   短期历史只作加速，不能替代数据库中的权威消息历史。
+5. 仅显式处理请求的执行调度可创建分身 Task，创建受幂等约束；历史重放、事件重投或成员多设备
+   在线不会重复启动执行。
+
+实时组件故障时，只要数据库和业务接收条件正常，ShareServer 可确认消息已保存，并说明实时
+投递延迟；outbox 恢复后继续投递。数据库事务失败则不确认已发送。过期历史或游标失效时返回
+明确的重新同步路径，在现有保留范围内重建进度，不伪造完整历史。
+
+### 18.2 访问与事件范围
+
+首期优先使用不含正文、草稿或敏感摘要的更新通知，具体订阅标识由服务端授权生成；客户端
+经当前授权的内容 API 拉取正文。移除成员或关闭共享后，内容、历史及补收接口立即拒绝新
+读取，并撤销其订阅／连接资格，不能仅依赖长效订阅凭据自然过期。
+
+频道按组织、空间及受众隔离。AI 草稿使用独立私有范围，公开频道、历史、outbox 公开事件和
+普通成员补收中均不含草稿正文。本人确认后的最终回复作为新的公开消息提交。已在撤销前取得
+的正文无法通过断开连接擦除；旧通知也不能帮助客户端绕过当前内容授权。
+
+### 18.3 验证与定版条件
+
+- 两个真实客户端验证普通消息、提及、线程回复、请求处理和状态更新；暂停资料自动同步时消息仍及时到达。
+- 数据库提交后、实时发布前终止投递器，恢复后消息不丢失；发布后确认丢失允许重复事件但不重复显示或执行。
+- 多设备断线重连验证顺序、去重、历史分页和游标恢复；组件历史不可用时可从数据库补收。
+- 移除成员后旧连接不能获取新正文，旧 token 不能读取历史或补收；验证跨组织、跨空间与草稿隔离。
+- 本人接手和分身完成竞争、两个设备确认不同草稿时，只发布规则允许的结果。
+- 核验候选固定版本的许可证、维护状态、SDK 与 Desktop 兼容性，以及部署、备份恢复和资源需求。
+
+上述验证通过后再确定组件、版本、接口与部署拓扑。消息目标延迟、规模及保留期限仍待产品和
+部署评审；当前不作吞吐或实时性数值承诺。运维需记录 outbox 积压、投递重试及补收失败，备份
+消息与事件进度；连接、短期凭据不恢复。新增组件的配置、凭据和健康检查进入部署设计后才能上线。