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

docs/API_CURL_EXAMPLES.md

@@ -2,12 +2,23 @@
 
 | 項目 | 內容 |
 |------|------|
-| 版本 | V1.2 |
-| 日期 | 2026-03-23 |
+| 版本 | V1.4 |
+| 日期 | 2026-03-26 |
 | Base URL | `http://localhost:3002` |
 
 ---
 
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.4 | 2026-03-26 | 新增: 任務管理端點 (`/api/v1/jobs`, `/api/v1/jobs/:uuid`)，更新註冊端點回應格式 | OpenCode | deepseek-reasoner |
+| V1.3 | 2026-03-25 | 更新: n8n 搜尋回傳 `file_path` 取代 `media_url`，新增 API Key 驗證說明 | OpenCode | deepseek-reasoner |
+| V1.2 | 2026-03-23 | 建立 curl 範例文件 | Warren | OpenCode / MiniMax M2.5 |
+| V1.1 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
+
+---
+
 > **狀態說明**:
 > - ✅ **已實作**: 健康檢查、搜尋、影片管理端點
 > - ⚠️ **規劃中**: API Key 管理功能
@@ -76,6 +87,20 @@ sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
 
 ---
 
+## API 認證
+
+所有 `/api/v1/*` 端點（除了健康檢查）都需要 API Key 認證。請在請求標頭中加入：
+
+```
+-H "X-API-Key: YOUR_API_KEY"
+```
+
+**目前示範使用的 API Key**: `demo_api_key_12345`
+
+> **注意**: 正式環境請使用安全的 API Key 管理機制。
+
+---
+
 ## 1. 已實作端點
 
 ### 健康檢查
@@ -161,6 +186,7 @@ curl -X GET http://localhost:3002/api/v1/api-keys/stats \
 ```bash
 curl -X POST http://localhost:3002/api/v1/register \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"path": "/path/to/video.mp4"}'
 ```
 
@@ -168,30 +194,31 @@ curl -X POST http://localhost:3002/api/v1/register \
 
 ```json
 {
-  "id": 1,
   "uuid": "a1b2c3d4e5f6g7h8",
-  "file_path": "/path/to/video.mp4",
+  "video_id": 1,
+  "job_id": 123,
   "file_name": "video.mp4",
   "duration": 120.5,
   "width": 1920,
-  "height": 1080
+  "height": 1080,
+  "already_exists": false
 }
 ```
 
 ### 3.2 列出所有影片 ✅
 
 ```bash
-curl http://localhost:3002/api/v1/videos
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos
 ```
 
 ### 3.3 查詢影片 ✅
 
 ```bash
 # 依 UUID 查詢
-curl "http://localhost:3002/api/v1/lookup?uuid=a1b2c3d4e5f6g7h8"
+curl -H "X-API-Key: YOUR_API_KEY" "http://localhost:3002/api/v1/lookup?uuid=a1b2c3d4e5f6g7h8"
 
 # 依路徑查詢
-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"
 ```
 
 ### 3.4 處理影片 🔧 *(CLI - 非 API)*
@@ -209,7 +236,7 @@ cargo run --bin momentry -- process <uuid1> <uuid2> <uuid3>
 ### 3.5 取得處理進度 ✅
 
 ```bash
-curl http://localhost:3002/api/v1/progress/<uuid>
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/progress/<uuid>
 ```
 
 **回應範例**:
@@ -247,6 +274,67 @@ curl http://localhost:3002/api/v1/progress/<uuid>
 }
 ```
 
+### 3.6 任務管理 ✅
+
+```bash
+# 列出所有任務
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/jobs
+
+# 取得特定任務詳情
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/jobs/<uuid>
+```
+
+**任務列表回應範例**:
+```json
+{
+  "jobs": [
+    {
+      "id": 123,
+      "uuid": "a1b2c3d4e5f6g7h8",
+      "status": "pending",
+      "current_processor": null,
+      "progress_current": 0,
+      "progress_total": 100,
+      "created_at": "2026-03-26 10:30:00",
+      "started_at": null
+    }
+  ]
+}
+```
+
+**任務詳情回應範例**:
+```json
+{
+  "id": 123,
+  "uuid": "a1b2c3d4e5f6g7h8",
+  "status": "processing",
+  "current_processor": "asr",
+  "progress_current": 50,
+  "progress_total": 100,
+  "processors": [
+    {
+      "processor_type": "asr",
+      "status": "complete",
+      "started_at": "2026-03-26 10:30:00",
+      "completed_at": "2026-03-26 10:35:00",
+      "duration_secs": 300.5,
+      "error_message": null
+    },
+    {
+      "processor_type": "cut",
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "duration_secs": null,
+      "error_message": null
+    }
+  ],
+  "created_at": "2026-03-26 10:30:00",
+  "started_at": "2026-03-26 10:30:00",
+  "updated_at": "2026-03-26 10:35:00"
+}
+```
+
 ---
 
 ## 4. 查詢與搜索
@@ -256,6 +344,7 @@ curl http://localhost:3002/api/v1/progress/<uuid>
 ```bash
 curl -X POST http://localhost:3002/api/v1/search \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{
     "query": "測試關鍵字",
     "limit": 5
@@ -286,6 +375,7 @@ curl -X POST http://localhost:3002/api/v1/search \
 ```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": "測試關鍵字",
     "limit": 5
@@ -307,7 +397,7 @@ curl -X POST http://localhost:3002/api/v1/n8n/search \
       "title": "Chunk sentence_0006",
       "text": "fun plot twists...",
       "score": 0.92,
-      "media_url": "https://wp.momentry.ddns.net/video.mp4"
+      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
     }
   ]
 }
@@ -318,6 +408,7 @@ curl -X POST http://localhost:3002/api/v1/n8n/search \
 ```bash
 curl -X POST http://localhost:3002/api/v1/search/hybrid \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{
     "query": "測試關鍵字",
     "limit": 5
@@ -425,6 +516,8 @@ A: 需要將工作流程切換為 Active 狀態 (右上角開關)
 | `/api/v1/lookup` | GET | ✅ | 查詢影片 |
 | `/api/v1/videos` | GET | ✅ | 列出所有影片 |
 | `/api/v1/progress/:uuid` | GET | ✅ | 處理進度 |
+| `/api/v1/jobs` | GET | ✅ | 任務列表 |
+| `/api/v1/jobs/:uuid` | GET | ✅ | 任務詳情 |
 | `/api/v1/api-keys` | * | ⚠️ | API Key 管理 (規劃中) |
 
 ### C. 常見錯誤
@@ -475,11 +568,12 @@ curl -s "$API_URL/health" | jq .
 echo -e "\n=== Search ==="
 curl -s -X POST "$API_URL/api/v1/search" \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"query": "test", "limit": 3}' | jq .
 
 # 列出影片
 echo -e "\n=== Videos ==="
-curl -s "$API_URL/api/v1/videos" | jq '.videos | length'
+curl -s -H "X-API-Key: YOUR_API_KEY" "$API_URL/api/v1/videos" | jq '.videos | length'
 ```
 
 ---