上传与失败恢复

上传意图、分片传输、后台确认、幂等重试、替换版本和超时处理——完整了解一次上传经历了什么。

一次上传的四个阶段

Core 创建 Upload Intent，先预留配额，返回 intent、objectKey 和 uploadGrant。
浏览器按 5 MiB（5 × 1024 × 1024 字节）分片，依次上传到 Storage。
浏览器提交分片数量，Storage 把合并和完成工作交给后台 Worker。
Worker 校验并回调 Core；Core 完成文件版本和配额记账。到这一步，可用版本才会出现在文件列表里。

进度条反映的是已传分片数，不是后台完成进度。页面最多轮询 20 次、每次间隔约 500 ms。超出这个观察窗口，页面只会提示"后台仍在处理"，并不能说明最终失败了。轮询只检查前 100 个文件且按文件名匹配，想严格验证的话还需要核对版本、大小和下载内容。

文件和授权限制

文件必须非空。文件名是去掉首尾空白后 1–255 个字符，不能包含斜线、反斜线或控制字符；MIME 类型也要是非空字符串。API 的 sizeBytes 是正十进制整数字符串，不是浮点数或带单位的文本。

Upload Intent 有效期是 15 分钟；uploadGrant 最长只有 300 秒，两者不是同一个期限。如果文件比较大、网速又慢，可能在意图到期之前就先碰到 grant 过期。当前浏览器没有透明的授权续期或跨刷新的断点续传保证。5 MiB 是每个分片的大小，不是整个文件的最大限制——实际能传多大，受可用配额、授权期限和部署边界共同约束。

接口顺序与重试

创建：POST /api/v1/upload-intents，带 Idempotency-Key；请求体包含 fileName、字符串 sizeBytes、mimeType 和可选的 parentId。分片：PUT /api/v1/storage/uploads/{objectKey}/parts/{partNumber}，partNumber 从 1 开始；Storage 请求用 uploadGrant，不用登录的 access token。完成：POST /api/v1/storage/uploads/{objectKey}/complete，JSON 为 {"parts": 分片总数}。

同一次逻辑请求重试时，保持幂等键和原始参数不变。把同一个键用在不同文件上会导致冲突；每次失败都生成新键则会造成重复预留。不要主动调用 /api/v1/internal/* 完成回调，那属于服务间的私有协议。

失败后先判断阶段

状态	下一步
创建意图就失败了	检查参数、登录状态和配额——这时还没有可传输的授权
分片失败且尚未提交完成	页面会尝试取消意图；取消本身失败会另外提示
完成已提交但页面没有出现文件	等一等、刷新，核对文件和版本，避免立即重复提交
409 冲突	检查同名文件、幂等键、目标文件和意图状态
413	声明大小或允许上传的字节边界不匹配，不要单纯无限重试
401	核对使用的是正确 grant 及其时效——重新登录不等于旧 grant 续期

POST /api/v1/upload-intents/{id}/cancel 可以取消仍有效的意图，成功返回 204；如果意图已经不可取消，可能返回 409。取消不是删除已完成文件。

替换已有文件

API POST /api/v1/files/{fileId}/upload-intents 可以为已有文件创建替换意图，之后仍然走同样的分片和完成流程。目前上传面板只有新文件上传，没有替换选择器。普通新上传的同名冲突不应被理解成自动覆盖。替换会保留逻辑文件并增加版本，配额影响见配额。