goodbuddy-shareserver/docs/features/share-server/progress.md

ShareServer 实施进度

当前状态

ShareServer 包含控制台交互原型和可持久化的本地共享目录服务。GoodBuddy 已能注册设备、发布与 撤销元数据，Web 能查看真实目录；生产身份、组织隔离、设备控制连接、授权及任务路由仍未实现。

2026-10-01：Office 私有部署第一阶段设计

• 本轮仅更新文档：PRD 限定可信私有网络的 DOCX 浏览器往返范围，逻辑设计定义编辑轮次与保存 状态，UI 设计补充真实试验入口，技术设计集中维护容器、地址、JWT、回调和本地文件提交契约。
• 明确本阶段不以身份源、组织数据库、S3/MinIO 或独立 callback worker 为依赖；完整组织权限、 Desktop／Agent 和三格式能力仍属后续目标，不能从私有试验推定用户授权或组织隔离。
• 当前 Compose 仍只有 ShareServer，使用宿主 data/ bind mount，无 named volumes。 docker/compose.office.yaml 仅为拟议路径，镜像 edition／固定版本及协议兼容性待核验。
• 未修改代码、容器或配置，未启动 ONLYOFFICE，也未验证真实上传、编辑、callback 或保存。 git diff --check 通过，已复核新增内部引用及阶段约束，并查阅官方 JWT／callback 文档； 未选定镜像版本，运行与端到端验证需在实现后完成。

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、安装包或跨平台原生窗口。 定向检查与全仓测试差异见桌面验证记录： 全仓测试曾有两项失败，修正配置样例及单独复跑后通过，未将全仓结果记为一次全绿。

本轮完成本地元数据流程；设备认证、组织归属、能力执行、知识正文检索和同步、模型转发、 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 误认为生产服务。

验证证据：

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 逐步演变为权威状态：

以下顺序用于组织生产服务；Office 私有部署第一阶段可按技术设计第 10.1 节独立推进，不等同于第 7 项交付。

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 仍要求选择接收人并自动进入处理流程，尚未支持普通消息、提及与 请求处理分离、真实实时推送及离线补收；需在后续原型迭代中对齐。