# Resource Monitoring Specification (資源監控規範)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 定義 Processor/Agent 的註冊與心跳協定 (僅限監控) | OpenCode | OpenCode |

---

## 1. 核心概念

本階段資源註冊機制 (Resource Registry) **僅用於監控 (Monitoring)**，不介入動態任務調度。
所有 Processor (YOLO, ASR...) 和 Agent (Translation, Summary...) 啟動時應主動註冊。

### 1.1 註冊時機
* **Processor**: 在 Python 腳本啟動時，呼叫 HTTP Endpoint 註冊。
* **Agent**: 在服務啟動時呼叫 HTTP Endpoint 註冊。

---

## 2. 註冊協定 (Registration Protocol)

### 2.1 API Endpoint

`POST /api/v1/resources/register`

### 2.2 Request Payload

```json
{
  "resource_id": "unique_id", 
  "resource_type": "processor | agent",
  "name": "Yolo Object Detector",
  "capabilities": ["detect_object", "detect_face"],
  "config": {
    "model_version": "v8n",
    "gpu_enabled": true
  }
}
```

* **resource_id**: 建議格式 `{type}_{name}_{uuid}`，例如 `processor_yolo_a1b2c3`。

### 2.3 Response

```json
{
  "success": true,
  "message": "Resource registered"
}
```

---

## 3. 心跳協定 (Heartbeat Protocol)

資源應定期發送心跳，回報當前狀態與進度。

### 3.1 API Endpoint

`POST /api/v1/resources/{resource_id}/heartbeat`

### 3.2 Request Payload

```json
{
  "status": "idle | busy | error",
  "job_uuid": "current_file_uuid", 
  "progress": 0.45, 
  "last_frame_index": 12500
}
```

* **progress**: 0.0 到 1.0 之間的浮點數。
* **job_uuid**: 當前正在處理的任務 ID。

---

## 4. 監控用途

系統後台 (Portal Dashboard) 可透過查詢 Registry 實現：
1. **即時儀表板**: 顯示目前有幾個 Processor 在運行 (`busy` 數量)。
2. **進度條**: 透過 `last_frame_index` 與影片總幀數計算百分比。
3. **健康檢查**: 若資源超過 60 秒未發送心跳，標記為 `offline`。

---

## 5. Rust Worker 整合建議

在 `src/worker/processor.rs` 的 `run_processor` 函數中：

```rust
// 1. 生成唯一的 Resource ID
let resource_id = format!("processor_{}_{}", processor_type, job.uuid);

// 2. 註冊資源
register_resource(&resource_id, processor_type).await;

// 3. 執行腳本 (腳本內部應定期發送心跳，或由 Rust Wrapper 發送)
run_python_script(...);

// 4. 登出資源 (可選，或由 TTL 自動清理)
deregister_resource(&resource_id).await;
```

---

## 版本資訊

* 版本: V1.0
* 建立日期: 2026-04-25
