docs: add REFERENCE docs, M4 workspace, Caddyfile

docs_v1.0/REFERENCE/Cut_Structure.md

@@ -0,0 +1,108 @@
+# Cut 結構說明
+
+**Date**: 2026-05-16
+
+---
+
+## 定義
+
+Cut = **視覺 chunk**。  
+同鏡頭連續拍攝的一組 frame（one continuous camera take）。  
+由 `cut_processor.py`（PySceneDetect）偵測場景轉換點自動切割。
+
+與 **聽覺 chunk（sentence）** 的對照：
+
+```
+chunk 類型      | 模態  | 產出者              | 內容
+----------------|-------|---------------------|----------------------
+cut (視覺)      | video | cut_processor.py    | scene boundary
+sentence (聽覺) | audio | asr_processor.py    | speech text
+```
+
+兩者各自獨立：cut 不含聽覺資訊，sentence 不含視覺資訊。  
+但在時間軸上可以對齊：某個 cut 時間區間內包含哪些 sentence。
+
+特性：
+- 同一個 cut 內：光線、構圖、背景一致
+- 換鏡頭 → 新 cut → 物體動態軌跡中斷
+- trace 必定落在一個 cut 內（不跨 cut）
+
+儲存在 `chunk` 表中，`chunk_type = 'cut'`。
+
+## 儲存方式
+
+獨立的 `cuts` 表：
+
+```sql
+cuts 表
+├── id            SERIAL PK
+├── file_uuid     VARCHAR(32)  所屬檔案
+├── cut_number    INTEGER      同一檔案內序號 (1, 2, 3...)
+├── start_frame   BIGINT       開始影格
+├── end_frame     BIGINT       結束影格
+├── start_time    FLOAT8       開始時間（秒）
+├── end_time      FLOAT8       結束時間（秒）
+├── fps           FLOAT8       影格率
+├── metadata      JSONB       附加資訊
+├── created_at    TIMESTAMPTZ  建立時間
+└── UNIQUE(file_uuid, cut_number)
+```
+
+## 資料範例
+
+```json
+{
+  "id": 989849,
+  "chunk_id": "989849",
+  "chunk_type": "cut",
+  "start_frame": 0,
+  "end_frame": 867,
+  "fps": 25.0,
+  "content": {"type": "scene", "scene_number": 1}
+}
+```
+
+## 與 Trace 的關係
+
+每個 cut 涵蓋一定範圍的影格，trace 則落在 cut 的影格範圍內：
+
+```
+cut 1:  frame 0-867      → trace_id 0-31    (32 traces)
+cut 2:  frame 868-973    → trace_id 35-45   (11 traces)
+cut 3:  frame 974-1073   → trace_id 46      (1 trace)
+```
+
+`trace_id` 是 **per-file global sequential**，不因 cut 重設。  
+同一個人的不同 cut 會得到不同的 trace_id（因為物體軌跡不連續），但 trace_id 是持續給號的。
+
+```
+cut 1 (camera A): frame 0-867     → trace_1 0~31
+cut 2 (camera B): frame 868-973   → trace_1 32~45  ← 繼續給號，不歸零
+cut 3 (camera C): frame 974-1073  → trace_1 46     ← 繼續給號
+```
+
+**唯一約束仍然是 `(file_uuid, trace_id)`**，`cut_id` 只是輔助查詢用的 scope 欄位。
+
+## 查詢
+
+```sql
+-- 列出所有 cuts
+SELECT id, cut_number, start_frame, end_frame, 
+       (end_frame - start_frame) as frames
+FROM cuts
+WHERE file_uuid = ?
+ORDER BY cut_number;
+
+-- 某個 cut 內的 traces
+SELECT DISTINCT fd.trace_id, count(*) as faces
+FROM face_detections fd
+WHERE fd.file_uuid = ? AND fd.cut_id = ?
+GROUP BY fd.trace_id
+ORDER BY fd.trace_id;
+```
+
+## 數量
+
+| File | Cuts | Faces per Cut (avg) |
+|------|:----:|:-------------------:|
+| `3abeee81...` | 70 | ~1,546 |