儀錶盤與指標

兩類資料分開讀

/admin/overview 把業務分析和系統健康放在一起展示。對應的 API 分別是 /api/v1/admin/dashboard/business 和 /api/v1/admin/dashboard/system。兩者都是管理員專用的介面；儀錶盤是讀模型，並不是身份、檔案、配額或物件狀態的最終寫入權威。

業務事件經 Analytics Worker 投影到讀模型，所以資料可能有延遲。重新整理圖表不代表後台事件已經全部處理完，也不應該從暫時缺少的曲線就推斷業務資料已經遺失。

時間範圍

range 支援 today、7d 和 30d，以 Asia/Shanghai 日曆日期為基準，結束時間是回應生成的當下。today 從當地午夜起算，7d 涵蓋今天和之前 6 個日曆日，30d 涵蓋今天和之前 29 個日曆日。

這些範圍不是固定向前滾動的 24、168、720 小時窗口。比較兩次回應時，請同時確認實際的起止時刻、時區和資料涵蓋範圍，不要只看按鈕上的文字。

下載次數的兩個口徑

Successful Download 只有在 Storage 完成完整物件位元組回應之後才會計入。單純申請或消費 Download Ticket 並不算一次完整成功下載。

而分享記錄的 downloadCount 是在成功簽發分享票據時就增加的。因此可能出現分享次數限制已經減一、但儀錶盤的成功下載仍為零的情況——這通常意味著下載尚未完成，兩個數字並不矛盾。詳情請見分享。

空間和健康口徑

Committed Storage Bytes 是 Core 完成版本確認後計入配額的位元組數。Physical Object Bytes 是存儲層物件的實際佔用，其中可能包含歷史版本和暫時未協調完成的物件；兩個指標不一定隨時相等。

System Health 使用 available、partial、unavailable 來描述各資料來源的可用性。只有部分來源能回應時，某些欄位會保留 null。沒有 Prometheus 資料不等於 CPU 為零、服務正常或故障已經修復。

Freshness 與 Coverage

Freshness 描述的是最近處理的事實以及延遲狀況；Coverage 描述的是從何時開始有可靠觀測以及中間有無缺口。資料很新不一定歷史涵蓋完整，涵蓋範圍很長也可能當下處理有延遲。業務指標為 null 或涵蓋不完整時，應保持「未知」狀態，不要填零來湊齊圖表。

遇到空白或延遲

先區分是 401/403 權限錯誤、503 服務錯誤，還是成功回應中的 partial/null。接著由運營者去檢查 analytics-worker、資料庫、Prometheus 和 Core 的相關狀態。報告時提供選擇的 range、時間、可用性和脫敏後的錯誤就夠了；不要單憑儀錶盤的數字就去修改檔案或配額事實。