协同文件复制与删除

复制和删除是改变石墨侧文件状态的两个"硬动作"，做不好会让石墨侧和你的业务库长期不一致 —— 业务列表里点开找不到文件、删除后还能继续协同、复制半截子用户已经在编辑空文档。本文按"先理解石墨的接口语义、再设计业务侧一致性流程"的顺序，把这两件事讲清楚。

一、整体架构

复制和删除有两个共同的特征：

石墨和你的应用各持一份文件状态。石墨这边有文档内容、协同会话、历史版本；你的应用那边有文件元数据（标题、所有者、业务权限、归档状态）。两边必须在每一次复制 / 删除时同步变更，否则就会长期不一致。

一致性的责任在你的应用侧。石墨接口只保证"我这边的动作成功"，业务库的写入、回滚、补偿都由你的应用编排。

业务库写入与石墨 API 调用必须按一定顺序编排，下面两节会具体说明流程。

删除是"全量同步"，复制是"任务异步"，两个动作的失败处理逻辑也不一样。

二、复制文档

2.1 接口定义

POST /sdk/v2/collab-files/{fileId}/copy
Header: X-Shimo-Signature, X-Shimo-Token
Body:   { "fileId": "<新文件 ID>" }

Path 上的 fileId 是源文件 ID，Body 里的 fileId 是新文件 ID，两者不要弄反。

接口是异步任务：首次请求会创建任务并立即返回，状态查询靠"重复请求同一个新 fileId"来轮询。

新 fileId 由你的应用决定（长度不超过 64），同一个新 fileId 重复调用是安全的，落到同一个任务上。

响应的 HTTP / code 列表：

HTTP	`code`	含义	业务侧动作
200	—	首次创建任务成功	启动轮询
200	70019	副本创建中	继续轮询，建议指数退避
204	—	副本创建成功	解锁文件、回写业务状态
400	70016	任务信息找不到	视为失败，回滚业务记录
400	70017	副本任务执行失败	视为失败，回滚业务记录
500	70015	读取源文件出错	可重试 1-2 次后视为失败
500	70018	查询任务状态出错	可重试，避免无限轮询
500	70020	未知任务状态	视为失败、记日志

2.2 完整流程

要点：

业务库先建一条 copy_pending 记录，再调石墨。失败时业务库有明确的中间态可以查、可以补偿，比"成功才插库"更稳。

轮询用同一个新 fileId 反复 POST，不要因为多请求几次而误以为会创建多个副本 —— 接口是幂等的。

副本就绪前的新 fileId 不应该让用户能打开，前端应在业务库 status 为 ready 时才允许进入；否则用户会看到空文档或权限错误。

2.3 cURL 示例

2.4 与模板功能的关系

复制接口也是石墨文档模板功能的底层机制：把模板 fileId 作为源、业务实例 fileId 作为目标即可"套用模板"。需要复制后初始化权限、所有者、标题等，应当在 204 之后通过元信息回调改造，而不是塞到复制请求里。

三、删除文档

3.1 接口定义

DELETE /sdk/v2/api/files/{fileId}
Header: X-Shimo-Signature, X-Shimo-Token

详见官方接口文档。204 表示删除成功，无响应体。

删除是对石墨侧文档状态的硬约束，调用之后文档内容、协同会话都会失效。

调用前必须做业务侧权限校验。石墨接口本身不会校验"是不是文件所有者"这种业务规则。

删除后，下一次元信息回调应该返回不存在或 readable: false，以让前端编辑器直接拒绝加载（详见协同文档权限模型与回调实现）。

协同 SDK 在文档被删除时会主动断开当前在线协作者的 WebSocket 会话。

3.2 完整流程

注意：

顺序是"先业务校验 → 中间态落库 + 审计 → 调石墨 → 业务终态"。这样无论中间哪一步抖动，都有明确的状态可以补偿。

审计要在调用石墨之前写。如果调用石墨失败了再补审计，失败的删除请求就丢了痕迹。

3.3 cURL 示例

四、异常与回滚

4.1 复制失败

场景	业务侧处理
首次 POST 直接 4xx / 5xx（非任务相关错误码）	业务库直接改 `copy_failed`，不进入轮询
轮询过程中收到 70015 / 70016 / 70017 / 70020	业务库改 `copy_failed`，不要让新 `fileId` 暴露给用户
轮询超过最大次数仍是 70019	视超时阈值告警；可以选择"继续后台轮询 + 前端先提示用户稍后再来"
70015（源文件读取错误）	检查源文件是否被删除、或源文件 `fileId` 是否拼错

永远不要因为复制失败就去删除源文件 —— 异常情况下保留源文件是底线。

4.2 删除失败

场景	业务侧处理
石墨返回非 204	业务库保留 `deleting`，进入补偿队列，不要回滚到 `active`（避免删了一半又看起来正常）
重复点击删除	业务库 `deleting` / `deleted` 状态下直接幂等返回，不再二次调用石墨
用户已经在协同	调用成功后，石墨会断开其会话；前端编辑器抛错时业务侧记录这次状况即可

4.3 元信息回调与已删除文件

删除完成后，针对该 fileId 的文件元信息回调有两种合规返回：

HTTP 404：表示文件不存在；编辑器会直接拒绝加载。

HTTP 200 + permissions.readable: false：表示存在但无权访问；编辑器进入"无权"提示界面。

两种返回都可以，区别在于业务侧是否还保留"已删除"软删记录。如果保留就用 2，如果硬删则用 1。

五、常见误区

误区	实际影响	正确做法
Path `fileId`（源）与 Body `fileId`（目标）弄反	复制的是空文档，或撞库到已存在的目标	严格区分：Path 是源，Body 是目标
首次 POST 返回 200 后就当成功	实际是任务被接受、内容还没复制完	等到 204 才算成功
不轮询、直接告诉用户"成功"	用户立刻打开拿到空白文档	完成轮询、状态置 `ready` 再开放访问
调用石墨成功才写业务库	失败时业务侧没记录、无法补偿	业务侧先写 pending，再调石墨，最后落终态
删除时不做业务侧权限校验，依赖石墨	石墨不校验业务权限，任何人都能删	业务侧先校验 owner / manageable
删除失败时回滚业务库为 `active`	用户以为没删，但其实石墨那边已经删了	保留 `deleting`，进补偿队列
已删除文件的元信息回调仍返回 `readable: true`	用户能继续打开"幽灵文档"	返回 404 或 `readable: false`
不写删除审计，依赖事后查石墨日志	出问题时无法追溯责任人和时间	业务侧先写审计、再调石墨

一、整体架构#

二、复制文档#

2.1 接口定义#

2.2 完整流程#

2.3 cURL 示例#

2.4 与模板功能的关系#

三、删除文档#

3.1 接口定义#

3.2 完整流程#

3.3 cURL 示例#

四、异常与回滚#

4.1 复制失败#

4.2 删除失败#

4.3 元信息回调与已删除文件#

五、常见误区#