告警 API
告警規則用於在分析指標超過閾值時觸發通知。
端點概覽
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /api/v1/alerts/metrics/queue_analysis | 取得排隊分析可用指標 |
| GET | /api/v1/alerts/metrics/queue_analysis/grouped | 取得分組後的可用指標 |
| POST | /api/v1/alerts/rules | 建立告警規則 |
| GET | /api/v1/alerts/rules | 查詢規則列表 |
| GET | /api/v1/alerts/rules/{id} | 取得單一規則 |
| PATCH | /api/v1/alerts/rules/{id} | 更新規則 |
| DELETE | /api/v1/alerts/rules/{id} | 刪除規則 |
| GET | /api/v1/analysis/alerts | 查詢告警觸發記錄 |
| GET | /api/v1/analysis/alerts/stats | 取得告警統計 |
| GET | /api/v1/analysis/alerts/{id} | 取得單一告警詳情 |
| DELETE | /api/v1/analysis/alerts/{id} | 刪除單一告警記錄（軟刪除） |
使用場景
- 閾值告警：排隊人數超標、等待時間過長
- 運營監控：服務效率下降、放棄率升高
取得可用指標
GET /api/v1/alerts/metrics/queue_analysis
回傳所有可用於告警條件的指標路徑。詳見指標路徑列表。
GET /api/v1/alerts/metrics/queue_analysis/grouped
回傳按分類分組後的指標（current / rolling / total）。
建立告警規則
POST /api/v1/alerts/rules
請求參數
| 參數 | 型別 | 必填 | 範圍/限制 | 說明 |
|---|---|---|---|---|
name | String | ✅ | 1-100 字元 | 規則名稱 |
description | String | ❌ | 最大 500 字元 | 規則描述 |
sceneId | String (UUID) | ✅ | - | 關聯的場景 ID |
severity | String (enum) | ✅ | warning / critical | 嚴重程度 |
conditions | Object[] | ✅ | - | 觸發條件陣列 |
logicOperator | String (enum) | ❌ | AND / OR | 條件組合邏輯，預設 OR |
cooldownMinutes | Number | ❌ | 1-1440 | 冷卻時間（分鐘），預設 5 |
Conditions 結構
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
metricPath | String | ✅ | 指標路徑（從 /metrics 取得） |
operator | String (enum) | ✅ | 運算符 |
threshold | Number | ✅ | 閾值 |
運算符
| 值 | 說明 |
|---|---|
GT | 大於 > |
GTE | 大於等於 >= |
LT | 小於 < |
LTE | 小於等於 <= |
EQ | 等於 == |
NEQ | 不等於 != |
請求範例（排隊人數過多警報）
{
"name": "排隊人數過多警報",
"description": "當等候人數超過 10 人時發出警報",
"sceneId": "scene-uuid",
"severity": "warning",
"conditions": [
{
"metricPath": "current.inQueue",
"operator": "GT",
"threshold": 10
}
],
"cooldownMinutes": 5
}
請求範例（等待時間過長警報）
{
"name": "等待時間過長警報",
"sceneId": "scene-uuid",
"severity": "critical",
"conditions": [
{
"metricPath": "rolling5Min.completed.waitTimeAvgSeconds",
"operator": "GT",
"threshold": 300
}
],
"cooldownMinutes": 10
}
請求範例（放棄率過高警報）
{
"name": "放棄率過高警報",
"sceneId": "scene-uuid",
"severity": "warning",
"conditions": [
{
"metricPath": "rolling5Min.abandonRate",
"operator": "GT",
"threshold": 0.2
}
],
"cooldownMinutes": 15
}
更新告警規則
PATCH /api/v1/alerts/rules/{id}
所有建立時的欄位皆可更新，另可更新 status (enabled / disabled)。
刪除告警規則
DELETE /api/v1/alerts/rules/{id}
回應: 204 No Content
⚠️ 刪除為軟刪除（保留審計記錄），僅能刪除自己帳號下的告警規則。
查詢告警觸發記錄
GET /api/v1/analysis/alerts
Query 參數
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
page | Number | ❌ | 頁碼（預設 1） |
limit | Number | ❌ | 每頁數量（預設 20） |
sceneId | String (UUID) | ❌ | 場景 ID 篩選 |
deviceId | String (UUID) | ❌ | 設備 ID 篩選 |
ruleId | String (UUID) | ❌ | 規則 ID 篩選 |
severity | String (enum) | ❌ | warning / critical |
metricPath | String | ❌ | 指標路徑篩選 |
startDate | String (ISO 8601) | ❌ | 開始時間 |
endDate | String (ISO 8601) | ❌ | 結束時間 |
響應範例
{
"success": true,
"statusCode": 200,
"message": "Analysis alerts retrieved successfully",
"data": [
{
"id": "alert-uuid",
"severity": "critical",
"triggeredAt": "2026-01-29T10:30:00Z",
"metricPath": "current.inQueue",
"operator": "GT",
"threshold": 10,
"actualValue": 15,
"message": "Queue length exceeded threshold: 15 > 10",
"snapshotUrls": [
"https://storage.example.com/snapshots/alert-123-1.jpg"
],
"ruleId": "rule-uuid",
"sceneId": "scene-uuid",
"deviceId": "device-uuid",
"userId": "user-uuid",
"computeNodeId": "node-uuid",
"createdAt": "2026-01-29T10:30:01Z",
"rule": { "id": "rule-uuid", "name": "排隊人數過多警報" },
"scene": { "id": "scene-uuid", "name": "主入口排隊區" },
"device": { "id": "device-uuid", "name": "入口攝影機" }
}
],
"meta": {
"timestamp": "2026-01-29T12:00:00.000Z",
"requestId": "req-uuid",
"pagination": {
"limit": 20,
"currentPage": 1,
"totalRecords": 150,
"totalPages": 8,
"nextPage": 2,
"previousPage": null
}
}
}
取得告警統計
GET /api/v1/analysis/alerts/stats
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
startDate | String (ISO 8601) | ❌ | 統計開始時間 |
endDate | String (ISO 8601) | ❌ | 統計結束時間 |
回傳 total、bySeverity、topScenes、topRules、hourlyDistribution。
刪除告警事件
DELETE /api/v1/analysis/alerts/{id}
- 刪除方式：軟刪除
- 回應：
204 No Content