docs: scope private ONLYOFFICE integration

docs/features/share-server/README.md

@@ -11,6 +11,11 @@ ShareServer 是 GoodBuddy 设备共享网络的独立 Web 服务。它为一个
 Office 区分服务端主存文档与显式的本地来源导入／回写模式。既有 Desktop 源文件、检查点和
 冲突契约用于后者；编辑会话结束不删除服务端主文档，检查点可用也不等于本地或 SSH 源文件已回写。
 
+Office 私有部署第一阶段仍待实现：先验证浏览器 DOCX 上传、编辑、保存与重新打开，默认本地
+文件存储，独立 Document Server 容器；范围见 [PRD](./prd.md#office-私有部署第一阶段待实现)，
+部署与协议以[技术设计第 10.1 节](./technical-design.md#101-私有部署第一阶段待实现)为准。
+拟议 `docker/compose.office.yaml` 尚不存在，现有 Compose 不包含 ONLYOFFICE。
+
 ShareServer 不属于 Electron Main，不负责桌面端局域网发现，也不自动取得设备上的能力、
 文件、凭据或 SSH Host。
 

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

@@ -5,8 +5,8 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中 |
-| 版本 | 0.5 |
+| 版本 | 0.6 |
-| 日期 | 2026-09-28 |
+| 日期 | 2026-10-01 |
 | 关联 PRD | [ShareServer PRD](./prd.md) |
 | 共享规则 | [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) |
 
@@ -14,6 +14,7 @@
 
 当前本地联调仅实现设备与发布元数据，使用[技术设计第 4.1 节](./technical-design.md#41-本地共享目录契约已实现)
 的独立接口。下文组织身份、Grant、任务和文档归属规则属于目标设计。
+Office 私有部署第一阶段的限定状态规则见第 8.2 节，不声称具备 INV-1 的组织隔离或 INV-12 的多类凭据体系。
 
 - 注册相同设备 ID 更新名称、平台及版本，保留首次注册时间；相同内容重试不改变时间。
 - 注册不自动发布内容，也不表示设备在线。设备列表目前没有心跳或离线判断。
@@ -384,6 +385,27 @@ Publication/Grant，本人草稿确认也不能绕过当前访问权限。
 | Desktop 报告源文件冲突 | 保留 checkpoint 至到期，记录 `source_conflict` |
 | 设备或组织权限撤销 | 拒绝新操作并关闭会话，不删除 Desktop 源文件 |
 
+### 8.2 Office 私有部署第一阶段（待实现）
+
+服务端主文档有稳定 ID 和单调递增的持久化 revision；编辑会话关联文档 ID、基准 revision、
+编辑轮次及 ONLYOFFICE `document.key`。同一文档同一轮共同编辑复用 key，不按浏览器或每次打开
+生成不同 key。活动轮次不接受另一份上传覆盖主文档；另传文件创建新文档。
+
+- status `6` 表示编辑期间的 forcesave：持久化快照后更新已保存 revision，继续当前编辑轮次，
+  不更换 key，也不据此宣布后续人工修改已保存。
+- status `2` 表示本轮编辑结束后的保存：持久化最终内容后结束该轮；等待最终保存时，新打开请求
+  等待或返回可重试状态，不能先开启一个会被旧回调覆盖的新轮次。下轮从最新 revision 生成新 key。
+- 关闭浏览器不等于服务端保存完成；无修改结束按 status `4` 收束，status `3`/`7` 保存错误保留
+  最近成功版本并报告失败。status `4` 不增版，无内容变化时允许恢复原 key 的连接；需验证断网后
+  重连场景，不因一次断连即换 key。连接和其他通知不触发文件保存。
+- 同文档保存串行处理，重复回调返回原结果；已结束轮次的迟到回调不得覆盖新轮次，迟到的
+  forcesave 不得覆盖最终保存。无法确定先后或版本冲突时保留原版本并报告待确认，不按到达时间盲目覆盖。
+- 已持久化才显示“已保存到服务器”；写盘失败不确认成功，确认丢失后查询或重试同一次保存。
+  主文档不因会话结束而删除，首期不提供归属转移或组织权限承诺。
+
+协议、幂等依据与文件提交方式由[技术设计第 10.1 节](./technical-design.md#101-私有部署第一阶段待实现)
+定义。首期保存结果不涉及 Desktop／SSH 源文件回写。
+
 ## 9. 需求追踪
 
 | 需求 | 主要逻辑 |
@@ -401,7 +423,7 @@ Publication/Grant，本人草稿确认也不能绕过当前访问权限。
 | `FR-11` | 组织角色边界及各对象状态；展示行为由 UI 设计定义 |
 | `FR-12` | 短期权威恢复规则和逻辑完整性；部署结构由技术设计定义 |
 | `FR-13` | 注册、Publication、目录与授权不变量，provider 冻结及 `INV-10` |
-| `FR-14` | `INV-11`、`INV-12`、DocumentEditSession、Office 保存与保留规则 |
+| `FR-14` | `INV-11`、`INV-12`、DocumentEditSession、Office 保存与保留规则；私有部署第一阶段见 8.2 |
 | `FR-15` | 2.8 工作空间共享状态、组织与空间成员边界 |
 | `FR-16` | 2.8 资料同步与消息连接分离；2.9 交付确认、实时更新与补收 |
 | `FR-17` | 2.9 普通消息与处理请求分离；5.1 处理优先级与接手竞争 |

docs/features/share-server/prd.md

@@ -5,8 +5,8 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中 |
-| 版本 | 0.7 |
+| 版本 | 0.8 |
-| 日期 | 2026-09-30 |
+| 日期 | 2026-10-01 |
 | 适用产品 | 独立部署的 ShareServer 与 Web 管理控制台 |
 | 关联架构 | [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) |
 | 关联文档 | [功能逻辑](./logic-design.md)、[管理界面](./ui-design.md)、[技术设计](./technical-design.md) |
@@ -41,6 +41,20 @@
 真实目录与组织样例分别展示。API、状态和验证证据分别由技术设计、逻辑设计和实施进度维护。
 身份认证、组织授权、内容同步与远程调用仍按以下完整产品范围继续实现。
 
+### Office 私有部署第一阶段（待实现）
+
+在可信私有网络内，先验证浏览器上传 DOCX、打开、编辑、保存到 ShareServer、关闭后重新打开，
+以及服务重启后仍能读取已保存内容。采用独立 ONLYOFFICE Document Server 容器，默认使用现有
+数据目录下的本地文件存储；不要求先建设身份源、组织数据库、S3/MinIO 或独立 callback worker。
+此阶段不提供用户授权或组织隔离，能访问服务的可信使用者可操作试验文档，不适合广泛暴露。
+JWT 用于编辑器配置和服务回调校验，不代表浏览器用户已认证；文档与会话关联也不是访问授权。
+
+第一阶段允许 Web 试验入口，完整产品的日常入口仍为 GoodBuddy。XLSX/PPTX、Desktop 文档 Tab、
+本地／SSH 回写、Agent 实时编辑、个人／组织归属与权限在后续阶段实现。FR-14 中的多类短期
+凭据、组织策略与插件要求属于这些后续能力，不作为本阶段的前置条件。存储和容器契约见
+[技术设计第 10.1 节](./technical-design.md#101-私有部署第一阶段待实现)，状态规则见
+[逻辑设计第 8.2 节](./logic-design.md#82-office-私有部署第一阶段待实现)。
+
 ### 3.1 包含
 
 - 本地账号及可配置 OIDC 身份源。
@@ -212,6 +226,8 @@
 
 ### FR-14 Office 编辑服务
 
+以下为完整产品目标；私有部署第一阶段按第 3 节的限定范围单独验收，不据此宣称完整 Office 能力已交付。
+
 - 日常文档使用在 GoodBuddy 中完成，ShareServer 主存文档与临时编辑会话分别管理。个人创建者
   可删除自己的文档或确认转移给组织；转移后按组织权限删除，原创建者的个人删除权失效。
   管理后台展示归属元数据不授予个人正文访问权。原型以显式“组织文档管理员”角色模拟组织

docs/features/share-server/progress.md

@@ -5,6 +5,18 @@
 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/`；
@@ -160,13 +172,15 @@ npm run build   # typecheck + Vite Web + server TypeScript passed
 
 按技术设计从以下纵向切片开始，不能把原型 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、策略、管理界面和三平台
+7. `FR-14` Office 会话、所选持久存储、ONLYOFFICE、callback、checkpoint、策略、管理界面和三平台
    Desktop 文档 Tab 端到端验证。
 8. `FR-15` 至 `FR-18` 本地空间共享关联、资料定期／按需同步、实时消息、显式处理请求和共享来源授权；
    对照用户故事完成服务端契约与 Desktop 集成，不能把静态 demo 当作真实消息服务。

docs/features/share-server/technical-design.md

@@ -5,8 +5,8 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中 |
-| 版本 | 0.5 |
+| 版本 | 0.6 |
-| 日期 | 2026-09-28 |
+| 日期 | 2026-10-01 |
 | 关联 PRD | [ShareServer PRD](./prd.md) |
 | 功能逻辑 | [功能逻辑设计](./logic-design.md) |
 | 共享协议 | [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) |
@@ -78,11 +78,14 @@ ShareServer 仍不得导入 Electron 的 `src/shared`，也不得依赖相邻桌
 
 ## 2. 技术选型约束
 
+本节及下文组织身份、数据库事务、Web session 安全与生产部署要求属于完整组织服务目标。
+本地目录按第 4.1 节实现；Office 私有部署第一阶段按第 10.1 节单独推进，不以前述能力为前置条件。
+
 - 使用与仓库一致的 TypeScript/Node.js 工具链，具体 HTTP 框架在实现前根据维护性选择。
 - PostgreSQL 是组织、策略、任务元数据和审计的权威数据库；工作空间消息、处理状态及可靠投递记录
   也以数据库为准，具体业务表与受控正文存储在协作模块实现时增加。
-- Package、可选中继暂存和 Office 工作副本使用 S3 兼容对象存储；不开启对应功能时不要求
+- 完整组织服务计划使用 S3 兼容对象存储保存 Package、可选中继暂存和 Office 工作副本。
-  对象存储，启用 Office 时对象存储是必需依赖。
+  Office 私有部署第一阶段默认本地文件系统，S3 是后续可选扩展，不是启用 Office 的必需依赖。
 - Web 控制台与 API 同源部署，采用严格 CSP，不在浏览器保存设备凭据。
 - 单实例部署可完整工作，不为未验证规模预设复杂分布式协议。工作空间实时投递优先评估独立
   实时组件，与是否水平扩展分开决策；第 18 节记录候选方案，尚未确定采用。
@@ -281,30 +284,117 @@ Release catalog 使用独立签名域。服务器不能重打包已签名 payloa
 
 ## 10. Office 编辑服务
 
-### 10.1 部署边界
+### 10.1 私有部署第一阶段（待实现）
+
+本节是首期容器、配置、接口和持久化的权威设计，范围以 PRD 第 3 节为准。当前 `/documents`
+仍为演示，仓库只有 ShareServer 的 `docker/compose.yaml`，没有 Office overlay 或真实编辑链路。
+第一阶段采用单个 ShareServer 进程、独立 Document Server 和本地文件系统，不新增身份源、数据库、
+S3/MinIO、独立 callback worker 或启动 code／安全 Cookie 交换。仅适用于可信私有网络；当前无认证，
+可访问服务者可操作试验文档，随机文档 ID 和 JWT 均不能据此宣称用户授权或组织隔离。
+
+#### 容器与地址
+
+后续实现拟增加可选 `docker/compose.office.yaml`，与现有 Compose 叠加使用；该文件尚未创建，
+现有默认启动不启用 Office。Document Server 与 Hono 分进程、分容器，通过 Docker 网络 HTTP
+取源文件和回传结果。镜像 edition、固定版本 tag／digest 待选型验证，不使用浮动 latest 作为验收基线。
+Developer Edition 仍是完整产品候选；私有 Web 编辑的许可证与后续 Desktop／Agent（含 Automation
+API 或插件）的授权分别核验，不由容器能启动推定已获授权或功能兼容。
+
+ShareServer 继续绑定宿主 `data/` 到 `/app/data`，Office 文件放在其中的 `office/`。Document Server
+所需数据、日志等挂载使用独立宿主目录（拟为 `data/onlyoffice/` 下各子目录），按选定镜像确认挂载点
+和 UID/GID，不使用 named volumes，也不把 ShareServer 文档目录挂给它写入。主文档只由 ShareServer
+提交；Document Server 缓存不作为主文档备份。备份需包含 Office 文件及其版本元数据，可停写后复制。
+
+以下是拟定配置项的语义，尚未加入环境变量或配置文件：
+
+| 配置 | 谁使用及用途 |
+| --- | --- |
+| Office 启用开关 | ShareServer；默认关闭，故障不影响其他服务 |
+| ShareServer 浏览器 URL | 浏览器访问 Web 与同源 API |
+| Document Server 浏览器 URL | 浏览器加载 `web-apps/apps/api/documents/api.js`、编辑器及其连接；必须在客户端可达 |
+| ShareServer 内部 origin | Document Server 下载源文件、发送 callback；例如 Docker 服务地址 `http://shareserver:8787` |
+| Document Server 内部 origin | ShareServer 请求保存输出或命令；例如拟定服务名 `http://onlyoffice` |
+| JWT 共享秘密 | 两服务配置一致，仅保存在部署环境或秘密文件，不返回原始秘密给浏览器 |
+| 上传／保存大小、请求超时和存储额度 | 设置有限值，首期只允许 DOCX；实现前确定默认值并在 UI 展示上传上限 |
+
+浏览器地址与容器内部地址分开配置，不能把 Docker 服务名当作用户浏览器可解析的域名，也不能把
+容器内 localhost 当另一服务。反向代理需支持编辑器连接；HTTPS 页面所用编辑器地址也需 HTTPS，
+按实际部署配置 CSP。ONLYOFFICE 对私有地址请求的过滤开关、默认值及例外配置须查验选定版本，
+只允许所需的 ShareServer 内部访问，不假设容器网络互通就能下载文件。
+
+#### 最小接口与协议
+
+拟在 `/api/v1/office/` 提供 DOCX 上传、文档列表／详情及按文档 ID 打开编辑会话的接口，供同源
+Web 使用；在 `/internal/office/` 提供按会话关联的源文件读取和 callback。具体路径在实现时定版，
+不复用第 10.2 节的 Desktop 凭据流程。服务端生成文档 ID、存储文件名和会话 ID，记录基准 revision、
+编辑轮次与 `document.key`；客户端只提交 ID，不接收绝对路径、路径片段或任意源文件 URL。
+上传按流限制字节数并验证 DOCX 实际格式，不仅检查扩展名／MIME；返回的保存文件同样限制大小和格式。
+
+1. 上传持久化后返回文档 ID。打开时解析服务器记录，复用当前活动编辑轮次，或从最新已保存版本
+   建立新轮次；将源文件 URL、`document.key` 和 `editorConfig.callbackUrl` 组成编辑器配置。
+2. 配置由 ShareServer 用共享秘密签发 JWT，浏览器只取得配置及签名 token。按所选版本的
+   [JWT 协议](https://api.onlyoffice.com/docs/docs-api/additional-api/signature/)配置算法、签名范围、
+   入站／出站 token 开关及传递位置；callback 验签并核对受签名保护的 payload、key 与会话关联，
+   不仅检查存在一个 token。源文件请求按该版本支持的出站 JWT 校验方式验证并解析关联版本。
+3. 按 [callback 协议](https://api.onlyoffice.com/docs/docs-api/usage-api/callback-handler/)处理状态。
+   status `2`／`6` 才下载保存输出；其他状态按逻辑设计第 8.2 节更新，不误取不存在的 URL。
+   `document.url` 和 callback 地址由固定配置生成，浏览器不能指定回调目的地。
+4. callback 中的输出 `url` 即使签名有效，也只允许明确配置的 Document Server origin。
+   若输出使用浏览器 origin，按配置的固定映射转换到内部 origin，保留合法路径和查询；禁止任意
+   主机和用户信息，不跟随重定向。下载有超时和字节上限，不开放通用 URL 抓取接口。
+
+#### 持久化与保存确认
+
+复用单进程文件存储方式，但 Office 使用独立元数据，不混入 `sharing.json`。每个文档的保存按队列
+串行提交：先将输出写入同一文件系统的临时文件，验证并计算 SHA-256，再同步、rename 为不可变
+版本文件；随后以临时文件、同步、原子 rename 提交该文档的元数据，包含当前 revision、文件引用、
+摘要、轮次状态和已处理保存记录。元数据是发布点，读取只跟随已提交引用；崩溃留下的未引用文件
+不成为当前版本，重启从元数据恢复，坏元数据报错而非清空。文件与目录同步要求随宿主文件系统验证。
+
+保存记录结合轮次 key、status、协议中可用的保存标识及内容摘要去重，不假设 callback 自带唯一事件
+ID，也不以临时 URL 作为唯一幂等依据。首期由服务端触发的 forcesave 串行发起，用该版本支持的
+`userdata` 关联单调保存序号；首期不启用额外的定时／编辑器按钮 forcesave，后续启用前须核验其
+身份与排序，不能识别的并发保存不盲目覆盖。最终保存与迟到快照的优先级见逻辑设计第 8.2 节，协议字段映射及重复、
+乱序用例是实现前的验证项。活动 key 不因 forcesave 或持久化 revision 增长而改变。
+
+首期在 Hono 回调处理中完成持久化后才返回协议成功响应 `{"error":0}`；失败返回协议错误并保留
+上一个成功版本。不能先确认再在内存中异步写盘。未来若改为异步处理，必须先形成可恢复的持久任务
+才确认接收，且另行报告实际保存结果；本阶段不为此引入新 worker。成功记录与版本引用一同提交，
+确认丢失后重复 callback 不重复增版。服务重启不自动轮换仍未收束的 key；先按持久轮次状态核对
+Document Server，无法确认时阻止覆盖并提示待确认。
+
+#### 第一阶段验证
+
+基础 liveness 只证明 HTTP 进程可访问，不在周期健康探针里编辑文档。Office 启用验收另做真实往返：
+浏览器加载编辑器，Document Server 下载 DOCX，编辑并收到 callback，ShareServer 持久化后关闭／
+重新打开可见修改；重启 ShareServer 后再次验证。记录固定镜像版本、edition、地址组合及验证时间。
+同时验证 forcesave 不更换 key、同轮多开复用 key、最终保存与重复／迟到回调、磁盘失败、下载超时、
+非法 JWT／文档 ID／格式／超限上传、非配置输出 origin 和重定向均不造成错误覆盖或虚假成功。
+端口健康或 UI 模拟结果不能替代上述验收，完成后仍不将 `productionReady` 改为 true。
+
+### 10.2 后续 Desktop API 与部署边界
 
 文档以 ShareServer 为主存储，GoodBuddy 承担日常操作。个人创建者可删除或转移给组织，转移
 后删除按组织权限判断；管理元数据可见性不授予个人正文访问权。服务端主文档与编辑会话分开
 管理，主文档纳入备份及自身删除／保留规则，不随会话过期清理。
 
-第 10.2、10.3 节既有上传、检查点下载和 `source-commit` 契约描述显式的本地来源导入／回写
+本节及第 10.3 节的上传、检查点下载和 `source-commit` 契约描述显式的本地来源导入／回写
 模式，继续保留 Desktop／SSH 源文件基准校验和冲突处理。服务端主存模式不要求本地回写确认；
 其具体存取接口未在本次演示中实现，不由会话 API 推定已经具备文档持久化。
 
 目标设计集成 ONLYOFFICE Docs Developer Edition，但不把 Document Server 代码并入 Hono
-进程。生产部署使用独立容器和内部网络：
+进程。后续组织部署可扩展为以下结构，S3 和独立 worker 不属于第一阶段依赖：
 
 ```text
 GoodBuddy Desktop -> TLS reverse proxy -> ShareServer Office API
                                           |-> S3 compatible object storage
                                           |-> ONLYOFFICE Document Server
-                                          `-> Office callback worker
+                                          `-> 可选独立 Office callback worker
 ```
 
-Desktop 只知道 ShareServer 公开 origin。Document Server 内部地址、JWT 密钥、对象存储凭据和
+Desktop 经 ShareServer 获取编辑配置，编辑器仍需可达的 Document Server 浏览器 URL。
-callback 内部地址只存在于部署配置或密钥管理系统。正式采用前必须完成许可证和桌面分发审核。
+内部地址由部署配置确定，源文件和 callback URL 会进入编辑器配置，不承诺对浏览器隐藏；
-
+JWT 原始密钥和对象存储凭据仅由服务端保管。正式采用前必须完成许可证和桌面分发审核。
-### 10.2 Desktop API
 
 ```text
 POST   /api/v1/office/sessions
@@ -383,17 +473,16 @@ ShareServer API + Web
 PostgreSQL
 可选：S3 compatible object storage
 可选：Relay worker
-可选套件：ONLYOFFICE Document Server + Office callback worker（需要对象存储）
+可选套件：ONLYOFFICE Document Server（存储与回调处理按阶段选取，见第 10 节）
 ```
 
 部署配置通过环境变量或挂载文件提供数据库、主密钥、公开 URL、OIDC、邮件、对象存储和限制。
 普通 Web 管理员不能修改基础设施秘密。提供数据库迁移命令、不可变镜像、非 root 容器、健康
 与就绪端点、优雅停止和部署示例。
 
-Office 配置包括启用状态、Document Server 内部地址、公开编辑 origin、JWT 密钥引用、对象
+Office 第一阶段配置与独立往返验收见第 10.1 节；后续组织部署增加所选对象存储 bucket、
-存储 bucket、允许格式、文件大小、组织/用户并发、会话期限和 checkpoint 保留。管理界面不能
+组织/用户并发、会话期限和 checkpoint 保留。管理界面不能回显密钥。基础 liveness/readiness
-回显密钥。Office readiness 必须完成最小文档创建、编辑器加载、callback 和输出摘要验证，不能
+不代表 Office 编辑可用，完整 Office 验收须验证编辑器加载、callback 和持久化输出。
-只检查 Document Server HTTP 端口。
 
 ## 14. 可观测性与备份
 
@@ -447,8 +536,9 @@ Office 配置包括启用状态、Document Server 内部地址、公开编辑 or
 
 `/api/v1/public/ready` 返回 `mode=interactive-prototype` 和
 `productionReady=false`。原型 fixture、角色切换和操作确认只用于评审信息架构，不得被
-Desktop 或部署脚本当作真实身份、策略、任务或审计 API。下一实施阶段必须从 FR-1
+Desktop 或部署脚本当作真实身份、策略、任务或审计 API。组织生产实施须从 FR-1
-初始化、本地身份、PostgreSQL 组织作用域和事务审计开始，不在 fixture 上叠加生产状态。
+初始化、本地身份、PostgreSQL 组织作用域和事务审计开始；第 10.1 节私有 Office 试验可独立推进，
+使用真实文件和独立元数据，不在 fixture 上叠加权威状态。
 当前 `/documents` 已有 OnlyOffice 实例配置与预设检查模拟；Office 会话 API、对象存储、
 ONLYOFFICE 编辑、callback、文档保存和 Desktop 文档 Tab 集成仍未实现。
 

docs/features/share-server/ui-design.md

@@ -5,8 +5,8 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中 |
-| 版本 | 0.5 |
+| 版本 | 0.6 |
-| 日期 | 2026-09-28 |
+| 日期 | 2026-10-01 |
 | 关联 PRD | [ShareServer PRD](./prd.md) |
 | 功能逻辑 | [功能逻辑设计](./logic-design.md) |
 
@@ -200,7 +200,7 @@ Office 编辑管理归入“文档与协作”，属于系统管理员的服务
 系统管理员视图显示：
 
 - 服务状态、ONLYOFFICE 版本、许可证状态和最近一次完整健康检查。
-- Document Server、callback worker、对象存储的独立状态和稳定错误阶段。
+- Document Server、回调处理和所选存储的独立状态和稳定错误阶段。
 - 活动/断线/过期会话数、保存成功/失败/结果未知、存储用量和待清理对象。
 - 全局允许格式、最大文件、并发、会话期限、checkpoint 保留和紧急停用。
 
@@ -215,6 +215,20 @@ Office 编辑管理归入“文档与协作”，属于系统管理员的服务
 保留策略处理。删除会话是危险操作，显示用户、设备、文件显示名、稳定 checkpoint 和未确认
 回写状态；不能提供管理员直接下载任意成员文档的默认入口。
 
+### 13.1 私有部署第一阶段入口（待实现）
+
+在 `/documents` 提供明确区分于现有演示的“私有文档试验”入口，展示无用户授权的使用范围。
+提供 DOCX 上传、真实文档列表、打开编辑器、保存状态与关闭后重新打开；不使用模拟个人／组织
+归属或角色开关解释真实文件。列表显示名称、大小、最近持久化版本与保存时间，不显示服务器路径。
+
+编辑器加载失败、上传格式或大小超限、等待最终保存、保存失败和结果待确认各自显示原因及可用的
+重试操作。编辑器本地保存提示不直接变成“已保存到服务器”，以服务端持久化结果为准；关闭后若
+最终保存未完成，重新打开需提示等待。forcesave 后继续编辑时，已保存版本不代表当前全部修改。
+
+服务信息区分“进程可访问”与“编辑往返已验证”，后者显示最近真实验证时间和结果；不使用预设
+检查冒充实测。部署地址和 JWT 秘密由部署配置提供，首期不增加密钥表单。配置与验证契约见
+[技术设计第 10.1 节](./technical-design.md#101-私有部署第一阶段待实现)。
+
 ## 14. 系统设置
 
 只包含实例名称、公开地址、身份源、邮件、数据库/对象存储状态、中继开关与上限、Office 服务