feat: 新增 Job Worker 系統與 API 文檔全面更新

docs/API_REFERENCE.md

@@ -4,7 +4,7 @@
 |------|------|
 | 建立者 | Warren |
 | 建立時間 | 2026-03-18 |
-| 文件版本 | V1.0 |
+| 文件版本 | V1.3 |
 
 ---
 
@@ -15,6 +15,7 @@
 | V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
 | V1.1 | 2026-03-23 | 更新端點與實際一致 | OpenCode | - |
 | V1.2 | 2026-03-25 | 新增快取/刪除 API | OpenCode | - |
+| V1.3 | 2026-03-26 | 修正認證聲明與API回應格式 | OpenCode | - |
 
 ---
 
@@ -38,7 +39,22 @@
 
 ## Authentication
 
-Currently no authentication is required.
+**API Key 認證：**
+
+所有 `/api/v1/*` 端點需要 `X-API-Key` header 進行認證。
+
+**公開端點：**
+- `GET /health` - 健康檢查
+- `GET /health/detailed` - 詳細健康檢查
+
+**認證格式：**
+```bash
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos
+```
+
+**API Key 管理：**
+- 使用 `/api/v1/api-keys` 端點管理 API Keys
+- 詳細說明請參考 [API Key Management Guide](../docs/API_KEY_MANAGEMENT.md)
 
 ---
 
@@ -65,10 +81,12 @@ Register a video file to the system.
 {
   "uuid": "5dea6618a606e7c7",
   "video_id": 1,
+  "job_id": 10,
   "file_name": "video.mp4",
   "duration": 120.5,
   "width": 1920,
-  "height": 1080
+  "height": 1080,
+  "already_exists": false
 }
 ```
 
@@ -76,6 +94,7 @@ Register a video file to the system.
 ```bash
 curl -X POST http://localhost:3002/api/v1/register \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"path": "/Users/accusys/test_video/BigBuckBunny_320x180.mp4"}'
 ```
 
@@ -152,7 +171,7 @@ Get real-time processing progress via Redis.
 **Example:**
 ```bash
 # Get progress for specific video
-curl http://localhost:3002/api/v1/progress/5dea6618a606e7c7
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/progress/5dea6618a606e7c7
 ```
 
 ---
@@ -199,6 +218,7 @@ Search video chunks using natural language queries (RAG).
 ```bash
 curl -X POST http://localhost:3002/api/v1/search \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"query": "machine learning", "limit": 5}'
 ```
 
@@ -238,7 +258,7 @@ N8n-compatible search endpoint with standardized response format for direct work
       "title": "Sunset Scene",
       "text": "The sun slowly sets over the ocean...",
       "score": 0.92,
-      "media_url": "https://wp.momentry.ddns.net/video.mp4"
+      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
     }
   ]
 }
@@ -255,12 +275,13 @@ N8n-compatible search endpoint with standardized response format for direct work
 | `hits[].title` | string | Chunk title (from metadata or auto-generated) |
 | `hits[].text` | string | Text content |
 | `hits[].score` | number | Relevance score (0-1) |
-| `hits[].media_url` | string | Full media URL (optional) |
+| `hits[].file_path` | string | Full file path to video file |
 
 **Example:**
 ```bash
 curl -X POST http://localhost:3002/api/v1/n8n/search \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"query": "sunset", "limit": 5}'
 ```
 
@@ -296,10 +317,10 @@ Lookup video UUID by path or get video details by UUID.
 **Example:**
 ```bash
 # Lookup by path
-curl "http://localhost:3002/api/v1/lookup?path=/path/to/video.mp4"
+curl -H "X-API-Key: YOUR_API_KEY" "http://localhost:3002/api/v1/lookup?path=/path/to/video.mp4"
 
 # Lookup by UUID
-curl "http://localhost:3002/api/v1/lookup?uuid=5dea6618a606e7c7"
+curl -H "X-API-Key: YOUR_API_KEY" "http://localhost:3002/api/v1/lookup?uuid=5dea6618a606e7c7"
 ```
 
 ---
@@ -327,7 +348,7 @@ List all registered videos.
 
 **Example:**
 ```bash
-curl http://localhost:3002/api/v1/videos
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos
 ```
 
 ---