上传与失败恢复

一次上传的四个阶段

1. Core 创建 Upload Intent，先预留配额，返回 intent、objectKey 和 uploadGrant。
2. 浏览器按 5 MiB（5 × 1024 × 1024 字节）分片，依次上传到 Storage。
3. 浏览器提交分片数量，Storage 将合并和完成工作交给后台 Worker。
4. 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 为已有文件创建替换意图；之后仍走同样的分片和完成流程。当前上传面板只有新文件上传，没有替换选择器。普通新上传的同名冲突不应被理解成自动覆盖。替换保留逻辑文件并增加版本，其配额影响见配额。