# Trace 結構說明

**Date**: 2026-05-16

---

## 定義

Trace 是 Face Tracker 輸出的一組連續人臉偵測結果，代表同一個人在畫面中的連續出現。每一條 trace 包含多個 `face_detections` 記錄，共享同一個 `trace_id`。

## 結構

### 資料庫

```sql
-- face_detections 表
trace_id    INTEGER       -- 同檔案內順序編號 (0, 1, 2, ...)
file_uuid   VARCHAR(32)   -- 所屬檔案
face_id     VARCHAR       -- 單一偵測 ID (未使用)
identity_id INTEGER       -- 綁定的身份 ID (FK → identities.id)
frame_number INTEGER       -- 所在影格
x, y, w, h  INTEGER       -- Bounding box
confidence  FLOAT4         -- 信心度
```

### scope

| 範圍 | 說明 |
|------|------|
| **Per-file** | `trace_id` 在同一個 `file_uuid` 內唯一，從 0 開始遞增 |
| **Global** | 不同檔案的相同 `trace_id` 沒有關聯，需搭配 `file_uuid` 使用 |

### API 端點

```bash
# Trace 列表（含 face_count、時間範圍、信心度）
POST /api/v1/file/:file_uuid/face_trace/sortby
Body: {"sort_by": "face_count", "limit": 100}

# Trace 內的人臉偵測（含 interpolation）
GET  /api/v1/file/:file_uuid/trace/:trace_id/faces?page=1&page_size=200

# Trace 綁定身份 (trace→identity)
POST /api/v1/identity/:identity_uuid/bind
Body: {"file_uuid": "...", "trace_id": 5}
```

### Trace 與 Identity 的關係

```
trace_id (per-file seq)
     │
     ├── identity_id (FK → identities.id)
     │       │
     │       └── identity_uuid (global UUID, 32碼無-)
     │
     └── face_detections (N rows per trace)
             │
             ├── frame_number (哪一幀)
             ├── bbox (位置)
             └── confidence (信心度)
```

### Trace 資料範例

```json
{
  "trace_id": 2,
  "face_count": 46,
  "start_frame": 4587,
  "end_frame": 4722,
  "start_time": 191.38,
  "end_time": 196.95,
  "duration_sec": 5.57,
  "avg_confidence": 0.85,
  "sample_face_id": null
}
```

## 生命週期

```
Face Tracker (Python script)
    → 分析人臉 embedding + IoU + 距離
    → 產生 trace_id (同檔案內獨立 numbering)
    → 寫入 face_detections 表
    → Identity Agent 比對 embedding
    → 設定 identity_id (綁定身份)
```

## 特點

| 特性 | 說明 |
|------|------|
| **順序編號** | 無 UUID，簡單整數，每個檔案從 0 開始 |
| **唯一性** | `(file_uuid, trace_id)` 唯一，`trace_id` 單獨不唯一 |
| **補幀** | API 支援 `interpolate=true` 參數補齊中間幀 |
| **綁定** | 透過 Agent API 綁定到 `identity_uuid` |