ctms/docs/onlyoffice-collaboration.md

ONLYOFFICE 在线协作模块

范围

在线协作是共享库下的独立业务模块，不复用附件、文档管理、文件版本管理或 eTMF 的数据表和文件标识。当前支持新建或导入 DOCX、XLSX、PPTX，通过 ONLYOFFICE 进行多人共同编辑，并把保存结果固化为不可变修订。

原有附件与文档版本仍保持只读预览流程，不会自动进入协作空间，也不会因协作回调被覆盖。

数据与权限边界

• collaboration_files 保存协作文件元数据、当前修订指针和统一的内容操作权限设置。
• collaboration_revisions 保存不可变文件修订；每次有效保存或历史恢复都会创建新修订。
• collaboration_members 保存文件级编辑者和管理者。
• collaboration_edit_requests 保存系统内项目成员发起的编辑权限申请及审批结果；同一成员、同一文件同时只允许存在一条待处理申请。
• notifications 是收件人级通用通知表，统一保存通知类别、优先级、内部操作路径、业务来源、去重键、已读和业务关闭状态。编辑权限申请只通知当前有效的文件所有者和文件管理者；申请处理后，同一业务来源的所有收件人通知一并关闭。
• collaboration_sessions 使用稳定的文件代次生成 ONLYOFFICE document.key，同一代次的用户进入同一共同编辑会话。
• collaboration_callback_receipts 对回调做幂等确认。
• collaboration_share_links 保存单文件公开链接的启停状态、查看/编辑权限、有效期策略和密码哈希；不保存明文密码或共享令牌。
• 项目接口权限只控制在线协作模块入口、项目级新建/导入/文件夹操作，以及账号能否被授予文件角色；文件创建后的编辑、管理、导出和所有权转让统一由文件身份判定，项目角色不再隐式覆盖文件角色。
• 文件所有者始终拥有编辑、管理、导出和转让能力；文件管理者始终拥有编辑、管理和导出能力，但不能转让所有权；文件编辑者可以编辑，导出能力由文件“权限设置”开关控制。系统管理员继续保留平台级完整访问能力。
• 授予编辑者、管理者或转让所有权时，目标账号必须是当前项目的有效成员，并具备对应项目角色资格；不合格账号在联系人列表中不可选择，后端同时拒绝绕过界面的授权请求。
• 文件管理者可开启“允许申请编辑权限”。只读项目成员可从 CTMS 顶栏或 ONLYOFFICE 的“请求编辑”入口提交申请；批准后写入文件级编辑者授权，拒绝或重复处理均有明确状态和审计记录。匿名链接访问者不能申请系统账号权限。
• 顶栏铃铛通过通用通知 Feed 展示当前收件人的未关闭通知并记录已读状态；编辑权限申请通知可直接进入对应文件的“权限设置”，审批结果作为一次性信息通知申请人。AE、监查问题、文件回执和里程碑时效提醒也由同一 Feed 返回，具体规则见 docs/project-notifications.md。
• Excel 文件可通过“允许所有协作者添加、删除工作表”控制工作簿结构。关闭时 CTMS 在新的不可变修订中启用工作簿结构保护并推进文件代次；重新开启时恢复文件原有的工作簿保护状态。该开关作用于所有协作者且不影响单元格内容编辑权限。
• 仅文档所有者和系统管理员可转让所有权。目标联系人必须具备文件管理者资格；转让后目标联系人升级为文件管理者，原所有者保留管理者身份，所有权变更写入审计。
• 文件编辑器“下载为”由文件导出规则判定：所有者和管理者始终允许，编辑者受文件开关控制，并由 CTMS 网页/桌面文件运行时保存到本机且记录下载审计。“另存为…”还会在项目工作区创建独立协作文件，因此额外要求项目级 collaboration:create 权限。

公开分享链接

• 文件管理者可开启链接，并选择只读或协作编辑、1 天/7 天/30 天/永久有效及可选访问密码；设置修改后自动保存，无需额外提交整张表单。
• 文件操作菜单以一个“访问与权限”弹窗统一管理账号授权、匿名访问和“权限设置”；下载、打印、另存和复制不在两种访问方式下重复配置。
• “权限设置”中的内容操作开关只作用于已授权编辑者和匿名访问者。所有者、文件管理者和系统管理员始终保留导出能力；外部链接不具备向项目工作区另存副本的权限。
• 共享令牌只放在网页 URL 的 fragment（#...）中，不进入服务器请求路径、查询参数或本地缓存；前端调用公开 API 时通过会被审计层脱敏的请求头传递。
• 每个文件首次创建分享记录后使用固定共享地址；修改权限、密码、有效期或关闭后重新开启都不会改变 URL。关闭期间同一地址暂停访问，重新开启后恢复访问。
• 链接密码仅保存 bcrypt 哈希；验证成功后签发短时、链接记录绑定的内存访问凭证。连续错误达到阈值后链接密码验证会临时锁定。
• 外部共享页不依赖 CTMS 登录状态，不提供工作区“另存为”；开启允许导出后可下载到访问者本机，编辑链接仍通过现有 ONLYOFFICE 会话写入不可变修订。
• JWT_SECRET_KEY 轮换属于平台级全局失效操作，会使现有公开分享链接和短时访问凭证失效；生产环境必须按安全变更流程评估影响并提前通知链接使用者。

保存流程

1. 浏览器请求 /api/v1/studies/{study_id}/collaboration/files/{file_id}/editor-config。
2. 后端生成带 JWT 的编辑配置、内部内容地址和回调地址。
3. Document Server 从内部内容接口读取当前修订。
4. 共同编辑期间使用 fast 模式；强制保存产生新修订并更新会话恢复基线。
5. 最后一位编辑者退出后，状态 2 回调产生最终修订并推进文件代次；下一次编辑使用新的 document.key。
6. 重复回调通过指纹幂等处理；旧代次回调不会覆盖当前文件。

内部内容和回调接口不经过 Nginx 公网入口，只接受 AuthorizationJwt。回调结果文件仅允许从配置的 Document Server 内部源获取，禁止重定向、凭据 URL 和任意主机。

本地开发

标准开发安装会直接启动 ONLYOFFICE：

bash scripts/install.sh dev

安装脚本会生成或复用独立的开发 JWT 密钥和稳定实例标识，默认启动 Document Server，并验证后端配置和 HTTP 健康状态。bash scripts/onlyoffice-dev-up.sh 仅用于开发环境单独重建、验证或轮换密钥。协作修订保存在现有后端上传卷下的独立 collaboration/ 目录。

关键配置：

• ONLYOFFICE_ENABLED
• ONLYOFFICE_JWT_SECRET
• ONLYOFFICE_INTERNAL_URL
• ONLYOFFICE_STORAGE_BASE_URL
• ONLYOFFICE_INSTANCE_ID
• ONLYOFFICE_CONFIG_TTL_SECONDS
• COLLABORATION_MAX_FILE_BYTES

生产标准安装同样包含 ONLYOFFICE；正式上线前必须按既有发布要求确认镜像许可、独立 JWT 密钥、内部网络、容量、备份与监控。

参考：

• ONLYOFFICE 共同编辑模式
• ONLYOFFICE 回调处理器
• ONLYOFFICE 文档权限