fix: trace debug — show Stranger_NNN for unnamed traces instead of unknown

2026-05-14 15:12:21 +08:00
parent 8f013cbdbc
commit c90394897d
42 changed files with 1806 additions and 1722 deletions
--- a/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md
@@ -20,6 +20,8 @@ owner: "Warren"
 | Development | `http://localhost:3003` |
 | Auth | Header `X-API-Key: <key>` (login endpoint unprotected) |

+> **Note**: All examples below use production port 3002. For dev testing, replace `3002` with `3003`.
+
 ---

 ## 1. System
@@ -55,22 +57,32 @@ curl http://localhost:3002/health
 | 13 | GET | `/api/v1/file/:file_uuid` | Single file detail |
 | 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
 | 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
-| 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks |
+| 16 | GET | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) |
 | 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
 | 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) |

 ```bash
-curl -X POST http://localhost:3002/api/v1/files/register  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_path":"/sftpgo/data/demo/video.mp4"}'
+curl -X POST http://localhost:3002/api/v1/files/register  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_path":"/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"}'
 ```
 ```json
 {"success":true,"file_uuid":"3abeee81d94597629ed8cb943f182e94","duration":5954.0}
 ```

+```bash
+curl -X POST http://localhost:3002/api/v1/unregister \
+  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
+  -H "Content-Type: application/json" \
+  -d '{"uuid":"53e3a229bf68878b7a799e811e097f9c"}'
+```
+```json
+{"success":true,"uuid":"53e3a229bf68878b7a799e811e097f9c","message":"File unregistered successfully"}
+```
+
 ```bash
 curl "http://localhost:3002/api/v1/files?page=1&page_size=2" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
 ```
 ```json
-{"files":[{"file_name":"Charade (1963)..."}],"total":37}
+{"success":true,"data":[{"file_uuid":"aeed7134...","file_name":"Charade (1963)...","status":"ready"}],"total":0,"page":1,"page_size":2}
 ```

 ---
@@ -92,14 +104,14 @@ curl "http://localhost:3002/api/v1/files?page=1&page_size=2" -H "X-API-Key: muse
 curl -X POST http://localhost:3002/api/v1/search/universal  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"query":"name","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```
 ```json
-{"count":1,"results":[{"text":"What's your name?","score":0.90}]}
+{"query":"name","results":[{"chunk_id":"100","text":"What's your name?","start_time":258.68,"score":0.90}],"total":5,"page":1,"page_size":20,"took_ms":42}
 ```

 ```bash
 curl -X POST http://localhost:3002/api/v1/search/universal  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"query":"friends","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```
 ```json
-{"count":1,"results":[{"text":"You won't find it difficult to make some new friends.","score":0.90}]}
+{"query":"friends","results":[{"chunk_id":"104","text":"You won't find it difficult to make some new friends.","start_time":272.38,"score":0.90}],"total":3,"page":1,"page_size":20,"took_ms":38}
 ```

 ---
@@ -183,7 +195,7 @@ Returns MP4 video binary (3.0MB) with bbox overlay.
 curl "http://localhost:3002/api/v1/identities?page=1&page_size=3"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
 ```
 ```json
-{"identities":[
+{"count":3,"page":1,"page_size":3,"identities":[
  {"name":"Cary Grant","tmdb_id":2102},
  {"name":"Audrey Hepburn","tmdb_id":187},
  {"name":"Walter Matthau","tmdb_id":2091}
@@ -228,7 +240,7 @@ curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c
 curl "http://localhost:3002/api/v1/resources"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
 ```
 ```json
-{"resources":[{"resource_id":"mxbai-embed-large-v1","resource_type":"embedding_model"}]}
+{"success":true,"data":[{"resource_id":"mxbai-embed-large-v1","resource_type":"embedding_model"}],"message":"OK"}
 ```

 ---
--- a/docs_v1.0/API_V1.0.0/API_REFERENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/API_REFERENCE_v1.0.0.md
@@ -20,6 +20,8 @@ owner: "Warren"
 | Development | `http://localhost:3003` |
 | Auth | Header `X-API-Key: <key>` (login endpoint unprotected) |

+> **Note**: All examples below use production port 3002. For dev testing, replace `3002` with `3003`.
+
 ---

 ## 1. System
@@ -55,22 +57,32 @@ curl http://localhost:3002/health
 | 13 | GET | `/api/v1/file/:file_uuid` | Single file detail |
 | 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
 | 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
-| 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks |
+| 16 | GET | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) |
 | 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
 | 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) |

 ```bash
-curl -X POST http://localhost:3002/api/v1/files/register  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_path":"/sftpgo/data/demo/video.mp4"}'
+curl -X POST http://localhost:3002/api/v1/files/register  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_path":"/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"}'
 ```
 ```json
 {"success":true,"file_uuid":"3abeee81d94597629ed8cb943f182e94","duration":5954.0}
 ```

+```bash
+curl -X POST http://localhost:3002/api/v1/unregister \
+  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
+  -H "Content-Type: application/json" \
+  -d '{"uuid":"53e3a229bf68878b7a799e811e097f9c"}'
+```
+```json
+{"success":true,"uuid":"53e3a229bf68878b7a799e811e097f9c","message":"File unregistered successfully"}
+```
+
 ```bash
 curl "http://localhost:3002/api/v1/files?page=1&page_size=2" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
 ```
 ```json
-{"files":[{"file_name":"Charade (1963)..."}],"total":37}
+{"success":true,"data":[{"file_uuid":"aeed7134...","file_name":"Charade (1963)...","status":"ready"}],"total":0,"page":1,"page_size":2}
 ```

 ---
@@ -92,14 +104,14 @@ curl "http://localhost:3002/api/v1/files?page=1&page_size=2" -H "X-API-Key: muse
 curl -X POST http://localhost:3002/api/v1/search/universal  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"query":"name","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```
 ```json
-{"count":1,"results":[{"text":"What's your name?","score":0.90}]}
+{"query":"name","results":[{"chunk_id":"100","text":"What's your name?","start_time":258.68,"score":0.90}],"total":5,"page":1,"page_size":20,"took_ms":42}
 ```

 ```bash
 curl -X POST http://localhost:3002/api/v1/search/universal  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"query":"friends","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```
 ```json
-{"count":1,"results":[{"text":"You won't find it difficult to make some new friends.","score":0.90}]}
+{"query":"friends","results":[{"chunk_id":"104","text":"You won't find it difficult to make some new friends.","start_time":272.38,"score":0.90}],"total":3,"page":1,"page_size":20,"took_ms":38}
 ```

 ---
@@ -183,7 +195,7 @@ Returns MP4 video binary (3.0MB) with bbox overlay.
 curl "http://localhost:3002/api/v1/identities?page=1&page_size=3"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
 ```
 ```json
-{"identities":[
+{"count":3,"page":1,"page_size":3,"identities":[
  {"name":"Cary Grant","tmdb_id":2102},
  {"name":"Audrey Hepburn","tmdb_id":187},
  {"name":"Walter Matthau","tmdb_id":2091}
@@ -228,7 +240,7 @@ curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c
 curl "http://localhost:3002/api/v1/resources"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
 ```
 ```json
-{"resources":[{"resource_id":"mxbai-embed-large-v1","resource_type":"embedding_model"}]}
+{"success":true,"data":[{"resource_id":"mxbai-embed-large-v1","resource_type":"embedding_model"}],"message":"OK"}
 ```

 ---
--- a/docs_v1.0/API_V1.0.0/INTERNAL/API_DICTIONARY_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/API_DICTIONARY_V1.0.0.md
@@ -84,7 +84,7 @@ related_documents:
 | `GET` | `/api/v1/files` | Public |
 | `GET` | `/api/v1/files/scan` | Public |
 | `POST` | `/api/v1/files/register` | Public |
-| `POST` | `/api/v1/files/unregister` | Public |
+| `POST` | `/api/v1/unregister` | Public |
 | `GET` | `/api/v1/file/:file_uuid` | Public |
 | `GET` | `/api/v1/file/:file_uuid/probe` | Public |
 | `POST` | `/api/v1/file/:file_uuid/process` | Public |
--- a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_V1.0.0.md
@@ -63,7 +63,7 @@ curl $BASE/health
 | 13 | GET | `/api/v1/file/:file_uuid` | Single file detail |
 | 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
 | 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
-| 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks |
+| 16 | GET | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) |
 | 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
 | 18 | GET | `/api/v1/jobs` | Monitor jobs |

--- a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md
@@ -63,7 +63,7 @@ curl $BASE/health
 | 13 | GET | `/api/v1/file/:file_uuid` | Single file detail |
 | 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
 | 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
-| 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks |
+| 16 | GET | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) |
 | 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
 | 18 | GET | `/api/v1/jobs` | Monitor jobs |

--- a/docs_v1.0/REFERENCE/API_3002_VS_3003_COMPARISON.md
+++ b/docs_v1.0/REFERENCE/API_3002_VS_3003_COMPARISON.md
@@ -1,6 +1,6 @@
 # 3002 vs 3003 API 比較報告

-> **日期**: 2026-04-14 | **目的**: 分析正式版與開發版 API 差異
+**日期**: 2026-05-13 | **目的**: 正式版與開發版 API 差異（Release 前）

 ---

@@ -8,191 +8,50 @@

 | 項目 | 3002 (正式版) | 3003 (開發版) |
 |------|:---:|:---:|
-| **Build 日期** | 2026-04-13 00:29:25 | 2026-04-14 23:01:47 |
-| **程式碼狀態** | ❌ 舊版，缺少新 API | ✅ 最新版，包含所有新功能 |
-| **需要重新編譯** | ✅ 是 | ❌ 否 |
+| **Build 日期** | 2026-05-13 21:07 | 2026-05-13 (持續開發) |
+| **Version** | v1.0.0 | v1.0.0 |
+| **Build Git Hash** | `d34bcae+` | `d34bcae+` |
+| **程式碼狀態** | ✅ 同步（從 dev release binary） | ✅ 最新 |
+| **Schema** | `public`（需執行 `chunks→chunk` RENAME） | `dev` |

 ---

-## 2. API 端點可用性比較
+## 2. 共同端點（JSON 結構一致）

-### 2.1 完全相同的端點（JSON 結構一致）
-
-| 端點 | 3002 | 3003 | JSON 結構 |
-|------|:---:|:---:|:---:|
-| `GET /health` | ✅ 200 | ✅ 200 | ✅ 一致 |
-| `GET /api/v1/person/:id` | ✅ 200 | ✅ 200 | ✅ 一致 |
-| `GET /api/v1/chunks/:id/persons` | ✅ 200 | ✅ 200 | ✅ 一致 |
-| `GET /api/v1/face/list` | ✅ 200 | ✅ 200 | ✅ 一致 |
-| `GET /api/v1/face/:id` | ✅ 200 | ✅ 200 | ✅ 一致 |
-| `POST /api/v1/face/search` | ✅ 200 | ✅ 200 | ✅ 一致 |
-
-### 2.2 3002 缺少的端點
-
-| 端點 | 3002 | 3003 | 新增日期 |
-|------|:---:|:---:|:---:|
-| `GET /api/v1/person/list` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/person/auto-identify` | ❌ 405 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/person/suggest` | ❌ 405 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/person/merge` | ❌ 405 | ✅ 200/400 | 2026-04-14 |
-| `POST /api/v1/person/merge/undo` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `GET /api/v1/person/merge/history` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `GET /api/v1/person/:id/similar` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `PATCH /api/v1/person/:id/confirm` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/person/:id/unbind-speaker` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/person/:id/reassign-speaker` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/person/:id/remove-appearance` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/person/:id/reassign-appearance` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/person/:id/split` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/search/universal` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `POST /api/v1/search/frames` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `GET /api/v1/search/persons` | ❌ 404 | ✅ 200 | 2026-04-14 |
-| `GET /api/v1/person/:id/thumbnail` | ❌ 404 | ✅ 200 | 2026-04-14 |
+| 端點 | 3002 | 3003 | 備註 |
+|------|:---:|:---:|------|
+| `GET /health` | ✅ | ✅ | 含 `version` + `build_git_hash` |
+| `GET /health/detailed` | ✅ | ✅ | 同上 |
+| `GET /api/v1/files` | ✅ | ✅ | `total` 從 DB 讀取（不再寫死 0） |
+| `GET /api/v1/files/scan` | ✅ | ✅ | 含 `.jpg/.png` 掃描（不再限 mp4） |
+| `GET /api/v1/file/:uuid/process` | ✅ | ✅ | |
+| `GET /api/v1/file/:uuid/chunk/:id` | ✅ | ✅ | |
+| `GET /api/v1/identities` | ✅ | ✅ | 含分頁 |
+| `GET /api/v1/identities/:id` | ✅ | ✅ | |
+| `GET /api/v1/identity_bindings` | ✅ | ✅ | |
+| `POST /api/v1/search/universal` | ✅ | ✅ | |
+| `GET /api/v1/resources` | ✅ | ✅ | |
+| `GET /api/v1/traces/:tid/faces` | ✅ | ✅ | |
+| `GET /api/v1/traces/:tid/video` | ✅ | ✅ | |

 ---

-## 3. JSON 回應結構比較
+## 3. 差異

-### 3.1 GET /api/v1/person/:id (兩者一致)
-
-```json
-{
-  "success": "bool",
-  "person_id": "str",
-  "name": "str",
-  "face_identity_id": "null",
-  "speaker_id": "str|null",
-  "confidence": "float",
-  "appearance_count": "int",
-  "total_appearance_duration": "float",
-  "first_appearance_time": "float",
-  "last_appearance_time": "float",
-  "is_confirmed": "bool",
-  "created_at": "str",
-  "updated_at": "str"
-}
-```
-
-### 3.2 3003 獨有的 JSON 結構
-
-#### POST /api/v1/person/auto-identify
-```json
-{
-  "success": "bool",
-  "message": "str",
-  "total_persons": "int",
-  "matched_speakers": "int",
-  "persons": [{
-    "person_id": "str",
-    "name": "str|null",
-    "speaker_id": "str|null",
-    "appearance_count": "int",
-    "total_appearance_duration": "float",
-    "first_appearance_time": "float|null",
-    "last_appearance_time": "float|null",
-    "is_confirmed": "bool",
-    "speaker_confidence": "float|null"
-  }]
-}
-```
-
-#### POST /api/v1/person/suggest
-```json
-{
-  "success": "bool",
-  "naming_suggestions": [{
-    "person_id": "str",
-    "current_name": "str|null",
-    "suggested_name": "str",
-    "confidence": "float",
-    "sources": [{"type": "str", "detail": "str", "weight": "float"}],
-    "action": "str (auto_apply|needs_review)"
-  }],
-  "merge_suggestions": [{
-    "person_id": "str",
-    "merge_with": ["str"],
-    "confidence": "float",
-    "reasons": ["str"],
-    "action": "str"
-  }],
-  "total_naming": "int",
-  "total_merge": "int"
-}
-```
-
-#### POST /api/v1/search/universal
-```json
-{
-  "query": "str",
-  "results": [{
-    "type": "str (chunk|frame|person)",
-    // chunk 類型
-    "chunk_id": "str",
-    "chunk_type": "str",
-    "start_time": "float",
-    "end_time": "float",
-    "score": "float",
-    "text": "str|null",
-    "speaker_id": "str|null",
-    "metadata": "object"
-    // 或 frame 類型
-    // 或 person 類型
-  }],
-  "total": "int",
-  "took_ms": "int"
-}
-```
-
---
-
-## 4. 資料來源隔離
-
-| 層級 | 3002 | 3003 |
+| 項目 | 3002 | 3003 |
 |------|------|------|
-| PostgreSQL Schema | `public` | `dev` |
+| PostgreSQL Schema | `public`（需 rename `chunks→chunk`） | `dev`（已為 `chunk`） |
 | MongoDB Database | `momentry` | `momentry_dev` |
 | Redis Prefix | `momentry:` | `momentry_dev:` |
-| Qdrant Collection | `momentry_rule1` | `momentry_dev_rule1` |
+| Qdrant Collection Prefix | `momentry_` | `momentry_dev_` |
 | Output Dir | `/Users/accusys/momentry/output` | `/Users/accusys/momentry/output_dev` |
+| `.env` | `.env`（`DATABASE_SCHEMA=public`） | `.env.development`（`DATABASE_SCHEMA=dev`） |

 ---

-## 5. 部署建議
+## 4. Release 必要步驟

-### 3002 需要更新
-
-3002 運行的是 **2026-04-13** 的舊版程式碼，缺少 **17 個新 API 端點**。
-
-**更新步驟**:
-```bash
-# 1. 確認程式碼已是最新
-git status
-
-# 2. 重新編譯
-cargo build --release
-
-# 3. 停止舊版
-kill $(lsof -ti:3002)
-
-# 4. 啟動新版
-nohup cargo run --release --bin momentry -- server > /tmp/momentry_prod.log 2>&1 &
-
-# 5. 驗證
-curl http://localhost:3002/test-schema
-# 應回傳: SCHEMA=public
-
-curl http://localhost:3002/api/v1/person/list?limit=1
-# 應回傳: {"success":true,"persons":[...], "total":N}
-```
-
---
-
-## 6. 總結
-
-| 類別 | 狀態 |
-|------|------|
-| **程式碼版本** | 3002 落後 1 天 (2026-04-13 vs 2026-04-14) |
-| **API 端點** | 3002 缺少 17 個新端點 |
-| **JSON 結構** | 相同端點的 JSON 結構完全一致 |
-| **資料隔離** | ✅ 完全獨立 (public vs dev) |
-| **需要行動** | ✅ 3002 需要重新編譯部署 |
+1. **Binary**：使用 M5 交付的 `momentry_v1.0.0` 取代 port 3002 binary
+2. **Schema**：`ALTER TABLE public.chunks RENAME TO chunk;`
+3. **Deploy**：`bash deploy.sh`（9 步驟，含 vec0.dylib）
+4. **Identity**：保留 15 TMDB + merge dev data（`file_uuid` 欄位輔助）