docs: clarify file_uuid vs identity_uuid across all API docs

docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md

@@ -41,7 +41,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
 - 單一實體下唯一 ID → `id`（`trace_id`, `chunk_id`, `face_id`）
 - 路徑尾端 → 動詞（`/video`, `/chunks`, `/bind`）
 - 集合列表 → **複數**（`/files`, `/identities`, `/resources`, `/faces`）
-- 單一資源操作 → **單數**（`/file/:uuid`, `/identity/:uuid`）
+- 單一資源操作 → **單數**（`/file/:file_uuid`, `/identity/:identity_uuid`）
 
 ## Legend
 
@@ -60,7 +60,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
 | 5 | GET | `/api/v1/stats/ingest` | Ingest statistics |
 | 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo service status |
 | 7 | GET | `/api/v1/stats/inference` | LLM/embedding health |
-| 8 | POST | `/api/v1/files/register` | Register video file → UUID |
+| 8 | POST | `/api/v1/files/register` | Register video file → file_uuid |
 | 9 | POST | `/api/v1/unregister` | Delete file + all data |
 | 10 | GET | `/api/v1/files/scan` | Scan directory for new files |
 | 11 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
@@ -98,7 +98,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
 |---|--------|-------|-------------|
 | 34 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
 | 35 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
-| 36 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge identities |
+| 36 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge identity :identity_uuid → target |
 
 ## Face Candidates (identities.rs)
 
@@ -111,7 +111,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
 | # | Method | Route | Description |
 |---|--------|-------|-------------|
 | 38 | POST | `/api/v1/search/smart` | Semantic search (EmbeddingGemma + pgvector) |
-| 39 | POST | `/api/v1/search/universal` | BM25 keyword search (requires uuid) |
+| 39 | POST | `/api/v1/search/universal` | BM25 keyword search (requires file_uuid) |
 | 40 | POST | `/api/v1/search/frames` | Frame-level search |
 
 ## Trace (trace_agent_api.rs)
@@ -155,7 +155,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
 | # | Method | Route | Description |
 |---|--------|-------|-------------|
 | 57 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunk results |
-| 58 | GET | `/api/v1/search/identity_text?q=&uuid=` | Full-text search → identity-bound chunks |
+| 58 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |
 
 ---
 

docs_v1.0/API_V1.0.0/API_DOCUMENTATION_V1.0.0.md

@@ -269,7 +269,7 @@ Response `200`:
 
 ```
 GET /api/v1/files
-Query: ?page=1&page_size=10&uuid=xxx
+Query: ?page=1&page_size=10&file_uuid=xxx
 ```
 
 Response `200`:

docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md

@@ -217,9 +217,9 @@ Two modes:
 
 ```bash
 # Normal mode
-curl -o trace.mp4 "http://localhost:3002/api/v1/file/{uuid}/trace/42/video?mode=normal"
+curl -o trace.mp4 "http://localhost:3002/api/v1/file/{file_uuid}/trace/42/video?mode=normal"
 # Debug mode
-curl -o trace_debug.mp4 "http://localhost:3002/api/v1/file/{uuid}/trace/42/video?mode=debug"
+curl -o trace_debug.mp4 "http://localhost:3002/api/v1/file/{file_uuid}/trace/42/video?mode=debug"
 ```
 
 Debug overlay shows at bottom-left:
@@ -248,7 +248,7 @@ Green bbox per face detection: actual frames `thickness=4`, interpolated `thickn
 | 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
 | 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
 | 41 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks |
-| 42 | GET | `/api/v1/search/identity_text?q=&uuid=` | Full-text search → identity chunks |
+| 42 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |
 
 ```bash
 curl "http://localhost:3002/api/v1/identities?page=1&page_size=3"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
@@ -276,7 +276,7 @@ curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2"  -H "X-A
 |---|--------|------|-------------|
 | 41 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
 | 42 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
-| 43 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge two identities |
+| 43 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge into another identity |
 
 ```bash
 curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_uuid":"3abeee81d94597629ed8cb943f182e94","face_id":"face_42"}'

docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md

@@ -27,16 +27,9 @@ sequenceDiagram
 flowchart LR
     A[上傳影片] --> B[POST /files/register]
     B --> C[取得 file_uuid]
-    C --> D[POST /file/:uuid/process]
-    D --> E{7 Processors}
-    E --> F[ASR]
-    E --> G[ASRX]
-    E --> H[CUT]
-    E --> I[FACE]
-    E --> J[OCR]
-    E --> K[POSE]
-    E --> L[YOLO]
-    F --> M[GET /progress/:uuid]
+    C --> D[POST /file/:file_uuid/process]
+    ...
+    F --> M[GET /progress/:file_uuid]
     G --> M
     H --> M
     I --> M
@@ -169,7 +162,7 @@ mindmap
     Identities
       GET /identities
       POST /identity
-      POST /identity/:uuid/bind
+      POST /identity/:identity_uuid/bind
     Agents
       POST /agents/translate
       POST /agents/5w1h/analyze

docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md

@@ -204,10 +204,10 @@ Green bbox: actual detection frames `thickness=4`, interpolated `thickness=1`.
 **Usage:**
 ```bash
 # Normal mode (default)
-curl -o trace.mp4 "https://host/api/v1/file/{uuid}/trace/{id}/video?mode=normal"
+curl -o trace.mp4 "https://host/api/v1/file/{file_uuid}/trace/{trace_id}/video?mode=normal"
 
 # Debug mode
-curl -o trace.mp4 "https://host/api/v1/file/{uuid}/trace/{id}/video?mode=debug"
+curl -o trace.mp4 "https://host/api/v1/file/{file_uuid}/trace/{trace_id}/video?mode=debug"
 ```
 
 ---