goodbuddy-shareserver/docs/features/share-server/logic-design.md

ShareServer 功能逻辑设计

文档信息

项目	内容
状态	设计中
版本	0.6
日期	2026-10-01
关联 PRD	ShareServer PRD
共享规则	共享网络总体设计

本地目录首期状态规则

当前本地联调仅实现设备与发布元数据，使用技术设计第 4.1 节 的独立接口。下文组织身份、Grant、任务和文档归属规则属于目标设计。 Office 私有部署第一阶段的限定状态规则见第 8.2 节，不声称具备 INV-1 的组织隔离或 INV-12 的多类凭据体系。

• 注册相同设备 ID 更新名称、平台及版本，保留首次注册时间；相同内容重试不改变时间。
• 注册不自动发布内容，也不表示设备在线。设备列表目前没有心跳或离线判断。
• 发布必须关联已有设备。新 ID 创建 published 条目；相同 ID、相同内容返回已有记录， 相同 ID、不同内容报冲突，不覆盖原记录。
• 撤销将状态变为 revoked 并保留目录记录。重复撤销不改变结果；重试旧发布请求不恢复已撤销记录。
• 能力与知识按 kind 区分。知识的搜索、原文、下载标志分别存储，不相互推导； server 来源也只是发布者声明，不表示文件已经上传或同步。
• 当前没有用户主体或组织所有权，因此真实目录按设备查看。按用户查看仍使用组织示例， 不把设备名称推定为用户身份。

1. 核心不变量

INV-1 组织隔离先于角色

任何查询和变更先绑定 organization，再计算角色。系统管理员的跨组织操作使用独立系统管理 入口并形成审计，不能依靠省略 organization 条件获得全局数据。

INV-2 注册不等于发布

设备注册只建立身份和连接资格。没有有效 Publication 时，目录中没有该设备能力。

INV-3 目录不等于授权

看到能力不能推导可调用或可下载。创建任务和下载包时重新计算当前授权。

INV-4 服务端授权不能扩大端点授权

ShareServer 的 allow 只是签发任务资格。Provider 和调用方仍执行各自本地策略；任一端拒绝 即终止动作。

INV-5 策略拒绝优先

同一动作命中多个规则时使用 deny > require_approval > allow。没有匹配 allow 时默认 deny。

INV-6 联邦为双边交集

单方创建或接受的关系不生效。双方 active 且两端发布、Grant 和数据策略均允许时才能跨组织 创建任务。

INV-7 任务提供者不可改写

ShareServer 只路由调用方冻结的 provider，不在离线、繁忙或失败时替换节点。

INV-8 不恢复短期权威

备份恢复不恢复 Web 会话、设备 socket、一次性挑战、审批 nonce 或任务数据通道。终端必须 重新连接并证明身份。

INV-9 初始化入口一次性关闭

初始化只在实例尚无系统管理员时可用。首个系统管理员创建成功后，后续请求即使持有旧的 一次性引导材料也不能再次进入初始化流程。

INV-10 数字人发布不等于记忆公开

发布数字人只建立一个有界 Agent Publication。它默认不取得所有者任何本地记忆；所有者可以 在发布时勾选 Agent、Global、指定 Project 和指定 Automation 分区，不能开放 Conversation 和 Run 分区。ShareServer 和调用者只能看到允许分区种类与“本次调用会使用本地记忆”的政策 事实，不能读取原始条目、分区内容、来源正文或检索结果。新增可读分区按权限扩大重新审批， 移除分区可以立即收紧。

以上限制针对本地记忆授权。用户另行选定并发布的知识、监督回顾副本按 FR-18 计算内容授权， 不使底层记忆分区可浏览；回答使用与原文读取是不同动作。

INV-11 服务端检查点不等于源文件已保存

在显式的本地来源导入／回写模式中，ONLYOFFICE 保存只产生 ShareServer 权威的 DocumentCheckpoint。只有 Desktop 或远程 GoodBuddy Agent 校验源文件基准并完成原子替换后，源文件才是已保存状态。ShareServer 不根据 callback 成功推断本机或 SSH 文件已经更新。

文档默认以 ShareServer 为主存储，日常操作在 GoodBuddy 中完成。服务端主存模式不要求本地 回写确认；主文档生命周期独立于编辑会话，不能因会话关闭或检查点清理而删除主文档。

个人创建者可删除自己的文档或确认转移所有权给组织。转移后原个人删除权立即失效，删除和 恢复按当前组织权限判断；恢复不改变归属。管理身份和归属元数据可见性不授予个人正文访问权。

INV-12 Office 凭据单用途

设备 API 凭据、编辑器一次性启动授权、ONLYOFFICE 文件令牌和 callback token 分别绑定不同 audience、单个文档会话和短期限。任何一种凭据都不能换取其他 API 权限。

2. 主要状态

2.1 成员

invited -> active -> suspended -> active
invited -> expired | revoked
active/suspended -> removed

suspended 不能登录或创建新任务；历史归属保留。removed 不级联删除审计和已完成任务。

2.2 注册设备

pending -> active <-> offline
pending -> expired | rejected
active/offline -> revoked

客户端心跳只决定 active/offline，不能清除 revoked。重新注册生成新设备 registration。

2.3 Publication

draft -> pending_approval -> active
draft/pending_approval -> rejected
active <-> paused
active/paused -> revoked

provider 离线不会把 Publication 变为 paused；目录同时展示“已发布”和“当前离线”两个事实。

2.4 审批

pending -> approved | rejected | cancelled | expired

审批对象内容摘要、申请主体或策略版本变化后，原审批不能复用。approved 只产生其声明范围内 的 Grant 或一次性决定。

2.5 Package Release

draft -> verifying -> available -> paused -> available
verifying -> invalid
available/paused -> revoked

发布后的版本和字节不可变。修复内容必须使用新版本；revoked 不删除审计证据和对象摘要。

2.6 FederationTrust

draft -> offered -> mutually_confirmed -> active
offered -> rejected | expired
active <-> paused
任意非终态 -> revoked

mutually_confirmed 只表示身份确认完成；双方策略同步成功后才进入 active。

2.7 DocumentEditSession

以下包含上传阶段的流程描述本地来源模式；不将其作为服务端主文档的生命周期。

creating -> uploading -> ready -> editing
creating/uploading -> failed | cancelled | expired
ready/editing <-> offline
ready/editing/offline -> closing -> closed
任意非终态 -> revoked | expired

编辑内容使用独立状态维度：

clean -> dirty -> saving -> checkpoint_available
saving -> failed | outcome_unknown
checkpoint_available -> dirty

offline 不删除已确认 checkpoint。outcome_unknown 必须通过对象摘要和 callback 幂等键查询 同一次保存，不能自动创建另一份 checkpoint。

2.8 工作空间共享与资料同步

本地 Workspace 始终具有本地身份，共享关联记录目标组织和服务端身份。每个关联单独记录：

维度	状态与含义
共享生命周期	local_only -> enable_pending -> shared -> revoke_pending -> revoked；开启失败回到 local_only 并保留原因
资料同步策略	on_demand 或 periodic；暂停只暂停资料自动交换，不影响实时消息或撤销共享
消息连接	实时订阅及断线补收独立运行，消息与处理状态不等待资料周期
连接	online / offline，与共享授权独立
同步结果	idle / syncing / partial / failed / conflict，附最近成功时间及未确认变更

revoked 表示该共享关联终止，本地 Workspace 仍可使用。重新开启使用新关联。撤销请求结果 未知时保持 revoke_pending 并查询同一请求；权限被拒不能伪装为已撤销。已有共享关联被 服务端移除或组织停用时，由服务端状态收紧访问，本地的 shared 缓存不产生权威。

开启共享仅发布确认清单中的内容。新增成员可以访问当前被授予的空间历史，管理者添加前 必须确认该范围；不能通过添加成员突破来源授权。首期同一关联不可跨组织移动。

同步以逐项确认推进进度；冲突保留本地和远端版本，权限与撤销始终采用服务端当前权威。 发起关闭后本端停止普通上传，联网先提交关闭；服务端已确认的关闭阻止旧队列重放。 已经发送的历史不能通过暂停、删除本地队列或关闭共享改写为从未发送。

2.9 消息交付与处理

消息交付：local_pending -> submitting -> accepted | rejected。local_pending 显示“待发送”。确认丢失时保留未确认状态， 按稳定消息身份重试或查询；不能先生成第二个身份。accepted 仅表示服务端接收，不表示成员 设备收到、已读或已执行。公开回复同样先经历交付确认。未确认 AI 草稿存入本人私有范围， 其正文不进入空间实时流、公开历史和普通成员的离线补收；只可向本人发送私有草稿就绪通知。

普通消息和提及只有交付状态；只有 accepted 且明确携带“请求处理”及处理人身份的消息进入处理流程：

本人模式 / 要求本人确认 -> awaiting_human -> human_handling -> replied_by_human
分身先回复 -> ai_running -> replied_by_ai
分身起草 -> ai_running -> draft_ready -> replied_by_human_confirmed
ai_running / draft_ready / replied_by_ai -> human_handling
AI 不可用 / 失败 -> awaiting_human（保留原因）

状态描述一次定向请求的当前处理事实。接手保留此前回复，不覆盖作者；本次回复完成后继续 讨论可创建关联回复或新请求。空间撤销、成员移除或资料授权失效可将未完成处理阻止在当前 状态并显示原因，不能标记为已完成。已发布事实保留，新的读取仍需有效授权。

开启尚未确认时也可 enable_pending -> revoke_pending。关闭请求绑定原开启操作身份，服务端 必须串行确定开启是否已生效：已生效则撤销同一关联，未生效则阻止该开启操作随后生效。 仅在确认不存在仍有效的关联后显示关闭完成。重连时此检查优先于普通上传。

成员范围扩大时检查既有共享正文、附件及上下文快照的来源授权。若新增受众不被允许，拒绝 该成员变更，保留原成员集合；管理者先补齐授权或移除不兼容共享内容，再提交变更。 资料定期模式在客户端运行且联网时按周期交换资料增量。显式提交的资料按需同步在重连后继续重试， 暂停资料自动同步不取消此类显式请求；未提交本地草稿不得随重连上传。

实时消息由服务端接受后通知在线成员；客户端按服务端进度补收消息、回复与状态事件，按稳定 身份及状态版本去重合并，旧事件不能回退处理状态。断线恢复可以重复传输事件，不得重新创建 处理任务。消息附带内容准备失败时保持待发送并显示原因，不先创建缺少上下文的处理请求。

3. 授权计算顺序

1. 验证请求身份、会话 audience 和 organization。
2. 验证用户、设备、provider、Publication 和 FederationTrust 当前状态。
3. 校验能力或数字人版本、动作、输入 schema、数据类别、大小和委托链。
4. 收集调用方组织、提供方组织、Publication 和 Grant 规则。
5. 按拒绝优先合并，计算 deny/require_approval/allow。
6. 校验次数、并发、预算和有效期。
7. 返回决定、稳定原因和策略引用；需要批准时建立内容绑定申请。
8. 创建任务时再次计算，并把决定快照写入任务。

目录查询可以预计算“可能可用”，但不能替代第 1 至 8 步。

此顺序用于能力调用。空间消息先检查组织、空间、发送者、提及身份、处理人（如有）和附带内容的共享范围， 普通发言及提及无需 Publication；只有显式处理请求选择分身执行时再走上述能力授权。空间访问授权不能代替 Publication/Grant，本人草稿确认也不能绕过当前访问权限。

4. 组织角色边界

动作	系统管理员	组织管理员	发布者	审批人	审计员	成员
实例设置	是	否	否	否	只读有限项	否
成员与组	紧急管理	是	否	否	只读	自己
注册设备	只读/撤销	是	自己	否	只读	自己
发布能力/包	否	是	授权范围	否	只读	否
发布自己的数字人	否	是	授权范围	否	只读	自己
编辑策略	否	是	否	否	只读	否
处理审批	否	可配置	否	授权范围	只读	自己的申请
联邦关系	实例级许可	是	否	可共同审批	只读	否
Office 服务配置	是	策略与会话管理	否	可配置	只读	使用获准服务
审计导出	实例级	组织级	自己相关	自己相关	授权范围	自己相关

实际权限仍由策略计算，表格定义产品默认职责而非硬编码角色名称。

5. 任务路由决策

条件	结果
provider 在线且双方可直连	签发短期直连协商信息
无法直连且双方策略允许中继	建立有界中继通道
中继关闭或任一方禁止	创建失败，说明无可用路由
provider 离线	不排队到无限期，按能力配置有界等待或拒绝
provider 接受后连接中断	保留 task，等待同一 provider 恢复/查询
provider 终态未知且恢复期结束	outcome_unknown
调用方取消	转发取消；provider 确认后终态 cancelled

中继容量不足只产生排队或资源错误，不切换 provider，不改变是否允许中继。

5.1 成员消息的处理决定

普通消息与提及不创建处理任务。按以下顺序决定一次已接收的显式处理请求的处理方式：

1. 校验当前空间、成员和附带内容权限。无权时阻止处理，不改投其他人。
2. “需要本人确认”直接进入 awaiting_human。
3. 使用服务端接受处理请求时的成员空间偏好版本；未配置时为本人处理。
4. 分身方式解析接收者明确绑定的 Publication/version/provider，并记录任务关联；不可用时转本人待处理。
5. 执行前和发布前重验权限及处理版本。普通偏好更新不改写在途任务，撤销或本人接手可以阻止后续发布。

消息身份、AI 执行身份和公开回复身份分别幂等。多个设备不能对同一待处理版本创建重复任务。 本人接手以服务端原子变更处理版本为生效点；其后旧版本 AI 结果只可作为不公开的结果保留， 不得自动发送。若 AI 回复先发布，则保留该回复，本人可在其后补充。

确认草稿绑定草稿版本、确认者和最终正文摘要。其他成员和普通审计不能读取未发送草稿， 政策审批产生的 Grant 不构成本人对该正文的确认。

确认操作原子消费待确认的处理版本。相同操作重试返回既有结果；不同设备对同一草稿提交不同 正文时仅首个成功确认生效，后续返回版本冲突并保留客户端编辑。本人接手也推进处理版本， 其后迟到的旧草稿确认不能另建回复绕过冲突。

5.2 来源、受众与动作

共享知识区分服务器同步副本和远程设备取用。已就绪的服务器副本不因来源设备离线而失效， 但更新需等待设备连接；远程取用在设备离线时不可用。发布暂停或设备撤销仍阻止使用，不能 以已有副本绕过撤销。搜索、读取原文、下载分别判断权限；可用状态、共享对象和管理员元数据 可见性均不替代动作授权。当前共享中心只演示这些状态，无真实内容请求。

可用内容为来源授权、当前入口受众、动作、空间权限、组织策略及 Provider 本地权限的交集。 个人外部入口与组织空间独立授权；同一分身身份复用不复制其所有来源权限。

回顾用于回答	回顾原文可读	行为
否	否	不向该入口提供回顾
是	否	分身可参考，访客不能取得原文
否	是	访客可阅读，分身不得将其作为回答来源
是	是	两种动作均需按各自授权检查

撤销影响新读取、检索和发布，不追溯删除已经发送的文字或已下载副本。同步内容快照不冻结 授权；发送后、执行前授权失效时，应阻止使用相应来源并说明原因，不能因为曾经发送就继续访问。

6. 更新策略优先级

紧急撤销
> 组织强制固定版本/禁止版本
> 设备组发布通道
> 用户允许的版本范围
> 当前已安装版本

任何权限扩大都从自动路径转为 require_approval。降级只有在目标版本仍被签名目录允许且 策略明确指定时才提供，不自动视为故障回滚。

6.1 网关配置演示

模型网关负责向其他服务转发，不托管模型。原型仅在上游与映射均启用、目标组被允许时判定 模型可用；模拟调用记录允许／拒绝及路由元数据，不发送请求或记录正文。

配置演示与上述签名能力包更新分开。草稿选择目标组可用模型，发布时重新检查策略；每组 独立记录发布历史。回退仅选择该组上一条记录，并重新检查其模型可用性，恢复版本及默认 模型后移除当前历史末项。发布和回退仅更新目标组在线示例设备；离线设备保留已应用版本， 目标版本随发布变化并显示待下发，未模拟重连交付。

这些状态仅保存在三页共享的会话内存中，刷新重置；角色开关不构成实际授权，发布状态不构成 设备确认。文档演示中仅本人可删除／转移个人文档，组织删除／恢复要求显式模拟组织文档管理员 角色，其他成员个人文档仅显示元数据，回收站不提供永久删除。

7. 联邦可见性

联邦目录只导出对方明确允许的能力投影：组织显示名、能力、版本范围、数据政策和可用性摘要。 不导出内部设备名、成员清单、组结构、节点地址、内部策略全文或审计记录。跨组织请求使用 双方关联 ID，双方各自解析本地主体。

8. 删除、撤销与保留

• 删除组织前必须停止新任务、撤销联邦和设备，并按保留策略归档审计；不提供无提示级联。
• 删除用户不删除其历史动作，审计显示不可变主体摘要。
• 撤销设备、Publication、Grant、Package 或联邦后立即阻止新令牌。
• 对象存储中的未完成任务正文按任务期限清理；审计元数据按组织保留策略清理。
• Office 会话关闭、撤销或到期后停止签发新启动、文件和 callback 令牌。工作副本与 checkpoint 按 Office 保留策略清理，不连带删除服务端主文档；法定保留只能保留匹配对象和审计，不能恢复会话权限。
• 法定保留只锁定匹配审计事件，不使被撤销身份重新可用。

8.1 Office 保存与回写结果

下表的源文件确认与冲突项仅适用于本地来源导入／回写模式。

条件	ShareServer 结果
callback 通过验证且对象完整	原子发布新 checkpoint，通知 Desktop
callback 重复且幂等键相同	返回已有 checkpoint，不创建新版本
callback 超时且对象结果未知	outcome_unknown，查询确认后再转终态
Desktop 确认源文件已写回	记录 source_commit_confirmed 元数据
Desktop 报告源文件冲突	保留 checkpoint 至到期，记录 source_conflict
设备或组织权限撤销	拒绝新操作并关闭会话，不删除 Desktop 源文件

8.2 Office 私有部署第一阶段（待实现）

服务端主文档有稳定 ID 和单调递增的持久化 revision；编辑会话关联文档 ID、基准 revision、 编辑轮次及 ONLYOFFICE document.key。同一文档同一轮共同编辑复用 key，不按浏览器或每次打开 生成不同 key。活动轮次不接受另一份上传覆盖主文档；另传文件创建新文档。

• status 6 表示编辑期间的 forcesave：持久化快照后更新已保存 revision，继续当前编辑轮次， 不更换 key，也不据此宣布后续人工修改已保存。
• status 2 表示本轮编辑结束后的保存：持久化最终内容后结束该轮；等待最终保存时，新打开请求 等待或返回可重试状态，不能先开启一个会被旧回调覆盖的新轮次。下轮从最新 revision 生成新 key。
• 关闭浏览器不等于服务端保存完成；无修改结束按 status 4 收束，status 3/7 保存错误保留 最近成功版本并报告失败。status 4 不增版，无内容变化时允许恢复原 key 的连接；需验证断网后 重连场景，不因一次断连即换 key。连接和其他通知不触发文件保存。
• 同文档保存串行处理，重复回调返回原结果；已结束轮次的迟到回调不得覆盖新轮次，迟到的 forcesave 不得覆盖最终保存。无法确定先后或版本冲突时保留原版本并报告待确认，不按到达时间盲目覆盖。
• 已持久化才显示“已保存到服务器”；写盘失败不确认成功，确认丢失后查询或重试同一次保存。 主文档不因会话结束而删除，首期不提供归属转移或组织权限承诺。

协议、幂等依据与文件提交方式由技术设计第 10.1 节 定义。首期保存结果不涉及 Desktop／SSH 源文件回写。

9. 需求追踪

需求	主要逻辑
FR-1	INV-1、INV-9 和系统管理员角色边界
FR-2	组织隔离不变量、成员状态和角色边界
FR-3	注册不等于发布、设备状态和短期权威恢复规则
FR-4	注册、Publication、目录与授权不变量
FR-5	拒绝优先不变量和授权计算顺序
FR-6	审批状态、内容绑定和授权重算
FR-7	provider 冻结不变量和任务路由决策
FR-8	Package Release 状态和更新策略优先级
FR-9	联邦双边交集、FederationTrust 状态和联邦可见性
FR-10	组织隔离、删除撤销与保留规则
FR-11	组织角色边界及各对象状态；展示行为由 UI 设计定义
FR-12	短期权威恢复规则和逻辑完整性；部署结构由技术设计定义
FR-13	注册、Publication、目录与授权不变量，provider 冻结及 INV-10
FR-14	INV-11、INV-12、DocumentEditSession、Office 保存与保留规则；私有部署第一阶段见 8.2
FR-15	2.8 工作空间共享状态、组织与空间成员边界
FR-16	2.8 资料同步与消息连接分离；2.9 交付确认、实时更新与补收
FR-17	2.9 普通消息与处理请求分离；5.1 处理优先级与接手竞争
FR-18	INV-10、5.2 来源、受众与动作交集

10. 逻辑完整性

本设计覆盖实例、组织、成员、设备、能力与数字人发布、授权、审批、任务、更新、联邦、Office 编辑、撤销和恢复。实现前仍需确定首个 OIDC 提供者矩阵、默认审计保留期、部署规模目标、中继 带宽上限、Office 文件上限和 checkpoint 保留期；这些部署参数应可配置，不改变拒绝优先、双边 联邦、provider 冻结、Office 凭据单用途和源文件权威规则。