docs: add REFERENCE docs, M4 workspace, Caddyfile

docs_v1.0/REFERENCE/Trace_Structure.md

@@ -0,0 +1,98 @@
+# 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` |