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

docs/API_ACCESS.md

@@ -1,5 +1,23 @@
 # Momentry Core API 存取指南
 
+| 項目 | 內容 |
+|------|------|
+| 版本 | V1.3 |
+| 日期 | 2026-03-25 |
+| 用途 | API 存取方式、端點與整合指南 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.3 | 2026-03-25 | 更新: n8n 搜尋回傳 `file_path` 取代 `media_url`，新增 API Key 驗證說明 | OpenCode | deepseek-reasoner |
+| V1.2 | 2026-03-24 | 更新網址與服務列表 | Warren | OpenCode / MiniMax M2.5 |
+| V1.1 | 2026-03-23 | 初始版本 | Warren | OpenCode / MiniMax M2.5 |
+
+---
+
 ## 基本網址
 
 | 環境 | URL | 說明 |
@@ -20,7 +38,16 @@
 - 生產環境
 
 ## 認證
-目前為開放狀態（示範用途無需認證）。正式環境將實作 API Key。
+所有 `/api/v1/*` 端點（除了健康檢查 `/health` 與 `/health/detailed`）都需要 API Key 認證。
+
+請在請求標頭中加入：
+```
+X-API-Key: YOUR_API_KEY
+```
+
+**目前示範使用的 API Key**: `demo_api_key_12345`
+
+> **注意**: 正式環境請使用安全的 API Key 管理機制，避免在客戶端暴露 API Key。
 
 ---
 
@@ -91,12 +118,14 @@
       "title": "Chunk sentence_0006",
       "text": "fun plot twists...",
       "score": 0.526,
-      "media_url": "https://wp.momentry.ddns.net/Old_Time_Movie_Show_-_Charade_1963.HD.mov"
+      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/Old_Time_Movie_Show_-_Charade_1963.HD.mov"
     }
   ]
 }
 ```
 
+> **注意**: API 現在返回 `file_path`（檔案系統路徑）而非 `media_url`（網頁 URL）。如需在網頁中播放影片，請將檔案路徑轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）。
+
 ---
 
 ## 影片管理 API
@@ -134,7 +163,10 @@
 ```javascript
 const response = await fetch('http://localhost:3002/api/v1/search', {
   method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
+  headers: { 
+    'Content-Type': 'application/json',
+    'X-API-Key': 'YOUR_API_KEY'  // 替換為實際的 API Key
+  },
   body: JSON.stringify({ query: 'charade', limit: 5 })
 });
 const data = await response.json();
@@ -149,7 +181,10 @@ curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
   'query' => 'charade',
   'limit' => 5
 ]));
-curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
+curl_setopt($ch, CURLOPT_HTTPHEADER, [
+  'Content-Type: application/json',
+  'X-API-Key: YOUR_API_KEY'  // 替換為實際的 API Key
+]);
 $response = curl_exec($ch);
 $data = json_decode($response, true);
 ```
@@ -158,10 +193,12 @@ $data = json_decode($response, true);
 
 ## 影片嵌入網址
 
-影片可透過 SFTPGo 分享連結存取：
-```
-https://wp.momentry.ddns.net/{檔案名稱}
-```
+> **重要**: API 現在返回 `file_path`（檔案系統路徑），而非直接可訪問的網址。您需要將檔案路徑轉換為 SFTPGo 分享連結才能嵌入影片。
+
+**檔案路徑轉換為網址：**
+- API 返回的 `file_path` 範例：`/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4`
+- 對應的 SFTPGo 分享連結：`https://wp.momentry.ddns.net/demo/video.mp4`
+- 轉換方式：移除 `/Users/accusys/momentry/var/sftpgo/data/` 前綴，將剩餘路徑附加到 `https://wp.momentry.ddns.net/`
 
 **手動建立分享連結：**
 1. 開啟 SFTPGo Web UI：`http://localhost:8080`