檔案分享

建立、查詢和撤銷分享連結，理解口令、過期、次數限制以及一次性下載票據的運作方式。

分享與公開發佈不同

分享使用一組隨機 token，可以設置口令、過期時間和下載次數。目前應用沒有專屬的分享接收頁面；接收者需透過維運者提供的 API 用戶端來交換 token，不能自行拼出 /s/ 連結。token 不應進入公開索引。沒有設口令的分享連結本身就等同於存取憑據；即使設了口令，也不代表檔案內容有端對端加密。

目前個人中心沒有分享建立與管理的面板。以下管理操作需要檔案所有者使用已認證的 API 來進行；接收端同樣需要 API 用戶端。如果你想讓檔案出現在匿名可見的公開目錄中，請參考公開發佈。

創建與保存

POST /api/v1/files/{fileId}/shares，請求本體可以是 {}，或包含以下欄位：

字段	規則
`password`	非空字串，UTF-8 最多 1024 位元組；不設置則無需口令
`expiresAt`	未來的標準 UTC ISO 時間，格式為 `YYYY-MM-DDTHH:mm:ss.sssZ`
`maxDownloads`	1 到 2147483647 的整數；省略表示不設此項上限

成功回傳 201。建立時回傳的原始 token 只會出現這一次，伺服器存的是它的摘要；之後查詢分享列表不會幫你找回原始 token。請妥善保存建立結果，只發給預定的接收者，不要記錄在公開日誌裡。

GET /api/v1/files/{fileId}/shares 可以查看該檔案的分享記錄；用回傳記錄中的 shareId 呼叫 POST /api/v1/shares/{shareId}/revoke 即可撤銷，成功回傳 204。shareId 和接收端使用的 token 是不同的值。

接收與次數消耗

接收者使用維運者提供的用戶端，按需要輸入口令並申請下載。用戶端呼叫 POST /api/v1/shares/{token}/download-ticket；需要口令時請求本體須包含 password。票據簽發的瞬間，該分享的 downloadCount 就會加一。

因此 maxDownloads 限制的是成功簽發下載票據的次數，而不是完整下載到本地的次數。即使後來連線中斷，那一次也可能已經算進去了。請不要透過預先存取或自動重試票據請求的方式來探測分享是否還可用。

拿到的 downloadGrant 有效 60 秒且只能消費一次；用它去請求回傳的 objectKey 對應的物件即可。分享在簽發票據時會採用當時的當前版本，不能把長期分享視為綁定某個歷史版本的固定連結。

失效和撤銷後的邊界

口令錯誤、已過期、次數耗盡、已撤銷或檔案不可用，這些情況通常都統一回傳 404 share unavailable——這是刻意不透露具體原因的設計。接收者遇到 404 時應聯繫發送者確認，不要因此斷定檔案已經被刪除。

撤銷會阻止後續票據的簽發，但不保證能撤回已經簽發且仍在有效期內的 grant，也無法刪除別人已經保存的副本。如果需要變更限制或原始 token 遺失，由所有者重新建立一個合適的分享，並撤銷舊記錄即可。