momentry_core/SYNC_V1.1.md

Sync Notes 2026-05-21

M5Max128 收到後需要做的事

cd ~/momentry_core
git pull origin main       # 拉取所有變更
cat SYNC_V1.1.md           # 閱讀此文件

# 資料庫變更（必須先執行，否則 worker 會 fail）
psql -U accusys -d momentry -c "ALTER TABLE public.pre_chunks ALTER COLUMN coordinate_index SET DEFAULT 0;"

# 重建 + 重啟
cargo build --release --bin momentry
./run-server-3002.sh

---

Bugs Fixed (13)

#	問題	根因	修復
1	GET /identity/:uuid/files 空資料	SQL 缺 REPLACE(uuid) + 缺 JOIN videos	改用 REPLACE(uuid::text...) + JOIN videos + frame_number/fps
2	GET /identity/:uuid/faces crash + 空	i64/INT4 型別不符 + 硬編碼 NULL/0	id::bigint、confidence::float8 + 真實欄位
3	GET /identity/:uuid crash	IdentityDetailRecord.id 是 i64 但 DB 是 INT4	id::bigint as id
4	GET /file/:uuid/identities 空	雙重 stub（handler + DB 都 Vec::new()）	完整實作 + 正確 total count
5	GET /identities/search?q=Louis 500	c.text_content NULL 但 Rust tuple 用 String	改 Option<String>
6	POST /search/universal person type first/last_time null	search_persons_internal 用 timestamp_secs	改 frame_number/fps + JOIN videos
7	faces/files/chunks total 不正確	total: data.len()	獨立 COUNT 查詢
8	GET /identity/:uuid/traces 無分頁	缺 page/page_size	新增 TracesQuery + LIMIT/OFFSET
9	身分比對 frame-level 不穩定	frame-level Qdrant	改 trace-level（AVG embedding per trace）
10	Charade face embedding 不在 Qdrant	沒跑 sync_face_embeddings	match API 自動 push + ANN search
11	無眼睛 face 推入 Qdrant	無 QC 過濾	face_landmark_qc.py --apply + Qdrant sync 過濾 qc_ok
12	TMDb 比對 dev/prod 不一致	Qdrant ANN 不同 collection	trace-level 改善穩定性
13	faces/files/chunks total 顯示 page_size	total: data.len()	改為獨立 COUNT 查詢

✨ 新功能 (6)

#	功能	說明
1	POST /api/v1/tmdb/fetch	從 TMDb 下載 cast → 建立 identity + json + jpg + Qdrant
2	POST /api/v1/agents/tmdb/match/:file_uuid	推 face → Qdrant ANN search → bind identity
3	GET /api/v1/identity/:uuid/status	檢查 identity.json + profile.jpg 是否存在
4	/health 新增 watcher/worker/時區	watcher_running、worker_running、system_timezone
5	SYSTEM_TIMEZONE config	自動偵測系統時區，可 MOMENTRY_TIMEZONE 覆蓋
6	GET /identity/:uuid/traces 分頁	?page=1&page_size=20

🔧 資料庫變更

-- 必須執行（否則 worker 的 CUT processor 會失敗）
ALTER TABLE public.pre_chunks ALTER COLUMN coordinate_index SET DEFAULT 0;

-- 選擇性（face_landmark_qc.py --apply 需要）
ALTER TABLE public.face_detections ADD COLUMN metadata jsonb DEFAULT '{}'::jsonb;

🗑️ 清理

• 刪除 2,769 個孤兒 person_xxx identity（無 face_detections）
• person_identities + person_appearances table 已 DROP

📂 主要檔案變更

檔案	說明
src/api/identity_api.rs	identity detail/files/faces total 修正 + status endpoint
src/api/identity_binding.rs	traces 分頁（新增 page/page_size/total）
src/api/server.rs	health 新增 watcher/worker/system_timezone
src/api/tmdb_api.rs	新檔案 — tmdb/fetch + match 端點
src/api/universal_search.rs	person search 改 frame_number/fps
src/core/config.rs	新增 SYSTEM_TIMEZONE
src/core/db/qdrant_db.rs	search_face_collection + sync_trace_embeddings + batch upsert
src/core/db/postgres_db.rs	get_identity_files/faces 修正 + get_file_identities 實作
src/core/tmdb/probe.rs	extract_movie_name 改進（只取 ( 前）
scripts/face_landmark_qc.py	新增 --apply + --schema 參數
Cargo.toml	reqwest 加 gzip feature