M4: update bug report - found root cause ARG_MAX overflow

docs_v1.0/M4_workspace/2026-05-08_bug_video_endpoints_500.md

@@ -24,11 +24,15 @@
 | UUID 不存在於 DB | ✅ `public.videos` 與 `dev.videos` 皆有 |
 | launchd PATH | ❌ 但 dev server (3003) 也有相同問題 |
 
-## 建議調查方向
+## 根因
 
-1. `src/api/media_api.rs` 中 `std::process::Command::new("ffmpeg")` 使用相對路徑，應確認實際執行時的 working directory
-2. Unicode 檔名 `│` (U+2502) 在 subprocess 中可能被錯誤解碼
-3. 檢查 `trace_video()`、`bbox_overlay_video()`、`face_thumbnail()` 三個 handler 的錯誤處理是否有 panic
+`trace_video()` 為每個 trace 的所有 detection 產生 ffmpeg filter_complex 字串。trace #3128 有 1109 個 detection，filter 字串超過 macOS ARG_MAX (~256KB)，導致 ffmpeg 執行失敗。
+
+**驗證**: trace #2 (1 det) → ✅ 200, trace #5 (2 dets) → ✅ 200, trace #3128 (1109 dets) → ❌ 500
+
+## 建議修正
+
+將 ffmpeg filter 寫入暫存檔 (`-filter_complex_script`) 而不是 command line 參數，避開 ARG_MAX 限制。
 
 ## 相關檔案