上傳與失敗恢復

一次上傳的四個階段

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 為已有檔案創建替換意圖；之後仍走同樣的分片和完成流程。當前上傳面板只有新檔案上傳，沒有替換選擇器。普通新上傳的同名衝突不應被理解成自動覆蓋。替換保留邏輯檔案並增加版本，其配額影響見配額。