永彰 - 智慧辦公室專案

Bugs #11493

由 Sam Wang 於 14 天 前更新

# 告警規則管理 (Alarm Rules) 

 > 告警規則初始由 CSV `ALARM` 欄位同步匯入，後續以 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}`|刪除告警規則| 

 ```json 
 // 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" 
   }] 
 } 
 ``` 

 ```json 
 // 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., HighV） | 
 | `functionId` | 字串 | 觸發判斷的點位代碼。**注意**：若是 Modbus 設備，必須加上 `群組_` 前綴（例如：`01_Vol_A`，對應 MQTT 上報之格式），不可僅填寫 `Vol_A` | 
 | `operator` | 字串 | 比較運算子：`>=`, `<=`, `>`, `<`, `==` | 
 | `threshold` | 浮點數 | 告警門檻值 | 
 | `severity` | 字串 | 告警等級：`Warning` / `Critical` | 
 | `messageTemplate` | 字串 | 訊息樣板，佔位符：`{DeviceName}`, `{Value}`, `{Threshold}` | 
 | `isActive` | 布林 | 是否啟用 | 

 ### 💡 告警等級說明 (Severity) 

 系統目前提供兩種標準的告警等級，主要作為**前端介面展示區分**與**管理員嚴重程度識別**： 

 - **`Warning` (警告)**： 
   表示設備數據偏離正常範圍，但尚未危及整體系統運作或造成損壞。通常用於預防性維護或早期發現異常趨勢。 
   *情境範例：機房溫度略高於標準、電壓出現微幅波動。* 

 - **`Critical` (嚴重)**： 
   表示設備發生嚴重異常、狀態停機，或變數已達危險門檻，需要管理層或運維人員**立即介入處理**。 
   *情境範例：設備斷電、機房溫度過高可能導致伺服器當機。* 

 > ℹ️ **系統行為關聯**： 
 > 在當前的後端邏輯中，無論等級為 `Warning` 或 `Critical`，一旦觸發告警，系統皆會： 
 > 1. 將紀錄寫入 `alarm_log` (預設 Status = 0 未結案)。 
 > 2. 依照所屬系統 (EquipmentSystem) 在 `system_config_mail` 的設定，自動派發 Email 或 LINE 訊息。 
 > 3. 目前**尚未**針對等級差異進行通知渠道的分流（例如：Warning 只發 Email、Critical 才發 LINE），這部分保留給後續業務邏輯或前端做彈性運用。 

 ```json 
 // PATCH /api/v1/alarm-rules/1/toggle 
 // Response ✅ 
 { "code": 0, "message": "告警規則已停用" } 
 ``` 

 ### 關聯性資料表 
 |資料表名稱|說明| 
 |---|---| 
 |device_list|設備清單| 
 |device_alarm_rule|告警規則| 
 |alarm_log|告警表| 
 |system_config_mail|通知群郵件紀錄|

返回