协同文件保存与更新机制

石墨协同文件的"保存"不支持接入应用手动触发类似 POST /save 动作，而是石墨编辑器在用户每次输入后自动把增量的编辑动作推到石墨文档中台后端，石墨文档中台后端通过事件推送回调告诉接入应用"这个文档发生了什么"。本文系统讲清楚这套机制、所有相关事件的字段、典型业务侧用法，以及排查保存异常的流程。

一、整体架构

文件内容是自动保存。编辑器的协同引擎在用户输入瞬间就把增量的编辑动作推到石墨云端，并在所有协作者之间广播；详见官方说明。

接入应用关心的是"保存这件事发生了"，而不是"保存什么"。前端给用户提示、后端更新业务侧的元数据（最近更新时间、最近编辑人、版本号），不需要拿到文档正文本身。

前端 SDK 事件用来驱动 UI（保存中 / 已保存 / 失败），是用户体验层面的。

编辑事件推送用来驱动你的应用做后续的业务动作，比如更新文件列表时间戳、推送文件内容变动通知、触发审批联动等。

二、一次保存的完整业务流程

下图把一次"用户敲键盘 → 接入方业务库被更新"完整画出来：

值得记住的三件事：

前端 saved 事件不代表后端已经更新业务库。两条通道独立，业务侧依赖业务库时要等回调到达。

同一次输入引起的两条通知可能先后到达顺序不固定。前端 saved 经常先到，但接入方不要建立"先 saved 后回调"的硬假设。

回调可能因接入方端点抖动而重试，业务侧必须保证幂等。

三、后端：事件推送回调

3.1. 统一入口

所有事件都通过同一个 HTTP 端点推送：

POST {endpoint_url}/events

通过两个 Header 区分事件类型与鉴权方式：

Header	说明
`X-Shimo-Sdk-Event`	事件类型标识，路由到不同业务分支的依据
`X-Shimo-Token` 或 `X-Shimo-Signature`	鉴权凭证；`X-Shimo-Credential-Type=3` 时使用 signature

接入方在这一个端点里按 X-Shimo-Sdk-Event 做分发，不需要为每种事件单独配 URL。

3.2. 协同编辑相关事件列表

`X-Shimo-Sdk-Event` 类型	触发时机	关键字段	鉴权方式
`file.content.updated`	文件被修改、增量被服务器处理成功	`fileId`、`userId`、`fileContent.version`	signature
`file.collaborator.changed`	协作者进入 / 退出文档	`action(enter\|leave)`、`collaboratorChanged.clientId`	signature
`file.revision.*`	历史版本创建 / 修改 / 删除	`action(create\|update\|delete)`、`revision.revisionId`、`revision.title`	token

字段名仅是分类口径，实际请以 SDK 当前推送的 kind / type 字段为准。

所有事件 Body 都有四个公共字段，再按事件追加各自的实际业务内容：

{
  "kind": "...",
  "type": "...",
  "fileId": "doc_38291",
  "userId": "userid123",
  "timestamp": 1716800000000,
  "...": "事件特定字段"
}

注意：timestamp 是事件产生时间，业务侧落库时用它作为"事件时序"判断依据，不要用接到 HTTP 请求的本地时间，否则乱序到达时容易把旧事件覆盖新事件。

一、整体架构#

二、 一次保存的完整业务流程#

三、后端：事件推送回调#

3.1. 统一入口#

3.2. 协同编辑相关事件列表#

一、整体架构

二、一次保存的完整业务流程

三、后端：事件推送回调

3.1. 统一入口

3.2. 协同编辑相关事件列表