分析控制 API

控制設備的分析啟動與停止。

端點概覽

方法	路徑	說明
POST	`/api/v1/devices/{id}/analysis/start`	啟動分析
POST	`/api/v1/devices/{id}/analysis/stop`	停止分析
GET	`/api/v1/devices/{id}/analysis/status`	取得分析狀態
GET	`/api/v1/devices/{id}/analysis/history`	取得分析歷史紀錄
GET	`/api/v1/analysis/tasks`	查詢分析任務列表
GET	`/api/v1/analysis/tasks/statistics`	各狀態任務數量統計
GET	`/api/v1/analysis/tasks/{id}`	查詢單一任務詳情
PATCH	`/api/v1/analysis/tasks/{id}`	更新任務 (取消排隊中任務)
DELETE	`/api/v1/analysis/tasks/{id}`	軟刪除任務

使用場景

手動控制：即時啟動/停止特定場景的分析
API 整合：由外部系統觸發分析
狀態查詢：確認當前分析是否運行中

💡 若已設定設備排程，系統會自動啟停分析，可跳過此步驟。

啟動分析

POST /api/v1/devices/{deviceId}/analysis/start

請求參數

參數	型別	必填	範圍/限制	說明
`sceneId`	String (UUID)	✅	-	要執行的場景 ID
`priority`	Number	❌	1-5	優先級（1=最高），預設 3

前置條件

設備在線（onlineStatus = online）
場景狀態為 active
設備配額未超限
分析未在運行中

響應 (202 Accepted)

{
  "success": true,
  "statusCode": 202,
  "message": "Analysis started successfully",
  "data": {
    "sceneId": "scene-uuid",
    "deviceId": "device-uuid",
    "analysisId": "analysis-uuid",
    "sceneType": "queue_analysis",
    "status": "initializing",
    "estimatedInitMs": 3000,
    "createdAt": "2026-01-29T10:00:00Z"
  },
  "meta": {
    "timestamp": "2026-01-29T10:00:00.000Z",
    "requestId": "req-uuid",
    "computeNodeId": "node-uuid"
  }
}

錯誤碼

錯誤碼	說明
`ALREADY_RUNNING`	分析已在運行中
`DEVICE_OFFLINE`	設備離線
`NO_ACTIVE_SCENES`	無可用場景
`QUOTA_EXCEEDED`	配額已用罄

停止分析

POST /api/v1/devices/{deviceId}/analysis/stop

請求參數

參數	型別	必填	說明
`reason`	String (enum)	❌	停止原因，預設 `user_request`
`drain`	Boolean	❌	是否等待緩衝區處理完畢，預設 false

停止原因

值	說明
`user_request`	用戶請求停止
`timeout`	超時
`error`	錯誤
`resource_constraint`	資源限制
`scheduled`	排程停止

響應 (200)

{
  "success": true,
  "statusCode": 200,
  "message": "Analysis stopped successfully",
  "data": {
    "sceneId": "scene-uuid",
    "deviceId": "device-uuid",
    "analysisId": "analysis-uuid",
    "sceneType": "queue_analysis",
    "status": "stopped",
    "stoppedAt": "2026-01-29T12:00:00Z",
    "processingDuration": {
      "seconds": 7200,
      "milliseconds": 7200000
    }
  },
  "meta": {
    "timestamp": "2026-01-29T12:00:00.000Z",
    "requestId": "req-uuid",
    "computeNodeId": "node-uuid"
  }
}

取得分析狀態

GET /api/v1/devices/{deviceId}/analysis/status

響應 (200)

{
  "success": true,
  "statusCode": 200,
  "message": "Analysis status retrieved",
  "data": {
    "computeNodeHealth": "online",
    "activeDeviceCount": 1,
    "maxConcurrentDevices": 4,
    "devices": [
      {
        "deviceId": "device-uuid",
        "scenes": [
          {
            "sceneId": "scene-uuid",
            "sceneType": "queue_analysis",
            "status": "running",
            "uptimeMs": 3600000,
            "stats": {
              "processedFrames": 5000,
              "droppedFrames": 50,
              "fps": 25.5,
              "avgProcessingTimeMs": 120
            },
            "startedAt": "2026-01-29T10:00:00Z"
          }
        ]
      }
    ]
  },
  "meta": {
    "timestamp": "2026-01-29T11:00:00.000Z",
    "requestId": "req-uuid",
    "computeNodeId": "node-uuid"
  }
}

分析狀態

值	說明
`initializing`	初始化中
`running`	運行中
`stopped`	已停止
`error`	錯誤

取得分析歷史紀錄

GET /api/v1/devices/{id}/analysis/history

Query 參數

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	20	每頁數量
`status`	Enum	-	任務狀態：QUEUED / PROCESSING / COMPLETED / FAILED / CANCELLED
`startedAfter`	ISO 8601	-	篩選此時間之後開始的任務
`startedBefore`	ISO 8601	-	篩選此時間之前開始的任務

響應 (200)

{
  "success": true,
  "data": [
    {
      "taskId": "task-uuid",
      "analysisType": "queue_analysis",
      "status": "COMPLETED",
      "computeNodeId": "node-uuid",
      "startedAt": "2026-02-25T08:00:00Z",
      "completedAt": "2026-02-25T18:00:00Z",
      "processingTimeMs": 36000000,
      "errorMessage": null,
      "createdAt": "2026-02-25T07:59:50Z"
    }
  ],
  "meta": { "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 } }
}

分析任務管理

獨立的分析任務 CRUD API。

API Key Scope：TASK_READ (讀取) / TASK_WRITE (修改/刪除)

查詢分析任務列表

GET /api/v1/analysis/tasks

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	10	每頁數量
`q`	String	-	搜尋關鍵字
`deviceId`	UUID	-	按設備篩選
`status`	Enum	-	任務狀態：queued / processing / completed / failed / cancelled
`analysisType`	Enum	-	分析類型（目前僅 `queue_analysis`）
`sortBy`	Enum	createdAt	排序欄位
`sortOrder`	Enum	DESC	排序方向

任務統計

GET /api/v1/analysis/tasks/statistics

回傳各狀態的任務數量統計。

更新任務

PATCH /api/v1/analysis/tasks/{id}

可用於取消排隊中的任務。

刪除任務

DELETE /api/v1/analysis/tasks/{id}

軟刪除任務記錄。

分析控制 API

控制設備的分析啟動與停止。

端點概覽

方法	路徑	說明
POST	`/api/v1/devices/{id}/analysis/start`	啟動分析
POST	`/api/v1/devices/{id}/analysis/stop`	停止分析
GET	`/api/v1/devices/{id}/analysis/status`	取得分析狀態
GET	`/api/v1/devices/{id}/analysis/history`	取得分析歷史紀錄
GET	`/api/v1/analysis/tasks`	查詢分析任務列表
GET	`/api/v1/analysis/tasks/statistics`	各狀態任務數量統計
GET	`/api/v1/analysis/tasks/{id}`	查詢單一任務詳情
PATCH	`/api/v1/analysis/tasks/{id}`	更新任務 (取消排隊中任務)
DELETE	`/api/v1/analysis/tasks/{id}`	軟刪除任務

使用場景

手動控制：即時啟動/停止特定場景的分析
API 整合：由外部系統觸發分析
狀態查詢：確認當前分析是否運行中

💡 若已設定設備排程，系統會自動啟停分析，可跳過此步驟。

啟動分析

POST /api/v1/devices/{deviceId}/analysis/start

請求參數

參數	型別	必填	範圍/限制	說明
`sceneId`	String (UUID)	✅	-	要執行的場景 ID
`priority`	Number	❌	1-5	優先級（1=最高），預設 3

前置條件

設備在線（onlineStatus = online）
場景狀態為 active
設備配額未超限
分析未在運行中

響應 (202 Accepted)

{
  "success": true,
  "statusCode": 202,
  "message": "Analysis started successfully",
  "data": {
    "sceneId": "scene-uuid",
    "deviceId": "device-uuid",
    "analysisId": "analysis-uuid",
    "sceneType": "queue_analysis",
    "status": "initializing",
    "estimatedInitMs": 3000,
    "createdAt": "2026-01-29T10:00:00Z"
  },
  "meta": {
    "timestamp": "2026-01-29T10:00:00.000Z",
    "requestId": "req-uuid",
    "computeNodeId": "node-uuid"
  }
}

錯誤碼

錯誤碼	說明
`ALREADY_RUNNING`	分析已在運行中
`DEVICE_OFFLINE`	設備離線
`NO_ACTIVE_SCENES`	無可用場景
`QUOTA_EXCEEDED`	配額已用罄

停止分析

POST /api/v1/devices/{deviceId}/analysis/stop

請求參數

參數	型別	必填	說明
`reason`	String (enum)	❌	停止原因，預設 `user_request`
`drain`	Boolean	❌	是否等待緩衝區處理完畢，預設 false

停止原因

值	說明
`user_request`	用戶請求停止
`timeout`	超時
`error`	錯誤
`resource_constraint`	資源限制
`scheduled`	排程停止

響應 (200)

{
  "success": true,
  "statusCode": 200,
  "message": "Analysis stopped successfully",
  "data": {
    "sceneId": "scene-uuid",
    "deviceId": "device-uuid",
    "analysisId": "analysis-uuid",
    "sceneType": "queue_analysis",
    "status": "stopped",
    "stoppedAt": "2026-01-29T12:00:00Z",
    "processingDuration": {
      "seconds": 7200,
      "milliseconds": 7200000
    }
  },
  "meta": {
    "timestamp": "2026-01-29T12:00:00.000Z",
    "requestId": "req-uuid",
    "computeNodeId": "node-uuid"
  }
}

取得分析狀態

GET /api/v1/devices/{deviceId}/analysis/status

響應 (200)

{
  "success": true,
  "statusCode": 200,
  "message": "Analysis status retrieved",
  "data": {
    "computeNodeHealth": "online",
    "activeDeviceCount": 1,
    "maxConcurrentDevices": 4,
    "devices": [
      {
        "deviceId": "device-uuid",
        "scenes": [
          {
            "sceneId": "scene-uuid",
            "sceneType": "queue_analysis",
            "status": "running",
            "uptimeMs": 3600000,
            "stats": {
              "processedFrames": 5000,
              "droppedFrames": 50,
              "fps": 25.5,
              "avgProcessingTimeMs": 120
            },
            "startedAt": "2026-01-29T10:00:00Z"
          }
        ]
      }
    ]
  },
  "meta": {
    "timestamp": "2026-01-29T11:00:00.000Z",
    "requestId": "req-uuid",
    "computeNodeId": "node-uuid"
  }
}

分析狀態

值	說明
`initializing`	初始化中
`running`	運行中
`stopped`	已停止
`error`	錯誤

取得分析歷史紀錄

GET /api/v1/devices/{id}/analysis/history

Query 參數

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	20	每頁數量
`status`	Enum	-	任務狀態：QUEUED / PROCESSING / COMPLETED / FAILED / CANCELLED
`startedAfter`	ISO 8601	-	篩選此時間之後開始的任務
`startedBefore`	ISO 8601	-	篩選此時間之前開始的任務

響應 (200)

{
  "success": true,
  "data": [
    {
      "taskId": "task-uuid",
      "analysisType": "queue_analysis",
      "status": "COMPLETED",
      "computeNodeId": "node-uuid",
      "startedAt": "2026-02-25T08:00:00Z",
      "completedAt": "2026-02-25T18:00:00Z",
      "processingTimeMs": 36000000,
      "errorMessage": null,
      "createdAt": "2026-02-25T07:59:50Z"
    }
  ],
  "meta": { "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 } }
}

分析任務管理

獨立的分析任務 CRUD API。

API Key Scope：TASK_READ (讀取) / TASK_WRITE (修改/刪除)

查詢分析任務列表

GET /api/v1/analysis/tasks

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	10	每頁數量
`q`	String	-	搜尋關鍵字
`deviceId`	UUID	-	按設備篩選
`status`	Enum	-	任務狀態：queued / processing / completed / failed / cancelled
`analysisType`	Enum	-	分析類型（目前僅 `queue_analysis`）
`sortBy`	Enum	createdAt	排序欄位
`sortOrder`	Enum	DESC	排序方向

任務統計

GET /api/v1/analysis/tasks/statistics

回傳各狀態的任務數量統計。

更新任務

PATCH /api/v1/analysis/tasks/{id}

可用於取消排隊中的任務。

刪除任務

DELETE /api/v1/analysis/tasks/{id}

軟刪除任務記錄。