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

docs/API_WORDPRESS_GUIDE.md

@@ -2,12 +2,21 @@
 
 | 項目 | 內容 |
 |------|------|
-| 版本 | V1.0 |
-| 日期 | 2026-03-23 |
+| 版本 | V1.1 |
+| 日期 | 2026-03-25 |
 | 用途 | 在 WordPress 中呼叫 Momentry API |
 
 ---
 
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.1 | 2026-03-25 | 更新: n8n 搜尋回傳 `file_path` 取代 `media_url`，新增 API Key 驗證說明 | OpenCode | deepseek-reasoner |
+| V1.0 | 2026-03-23 | 創建 WordPress API 指南 | Warren | OpenCode / MiniMax M2.5 |
+
+---
+
 ## API URL
 
 在 WordPress 中呼叫 API，**請使用外部 URL**：
@@ -20,6 +29,20 @@ https://api.momentry.ddns.net
 
 ---
 
+## API 認證
+
+所有 `/api/v1/*` 端點（除了健康檢查）都需要 API Key 認證。請在請求標頭中加入：
+
+```
+'headers' => ['Content-Type' => 'application/json', 'X-API-Key' => 'YOUR_API_KEY']
+```
+
+**目前示範使用的 API Key**: `demo_api_key_12345`
+
+> **注意**: 正式環境請使用安全的 API Key 管理機制，避免在客戶端 JavaScript 中暴露 API Key。
+
+---
+
 ## 常用端點
 
 | 方法 | 端點 | 說明 |
@@ -45,7 +68,7 @@ $data = [
 ];
 
 $response = wp_remote_post($api_url, [
-    'headers' => ['Content-Type' => 'application/json'],
+    'headers' => ['Content-Type' => 'application/json', 'X-API-Key' => 'YOUR_API_KEY'],
     'body'    => json_encode($data),
     'timeout' => 30
 ]);
@@ -65,7 +88,10 @@ if (is_wp_error($response)) {
 <?php
 $api_url = 'https://api.momentry.ddns.net/api/v1/videos';
 
-$response = wp_remote_get($api_url, ['timeout' => 30]);
+$response = wp_remote_get($api_url, [
+    'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
+    'timeout' => 30
+]);
 
 if (!is_wp_error($response)) {
     $body = json_decode(wp_remote_retrieve_body($response), true);
@@ -83,7 +109,10 @@ if (!is_wp_error($response)) {
 $uuid = '5dea6618a606e7c7';
 $api_url = 'https://api.momentry.ddns.net/api/v1/lookup?uuid=' . $uuid;
 
-$response = wp_remote_get($api_url, ['timeout' => 30]);
+$response = wp_remote_get($api_url, [
+    'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
+    'timeout' => 30
+]);
 
 if (!is_wp_error($response)) {
     $video = json_decode(wp_remote_retrieve_body($response), true);
@@ -104,7 +133,7 @@ if (!is_wp_error($response)) {
 async function searchVideos(query, limit = 10) {
     const response = await fetch('https://api.momentry.ddns.net/api/v1/n8n/search', {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY' },
         body: JSON.stringify({ query, limit })
     });
     
@@ -132,6 +161,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([
@@ -144,7 +191,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']
@@ -164,10 +214,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']
         );
     }
@@ -199,7 +254,7 @@ add_action('rest_api_init', function() {
             $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'],
                     'body'    => json_encode([
                         'query' => $request->get_param('query'),
                         'limit' => $request->get_param('limit', 10)