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

docs/API_EXAMPLES.md

@@ -2,13 +2,22 @@
 
 | 項目 | 內容 |
 |------|------|
-| 版本 | V2.0 |
-| 日期 | 2026-03-25 |
+| 版本 | V2.1 |
+| 日期 | 2026-03-26 |
 | Base URL (本地) | `http://localhost:3002` |
 | Base URL (外部) | `https://api.momentry.ddns.net` |
 
 ---
 
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 |
+|------|------|------|--------|
+| V2.0 | 2026-03-25 | 創建完整範例總覽 | OpenCode |
+| V2.1 | 2026-03-26 | 更新API回應格式 (media_url→file_path) 與認證標頭 | OpenCode |
+
+---
+
 ## 快速參考
 
 ### 環境 URL 選擇
@@ -105,16 +114,19 @@ curl http://localhost:3002/health/detailed
 # 標準格式搜尋
 curl -X POST http://localhost:3002/api/v1/search \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"query": "charade", "limit": 5}'
 
 # n8n 格式搜尋（推薦）
 curl -X POST http://localhost:3002/api/v1/n8n/search \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"query": "charade", "limit": 5}'
 
 # 混合搜尋
 curl -X POST http://localhost:3002/api/v1/search/hybrid \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"query": "charade", "limit": 5}'
 ```
 
@@ -150,7 +162,7 @@ curl -X POST http://localhost:3002/api/v1/search/hybrid \
       "title": "Chunk sentence_0001",
       "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"
     }
   ]
 }
@@ -160,26 +172,28 @@ curl -X POST http://localhost:3002/api/v1/search/hybrid \
 
 ```bash
 # 列出所有影片
-curl http://localhost:3002/api/v1/videos
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos
 
 # 查詢特定影片（依 UUID）
-curl "http://localhost:3002/api/v1/lookup?uuid=a1b10138a6bbb0cd"
+curl -H "X-API-Key: YOUR_API_KEY" "http://localhost:3002/api/v1/lookup?uuid=a1b10138a6bbb0cd"
 
 # 查詢特定影片（依路徑）
-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"
 
 # 取得處理進度
-curl http://localhost:3002/api/v1/progress/a1b10138a6bbb0cd
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/progress/a1b10138a6bbb0cd
 
 # 探測影片（不註冊）
 curl -X POST http://localhost:3002/api/v1/probe \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"path": "/path/to/video.mp4"}'
 
 # 註冊影片
 curl -X POST http://localhost:3002/api/v1/register \
   -H "Content-Type: application/json" \
-  -d '{"path": "/path/to/video.mp4", "file_name": "video.mp4"}'
+  -H "X-API-Key: YOUR_API_KEY" \
+  -d '{"path": "/path/to/video.mp4"}'
 ```
 
 ### 1.4 批次測試腳本
@@ -196,10 +210,11 @@ curl -s "$API_URL/health" | jq .
 echo -e "\n=== 語意搜尋 ==="
 curl -s -X POST "$API_URL/api/v1/search" \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"query": "charade", "limit": 3}' | jq .
 
 echo -e "\n=== 影片列表 ==="
-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'
 ```
 
 ### 1.5 外部 URL 範例
@@ -211,6 +226,7 @@ curl https://api.momentry.ddns.net/health
 # 外部搜尋
 curl -X POST https://api.momentry.ddns.net/api/v1/n8n/search \
   -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{"query": "charade", "limit": 5}'
 ```
 
@@ -227,11 +243,14 @@ Node: HTTP Request
 ├── Authentication: None
 ├── Send Body: ✓ (checked)
 ├── Content Type: JSON
-└── Body:
-    {
-      "query": "={{ $json.query }}",
-      "limit": "={{ $json.limit || 10 }}"
-    }
+├── Body:
+│   {
+│     "query": "={{ $json.query }}",
+│     "limit": "={{ $json.limit || 10 }}"
+│   }
+├── Send Headers: ✓ (checked)
+└── Header Parameters:
+    └── X-API-Key: {{ $env.MOMENTRY_API_KEY }}
 ```
 
 ### 2.2 基本搜尋 Workflow
@@ -460,6 +479,24 @@ searchVideos('charade', 5)
 
 ```php
 <?php
+// 將文件路徑轉換為可訪問的 URL
+function convert_file_path_to_url($file_path) {
+    // 範例: 將 SFTPGo 文件路徑轉換為 web URL
+    // /Users/accusys/momentry/var/sftpgo/data/demo/video.mp4
+    // → https://sftpgo.example.com/demo/video.mp4
+    
+    // 移除基本路徑
+    $base_path = '/Users/accusys/momentry/var/sftpgo/data/';
+    if (strpos($file_path, $base_path) === 0) {
+        $relative_path = substr($file_path, strlen($base_path));
+        // 替換為實際的 SFTPGo web URL
+        return 'https://sftpgo.example.com/' . $relative_path;
+    }
+    
+    // 如果無法轉換，返回原始路徑
+    return $file_path;
+}
+
 // 註冊短碼
 add_shortcode('momentry_search', function($atts) {
     $atts = shortcode_atts([
@@ -472,7 +509,10 @@ add_shortcode('momentry_search', function($atts) {
     }
     
     $response = wp_remote_post('https://api.momentry.ddns.net/api/v1/n8n/search', [
-        'headers' => ['Content-Type' => 'application/json'],
+        'headers' => [
+            'Content-Type' => 'application/json',
+            'X-API-Key' => 'YOUR_API_KEY'  // 替換為實際的 API Key
+        ],
         'body'    => json_encode([
             'query' => $atts['query'],
             'limit' => (int)$atts['limit']
@@ -492,10 +532,15 @@ add_shortcode('momentry_search', function($atts) {
     
     $output = '<ul class="momentry-results">';
     foreach ($data['hits'] as $hit) {
+        // 注意: API 現在返回 file_path 而非 media_url
+        // 需要將文件路徑轉換為可訪問的 URL
+        $file_path = $hit['file_path'];
+        $video_url = convert_file_path_to_url($file_path); // 需要實作此函數
+        
         $output .= sprintf(
             '<li>%s <a href="%s?start=%s">播放</a></li>',
             esc_html($hit['text']),
-            $hit['media_url'],
+            $video_url,
             $hit['start']
         );
     }
@@ -569,7 +614,7 @@ Body: {"query": "charade", "limit": 5}
       "title": "Chunk sentence_0001",
       "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"
     }
   ]
 }