model-platform/contracts/locks/file-edit-lock-v1.md

文件编辑锁契约 v1

公共接口

POST   /api/v1/files/{storage_object_id}/lock
POST   /api/v1/file-locks/{edit_session_id}/heartbeat
DELETE /api/v1/file-locks/{edit_session_id}

三个接口均要求 X-User-ID 和 X-Workspace-ID。加锁成功返回一次性原始 lock_token；心跳和释放请求体均为：

{"lock_token": "raw-token-returned-by-acquire"}

原始 token 只由客户端持有，数据库只保存 SHA-256 摘要。

MySQL 租约

edit_sessions 是实时锁权威：

• session_status=active 且 expires_at > now() 表示锁有效；
• 同一 storage_object_id 同时只能存在一个有效编辑会话；
• 心跳更新 last_heartbeat_at 与 expires_at；
• 主动释放将状态改为 closed；
• 后台清理将超时租约改为 expired。

加锁、心跳和释放都在数据库事务中校验 edit_session_id + lock_token_hash。 部署时 Runtime 保持单副本；若扩展到多副本，应为加锁查询增加数据库行锁或唯一 租约表约束。

状态与错误

• 冲突返回 HTTP 409、错误码 FILE_LOCK_CONFLICT，并包含当前编辑者和租约到期时间；
• 错误 token 返回 HTTP 403，且不得续期或释放现有锁；
• 浏览器建议每 15 秒心跳，默认租约为 45 秒。