Sensor Data Collector後端資料模型實作建議 by ChatGPT ----- Q: 請依照剛才的模型設計給我該系統所需要的API定義文件，認證的部分需加入recaptcha與jwt（auth_token與refeash_token），jwt設定24小時過期，登出功能直接紀錄失效的access_token強制他重新登入。 需再加上修改密碼、忘記密碼等功能，修改密碼與忘記密碼都需要confirm_password。 用戶的profile管理功能應該與user register或是admin用的create user等功能綁在一起實作，對於前端來說就是一般的User CRUD，在後端自動組合User與Profile的欄位資料。 其他model則為基本CRUD 都要有，另外加上dashboard相關的API，請提供建議的設計方案。 ----- A: 好的，根據您提供的模型和需求，我將為您設計適合的 API 定義文件。這些 API 將涵蓋以下部分： 1. **認證與授權**：使用 JWT（包含 `access_token` 和 `refresh_token`），並整合 reCAPTCHA。`access_token` 設定為 24 小時過期。登出功能將紀錄失效的 `access_token`，強制用戶重新登入。 2. **用戶管理**：包含註冊、登入、登出、修改密碼、忘記密碼，以及用戶的 CRUD 功能。`Profile` 將與 `User` 模型結合，對前端呈現為一個統一的用戶介面。 3. **設備與感測器管理**：提供 `Device`、`SensorType`、`Sensor` 的基本 CRUD API。 4. **Dashboard 相關 API**：提供數據統計、圖表資料等需要的 API。 以下是詳細的 API 定義： --- ## 目錄 - [認證與授權](#認證與授權) - [用戶註冊](#用戶註冊) - [用戶登入](#用戶登入) - [用戶登出](#用戶登出) - [刷新 Token](#刷新-token) - [修改密碼](#修改密碼) - [忘記密碼](#忘記密碼) - [用戶管理](#用戶管理) - [取得用戶列表](#取得用戶列表) - [取得用戶詳情](#取得用戶詳情) - [新增用戶](#新增用戶) - [更新用戶](#更新用戶) - [刪除用戶](#刪除用戶) - [公司管理](#公司管理) - [設備管理](#設備管理) - [感測器管理](#感測器管理) - [Dashboard API](#dashboard-api) --- ## 認證與授權 ### 用戶註冊 **Endpoint**: `/api/auth/register/` **Method**: `POST` **描述**: 用於新用戶註冊，將 `User` 和 `Profile` 資料結合。 **Request Body**: ```json { "username": "string", "password": "string", "confirm_password": "string", "email": "string", "first_name": "string", "last_name": "string", "company": "string", // 公司名稱或 ID "phone": "string", "recaptcha_token": "string" // Google reCAPTCHA 驗證令牌 } ``` **Response**: - **201 Created**: 註冊成功，返回用戶資料。 - **400 Bad Request**: 註冊失敗，返回錯誤訊息。 ### 用戶登入 **Endpoint**: `/api/auth/login/` **Method**: `POST` **描述**: 用戶登入，取得 `access_token` 和 `refresh_token`。 **Request Body**: ```json { "username": "string", "password": "string", "recaptcha_token": "string" // Google reCAPTCHA 驗證令牌 } ``` **Response**: - **200 OK**: 登入成功，返回令牌。 ```json { "access_token": "string", "refresh_token": "string" } ``` - **401 Unauthorized**: 登入失敗，返回錯誤訊息。 ### 用戶登出 **Endpoint**: `/api/auth/logout/` **Method**: `POST` **描述**: 用戶登出，將當前的 `access_token` 記錄為失效。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **204 No Content**: 登出成功。 - **401 Unauthorized**: 未經授權，可能令牌無效或已過期。 ### 刷新 Token **Endpoint**: `/api/auth/refresh/` **Method**: `POST` **描述**: 使用 `refresh_token` 獲取新的 `access_token`。 **Request Body**: ```json { "refresh_token": "string" } ``` **Response**: - **200 OK**: 返回新的 `access_token`。 ```json { "access_token": "string" } ``` - **401 Unauthorized**: 令牌無效或已過期。 ### 修改密碼 **Endpoint**: `/api/auth/change-password/` **Method**: `POST` **描述**: 已登入用戶修改密碼。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "old_password": "string", "new_password": "string", "confirm_password": "string" } ``` **Response**: - **200 OK**: 修改成功，返回成功訊息。 - **400 Bad Request**: 修改失敗，返回錯誤訊息。 - **401 Unauthorized**: 未經授權。 ### 忘記密碼 **Endpoint**: `/api/auth/forgot-password/` **Method**: `POST` **描述**: 用戶忘記密碼，請求重置。 **Request Body**: ```json { "email": "string", "recaptcha_token": "string" // Google reCAPTCHA 驗證令牌 } ``` **Response**: - **200 OK**: 已發送重置密碼的郵件。 - **400 Bad Request**: 請求失敗，返回錯誤訊息。 **備註**: - 系統會向用戶發送一封包含重置連結的電子郵件。 - 重置連結指向一個帶有 `token` 的前端頁面，讓用戶輸入新密碼。 ### 重置密碼確認 **Endpoint**: `/api/auth/reset-password/` **Method**: `POST` **描述**: 用於用戶透過電子郵件連結重置密碼。 **Request Body**: ```json { "token": "string", "new_password": "string", "confirm_password": "string" } ``` **Response**: - **200 OK**: 重置成功，返回成功訊息。 - **400 Bad Request**: 重置失敗，返回錯誤訊息。 --- ## 用戶管理 ### 取得用戶列表 **Endpoint**: `/api/users/` **Method**: `GET` **描述**: 獲取所有用戶列表。需要管理員權限。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回用戶列表。 - **403 Forbidden**: 權限不足。 ### 取得用戶詳情 **Endpoint**: `/api/users/<user_id>/` **Method**: `GET` **描述**: 獲取特定用戶的詳細資訊。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回用戶詳情。 - **403 Forbidden**: 權限不足。 ### 新增用戶 **Endpoint**: `/api/users/` **Method**: `POST` **描述**: 創建新用戶。需要管理員權限。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "username": "string", "password": "string", "confirm_password": "string", "email": "string", "first_name": "string", "last_name": "string", "company": "string", // 公司名稱或 ID "phone": "string", "groups": ["string"], // 用戶角色或群組 "is_active": true } ``` **Response**: - **201 Created**: 創建成功，返回用戶資料。 - **400 Bad Request**: 創建失敗，返回錯誤訊息。 - **403 Forbidden**: 權限不足。 ### 更新用戶 **Endpoint**: `/api/users/<user_id>/` **Method**: `PUT` **描述**: 更新用戶資料。需要管理員權限或用戶本人。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "email": "string", "first_name": "string", "last_name": "string", "company": "string", // 只有管理員可以更改 "phone": "string", "groups": ["string"], // 只有管理員可以更改 "is_active": true // 只有管理員可以更改 } ``` **Response**: - **200 OK**: 更新成功，返回用戶資料。 - **400 Bad Request**: 更新失敗，返回錯誤訊息。 - **403 Forbidden**: 權限不足。 ### 刪除用戶 **Endpoint**: `/api/users/<user_id>/` **Method**: `DELETE` **描述**: 刪除用戶。需要管理員權限。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **204 No Content**: 刪除成功。 - **403 Forbidden**: 權限不足。 --- ## 公司管理 **公司相關的 API 根據需要可以提供，例如公司列表、創建公司等。以下提供基本的 API：** ### 取得公司列表 **Endpoint**: `/api/companies/` **Method**: `GET` **描述**: 獲取所有公司列表。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回公司列表。 ### 取得公司詳情 **Endpoint**: `/api/companies/<company_id>/` **Method**: `GET` **描述**: 獲取特定公司的詳細資訊。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回公司詳情。 ### 新增公司 **Endpoint**: `/api/companies/` **Method**: `POST` **描述**: 創建新公司。需要管理員權限。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "name": "string", "address": "string" } ``` **Response**: - **201 Created**: 創建成功，返回公司資料。 - **400 Bad Request**: 創建失敗。 - **403 Forbidden**: 權限不足。 --- ## 設備管理 ### 取得設備列表 **Endpoint**: `/api/devices/` **Method**: `GET` **描述**: 獲取當前公司所有設備列表。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回設備列表。 ### 取得設備詳情 **Endpoint**: `/api/devices/<device_id>/` **Method**: `GET` **描述**: 獲取特定設備的詳細資訊。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回設備詳情。 ### 新增設備 **Endpoint**: `/api/devices/` **Method**: `POST` **描述**: 創建新設備。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "name": "string", "device_id": "string", // 必須唯一 "description": "string" } ``` **Response**: - **201 Created**: 創建成功，返回設備資料。 - **400 Bad Request**: 創建失敗。 ### 更新設備 **Endpoint**: `/api/devices/<device_id>/` **Method**: `PUT` **描述**: 更新設備資料。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "name": "string", "description": "string" } ``` **Response**: - **200 OK**: 更新成功，返回設備資料。 - **400 Bad Request**: 更新失敗。 ### 刪除設備 **Endpoint**: `/api/devices/<device_id>/` **Method**: `DELETE` **描述**: 刪除設備。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **204 No Content**: 刪除成功。 --- ## 感測器管理 ### 感測器類型管理 #### 取得感測器類型列表 **Endpoint**: `/api/sensor-types/` **Method**: `GET` **描述**: 獲取所有感測器類型。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回感測器類型列表。 #### 新增感測器類型 **Endpoint**: `/api/sensor-types/` **Method**: `POST` **描述**: 創建新感測器類型。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "name": "string", "data_type": "string", // 例如 'float', 'integer', 'string', 'boolean' "min_value": 0.0, "max_value": 100.0, "description": "string" } ``` **Response**: - **201 Created**: 創建成功。 - **400 Bad Request**: 創建失敗。 ### 感測器管理 #### 取得感測器列表 **Endpoint**: `/api/sensors/` **Method**: `GET` **描述**: 獲取當前公司所有感測器列表。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回感測器列表。 #### 取得感測器詳情 **Endpoint**: `/api/sensors/<sensor_id>/` **Method**: `GET` **描述**: 獲取特定感測器的詳細資訊。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回感測器詳情。 #### 新增感測器 **Endpoint**: `/api/sensors/` **Method**: `POST` **描述**: 為特定設備添加感測器。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "name": "string", "sensor_id": "string", // 必須唯一 "device": "string", // 設備 ID "sensor_type": "string", // 感測器類型 ID "description": "string" } ``` **Response**: - **201 Created**: 創建成功。 - **400 Bad Request**: 創建失敗。 #### 更新感測器 **Endpoint**: `/api/sensors/<sensor_id>/` **Method**: `PUT` **描述**: 更新感測器資料。 **Headers**: - `Authorization`: `Bearer <access_token>` **Request Body**: ```json { "name": "string", "description": "string" } ``` **Response**: - **200 OK**: 更新成功。 - **400 Bad Request**: 更新失敗。 #### 刪除感測器 **Endpoint**: `/api/sensors/<sensor_id>/` **Method**: `DELETE` **描述**: 刪除感測器。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **204 No Content**: 刪除成功。 --- ## Dashboard API Dashboard API 用於提供數據視覺化所需的資料，例如統計數據、圖表資料等。以下是建議的設計方案： ### 獲取感測器數據 **Endpoint**: `/api/dashboard/sensor-data/` **Method**: `GET` **描述**: 獲取特定感測器的數據。 **Headers**: - `Authorization`: `Bearer <access_token>` **Query Parameters**: - `sensor_id`: 感測器 ID - `start_time`: 開始時間（ISO 8601 格式） - `end_time`: 結束時間（ISO 8601 格式） - `interval`: 資料間隔（例如 `hourly`, `daily`） **Response**: - **200 OK**: 返回感測器數據列表。 ```json [ { "timestamp": "ISO 8601 string", "value": "depends on data_type" }, ... ] ``` - **400 Bad Request**: 請求參數錯誤。 ### 獲取設備狀態統計 **Endpoint**: `/api/dashboard/device-stats/` **Method**: `GET` **描述**: 獲取當前公司所有設備的狀態統計。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回統計資料。 ```json { "total_devices": 10, "active_devices": 8, "inactive_devices": 2 } ``` ### 獲取感測器異常警報 **Endpoint**: `/api/dashboard/alerts/` **Method**: `GET` **描述**: 獲取感測器數據異常的警報資訊。 **Headers**: - `Authorization`: `Bearer <access_token>` **Response**: - **200 OK**: 返回警報列表。 ```json [ { "alert_id": "string", "sensor_id": "string", "sensor_name": "string", "device_name": "string", "timestamp": "ISO 8601 string", "value": "depends on data_type", "message": "string" }, ... ] ``` ### 建議的設計方案 - **資料存儲**：感測器數據可能會非常龐大，建議使用時序數據庫（如 InfluxDB）或優化過的資料庫結構來存儲大量的時間序列數據。 - **數據聚合與分析**：為了提供快速的 Dashboard 反應，預先計算和存儲一些常用的統計資料（如日均值、最大值、最小值）。 - **實時更新**：如果需要實時數據，可以考慮使用 WebSocket 或其他推送技術，讓前端可以即時接收到最新的感測器數據。 - **權限控制**：確保用戶只能訪問自己公司內的數據。使用 Django 的權限系統或自定義的權限驗證。 - **錯誤處理**：在 API 中加入完善的錯誤處理和日誌記錄，方便未來的維護和調試。 --- ## 總結 以上是根據您的需求設計的 API 定義文件。這些 API 涵蓋了用戶認證、用戶管理、設備與感測器的 CRUD 操作，以及 Dashboard 所需的數據接口。 在實作時，建議使用 **Django REST Framework** 來構建 API，並使用以下工具與套件： - **JWT 認證**：使用 `djangorestframework-simplejwt` 套件，並配置 `ACCESS_TOKEN_LIFETIME` 為 24 小時。 - **reCAPTCHA 驗證**：在相關的 API（如註冊、登入、忘記密碼）中整合 Google reCAPTCHA，驗證 `recaptcha_token` 的有效性。 - **密碼處理**：在修改密碼和重置密碼的功能中，確保新密碼與 `confirm_password` 一致，並符合密碼強度要求。 - **用戶與 Profile 結合**：在序列化器（Serializer）中使用嵌套關聯，讓前端可以在一次請求中提交和獲取所有用戶相關資料。 - **權限與驗證**：使用 Django 的權限系統和 `IsAuthenticated`、`IsAdminUser` 等權限類別，控制 API 的訪問權限。 希望這些資訊能夠幫助您順利開發系統，如有任何問題，請隨時提出！