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

ShareServer 功能逻辑设计

文档信息

项目	内容
状态	设计中
版本	0.1
日期	2026-09-03
关联 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 初始化入口一次性关闭

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

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。

3. 授权计算顺序

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

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

4. 组织角色边界

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

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

5. 任务路由决策

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

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

6. 更新策略优先级

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

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

7. 联邦可见性

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

8. 删除、撤销与保留

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

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	短期权威恢复规则和逻辑完整性；部署结构由技术设计定义

10. 逻辑完整性

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