M4: bug report - video endpoints 500 (trace, bbox, thumbnail)

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

@@ -0,0 +1,40 @@
+# Bug: Video Endpoints Return HTTP 500
+
+## 發現時間
+
+2026-05-08 demo 驗證時
+
+## 症狀
+
+以下 endpoint 回傳 HTTP 500（dev 3003 與 production domain 皆受影響）：
+
+| Endpoint | HTTP |
+|----------|------|
+| `GET /file/:uuid/trace/:id/video` | 500 |
+| `GET /file/:uuid/video/bbox` | 500 |
+| `GET /file/:uuid/thumbnail` | timeout |
+
+## 已排除的原因
+
+| 可能原因 | 檢查結果 |
+|---------|---------|
+| ffmpeg 不存在 | ✅ `/opt/homebrew/bin/ffmpeg` 存在 |
+| ffmpeg 無法處理檔案 | ✅ 直接執行 ffmpeg 可輸出 frame |
+| 視訊檔案不存在 | ✅ 檔案存在 624MB |
+| 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
+
+## 相關檔案
+
+| 檔案 | 行號 |
+|------|------|
+| `src/api/media_api.rs` | 184, 333, 393, 501 (ffmpeg calls) |
+| `src/api/media_api.rs` | 102 (bbox handler) |
+| `src/api/media_api.rs` | 236 (trace video handler) |
+| `src/api/media_api.rs` | 478 (thumbnail handler) |