205 lines
16 KiB
Markdown
205 lines
16 KiB
Markdown
# ShareServer 实施进度
|
||
|
||
## 当前状态
|
||
|
||
ShareServer 包含控制台交互原型和可持久化的本地共享目录服务。GoodBuddy 已能注册设备、发布与
|
||
撤销元数据，Web 能查看真实目录；生产身份、组织隔离、设备控制连接、授权及任务路由仍未实现。
|
||
|
||
### 2026-10-01：Web 与服务端目录整理
|
||
|
||
- Web 源码与测试迁至 `web/src/`，HTML、Vite 和 Web TypeScript 配置置于 `web/`；
|
||
Hono 源码与测试迁至 `server/src/`，服务端配置置于 `server/tsconfig.json`。根 `shared/` 保留。
|
||
- 根目录统一管理依赖、脚本、Vitest、ESLint 与 TypeScript 项目引用，未新增依赖或 workspace。
|
||
构建产物为 `dist/web/` 和 `dist/server/`，启动入口为 `dist/server/server/src/index.js`。
|
||
- 根 Node v24.16.0 环境下，`npm test` 的 5 个文件、51 个测试通过；`npm run typecheck`、
|
||
`npm run lint`、`npm run build` 和 `git diff --check` 通过。
|
||
- `docker compose -f docker/compose.yaml build` 与
|
||
`docker compose -f docker/compose.yaml up -d --wait --wait-timeout 60` 通过，现有服务重建后健康。
|
||
HTTP 验证覆盖首页、JS/CSS 资源、共享中心路由回退、health、ready 和本地元数据读取。
|
||
- Compose 的 `../data` 保持不变，实际挂载为仓库根 `data/` 到 `/app/data`；重启前后
|
||
`sharing.json` 的 SHA-256 一致。Vite 开发服务验证前端模块、根共享模块及 API 代理可访问。
|
||
- 本轮未做浏览器视觉验收。Docker 安装时完整依赖集报告 4 项 audit 问题，运行时依赖报告 0 项；
|
||
本轮未调整依赖版本。原型与本地元数据服务边界不变，readiness 仍报告 `productionReady: false`。
|
||
|
||
### 2026-10-01：本地目录与 GoodBuddy 联调
|
||
|
||
- 新增五个本地共享 HTTP 接口，覆盖设备注册和查询、发布查询和创建、撤销。JSON 文件保存真实
|
||
记录，重启后仍可查询；API 的输入限制、错误与部署范围见技术设计第 4.1 节。
|
||
- GoodBuddy 应用中心新增设备共享入口，通过生产页面、preload、可信 IPC 与 Main HTTP 服务
|
||
操作本地目录，持久化服务配置和本机 ID。两仓分别构建，没有源码跨仓依赖。
|
||
- Web 共享中心新增“本地服务目录”，提供真实设备与发布记录、组合筛选、错误重试和刷新；
|
||
既有组织示例保留。注册时间不解释为在线状态，来源及知识权限按声明显示。
|
||
- ShareServer `npm test`：5 个文件、51 个测试通过；`npm run typecheck`、`npm run lint`、
|
||
`npm run build` 和 `git diff --check` 通过。服务测试包含真实 HTTP 和独立进程重启持久化。
|
||
- Web 使用隔离临时数据及真实 API 完成发布、撤销、筛选、重载、刷新和空目录验证；注入 503 后
|
||
重试通过。Edge/Playwright 检查 1440px 桌面和 390px 手机深浅主题，无横向溢出或脚本错误。
|
||
- GoodBuddy 真实 Electron 组件组合联调通过，覆盖应用中心入口、注册、知识独立权限、发布、
|
||
撤销、刷新、设备 ID 重读及 480px 深浅主题。未验收完整生产 App、安装包或跨平台原生窗口。
|
||
定向检查与全仓测试差异见[桌面验证记录](../../../../goodbuddy/docs/features/device-sharing/progress.md#2026-10-01桌面实现轮次的独立验证)：
|
||
全仓测试曾有两项失败，修正配置样例及单独复跑后通过，未将全仓结果记为一次全绿。
|
||
|
||
本轮完成本地元数据流程；设备认证、组织归属、能力执行、知识正文检索和同步、模型转发、
|
||
OnlyOffice 编辑与真实配置下发仍待实现。测试使用独立端口和临时目录，不修改既有服务数据。
|
||
本次中文文档经过 deai-writing 扫描，无阻断项；枚举、权限边界和历史验证限制按原义保留。
|
||
最终本地预览在 `http://127.0.0.1:8787` 启动，readiness 返回本地 JSON 元数据模式。
|
||
浏览器打开 `/capabilities?view=local` 正常读取空目录，显示 0 台设备和 0 项发布，未填入测试样例。
|
||
|
||
### 2026-09-30：共享中心交互原型
|
||
|
||
- 既有 `/capabilities` 扩展为共享中心，提供能力目录、共享知识库、按用户查看、按设备查看。
|
||
本地示例包含 3 项能力和 4 项知识，关联现有成员与设备；搜索、筛选、详情及主体定位由 URL 保存。
|
||
- 知识详情分别展示来源模式、可用性及搜索／读取原文／下载权限，覆盖离线服务器副本、离线
|
||
远程取用和仅元数据可见场景。内容操作均未接入，管理员身份不增加内容权限。
|
||
- `/devices` 详情可跳转对应设备共享视图，内容详情可跳转发布用户与提供设备。修复顶栏搜索
|
||
按钮在手机宽度下无法收缩造成的横向溢出，保留本轮之前的服务演示改动。
|
||
- `npm test` 通过 3 个文件、16 个用例，其中新增 7 个共享中心用例；`npm run lint`、
|
||
`npm run build` 通过，构建包含前后端类型检查。测试覆盖离线语义、独立权限、组合筛选与重置、
|
||
URL 恢复、用户／设备跳转、既有设备入口、键盘页签及无效详情链接。
|
||
- 构建后使用现有 8791 服务完成 HTTP 冒烟和 Edge 浏览器检查。1440×1000、390×844 的深浅
|
||
主题均无页面横向溢出，详情在视口内；设备详情到共享设备、知识详情及发布用户的跳转通过，
|
||
无页面脚本错误。截图复核了桌面深色列表、手机浅色列表和手机深色详情；现有服务保持运行。
|
||
- 中文文档经 deai-writing 扫描与本次修改范围复核；无阻断项，字段枚举和权限限制按原义保留。
|
||
当前没有新增内容 API、真实同步、内容检索、读取、下载或生产授权，也未进行真实设备集成验证。
|
||
|
||
### 2026-09-30：GoodBuddy 服务联动演示
|
||
|
||
- 新增模型网关、文档与协作、配置下发三个管理员页面，并在导航和概览中集中展示入口。
|
||
模型网关只转发其他模型服务，不提供模型托管或推理。
|
||
- 网关演示支持添加上游、启停、模型映射、用户组策略和模拟调用审计。停用上游或限制用户组
|
||
后，相应模型无法用于配置发布。
|
||
- 文档演示支持本人将个人文档转交组织、删除至回收站、恢复，以及 OnlyOffice 实例配置与
|
||
预设健康检查。转交后个人删除权失效，组织文档删除与恢复依赖显式模拟角色；不展示个人正文。
|
||
- 配置演示支持草稿、按组发布、在线设备模拟生效、离线待下发和回退版本及默认模型。
|
||
三页共享内存状态，跨页导航保留，刷新重置；没有真实转发、文件存储、Office 编辑或客户端下发。
|
||
- 修复既有列表页切换路由时沿用上一页数据分类的问题。前端测试显式清理组件，避免测试间
|
||
留存的对话框和路由影响后续用例。
|
||
- `npm test` 通过 2 个文件、9 个用例；类型检查、lint 和前后端生产构建通过。
|
||
新增用例覆盖跨页数据、网关停用阻止发布、离线等待、版本与模型回退、归属与删除权限、
|
||
回收恢复、拒绝审计和成员菜单范围。
|
||
- 构建服务在回环地址通过浏览器加载验证；实际操作验证了文档转交和 OnlyOffice 模拟检查，
|
||
截图复核了折叠导航布局及深浅主题。尚未完成指定桌面／手机尺寸的完整视觉回归，
|
||
也未进行真实 GoodBuddy、上游模型或 OnlyOffice 集成测试。
|
||
|
||
### 2026-09-09：Office 编辑目标设计
|
||
|
||
- PRD 新增 `FR-14`，将 ONLYOFFICE Docs、编辑会话、工作副本、保存检查点和 callback 定义为
|
||
ShareServer 可选托管能力。
|
||
- 功能逻辑明确服务端 checkpoint 不等于 Desktop 源文件已保存，并定义单用途凭据、会话状态、
|
||
callback 幂等、冲突结果和保留规则。
|
||
- 技术设计增加 Office 模块、API audience、数据模型、对象存储、部署依赖、编辑器插件、安全
|
||
边界和三平台集成测试要求；管理界面设计增加 Office 健康、策略和会话管理。
|
||
- 这些变更只有设计文档，没有修改当前 Hono/React 原型。仓库仍未集成 ONLYOFFICE、对象存储、
|
||
callback、Office API 或 GoodBuddy Desktop 文档 Tab，不能视为功能实现。
|
||
|
||
### 2026-09-06：独立仓库迁移
|
||
|
||
- 源码、测试、锁文件、构建及容器配置从 GoodBuddy 的 `shareserver/` 移至
|
||
`goodbuddy-shareserver` 仓库根目录，六份功能文档随迁，保留原型行为不变。
|
||
- 跨端共享网络总体设计保留在 GoodBuddy 仓库。双向文档链接采用同级克隆布局，
|
||
服务安装、测试、构建和运行不依赖桌面端仓库。
|
||
- 原桌面工作区的依赖和构建产物未搬动或删除；其测试/lint 排除项保留以避开这些本地产物。
|
||
- 新仓库执行 `npm ci`、`npm test`（2 个文件、5 个测试）、`npm run typecheck`、
|
||
`npm run lint` 和 `npm run build` 全部通过。安装报告 1 个 low 级依赖漏洞，
|
||
未在本次迁移中升级依赖。
|
||
- 构建后的独立服务在回环地址通过健康、就绪、快照、无持久化操作确认、SPA 回退和
|
||
JS/CSS 静态资源 HTTP 冒烟验证，随后停止测试进程；未重跑浏览器交互或容器运行测试。
|
||
- 31 个非 README 源码/配置文件与来源提交逐字节一致，35 个相对 Markdown 链接均可解析。
|
||
- GoodBuddy 桌面仓库 `npm test`、`npm run typecheck`、`npm run lint` 全部通过；
|
||
首次全量验证达到 200 秒超时后，延长时限重跑通过。
|
||
- 历史来源记录于根 README。此次迁移不代表生产功能、Desktop 集成或容器运行已验收。
|
||
|
||
### 2026-09-06：桌面发布与测试边界
|
||
|
||
ShareServer 功能尚未完成，不属于本次 Desktop `0.12.5` / Agent `0.11.19`
|
||
的产品交付或发布验收范围。用户确认本次发布不需要单独测试 ShareServer，
|
||
其原型测试通过也不代表生产功能已完成。以下记录对应拆仓前的发布操作。
|
||
|
||
桌面端根测试和 lint 配置排除 `shareserver/**`，桌面发布 CI 不为其单独安装测试依赖。
|
||
ShareServer 独立项目自身的测试配置保留，供后续功能开发使用；本次不运行其独立测试。
|
||
此前候选 `89a81dd` 临时加入的 `npm ci --prefix shareserver` 步骤已撤除。
|
||
|
||
ShareServer 的实现与验证在后续功能开发中单独推进；真实 Desktop 集成验收仍属于
|
||
下文的剩余生产工作。
|
||
|
||
## 已验证实现
|
||
|
||
### 2026-09-05：全控制台交互原型
|
||
|
||
- `shareserver/` 是独立 Node.js/TypeScript 项目，不依赖 Electron Main 或
|
||
`src/shared`。
|
||
- Hono 同源提供健康、就绪、原型快照和无持久化操作确认 API。
|
||
- 管理控制台覆盖概览、组织与成员、设备、能力目录、权限策略、审批、发布与更新、网关联邦、
|
||
任务与中继、审计和系统设置。
|
||
- 成员自助覆盖自己的设备、授权和申请；角色切换后导航和 URL 范围同步变化。
|
||
- 控制台支持深浅主题、组织范围、全局搜索、列表搜索、状态筛选、详情、表单、确认、成功/
|
||
失败反馈、响应式侧栏和键盘对话框。
|
||
- 构建后的 Web 由 Hono 同源托管；`docker/Dockerfile` 使用多阶段构建和非 root 运行用户。
|
||
- readiness 明确返回 `interactive-prototype` 与 `productionReady=false`，避免把 fixture
|
||
误认为生产服务。
|
||
|
||
验证证据：
|
||
|
||
```text
|
||
cd shareserver
|
||
npm test # 2 files, 5 tests passed
|
||
npm run lint # passed
|
||
npm run build # typecheck + Vite Web + server TypeScript passed
|
||
```
|
||
|
||
浏览器实际验收：
|
||
|
||
- 生产构建在 `http://127.0.0.1:8787` 启动并成功加载 API 快照。
|
||
- 宽屏管理员概览、审批详情、批准确认和原型 API 提交流程通过。
|
||
- `390 × 844` 成员自助页面、筛选区和列表布局通过。
|
||
- 深色与浅色审批页的 WCAG 2 A/AA 自动检查均为 0 个确定违规；半透明侧栏被检查器列为
|
||
需人工判断项，已通过实际截图复核文字可读性。
|
||
- 仓库级 `npm test` 通过 325 个测试文件、3501 个测试，另有 8 个文件和 55 个测试按既有
|
||
条件跳过；仓库级 `npm run typecheck` 与 `npm run lint` 通过。
|
||
|
||
## 剩余生产工作
|
||
|
||
按技术设计从以下纵向切片开始，不能把原型 fixture 逐步演变为权威状态：
|
||
|
||
1. FR-1 一次性初始化、本地管理员身份、Web session 和 CSRF。
|
||
2. PostgreSQL migration、实例/组织/成员表、强制 organization repository 作用域和事务审计。
|
||
3. 真实组织与成员管理 API，再将对应原型页面切换到权威数据。
|
||
4. 设备挑战注册、凭据和出站 WebSocket 连接。
|
||
5. Publication、目录、拒绝优先策略、审批和任务路由。
|
||
6. Package、可选中继、联邦、保留、导出、备份恢复和真实 Desktop 端到端验证。
|
||
7. `FR-14` Office 会话、对象存储、ONLYOFFICE、callback、checkpoint、策略、管理界面和三平台
|
||
Desktop 文档 Tab 端到端验证。
|
||
8. `FR-15` 至 `FR-18` 本地空间共享关联、资料定期／按需同步、实时消息、显式处理请求和共享来源授权；
|
||
对照用户故事完成服务端契约与 Desktop 集成，不能把静态 demo 当作真实消息服务。
|
||
|
||
当前尚未满足 PRD 的组织产品验收；本地元数据范围的真实 Desktop/ShareServer 联调记录见上文。
|
||
|
||
2026-09-05 PRD `FR-13` 新增组织数字人发布和 `@数字人` 调用。当前交互原型尚无“数字人”
|
||
目录、发布管理、提及选择器或 Agent 记忆边界展示，因此这些能力仍属于剩余生产与原型工作，
|
||
不能由现有通用能力目录或原型操作确认替代。
|
||
2026-09-09 PRD `FR-14` 新增 Office 编辑服务；当前原型同样没有对应导航、配置或服务端路径。
|
||
|
||
## 2026-09-28：客户端协作 US 与逻辑审查
|
||
|
||
- 新增 `user-stories.md`，补充本地工作空间、组织共享、同步、成员消息、分身处理和来源授权的
|
||
验收场景。PRD 新增 FR-15 至 FR-18，逻辑设计补充分离的共享、同步、交付与处理状态。
|
||
- 修订 `@数字人` 与 `@成员` 的范围，保留直接能力调用，同时定义发给成员后由本人或已授权
|
||
分身处理的流程。补充本人确认优先、草稿可见范围和接手时的并发检查。
|
||
- `docs/demo/client` 已有个人共享、设置及组织工作空间的本地交互演示；只使用浏览器存储和
|
||
固定回复，没有身份校验、服务端持久化、同步或真实模型执行。本轮仅修改设计文档。
|
||
- demo 仍需按最新 US 调整：统一创建本地空间及共享属性，增加同步与撤销状态；回顾原文
|
||
阅读仍依赖回答授权，尚未覆盖 US 要求的“仅阅读”组合；空间分身尚未绑定真实 Publication。
|
||
- 默认同步周期、容量和保留期限待定；匿名分享仍为概念演示，不纳入首期已登录组织协作验收。
|
||
|
||
### 同日补充：轻量 IM 与实时组件提案
|
||
|
||
- FR-16 区分实时消息与资料同步：普通消息、公开回复及处理状态实时更新，资料定期／按需同步。
|
||
暂停资料自动同步不停止消息收发、通知或断线补收。
|
||
- FR-17 区分提及和请求处理。`@成员` 只通知；显式选择处理人后才进入本人／分身处理流程。
|
||
新增 US-MSG-04，覆盖普通消息、线程、实时更新、确认丢失、离线补收和旧连接撤销。
|
||
- 技术设计记录 ShareServer + PostgreSQL + Centrifugo 为优先验证提案，并比较 Matrix、OpenIM
|
||
和 Socket.IO；没有确定组件或版本，没有安装依赖，也没有运行候选服务验证。
|
||
- 补充消息与 outbox 同事务、至少一次投递、数据库补收、草稿私有事件及权限撤销的设计要求。
|
||
这些是待实现契约，不是现有 API 或数据库能力。
|
||
- 本轮仅更新文档。静态 demo 仍要求选择接收人并自动进入处理流程，尚未支持普通消息、提及与
|
||
请求处理分离、真实实时推送及离线补收；需在后续原型迭代中对齐。
|