動作
Bugs #11493
進行中
[點位告警機制]規則與紀錄
概述
告警規則管理 (Alarm Rules)¶
告警規則初始由 CSV
ALARM欄位同步匯入，後續以 API 入 DB 為唯一來源，修改後立即生效不須重啟服務。
| Method | Uri | 說明 |
|---|---|---|
GET |
/api/v1/alarm-rules |
取得告警規則列表（支援 ?deviceId= 過濾） |
GET |
/api/v1/alarm-rules/{id} |
取得單一告警規則 |
POST |
/api/v1/alarm-rules |
新增告警規則 |
PUT |
/api/v1/alarm-rules/{id} |
修改告警規則 |
PATCH |
/api/v1/alarm-rules/{id}/toggle |
啟用/停用告警規則 |
DELETE |
/api/v1/alarm-rules/{id} |
刪除告警規則 |
// Response ✅ GET /api/v1/alarm-rules?deviceId=5
{
"code": 0, "message": "", "timestamp": 1740902400000,
"payload": [{
"id": 1, "deviceListId": 5, "deviceName": "電錶-01",
"alertId": "HighV", "alertName": "A相電壓高壓告警",
"functionId": "01_Vol_A", "operator": ">=", "threshold": 260.0,
"severity": "Warning",
"messageTemplate": "{DeviceName} A相電壓 {Value}V 超過門檻 {Threshold}V",
"isActive": true, "createdAt": "2026-03-02T00:00:00Z", "updatedAt": "2026-03-02T00:00:00Z"
}]
}
// Request: POST /api/v1/alarm-rules
{
"deviceListId": 5, "alertId": "HighV", "alertName": "A相電壓高壓告警",
"functionId": "01_Vol_A", "operator": ">=", "threshold": 260.0,
"severity": "Warning",
"messageTemplate": "{DeviceName} A相電壓 {Value}V 超過門檻 {Threshold}V",
"isActive": true
}
| 欄位 | 類型 | 說明 |
|---|---|---|
deviceListId |
整數 | 關聯設備 ID |
alertId |
字串 | 告警代碼，同一設備下不可重複（e.g., AR_HighV_1） Format: AR_{fun}_{no} |
functionId |
字串 | 觸發判斷的點位代碼。注意：若是 Modbus 設備，必須加上 群組_ 前綴（例如：01_Vol_A，對應 MQTT 上報之格式），不可僅填寫 Vol_A
|
operator |
字串 | 比較運算子：>=, <=, >, <, ==
|
threshold |
浮點數 | 告警門檻值 |
severity |
字串 | 告警等級：Warning / Critical
|
messageTemplate |
字串 | 訊息樣板，佔位符：{DeviceName}, {Value}, {Threshold}
|
isActive |
布林 | 是否啟用 |
💡 告警等級說明 (Severity)¶
系統目前提供兩種標準的告警等級，主要作為前端介面展示區分與管理員嚴重程度識別：
-
Warning(警告)：
表示設備數據偏離正常範圍，但尚未危及整體系統運作或造成損壞。通常用於預防性維護或早期發現異常趨勢。
情境範例：機房溫度略高於標準、電壓出現微幅波動。 -
Critical(嚴重)：
表示設備發生嚴重異常、狀態停機，或變數已達危險門檻，需要管理層或運維人員立即介入處理。
情境範例：設備斷電、機房溫度過高可能導致伺服器當機。
ℹ️ 系統行為關聯：
在當前的後端邏輯中，無論等級為Warning或Critical，一旦觸發告警，系統皆會：
- 將紀錄寫入
alarm_log(預設 Status = 0 未結案)。- 依照所屬系統 (EquipmentSystem) 在
system_config_mail的設定，自動派發 Email 或 LINE 訊息。- 目前尚未針對等級差異進行通知渠道的分流（例如：Warning 只發 Email、Critical 才發 LINE），這部分保留給後續業務邏輯或前端做彈性運用。
// PATCH /api/v1/alarm-rules/1/toggle
// Response ✅
{ "code": 0, "message": "告警規則已停用" }
關聯性資料表¶
| 資料表名稱 | 說明 |
|---|---|
| device_list | 設備清單 |
| device_alarm_rule | 告警規則 |
| alarm_log | 告警表 |
| system_config_mail | 通知群郵件紀錄 |
動作