公開發佈與下載目錄

公開意味著什麼

實例的 /download 是無需登入的發佈目錄。只有可用檔案的 published 記錄進入公開結果；公開後訪問者能看到檔案名、類型、大小並申請下載。先確認你有權分發檔案，並確認檔案內容適合公開。

上傳成功不會自動發佈。創建分享也不等於進入公開目錄；兩者是獨立控制。目錄請求失敗會顯示錯誤，不能把錯誤當成“沒有發佈檔案”。

通過管理員頁面發佈自己的檔案

1. 管理員打開 /admin/publish，從列表選擇有可用當前版本的自己的檔案；必要時“加載更多”。
2. 填寫“公開標識”slug，只用小寫字母、數字和中划線，長度 1–64，首尾必須是字母或數字。
3. 明確選擇“立即公開”或“保存為草稿”。頁面默認選擇立即公開，提交前要檢查。
4. 點擊“保存發佈狀態”，核對結果中的標識和狀態。
5. 若選擇公開，在未登入瀏覽器打開 /download 並實際下載核對內容；保存草稿時不應出現在公開目錄。

頁面位於管理區域，但底層 PUT /api/v1/files/{fileId}/publication 校驗檔案所有權；管理員權限不表示可以用此接口直接發佈別人的檔案。普通所有者可通過已認證 API 管理自己的發佈，當前沒有對應普通使用者頁面。

API 狀態和衝突

請求體為 {"slug":"release-notes","status":"draft"}，status 支持 draft、published、disabled。每個檔案通過同一路徑創建或更新發佈；slug 衝突返回 409。更換 slug 會改變按標識申請票據的入口，應檢查已有分發方式。

disabled 可通過 API 下架，當前頁面選擇器只提供公開和草稿，沒有 disabled 選項。不要把“沒有下架按鈕”解釋成 API 不支持，也不要承諾已發出去的檔案副本能收回。

目錄和下載限制

GET /api/v1/publications 默認 50 條、最大 100 條，並返回 nextCursor。當前 /download 頁面只讀取第一批，沒有繼續分頁或搜索篩選控件；超過首批的發佈未顯示不代表記錄不存在。

點擊下載時調用 POST /api/v1/publications/{slug}/download-ticket，再以 grant 請求 Storage。票據 60 秒有效、單次消費；原始對象地址不是永久外鏈。draft、disabled 或不可用發佈的票據請求返回 404。

發佈跟隨檔案當前版本，既有票據鎖定簽發時的版本。狀態變更阻止新的不合規票據，不保證立即作廢已簽發的短期 grant。更精確的版本和下載語義見檔案與版本。