docs: M5 progress report — face tracker, bug fixes, pipeline

docs_v1.0/M4_workspace/2026-05-14_progress_report.md

@@ -0,0 +1,95 @@
+# M5 工作進度報告 — 2026-05-14
+
+**From**: M5
+**To**: M4
+
+---
+
+## 本次完成項目
+
+### 1. Face Tracker 5 層防護（scripts/utils/face_tracker.py）
+
+| 層 | 規則 | Commit |
+|:--:|------|--------|
+| CUT | 跨 scene cut 強制 split | `74f00d3` |
+| Embedding | sim < 0.5 + iou < 0.3 拒絕；fallback 0.6→0.75 | `70a796e` |
+| Bbox size | 面積 > 5× 且 sim < 0.8 拒絕 | `690254a` |
+| Edge exit | 邊緣→中央 且 sim < 0.8 拒絕 | `690254a` |
+| Frame gap | gap > 1 需 sim > 0.8 + iou > 0.2 | `70a796e` |
+| Same-position | iou > 0.35 + dist < 100（低 sim 也接受） | `3a7facd` |
+| Post-merge | 同 cut 內 centroid sim ≥ 0.75 合併 | `64bcfd7` |
+
+### 2. 重新執行完整 pipeline（多次迭代）
+
+| Run | Traces | Notes |
+|:---:|:-----:|-------|
+| 1 (before clean) | 70,691 (per-face) | 無 tracking |
+| 2 (after fix) | 9,825 | cut-aware + embedding |
+| 3 (iou fix) | 5,364 | iou>0.35 合併 |
+| 4 (cut merge) | **4,460** | 同 cut centroid 合併 |
+
+### 3. Bug Fixes
+
+| Bug | 狀態 |
+|-----|:--:|
+| swift_pose Y-flip 遺漏 | ✅ `ffc30d7` |
+| swift_ocr Y-flip + size | ✅ `ffc30d7` |
+| trace video 無音軌 | ✅ `-c:a aac` |
+| trace video bbox 超出最後檢測 | ✅ `9007e46` |
+| trace video frame number 顯示 | ✅ `ac96a42` |
+| trace video normal/debug mode | ✅ `8f877b4` |
+| trace_agent_api schema hardcode | ✅ `e8f44d7` |
+| face_detections 重複（-141,382） | ✅ |
+| gap merge 3132-3134 | ✅ |
+
+### 4. Database
+
+| 變更 | 說明 |
+|------|------|
+| `identities.file_uuid` column | backfill + 命名修正 |
+| `identity_bindings` per-file filter | `ib.identity_value IN (trace_ids)` |
+| TKG tables in data.sql | ✅ 已匯出 |
+| vec0.dylib | 包入 package |
+| identity pre-clean | Step 2/9 |
+| `chunk_vectors_chunk_id_key` DROP | ✅ 跨 file 不衝突 |
+
+### 5. Docs（6 新文件）
+
+| File | 用途 |
+|------|------|
+| `REFERENCE/DETECTOR_REGISTRY.md` | 25 detectors |
+| `REFERENCE/DETECTOR_SELECTION_SOP.md` | 選型標準 |
+| `REFERENCE/SPATIAL_COORDINATE_REGISTRY.md` | 6 層架構 |
+| `REFERENCE/IDENTITY_LIFECYCLE.md` | Identity 生命週期 |
+| `REFERENCE/DELIVERY_PROCEDURE.md` | 交付流程 v1.1 |
+| `REFERENCE/API_3002_VS_3003_COMPARISON.md` | 更新 |
+
+### 6. Commits（本 session, d34bcae → HEAD）
+
+```
+79e455c docs: deliver cut-based trace merge package
+64bcfd7 feat: merge traces within same cut — centroid similarity
+4e933a5 docs: reply to M4 on trace schema hardcode fix
+e8f44d7 fix: trace_agent_api.rs — replace dev.* with schema::table_name()
+995d925 docs: add trace video normal/debug mode to API reference
+8f877b4 feat: trace video normal/debug mode
+edadb02 docs: notify M4 of trace video mode param
+ac96a42 fix: correct frame number expression in trace video
+605d02a feat: trace video shows frame number overlay
+3a7facd fix: face tracker — add iou>0.35+dist<100 condition
+7e068f5 docs: reply to M4 deploy report
+11ec006 docs: reply to M4 --force request
+1023930 feat: deploy.sh --force flag
+d4386ab docs: notify M4 of binary + source delivery
+f482705 docs: deliver pipeline v2 package
+...
+
+Total: 40+ commits from d34bcae
+```
+
+## 已知待辦
+
+| 項目 | 優先級 |
+|------|:--:|
+| API doc vs actual field names 5 處差異 | 🟡 doc issue |
+| Version bump (1.0.0) | 🟢 待正式 release |