新增規則範例¶

POST {{baseUrl}}/api/v1/alarm-rules

模組斷線告警¶

{
  "deviceListId": 52,
  "alertId": "Online",
  "alertName": "14F燈控模組斷線告警",
  "functionId": "Online",
  "operator": "==",
  "threshold": 0,
  "severity": "Critical",
  "messageTemplate": "{DeviceName} 發生斷線異常 (狀態值: {Value})",
  "isActive": true
}

點位超出定義範圍告警¶

{
  "deviceListId": 1,
  "alertId": "HighV_2",
  "alertName": "A相電壓高壓告警",
  "functionId": "Vol_A",
  "operator": ">=",
  "threshold": 130,
  "severity": "Warning",
  "messageTemplate": "{DeviceName} A相電壓 {Value}V 超過門檻 {Threshold}V",
  "isActive": true
}

SMTP 設置說明¶

寄件參數設置於 appsettings.json

{
  "AppSettings":{
      "EmailSettings": {
          "SmtpHost": "smtp.gmail.com",
          "SmtpPort": 587,
          "SmtpUser": "sam8gamma@gmail.com",
          "SmtpPass": "xxxxxxxxx",
          "FromAddress": "sam8gamma@gmail.com",
          "FromName": "IoTServer 系統"
    }
   }
}

以gmail 為例，"SmtpPass" 取得參考如下:

1. App Password 只有在開啟「兩步驟驗證」後才會出現。
   https://myaccount.google.com/security
2. 進入 App Passwords，建立應用程式，並取得16 位密碼
   https://myaccount.google.com/apppasswords

告警紀錄API¶

提供告警紀錄查詢、Excel 匯出及人工結案功能。
人工結案後系統將透過 MQTT client/alarm 廣播 alarm.changed 通知。

◉ 取得告警紀錄列表 [GET]¶

:::info
GET /api/v1/alarm-logs支援多條件篩選與分頁，預設以最新時間排序
:::

Query 參數

:::spoiler Response ✅ 成功 (200 OK)

{
  "code": 0,
  "message": "Success",
  "timestamp": 1741248000000,
  "payload": {
    "items": [
      {
        "id": 1,
        "alarmId": "ALM-2026-0001",
        "deviceName": "E1401 電錶",
        "floor": "1F",
        "space": "機房A",
        "messageTemplate": "A相電壓 132.1V 超過門檻 120V",
        "status": 0,
        "triggerTime": "2026-03-06T13:49:02+08:00",
        "closeTime": null
      }
    ],
    "page": 1,
    "pageSize": 10,
    "totalRecords": 25,
    "totalPages": 3
  }
}

:::

◉ 匯出告警紀錄為 Excel [GET]¶

:::info
GET /api/v1/alarm-logs/export依據當前查詢條件將結果匯出成 .xlsx 檔案
:::

Query 參數與取得列表相同（page/pageSize 無效，匯出全部符合條件的紀錄）。

Response: Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，瀏覽器直接下載 AlarmLogs_Export_yyyyMMddHHmmss.xlsx。

◉ 人工關閉告警 [PATCH]¶

:::info
PATCH /api/v1/alarm-logs/{alarmId}/close將指定告警標記為已完成，並透過 MQTT 廣播 alarm.changed 通知
:::

路由參數

此端點無 Request Body。操作成功後，系統自動：

1. 將 status 設為 1，記錄 closeTime
2. 查詢當前 pendingCount（未結案告警數量）
3. 發布 MQTT 通知至 client/{OmniID}（與設備狀態異動機制一致）

:::spoiler MQTT 通知範例 (alarm.changed)

{
  "system": "Omni_BC241195477F",
  "timestamp": 1772787333837,
  "cmd": "alarm.changed",
  "payload": {
    "alarmId": "ALM-2026-0001",
    "deviceName": "E1401 電錶",
    "message": "A相電壓 132.1V 超過門檻 120V",
    "status": 1,
    "triggerTime": "2026-03-06T13:49:02+08:00",
    "closeTime": "2026-03-06T17:05:00+08:00",
    "pendingCount": 4
  }
}

:::

:::spoiler Response ✅ 成功 (200 OK)

{
  "code": 0,
  "message": "告警已成功結案，MQTT 通知已廣播。",
  "timestamp": 1741248300000,
  "payload": null
}

:::

:::spoiler Response ❌ 紀錄不存在或已結案

{
  "code": 404,
  "message": "AlarmId 'ALM-2026-0001' 不存在或已結案。",
  "timestamp": 1741248300000,
  "payload": null
}

:::

◉ 告警狀態異動通知 (alarm.changed)¶

當 alarm_log 產生或狀態變更（結案）時，系統主動廣播通知。前端訂閱 client/{OmniID} 即可接收所有告警異動事件。

觸發場景：

1. 告警規則評估後新產生告警（status: 0）
2. 告警條件解除，自動關閉（status: 1）
3. 透過 API PATCH /api/v1/alarm-logs/{alarmId}/close 人工結案（status: 1）

:::spoiler Event Message Example (alarm.changed)

{
  "system": "Omni_BC241195477F",
  "timestamp": 1772787333837,
  "cmd": "alarm.changed",
  "payload": {
    "alarmId": "ALM-2026-0001",
    "deviceName": "E1401 電錶",
    "message": "A相電壓 132.1V 超過門檻 120V",
    "status": 0,
    "triggerTime": "2026-03-06T13:49:02+08:00",
    "closeTime": null,
    "pendingCount": 5
  }
}

Payload 欄位說明: