附錄：最小資料結構（Manifest／分塊／狀態）
本附錄針對「平行分塊 + 可續傳 + 冪等重試」提供最小資料結構建議。 目標是在不需要複雜交易的前提下，實現高吞吐量的並行處理，以及失敗後的可靠復原。
一般原則
- 大型物件與小型狀態：分塊／manifest 是儲存於物件儲存的大型物件；狀態則很小，儲存於狀態儲存。
- 唯一鍵與冪等性：分塊 MUST 能以 (transferId, fileId, chunkIndex) 唯一定址，以支援冪等的重傳。
- 可復原性：狀態 MUST 表達「已完成的集合」，讓復原時可以跳過已完成的部分。
- 不洩漏敏感資訊：物件鍵與狀態 SHOULD 避免嵌入電子郵件或原始檔名等敏感欄位（這些是否加密取決於您的隱私政策）。
A.1 Manifest 的最小欄位
Manifest 是接收端下載與重組的「單一入口」。最小建議如下：
- manifestVersion：MUST。用於相容性升級（例如
1）。 - transferId：MUST。唯一的傳輸工作階段識別碼。
- createdAt / expiresAt：SHOULD。用於生命週期處理與介面提示。
- policy：SHOULD。政策摘要（下載次數限制、是否需要密碼、是否允許在上傳完成前分享等）。
- files[]：MUST。檔案清單說明（至少包含檔案大小與分塊範圍）。
- chunking：MUST。包含 chunkSize 以及 chunkCount 的計算方式，或每個檔案的 chunkCount。
- objectKeyRule：MUST。由 (transferId, fileId, chunkIndex) 推導物件鍵，或提供明確的對應表。
A.1.1 files[] 的最小欄位
- fileId：MUST。唯一的檔案識別碼（不要以檔名作為唯一鍵）。
- size：MUST。以位元組為單位的大小。
- mime：MAY。用於顯示與下載建議。
- name：MAY。若要做到嚴格的零知識／最小洩漏，請省略
name，或儲存加密後的名稱。 - chunkCount：MUST。此檔案的分塊數量。
- chunkOffset：MAY。若多個檔案共用全域的
chunkIndex，則需要偏移量；否則可以省略。
A.1.2 完整性與驗證欄位（選用但建議）
- chunkHashes[]：SHOULD。逐塊驗證（雜湊／長度／etag 之一或組合）。
- fileHash：MAY。整個檔案的校驗碼（下載後驗證）。
- ciphertextLength：MAY。密文層級的長度一致性檢查（不需要明文）。
A.2 分塊物件：最小限制
- 唯一定址：分塊 MUST 能以 (transferId, fileId, chunkIndex) 唯一定址。
- 冪等上傳：重複上傳同一個分塊 MUST NOT 破壞最終狀態（可以覆寫或被拒絕，但行為必須一致）。
- 最少中繼資料：伺服器 MAY 僅記錄密文長度、寫入時間、etag／版本等，以利觀測與疑難排解。
A.2.1 物件鍵規則（範例）
/transfers/{transferId}/chunks/{fileId}/{chunkIndex}/transfers/{transferId}/manifest
限制：物件鍵 MUST 支援依 transferId 前綴進行批次清理；物件鍵 SHOULD 避免攜帶敏感的業務資訊。
A.3 狀態記錄：最小欄位
狀態用來回答「上傳／下載進度與復原」。它應該很小，且讀寫快速。
- transferId：MUST。
- status：MUST。建議值：
UPLOADING/READY/DELETED/EXPIRED。 - uploadedSet：MUST。已完成的分塊集合；SHOULD 以位元圖（bitmap）／範圍集合壓縮。
- uploadedBytes：SHOULD。用於進度顯示與配額檢查（可由分塊推算，但另行維護速度更快）。
- downloadCount：MAY。若要強制執行下載次數限制，就必須記錄並以原子方式更新（細節取決於您的儲存方式）。
- expiresAt：SHOULD。用於到期的強制執行與背景清理。
A.3.1 復原 API 的最小輸出
對於可續傳的傳輸，伺服器 SHOULD 能回傳：
- 傳輸狀態（UPLOADING/READY/DELETED/EXPIRED）
- uploadedSet（已完成的分塊集合）
- 政策摘要（例如：超出配額、已過期、是否允許繼續上傳）
注意：與安全與隱私白皮書的分界
- 本附錄只描述傳輸／儲存所需的「結構與限制」。
- 關於加密欄位、金鑰材料如何攜帶／推導，以及驗證失敗時失敗即關閉的行為，請參閱安全與隱私白皮書。