場景 API

場景定義設備上的分析區域與參數配置。目前僅支援 queue_analysis（排隊分析）。

對齊版本：SaaS-API v0.10.0（2026-02-25）

端點概覽

方法	路徑	說明
POST	`/api/v1/scenes`	建立場景
GET	`/api/v1/scenes`	查詢場景列表
GET	`/api/v1/scenes/{id}`	取得場景詳情
PATCH	`/api/v1/scenes/{id}`	更新場景
DELETE	`/api/v1/scenes/{id}`	刪除場景

使用場景

排隊分析設定：為設備配置排隊人數偵測功能
區域劃設：定義排隊區和結帳區 (ROI)
參數調整：設定偵測信賴度、進出判定閾值等

建立場景

POST /api/v1/scenes

請求參數

參數	型別	必填	範圍/限制	說明
`deviceId`	String (UUID)	✅	-	所屬設備 ID
`name`	String	✅	1-100 字元	場景名稱
`description`	String	❌	最大 500 字元	場景描述
`analysisType`	String (enum)	✅	`queue_analysis`	分析類型
`config`	Object	❌	-	場景配置
`config.zones`	Object	❌	-	區域配置
`config.parameters`	Object	❌	-	演算法參數

分析類型

值	說明	zones 結構
`queue_analysis`	排隊分析	`queueZone` 和/或 `checkoutZone`（至少一個）

⚠️ 僅支援 queue_analysis。其他類型（如 crowd_analysis、intrusion_detection）已移除。

Zone 結構

queueZone 和 checkoutZone 至少需要提供一個。

欄位	型別	說明
`type`	String	固定 `polygon`
`points`	Number[][]	座標 `[[x1, y1], ...]`，值 0-1 百分比，3-20 個點

演算法參數

參數	型別	範圍	預設	說明
`confidenceThreshold`	Number	0.0-1.0	0.6	偵測信心度閾值
`class`	String (enum)	person / vehicle	person	偵測目標
`entryThresholdSeconds`	Number	1-60	3	進入判定閾值秒數
`exitThresholdSeconds`	Number	1-60	1	離開判定閾值秒數
`trackingMaxAgeSeconds`	Number	1-60	5	追蹤最大存活秒數

請求範例

{
  "deviceId": "device-uuid",
  "name": "櫃台排隊監控",
  "description": "監控服務櫃台的排隊情況",
  "analysisType": "queue_analysis",
  "config": {
    "zones": {
      "queueZone": {
        "type": "polygon",
        "points": [[0.1, 0.2], [0.5, 0.2], [0.5, 0.9], [0.1, 0.9]]
      },
      "checkoutZone": {
        "type": "polygon",
        "points": [[0.6, 0.3], [0.9, 0.3], [0.9, 0.8], [0.6, 0.8]]
      }
    },
    "parameters": {
      "confidenceThreshold": 0.6,
      "class": "person",
      "entryThresholdSeconds": 3,
      "exitThresholdSeconds": 1,
      "trackingMaxAgeSeconds": 5
    }
  }
}

響應範例（201）

{
  "success": true,
  "statusCode": 201,
  "message": "Scene created successfully",
  "data": {
    "id": "scene-uuid",
    "deviceId": "device-uuid",
    "name": "櫃台排隊監控",
    "description": "監控服務櫃台的排隊情況",
    "analysisType": "queue_analysis",
    "status": "active",
    "analysisStatus": "idle",
    "analysisStartedAt": null,
    "processingComputeNodeId": null,
    "config": {
      "zones": {
        "queueZone": {
          "type": "polygon",
          "points": [[0.1, 0.2], [0.5, 0.2], [0.5, 0.9], [0.1, 0.9]]
        },
        "checkoutZone": {
          "type": "polygon",
          "points": [[0.6, 0.3], [0.9, 0.3], [0.9, 0.8], [0.6, 0.8]]
        }
      },
      "parameters": {
        "confidenceThreshold": 0.6,
        "class": "person",
        "entryThresholdSeconds": 3,
        "exitThresholdSeconds": 1,
        "trackingMaxAgeSeconds": 5
      }
    },
    "latestMetrics": null,
    "metricsUpdatedAt": null,
    "userId": "user-uuid",
    "createdAt": "2026-01-29T09:00:00Z",
    "updatedAt": "2026-01-29T09:00:00Z"
  },
  "meta": {
    "timestamp": "2026-01-29T09:00:00.000Z",
    "requestId": "req-uuid"
  }
}

查詢場景列表

GET /api/v1/scenes

權限: scene:read

Query 參數

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	20	每頁數量
`deviceId`	UUID	-	篩選指定設備的場景
`analysisType`	String (enum)	-	篩選分析類型：`queue_analysis`
`status`	String (enum)	-	篩選場景狀態：`draft` / `active` / `paused` / `error`
`analysisStatus`	String (enum)	-	篩選分析狀態：`idle` / `starting` / `running` / `stopping` / `stopped` / `error`

響應 (200)

{
  "success": true,
  "statusCode": 200,
  "message": "Scenes retrieved successfully",
  "data": [
    {
      "id": "scene-uuid",
      "name": "櫃台排隊監控",
      "description": "監控服務櫃台的排隊情況",
      "analysisType": "queue_analysis",
      "status": "active",
      "analysisStatus": "running"
    }
  ],
  "meta": {
    "timestamp": "2026-02-26T10:00:00.000Z",
    "requestId": "req-uuid",
    "pagination": {
      "limit": 20,
      "currentPage": 1,
      "totalRecords": 3,
      "totalPages": 1,
      "nextPage": null,
      "previousPage": null
    }
  }
}

取得場景詳情

GET /api/v1/scenes/{id}

權限: scene:read

響應 (200)

同建立場景的響應格式。

錯誤代碼

HTTP 狀態	說明
404	場景不存在

更新場景

PATCH /api/v1/scenes/{id}

可更新 name、description、status、config。

可用狀態值

值	說明
`draft`	草稿
`active`	已啟用
`paused`	暫停
`error`	錯誤

⚠️ 不可修改 deviceId 和 analysisType，建立後不可變更。

響應 (200)：同建立場景的響應格式。

⚠️ 場景分析處於 RUNNING / STARTING / STOPPING 狀態時無法更新，需先停止分析。

刪除場景

DELETE /api/v1/scenes/{id}

回應: 204 No Content

級聯行為：刪除場景時會自動級聯軟刪除：

該場景的所有告警規則
場景本身

⚠️ 場景分析處於 RUNNING / STARTING / STOPPING 狀態時無法刪除，需先停止分析。

錯誤碼

HTTP 狀態	說明
404	場景不存在
400	場景分析執行中，無法刪除

場景 API

場景定義設備上的分析區域與參數配置。目前僅支援 queue_analysis（排隊分析）。

對齊版本：SaaS-API v0.10.0（2026-02-25）

端點概覽

方法	路徑	說明
POST	`/api/v1/scenes`	建立場景
GET	`/api/v1/scenes`	查詢場景列表
GET	`/api/v1/scenes/{id}`	取得場景詳情
PATCH	`/api/v1/scenes/{id}`	更新場景
DELETE	`/api/v1/scenes/{id}`	刪除場景

使用場景

排隊分析設定：為設備配置排隊人數偵測功能
區域劃設：定義排隊區和結帳區 (ROI)
參數調整：設定偵測信賴度、進出判定閾值等

建立場景

POST /api/v1/scenes

請求參數

參數	型別	必填	範圍/限制	說明
`deviceId`	String (UUID)	✅	-	所屬設備 ID
`name`	String	✅	1-100 字元	場景名稱
`description`	String	❌	最大 500 字元	場景描述
`analysisType`	String (enum)	✅	`queue_analysis`	分析類型
`config`	Object	❌	-	場景配置
`config.zones`	Object	❌	-	區域配置
`config.parameters`	Object	❌	-	演算法參數

分析類型

值	說明	zones 結構
`queue_analysis`	排隊分析	`queueZone` 和/或 `checkoutZone`（至少一個）

⚠️ 僅支援 queue_analysis。其他類型（如 crowd_analysis、intrusion_detection）已移除。

Zone 結構

queueZone 和 checkoutZone 至少需要提供一個。

欄位	型別	說明
`type`	String	固定 `polygon`
`points`	Number[][]	座標 `[[x1, y1], ...]`，值 0-1 百分比，3-20 個點

演算法參數

參數	型別	範圍	預設	說明
`confidenceThreshold`	Number	0.0-1.0	0.6	偵測信心度閾值
`class`	String (enum)	person / vehicle	person	偵測目標
`entryThresholdSeconds`	Number	1-60	3	進入判定閾值秒數
`exitThresholdSeconds`	Number	1-60	1	離開判定閾值秒數
`trackingMaxAgeSeconds`	Number	1-60	5	追蹤最大存活秒數

請求範例

{
  "deviceId": "device-uuid",
  "name": "櫃台排隊監控",
  "description": "監控服務櫃台的排隊情況",
  "analysisType": "queue_analysis",
  "config": {
    "zones": {
      "queueZone": {
        "type": "polygon",
        "points": [[0.1, 0.2], [0.5, 0.2], [0.5, 0.9], [0.1, 0.9]]
      },
      "checkoutZone": {
        "type": "polygon",
        "points": [[0.6, 0.3], [0.9, 0.3], [0.9, 0.8], [0.6, 0.8]]
      }
    },
    "parameters": {
      "confidenceThreshold": 0.6,
      "class": "person",
      "entryThresholdSeconds": 3,
      "exitThresholdSeconds": 1,
      "trackingMaxAgeSeconds": 5
    }
  }
}

響應範例（201）

{
  "success": true,
  "statusCode": 201,
  "message": "Scene created successfully",
  "data": {
    "id": "scene-uuid",
    "deviceId": "device-uuid",
    "name": "櫃台排隊監控",
    "description": "監控服務櫃台的排隊情況",
    "analysisType": "queue_analysis",
    "status": "active",
    "analysisStatus": "idle",
    "analysisStartedAt": null,
    "processingComputeNodeId": null,
    "config": {
      "zones": {
        "queueZone": {
          "type": "polygon",
          "points": [[0.1, 0.2], [0.5, 0.2], [0.5, 0.9], [0.1, 0.9]]
        },
        "checkoutZone": {
          "type": "polygon",
          "points": [[0.6, 0.3], [0.9, 0.3], [0.9, 0.8], [0.6, 0.8]]
        }
      },
      "parameters": {
        "confidenceThreshold": 0.6,
        "class": "person",
        "entryThresholdSeconds": 3,
        "exitThresholdSeconds": 1,
        "trackingMaxAgeSeconds": 5
      }
    },
    "latestMetrics": null,
    "metricsUpdatedAt": null,
    "userId": "user-uuid",
    "createdAt": "2026-01-29T09:00:00Z",
    "updatedAt": "2026-01-29T09:00:00Z"
  },
  "meta": {
    "timestamp": "2026-01-29T09:00:00.000Z",
    "requestId": "req-uuid"
  }
}

查詢場景列表

GET /api/v1/scenes

權限: scene:read

Query 參數

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	20	每頁數量
`deviceId`	UUID	-	篩選指定設備的場景
`analysisType`	String (enum)	-	篩選分析類型：`queue_analysis`
`status`	String (enum)	-	篩選場景狀態：`draft` / `active` / `paused` / `error`
`analysisStatus`	String (enum)	-	篩選分析狀態：`idle` / `starting` / `running` / `stopping` / `stopped` / `error`

響應 (200)

{
  "success": true,
  "statusCode": 200,
  "message": "Scenes retrieved successfully",
  "data": [
    {
      "id": "scene-uuid",
      "name": "櫃台排隊監控",
      "description": "監控服務櫃台的排隊情況",
      "analysisType": "queue_analysis",
      "status": "active",
      "analysisStatus": "running"
    }
  ],
  "meta": {
    "timestamp": "2026-02-26T10:00:00.000Z",
    "requestId": "req-uuid",
    "pagination": {
      "limit": 20,
      "currentPage": 1,
      "totalRecords": 3,
      "totalPages": 1,
      "nextPage": null,
      "previousPage": null
    }
  }
}

取得場景詳情

GET /api/v1/scenes/{id}

權限: scene:read

響應 (200)

同建立場景的響應格式。

錯誤代碼

HTTP 狀態	說明
404	場景不存在

更新場景

PATCH /api/v1/scenes/{id}

可更新 name、description、status、config。

可用狀態值

值	說明
`draft`	草稿
`active`	已啟用
`paused`	暫停
`error`	錯誤

⚠️ 不可修改 deviceId 和 analysisType，建立後不可變更。

響應 (200)：同建立場景的響應格式。

⚠️ 場景分析處於 RUNNING / STARTING / STOPPING 狀態時無法更新，需先停止分析。

刪除場景

DELETE /api/v1/scenes/{id}

回應: 204 No Content

級聯行為：刪除場景時會自動級聯軟刪除：

該場景的所有告警規則
場景本身

⚠️ 場景分析處於 RUNNING / STARTING / STOPPING 狀態時無法刪除，需先停止分析。

錯誤碼

HTTP 狀態	說明
404	場景不存在
400	場景分析執行中，無法刪除