# ShareServer Web 管理界面设计

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.6 |
| 日期 | 2026-10-01 |
| 关联 PRD | [ShareServer PRD](./prd.md) |
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |

ShareServer 是独立 Web 产品，不直接复用 Electron 页面壳层实现，但沿用 GoodBuddy 的语义
词汇、状态含义和克制的运营工具风格。界面以列表、表格和主从详情为主，不使用营销首页或
装饰性卡片墙。

## 1. 使用对象

当前控制台移除模拟数据与操作。`/capabilities` 直接读取本地服务的设备和发布数据，原
`/capabilities?view=local` 地址仍可访问。共享中心不再提供组织示例页签，不使用示例组织、
用户归属或在线状态解释本地记录。

概览只提供已接入服务的入口，不显示预设指标和活动。导航保留规划模块；未接入的页面显示
待实现说明，不提供虚假的保存、审批或健康检查。模型网关、共享目录分别加载自己的 API，
控制台不再依赖原型快照。移除预设身份、组织切换、角色切换、通知数量和未实现的全局搜索。
下文中的组织身份、文档协作及其他管理流程属于目标设计，尚未实现的部分不作为当前可用功能展示。

GoodBuddy 从应用菜单或应用中心进入“设备共享”，完成地址与名称保存、注册、发布、撤销和刷新。
Web 提供设备、类型、状态、关键词筛选，显示注册时间、来源声明及独立知识权限；提供加载、空目录、
无匹配结果、失败重试和刷新状态。Web 不重复提供本机发布表单。权限与来源提示跟随真实目录展示，
不把元数据发布成功写成能力可执行或知识可读取。桌面交互详见
[设备共享 UI 设计](../../../../goodbuddy/docs/features/device-sharing/ui-design.md)。

- 普通成员主要在 GoodBuddy Desktop 协作和使用能力；Web 端管理自己的设备、申请、授权和已发布数字人。
- 组织管理员使用完整组织控制台。
- 系统管理员使用与组织控制台分开的实例管理范围。
- 审计员进入只读视图，不显示可变更控件。

登录后直接进入当前身份可用的实际控制台，不显示产品宣传页。

## 2. 全局框架

```text
顶部栏：ShareServer 实例名 | 当前组织 | 全局搜索 | 审批 | 账号

侧栏：
概览
GoodBuddy 服务：模型网关 | 文档与协作 | 配置下发
组织与成员
GoodBuddy 接入
共享中心
数字人
权限策略
审批
发布与更新
网关联邦
任务与中继
审计
系统设置（仅系统管理员）
```

当前组织始终显示。切换组织会重新加载整个数据范围，不保留上一组织的选择、筛选或详情。
系统管理使用“实例范围”标识，不能伪装成某个组织。

### 2.1 页面 Tab 结构

每个管理页面围绕一个业务对象组织，页面内通过 Tab 切换查看范围或操作阶段。列表、详情和
编辑表单属于当前 Tab 的交互，不单独增加一级导航。未接入的页面保留 Tab 结构，但每个 Tab
只显示对应的待接入说明，不生成示例数据。

| 页面 | Tab |
| --- | --- |
| 运行概览 | 服务状态、待处理事项、最近活动 |
| 模型网关 | 概览、上游服务、模型目录、访问密钥、请求测试、调用审计、客户端接入 |
| 文档与协作 | 文档库、编辑会话、Office 服务、保存记录 |
| 配置下发 | 配置草稿、设备生效、发布记录、回滚记录 |
| GoodBuddy 接入 | 设备列表、设备详情、连接记录、撤销记录 |
| 共享中心 | 能力目录、共享知识库、按成员查看、按设备查看 |
| 数字人 | 数字人目录、我的数字人、调用权限、发布记录 |
| 组织与成员 | 成员、用户组、角色、服务账号 |
| 权限策略 | 强制策略、Grant、策略模拟、变更记录 |
| 审批 | 待处理、已处理、我的申请、审批规则 |
| 发布与更新 | 能力包、发布通道、更新策略、撤销记录 |
| 网关联邦 | 合作组织、待确认、开放范围、事件记录 |
| 任务与中继 | 任务列表、活动任务、中继连接、运行统计 |
| 审计 | 事件查询、调用链、导出任务、保留策略 |
| 系统设置 | 实例信息、身份与登录、基础设施、中继与联邦、通知、保留与审计 |
| 我的设备与授权 | 我的设备、我的授权、我的申请、我的数字人 |

Tab 的状态和功能范围以[产品功能列表](./feature-list.md)为准。当前原型已经为组织与成员
提供通用 Tab 组件；模型网关使用独立的真实 API 页面，其余尚未接入服务的页面显示占位说明。

## 3. 概览

概览只显示需要行动和运行事实：

- 待审批数量及最旧等待时间。
- 在线/离线/已撤销设备。
- 可用/离线/暂停能力。
- 当前任务、失败和结果未知。
- 包更新异常和紧急撤销。
- 联邦连接异常。
- 中继流量和容量，仅在中继启用时显示。
- Office 编辑健康、活动会话、保存失败和待清理对象，仅在 Office 服务启用时显示。

指标可点击进入已带筛选的对应页面。没有事件时不显示虚构趋势。

## 4. 组织与成员

使用“成员”“用户组”“角色”三个同级页签。成员表包含姓名、身份源、组、状态、设备数和
最近活动。邀请是唯一主操作；暂停和移除进入行末菜单。

成员详情采用抽屉，显示身份、组、角色、设备、有效 Grant、申请和审计。管理员不能查看成员
任务正文或桌面文件。

## 5. 设备

```text
设备             所有者      平台        状态      能力      最近在线
Jiang-PC         Jiang       Windows     在线      2        刚刚
GPU-Worker-02    AI Team     Linux       离线      8        2 小时前
```

设备详情包含概览、连接、已发布能力、Grant 和活动。设备状态与 Publication 状态分别显示。
撤销设备使用危险确认，说明新任务、活动任务和重新注册影响。

## 6. 共享中心

沿用 `/capabilities`，页签依次为“能力目录”“共享知识库”“按用户查看”“按设备查看”。
各内容展示发布者、提供设备、版本、设备在线状态、发布状态及共享对象，名称进入元数据详情。
发布者和设备链接切换到对应分组并清除旧筛选；既有 `/devices` 详情链接定位同一设备的共享视图。

四个页签支持元数据搜索、可用状态、来源和共享对象筛选，用户／设备视图增加主体选择。
显示当前结果数量、无结果说明及“清除筛选”，重置保留当前页签。页签支持方向键、Home、End，
窄屏横向滚动；筛选和列表随宽度换行，复用本地主题、按钮、状态徽标和详情对话框。

知识库同时显示来源模式与搜索、读取原文、下载三项显式权限。详情解释服务器副本和远程取用
的离线差异，管理员查看元数据不会获得正文权限。当前仅搜索示例元数据；内容按钮禁用并标注
“未接入”，不返回虚构正文或下载成功。能力就绪也不代表获得调用权限。

### 6.1 数字人

数字人使用独立栏目呈现，不混入普通工具能力表。目录按 `@handle`、显示名、所有者、专业
说明、提供者、Runtime、版本、在线状态和可用范围筛选；只有当前成员可发现的数字人进入
搜索和提及补全。

数字人详情显示：

- 所有者、来源组织、执行设备或服务节点。
- Publication 版本、支持的输入/输出、可用时间、并发和有效期。
- 数据去向、路由、中继可读性、是否允许委托。
- 是否使用本地记忆、允许的分区种类，以及允许处理的数据敏感度；不显示记忆条目、具体分区
  名称、来源正文和检索结果。
- 当前成员的 `discover/inspect/invoke` 权限、命中策略和审批要求。

成员可以在“我的数字人”中创建多个用途不同的发布草稿，选择一个本地 Agent、设置唯一
`@handle` 和开放范围、提交审批、暂停、恢复、更新或撤销。加入组织不会生成默认数字人，
创建本地 Agent 也不会自动发布。

发布表单的“可用记忆”默认全部关闭，并允许勾选数字人的 Agent、Global、指定 Project 和
指定 Automation 分区。Conversation 和 Run 不作为可选项。表单持续说明记忆只在提供者本地
检索，调用者和 ShareServer 看不到内容；新增分区在保存前明确标为权限扩大，移除分区明确
标为立即收紧。

直接能力调用输入区使用带搜索的显式选择器插入 `@数字人`，不能只靠自由文本猜测 handle。
选择后持续显示目标数字人；发送前确认实际接收者、执行位置、发送数据和授权。离线、无权或
需要审批的项保持可读并说明原因，但不能形成已发送调用。

工作空间的 `@成员` 是提及选择器，按第 17 节展示；“请求处理”单独选择处理人，不以分身在线状态限制本人收件。
上述本地记忆限制不阻止用户另行发布选定知识或回顾；内容入口按 FR-18 展示原文读取权限，
数字人目录仍不提供底层记忆浏览器。

## 7. 权限策略

策略页分“强制策略”和“Grant”。创建和编辑使用结构化表单：主体、能力、动作、输入、提供者、
时间、预算、批准和委托。保存前提供自然语言摘要：

> 允许“设计组”从合规设备调用组织内“图像生成”2.x；只发送文本和图片；每人每日 20 次；
> 不允许下游委托。

策略冲突预览显示最终结果和命中规则，但不提供允许规则覆盖拒绝规则的顺序拖拽。

## 8. 审批

审批收件箱按调用、发布、更新和联邦分类。详情必须显示申请人、能力或对象、目标范围、数据
类别、权限变化、期限和策略依据。批准按钮使用具体文案，例如“允许本次调用”“批准此版本
发布”，不能只有“同意”。

批量批准仅用于同类型、同策略且不包含权限扩大的低影响申请；联邦和权限扩大更新不支持
批量批准。

## 9. 发布与更新

页面分“能力包”“发布通道”“更新策略”“撤销记录”。Package 表显示版本、发布者、签名、
大小、目标平台、权限变化和状态。上传后先进入验证，不直接发布。

版本详情提供 manifest、摘要、签名、兼容范围、权限 diff、依赖和下载事实。紧急撤销位于
独立 danger zone，需要输入版本标识确认，并说明受影响设备和新任务。

## 10. 网关联邦

```text
合作组织          对端地址                 状态       开放能力     有效期
法务服务商        share.legal.example      已连接     2 项         12-31
```

建立关系采用向导：填写端点、核对组织和指纹、选择公开范围、设置调用与数据限制、生成 offer、
等待对方确认、复核双方交集。只有双方完成后显示“已连接”。

详情明确展示“我方开放”“对方开放”“最终可用”三个集合。暂停和撤销说明对活动任务的处理。

## 11. 任务与中继

任务表显示调用方、能力、provider、路由、数据类别、状态、耗时和时间。默认不显示正文。
活动任务提供取消；结果未知使用独立状态并显示 provider 最后确认点。

中继未启用时页面显示控制面正常和启用位置，不展示零值图表。启用后显示活动连接、吞吐、
排队、容量和拒绝原因，不提供查看正文的调试入口。

## 12. 审计

提供操作者、动作、对象、组织、结果、时间和关联 ID 的可筛选表格。导出前显示条件、估算行数、
时区和字段范围；大导出作为后台任务生成有时效下载。审计详情保持只读，不把原始内部错误、
认证信息或任务正文显示给管理员。

## 13. Office 编辑目标设计

Office 编辑管理归入“文档与协作”，属于系统管理员的服务配置和组织管理员的策略管理，不提供
文档正文浏览器。以下是生产目标，当前待接入页面见第 16.1 节。

日常文档操作在 GoodBuddy 中完成。文档以 ShareServer 为主存储；显式选择本地来源导入／回写
时，另行显示检查点与源文件回写状态。关闭会话不表示删除主文档，检查点可用不表示本地源文件已保存。

系统管理员视图显示：

- 服务状态、ONLYOFFICE 版本、许可证状态和最近一次完整健康检查。
- Document Server、回调处理和所选存储的独立状态和稳定错误阶段。
- 活动/断线/过期会话数、保存成功/失败/结果未知、存储用量和待清理对象。
- 全局允许格式、最大文件、并发、会话期限、checkpoint 保留和紧急停用。

组织管理员视图只显示本组织策略、用量和会话元数据，可以收紧允许格式、文件大小、并发、
只读和 AI 编辑策略，不能修改基础设施地址或密钥。会话表显示用户、设备、文档显示名、类型、
访问模式、状态、大小、创建时间、最后 checkpoint 和到期时间，不显示源文件路径或正文。

“测试 Office 服务”必须执行最小文档创建、编辑器加载、保存 callback 和输出校验。结果按阶段
显示，并说明测试会创建和自动清理临时文档。只检查端口不能显示为完整健康。

紧急停用需要说明：停止创建新会话和新保存，现有 Desktop 源文件不会删除，服务端工作副本按
保留策略处理。删除会话是危险操作，显示用户、设备、文件显示名、稳定 checkpoint 和未确认
回写状态；不能提供管理员直接下载任意成员文档的默认入口。

### 13.1 私有部署第一阶段入口（待实现）

后续在 `/documents` 提供“私有文档试验”入口，展示无用户授权的使用范围。
提供 DOCX 上传、真实文档列表、打开编辑器、保存状态与关闭后重新打开；不使用模拟个人／组织
归属或角色开关解释真实文件。列表显示名称、大小、最近持久化版本与保存时间，不显示服务器路径。

编辑器加载失败、上传格式或大小超限、等待最终保存、保存失败和结果待确认各自显示原因及可用的
重试操作。编辑器本地保存提示不直接变成“已保存到服务器”，以服务端持久化结果为准；关闭后若
最终保存未完成，重新打开需提示等待。forcesave 后继续编辑时，已保存版本不代表当前全部修改。

服务信息区分“进程可访问”与“编辑往返已验证”，后者显示最近真实验证时间和结果；不使用预设
检查冒充实测。部署地址和 JWT 秘密由部署配置提供，首期不增加密钥表单。配置与验证契约见
[技术设计第 10.1 节](./technical-design.md#101-私有部署第一阶段待实现)。

## 14. 系统设置

只包含实例名称、公开地址、身份源、邮件、数据库/对象存储状态、中继开关与上限、Office 服务
基础设施状态、保留策略、联邦总开关、证书和版本。秘密字段只支持替换或测试，不回显原值。

运行时基础设施配置优先来自部署环境；Web 界面不能修改数据库连接串、主密钥或容器挂载路径。

## 15. 状态、响应式与无障碍

- 加载、无数据、无匹配、无权限、服务错误和部分不可用分别展示。
- 管理表格支持键盘访问、可见焦点、表头关联和分页；行菜单有可访问名称。
- 窄屏将表格转为字段列表，保持组织、来源、状态和风险信息，不把管理动作挤成不可辨图标。
- 所有时间显示实例时区并可查看 ISO 时间；联邦事件同时显示对端时间时标明时区。
- 状态不只依赖颜色。危险操作在确认后保持原页面上下文和可恢复错误。

## 16. 交互原型视觉基线

2026-09-05 的首个可运行原型采用深海科技控制台方向，并同时提供浅色主题。视觉实现遵循
shadcn/ui 的本地组件模式和 Radix 可访问 primitives，布局参考成熟后台的侧栏、顶栏、数据
表格和详情对话框，但不复制第三方示例业务页面。

早期原型覆盖一级栏目、角色切换、搜索筛选、详情、创建表单与窄屏导航。
2026-10-02 起，控制台移除示例业务页面及其操作入口，保留侧栏、主题和窄屏导航。
`FR-13` 新增的数字人目录、“我的数字人”和 `@` 选择器尚未进入当前原型。
“文档与协作”显示待接入状态；Office 编辑与会话管理尚未实现。

### 16.1 GoodBuddy 服务入口

本节记录已实现的 [B1 网关界面](./backend-foundation-design.md#4-b1正常模型网关接入)，本轮未完成浏览器验收。

工作台顶部显示服务拓扑，按真实 API 汇总已登记 GoodBuddy 设备、ShareServer 发布目录和模型网关上游。拓扑表达服务职责和配置关系，登记设备不显示为在线，发布目录不显示为可执行内容；没有数据时显示零接入状态。
页面按 Tab 组织为“概览”“上游服务”“模型目录”“访问密钥”“请求测试”“调用审计”“客户端接入”。概览只展示网关地址、资源数量和最近状态；
上游服务管理外部连接，模型目录管理客户端可见的映射，访问密钥管理客户端授权，请求测试验证真实转发，调用审计查看有界元数据，客户端接入展示
GoodBuddy 所需的地址和模型配置。不同 Tab 不混合配置表单、运行结果和审计记录。上游表单输入 API 地址和密钥，移除前缀与变量名；
接入区展示完整 Base URL、协议、模型 ID，并支持创建与撤销访问 Key。凭据只显示配置状态，
编辑上游时，凭据输入框留空表示保留当前值，填写新值表示覆盖；页面不要求用户选择额外的凭据操作。新建访问 Key 仅当次显示完整值，离开后只保留名称及状态。
获取模型失败仍可手动添加，空状态引导接入，不填示例。访问 Key 的授权绑定模型记录 ID，修改别名不改变授权。

侧栏按业务流程分为“工作台”“GoodBuddy 服务”“共享资源”“组织管理”“运营与审计”“系统”和“成员自助”。
其中“GoodBuddy 服务”分组保留模型网关、文档与协作、配置下发三个管理路由；“共享资源”集中设备接入和共享中心。
各页分别说明实现范围。网关是无组织认证、
组织隔离和配额的本地技术预览，已实现客户端 Key 认证及模型授权；文档与配置下发显示待接入说明。

| 路由 | 交互与结果 |
| --- | --- |
| `/model-gateway` 模型网关 | 按“概览／上游服务／模型目录／访问密钥／请求测试／调用审计／客户端接入”组织；配置保存到服务器，可添加、编辑、启停上游与映射，发现模型、创建和撤销访问 Key、测试及刷新审计，无用户组策略控件 |
| `/documents` 文档与协作 | 显示尚未接入服务，无示例文档、实例或操作按钮 |
| `/distribution` 配置下发 | 显示“尚无配置下发服务”及模型网关链接；无草稿、设备生效回执或发布回滚记录，保存网关模型不会自动下发到 GoodBuddy |

网关初始展示空上游、空映射、空访问 Key 与空审计。上游表单填写名称、Base URL、协议、认证
方式和启用状态；API Key 留空时保留已有凭据，填写真实 API Key 时覆盖旧值，提交后清空密钥输入。保存失败保留
普通字段，密钥重试需重新输入。编辑默认保留；无需认证不会自动清除已有凭据。界面仅显示
凭据配置状态，不返回旧值或密文。旧环境引用保留存储兼容，当前界面没有导入入口。

“发现模型”访问真实上游并列出结果，选择结果打开映射表单，也可手动填写。测试只列出上游、
映射均启用且无需认证或已配置凭据的别名，用户填写提示词后通过本机管理 `/test` 发送非流式请求；发送前提示数据去向及
可能费用。测试支持取消、清除结果，提示词与结果仅在组件内存中，离开页面清除。页面显示客户端
Base URL 来自 `SHARESERVER_GATEWAY_BASE_URL`，本机示例为 `http://127.0.0.1:8787/api/v1/gateway/v1`；
未配置时提示管理员设置，不从 Vite 端口或浏览器 Host 推断。客户端使用访问 Key，不使用上游 API Key。

配置加载失败可重试；已有快照时保留并标注上次数据。保存失败保留普通字段，错误显示 HTTP
状态、错误码及请求 ID。取消测试后提示审计可能稍后更新。审计显示服务器保留的最新 200 条
调用元数据：时间、编号、模型、上游、访问 Key ID、流式方式、结果、HTTP 状态、耗时、Token 用量与错误码；
不展示正文，缺失用量显示“未知”。窄屏审计表可横向滚动。

文档页已移除“打开模拟 GoodBuddy 客户端”、示例文档、模拟角色和回收操作；归属操作待后端实现。

网关上游接受 HTTP/HTTPS，包括可信内网 HTTP，不允许账号、密码、查询参数或片段；保存不验证连接，
发现与测试才发真实请求。OnlyOffice 实例表单与预设检查已退出当前界面。
管理 API 与 Vite `/api` 均限制实际 socket 来源为回环；容器／反向代理管理待 B2 登录后支持。
既有网关策略与配置发布演示记录属于历史交互证据，不作为当前真实网关或设备交付的测试结论。

## 17. Desktop 工作空间协作目标交互

本节补充 Desktop 与 ShareServer 交界处的用户交互，不改变独立 Web 控制台的页面壳层。

- 新建入口统一为“新建工作空间”，默认“仅本地”。开启“共享”后选择所属组织、空间成员和
  内容范围；未加入组织时可引导加入，不阻塞本地创建。开启前提供历史内容预览。
- 空间列表允许多个本地及共享空间并存。标题附近展示共享状态、目标组织和消息连接状态；
  资料面板展示最近成功同步时间、待同步数量和立即同步资料入口，失败可定位到条目。
- 资料定期／按需同步与“暂停资料自动同步”分别设置，不控制消息通道。“关闭共享”说明撤销访问的影响，离线操作保持
  “待关闭共享”，不能以本地开关的外观冒充服务端确认。
- 默认输入框用于普通空间消息，支持回复线程和 `@成员` 提及，不要求处理人。提及仅通知，
  单独开启“请求处理”后选择一个处理人，再显示“需要本人确认”。
- 选择器按当前空间过滤，姓名标记绑定稳定身份。发送区展示可见受众、上下文清单及内容预览；
  无附带上下文也可提问。附件未就绪显示准备进度或失败，不能显示“已发送”。
- 消息即时出现，历史支持分页和断线补收。普通消息仅展示交付信息；处理请求同时展示交付和
  处理信息，例如“待发送”或“已发送 · 待本人处理”。分身失败、处理人离线
  和权限撤销分别说明，不能统一显示发送失败。
- 设置页按成员本人、空间保存“处理请求偏好”，不使用“收到 @ 时自动执行”的文案；分身模式选择明确的分身及来源授权。仅本人可以看到
  自己的待确认草稿、编辑、确认和接手操作。实际产品禁止用 demo 的角色下拉框代替登录授权。
- 共享知识配置复用已有来源列表，授权预览说明目标受众。监督回顾的回答使用与原文阅读分别
  设置；仅阅读场景不能被第二个开关或默认联动隐式改为允许回答。

`docs/demo/client` 是独立静态交互演示，已有成员消息与处理偏好；本地／共享统一创建、实时
消息、资料周期同步及撤销流程尚未实现。demo 仍把提及直接当作处理请求，需按本节调整；
其即时本地回复不是服务端送达或实时通信的验收证据。