上傳與失敗恢復

一次上傳的四個階段、分片與授權期限、冪等重試原則，以及替換版本的做法。

一次上傳的四個階段

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 可以為已有檔案建立替換意圖；之後仍走同樣的分片和完成流程。目前上傳面板只支援新檔案上傳，沒有替換選擇器。普通新上傳遇到同名衝突時也不會自動覆蓋。替換會保留邏輯檔案並增加一個版本，配額方面的影響請參考配額。