Billing Dashboard API
v0.10.0+ 計費儀表板與配額交易端點（4-feature 模型）
端點總覽
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /api/v1/billing/monthly-quota | 查詢當月配額狀態（UserQuotaDto） |
| GET | /api/v1/billing/quota | 查詢配額限額與用量（Legacy） |
| GET | /api/v1/billing/summary | 查詢帳期用量摘要 |
| GET | /api/v1/billing/summary/by-device | 查詢各設備用量明細 |
| GET | /api/v1/billing/usage | 查詢用量事件歷史（分頁） |
| GET | /api/v1/billing/dashboard/trend | 用量趨勢圖 |
| GET | /api/v1/billing/dashboard/comparison | 同期對比 |
| GET | /api/v1/billing/dashboard/forecast | 用量預測 |
| GET | /api/v1/billing/transactions | 配額交易紀錄（Ledger） |
共用模型：4-feature
{
"analysisSeconds": 3600,
"alertCount": 150,
"attributeCount": 80,
"vlmTokens": 12000
}
| 欄位 | 說明 |
|---|---|
analysisSeconds | 分析處理秒數 |
alertCount | 告警觸發次數 |
attributeCount | 屬性偵測次數 |
vlmTokens | VLM token 使用量 |
重要規則
billingPeriod使用YYYY-MM，格式不符會回傳400。month粒度趨勢圖效能最佳（直接讀月表）。- 指定
deviceId的month粒度會使用設備層級配額表。
常用查詢
1) 當月配額狀態
GET /api/v1/billing/monthly-quota
回傳完整 UserQuotaDto，含分析秒數與 alert/attribute/vlm 餘額。
2) 帳期摘要
GET /api/v1/billing/summary?billingPeriod=2026-02
回傳當期 4-feature 用量與 usageByType 分佈。
3) 趨勢圖
GET /api/v1/billing/dashboard/trend?granularity=day&startDate=...&endDate=...
可搭配 deviceId 做單設備趨勢。
4) 配額交易明細
GET /api/v1/billing/transactions?page=1&limit=20
支援 featureType / type / source / 日期範圍篩選。
交易來源 (source)
| Source | 說明 |
|---|---|
system_initial | 新用戶初始配額 |
admin_manual | 管理員手動加值 |
admin_adjustment | 管理員覆寫調整 |
consumption | 正常消耗 |
usage_rollback | 失敗回沖 |
payment | 付款購買（預留） |