公開發佈與下載目錄

將檔案發佈到公開目錄的流程、slug 規則、狀態管理以及下載票據的運作方式。

公開意味著什麼

實例的 /download 是一個無需登入就能瀏覽的公開發佈目錄。只有同時擁有可用版本且處於 published 狀態的檔案才會出現在公開結果裡；一旦公開，訪客就能看到檔案名稱、類型、大小，並申請下載。發佈之前，請先確認你有權分發這個檔案，並確認內容適合公開。

上傳成功不會自動發佈，建立分享也不等於進入公開目錄——兩者是各自獨立的控制。如果目錄頁面出現請求失敗的提示，那是錯誤，不能解讀成「沒有任何發佈的檔案」。

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

管理員打開 /admin/publish，從列表中選擇一個有可用當前版本的自有檔案；必要時點「載入更多」。
填寫「公開標識」slug：只接受小寫字母、數字和連字號，長度 1–64，開頭和結尾必須是字母或數字。
明確選擇「立即公開」或「保存為草稿」。頁面預設選中的是立即公開，提交前請確認一下。
點「保存發佈狀態」，核對回傳結果裡的標識和狀態。
如果選了公開，建議在未登入的瀏覽器打開 /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 會立即作廢。更精確的版本與下載語義，請參考檔案與版本。