數據查詢 API

查詢分析結果與統計數據。

📐 數據模型說明： Kafka scene-analysis-results 訊息同時攜帶 current + rolling5Min + rolling30Min + total 數據。Core API Consumer 收到後拆分寫入兩張表：

• current → scene_analytics_snapshots 表（Snapshots API 查詢）
• rolling5Min / rolling30Min / total → scene_analytics_rolling 表（Rolling API 查詢）

端點概覽

使用場景

• 歷史查詢：查詢特定時間範圍的快照記錄
• 趨勢分析：使用滾動統計觀察趨勢（5 / 30 分鐘等視窗）
• 即時監控：取得最新快照與滾動統計
• 報表產出：取得場景綜合指標進行分析

查詢快照歷史

GET /api/v1/analytics/snapshots

Query 參數

響應範例

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "id": "snapshot-uuid",
      "sceneId": "scene-uuid",
      "deviceId": "device-uuid",
      "sceneType": "queue_analysis",
      "windowStart": "2026-01-29T10:00:00Z",
      "windowEnd": "2026-01-29T10:00:00Z",
      "durationSeconds": 0,
      "currentMetrics": {
        "inQueue": 8,
        "inService": 2
      },
      "computeNodeId": "compute-node-uuid",
      "createdAt": "2026-01-29T10:00:00Z"
    }
  ],
  "meta": {
    "pagination": { "page": 1, "limit": 20, "total": 480, "totalPages": 24 }
  }
}

取得最新快照

GET /api/v1/analytics/snapshots/latest

取得場景最近 N 筆快照。

Query 參數

查詢滾動統計歷史

GET /api/v1/analytics/rolling

Query 參數

取得最新滾動統計

GET /api/v1/analytics/rolling/latest

取得各視窗類型的最新一筆滾動統計。

Query 參數

響應範例

{
  "success": true,
  "data": {
    "5min": { "...完成/放棄統計..." },
    "15min": { "...完成/放棄統計..." },
    "30min": { "...完成/放棄統計..." },
    "60min": { "...完成/放棄統計..." },
    "total": { "...完成/放棄統計..." }
  }
}

取得場景綜合最新指標

GET /api/v1/analytics/scenes/{id}/latest

取得場景的完整最新指標，包含快照和滾動統計。

Query 參數

響應範例

{
  "success": true,
  "data": {
    "sceneId": "scene-uuid",
    "snapshots": [
      {
        "id": "snapshot-uuid",
        "currentMetrics": { "inQueue": 8, "inService": 2 },
        "createdAt": "2026-01-29T10:00:00Z"
      }
    ],
    "rolling": {
      "5min": { "..." },
      "15min": { "..." },
      "30min": { "..." },
      "60min": { "..." },
      "total": { "..." }
    },
    "lastUpdatedAt": "2026-01-29T10:00:05Z"
  }
}

Analysis Insights（v0.8.0+）

洞察 API 用於查詢告警關聯的 VLM 分析與結構化輸出。

• 列表：GET /api/v1/analysis/insights
• 詳情：GET /api/v1/analysis/insights/{id}
• snapshots：GET /api/v1/analysis/insights/{id}/snapshots
• attributes：GET /api/v1/analysis/insights/{id}/attributes（LEVEL_02）
• stats：GET /api/v1/analysis/insights/attributes/stats（LEVEL_02）
• vlm summaries：GET /api/v1/analysis/insights/vlm-summaries

重點欄位

• vlmSummary：文字摘要（向後相容）
• vlmStructuredResult：結構化 JSON（v0.9.0+）
• snapshotUrls：時序抽樣結果（v0.10.0+）

Analysis Attributes（v0.10.0+）

屬性記錄 API 已與 Insights 解耦，提供獨立查詢。

• GET /api/v1/analysis/attributes
• GET /api/v1/analysis/attributes/{id}

權限與限制

• scope：analytics:read
• Plan Gate：僅 LEVEL_02 設備可用
• LEVEL_01 設備呼叫會回 403