# ShareServer 功能逻辑设计

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.3 |
| 日期 | 2026-09-09 |
| 关联 PRD | [ShareServer PRD](./prd.md) |
| 共享规则 | [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) |

## 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 成员

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

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

### 2.2 注册设备

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

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

### 2.3 Publication

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

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

### 2.4 审批

```text
pending -> approved | rejected | cancelled | expired
```

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

### 2.5 Package Release

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

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

### 2.6 FederationTrust

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

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

### 2.7 DocumentEditSession

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

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

```text
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. 更新策略优先级

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

任何权限扩大都从自动路径转为 `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 凭据单用途和源文件权威规则。