知識管理系統

本頁是唯讀的，您可以看到原始碼，但不能更動它。您如果覺得它不應被鎖上，請詢問管理員。
====== EMS API ======

===== 文件概述 =====

==== 需求說明 ====
  - 客戶希望能夠讀取設備資料後，進行邊緣運算之後，提供結果給我方呈現在 EMS 畫面上
  - 我方提供 API 服務供對方進行呼叫
  - 參考文件：[[https://hackmd.io/@bclin087/Hk6eKCsRJl]]

===== 系統流程 =====

==== 串接流程圖 ====
{{public:fronteco:api.diagram.png}}

===== 串接環境與部署資訊 =====

==== API 端點資訊 ====
^ 項目             ^ 資訊                                   ^
| 正式 API 網址    | https://ems.yo-win.com:81/api/v1       |
| 測試 API 網址    | https://emst.yo-win.com:81/api/v1      |
| API Key（範例）  | ''RnJpIE5vdiAwMyAyMDIzIDE1OjIwOjMwG''  |

==== API 功能總覽 ====
^ 動作              ^ 方法                         ^ 路徑                            ^ 說明                                                    ^
| 取得裝置列表      | <color #b5e61d>GET</color>   | ''/devices''             | 使用複數命名，代表裝置資源集合                          |
| 取得有效電能的裝置資料  | <color #b5e61d>GET</color>   | ''/devices/kwh''  | 取得特定裝置（依據 deviceId）之詳細資料                 |
| 取得有效電能日期區間的裝置資料  | <color #b5e61d>GET</color>   | ''/devices/kwh/dateRange''  | 取得特定裝置（依據 deviceId、日期區間）之詳細資料，限制數量三個月資料(每15分鐘裡最大值)                 |
| 取得溫、濕度的裝置資料  | <color #b5e61d>GET</color>   | ''/devices/temperature''  | 取得特定裝置（依據 deviceId）之詳細資料                 |
| 取得溫、濕度日期區間的裝置資料  | <color #b5e61d>GET</color>   | ''/devices/temperature/dateRange''  | 取得特定裝置（依據 deviceId、日期區間）之詳細資料，限制數量三個月資料(每15分鐘裡最大值)                 |
| 新增計算後資料數據 | <color #ff7f27>POST</color>  | ''/calculations''        | 將資料上傳至指定裝置，通常為裝置運算後需回傳的結果資料 |

===== 讀取資料 API（GET）說明 =====

==== 請求標頭 ==== 
  * x-api-key：''由 EMS 提供授權碼''

==== 傳遞參數 ====
^ 欄位      ^ 格式      ^ 必填  ^ 說明                          ^
| deviceId  | String     | Required  | 裝置唯一識別碼                |
| startTime | Datetime   | Optional  | 資料開始時間 (2025-04-18)     |
| endTime   | Datetime   | Optional  | 資料結束時間 (2025-05-18)     |

==== JSON ====
<code javascript>
{
    "deviceId": "device-002",
    "startTime": "2025-04-01 00:00:00",
    "endTime": "2025-04-31 23:59:59"
}
</code>
==== 回應參數 ====
^ 參數          ^ 型別    ^ 說明                   ^
| deviceId      | String  | 設備ID                 |
| deviceStatus  | String  | 設備狀態 (on/off)      |
| timestamp     | String  | 時間 （ISO8601 格式）  |
| rawData       | Object  | 實際設備數值           |

==== 溫、濕度 ====
^ rawData 實際設備數值                                    |||
^ 參數                                ^ 型別     ^ 說明                   ^
| temperature                         | Decimal  | 溫度                   |
| humidity                            | Decimal  | 濕度                   |

==== 每小時瓩 ====
^ rawData 實際設備數值                                    |||
^ 參數                                ^ 型別     ^ 說明                   ^
| kWh                                 | Decimal  | 每小時瓩               |


'' GET /devices/kwh ''
==== 回應內容 ====
<code javascript 電錶>
{
  "deviceId": "device-002",
  "deviceStatus": "off",
  "timestamp": "2025-04-01T00:00:00+08:00",
  "rawData": {
    "kWh": 14257.231
  }
}
</code>

'' GET /devices/temperature ''
<code javascript 溫溼度感測器>
{
  "deviceId": "device-001",
  "deviceStatus": "on",
  "timestamp": "2025-04-01T00:00:00+08:00",
  "rawData": {
    "temperature": 26.4,
    "humidity": 83.1
  }
}
</code>


'' GET /devices/kwh/dateRange ''
<code javascript 電錶(日期區間多筆資料)>
{
  "deviceId": "device-002",
  "deviceStatus": "off",
  "timestamp": "2025-04-01T00:00:00+08:00",
  "rawData": {
    "kWh": {
      "1745481208": 14241.231,
      "1745481213": 14244.231,
      "1745481219": 14248.231,
      "1745481226": 14250.231,
      "1745481230": 14253.231,
      "1745481237": 14257.231
    }
  }
}
</code>


'' GET /devices/temperature/dateRange ''
<code javascript 溫溼度感測器(日期區間多筆資料)>
{
  "deviceId": "device-001",
  "deviceStatus": "on",
  "timestamp": "2025-04-01T00:00:00+08:00",
  "rawData": {
    "temperature": {
      "1745481315": 25.12,
      "1745481319": 25.0,
      "1745481324": 25.06,
      "1745481329": 25.0,
      "1745481334": 24.87,
      "1745481340": 25.18
    },
    "humidity": {
      "1745481315": 78.12,
      "1745481319": 81.0,
      "1745481324": 84.06,
      "1745481329": 80.0,
      "1745481334": 76.87,
      "1745481340": 74.18
    }
  }
}
</code>

===== 上傳資料 API（POST）說明 =====

==== 請求標頭 ==== 
  * x-api-key：''由 EMS 提供授權碼''

==== 上傳參數====
^ 參數                  ^ 型別              ^ 說明                            ^
| deviceId              | String            | 裝置唯一識別碼                  |
| clientId              | String            | 客戶 ID                          |
| timestamp             | String (ISO8601)  | 計算時間                        |
| calculatedEnergy      | Decimal           | 計算電量 (時間區間內耗電kWh)    |
| adjustedEnergy        | Decimal           | 調整後電量 (時間區間內耗電kWh)  |
| calculatedSavingRate  | Decimal           | 計算節電率 0.00~1.00            |
| adjustedSavingRate    | Decimal           | 調整後節電率 0.00~1.00          |
| alertCode             | String            | 異常狀態碼（預設為 NO_ALERT）   |

==== 回應內容 ====
<code javascript>
{
  "deviceId": "device-001",
  "clientId": "client-001",
  "timestamp": "2025-04-15T08:05:00Z",
  "calculatedEnergy": 2.85,
  "adjustedEnergy": 2.67,
  "calculatedSavingRate": 0.17,
  "adjustedSavingRate": 0.15,
  "alertCode": "NO_ALERT"
}
</code>

==== 異常狀態碼對照表（alertCode） ====
^ 狀態碼     ^ 說明              ^
| NO_ALERT   | 無異常            |
| WARNING    | 輕微異常，需注意  |
| CRITICAL   | 嚴重異常，需處理  |

==== 回應內容 ====
<code javascript>
{
  "status": "success"
}
</code>

===== 錯誤代碼與說明 =====
^ 錯誤代碼          ^ 錯誤訊息                          ^
| UNAUTHORIZED      | API 金鑰無效或未授權              |
| SERVER_ERROR      | 伺服器內部錯誤，請稍後再試        |
| INVALID_INPUT     | 請求參數格式錯誤，請確認欄位資料  |
| DEVICE_NOT_FOUND  | 查無對應的裝置資料                |
| INVALID_OUTPUT    | 寫入失敗，裝置不存在              |
| INVALID_JSON      | JSON 解析失敗                     |
| INVALID_FIELD     | 欄位不存在                        |

==== 回應內容 ====
<code javascript>
{
  "status": "failure",
  "errorCode": "SERVER_ERROR",
  "message": "伺服器內部錯誤，請稍後再試"
}
</code>

===== 文件變更紀錄 =====
  * **2025-04-17** 建立此頁，設定基本雛型架構
  * **2025-04-18** 經過雙方會談後，整理出較接近的需求版本，並提供較細節的定義內容