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

ShareServer 功能逻辑设计

文档信息

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

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 和调用者只能看到允许分区种类与“本次调用会使用本地记忆”的政策 事实，不能读取原始条目、分区内容、来源正文或检索结果。新增可读分区按权限扩大重新审批， 移除分区可以立即收紧。

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

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

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。

3. 授权计算顺序

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

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

4. 组织角色边界

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

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

5. 任务路由决策

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

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

6. 更新策略优先级

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

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

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 源文件

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 保存与保留规则

10. 逻辑完整性

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