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

docs/MOMENTRY_RAG_PRESENTATION.md

@@ -1,5 +1,22 @@
 # Momentry Core 影片 RAG 系統說明稿
 
+| 項目 | 內容 |
+|------|------|
+| 建立者 | Warren |
+| 建立時間 | 2026-03-22 |
+| 文件版本 | V1.1 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
+| V1.1 | 2026-03-25 | 更新API回應格式 (media_url→file_path) 與認證標頭 | OpenCode | deepseek-reasoner |
+
+---
+
 ## 系統架構
 
 ```
@@ -85,22 +102,9 @@ POST http://localhost:3002/api/v1/search
 }
 ```
 
-**回應：**
-```json
-{
-  "results": [
-    {
-      "uuid": "a1b10138a6bbb0cd",
-      "chunk_id": "sentence_0006",
-      "chunk_type": "sentence",
-      "start_time": 48.8,
-      "end_time": 55.44,
-      "text": "fun plot twists, Woody Dialog and charming performances...",
-      "score": 0.526
-    }
-  ]
-}
-```
+> **注意**: 
+> 1. **API 認證**: 所有 `/api/v1/*` 端點需要 `X-API-Key` 標頭
+> 2. **檔案路徑轉換**: API 現在返回 `file_path`（檔案系統路徑），需要轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）
 
 ---
 
@@ -132,7 +136,7 @@ POST http://localhost:3002/api/v1/n8n/search
       "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/video.mp4"
     }
   ]
 }
@@ -187,6 +191,7 @@ POST http://localhost:3002/api/v1/n8n/search
    Method: POST
    URL: http://localhost:3002/api/v1/n8n/search
    Body Content Type: JSON
+   Headers: X-API-Key (需設定)
    ```
 
 3. Body:
@@ -215,12 +220,17 @@ const results = hits.map((hit, index) => ({
   text: hit.text,
   time: `${hit.start}s - ${hit.end}s`,
   score: Math.round(hit.score * 100) + "%",
-  url: hit.media_url + "#t=" + hit.start + "," + hit.end
+  // 注意: API 現在返回 file_path（檔案系統路徑），需要轉換為可訪問的 URL
+  url: hit.file_path + "#t=" + hit.start + "," + hit.end // 需實作檔案路徑轉換為 URL
 }));
 
 return { json: { results } };
 ```
 
+> **注意**: 
+> 1. **API 認證**: 所有 `/api/v1/*` 端點需要 `X-API-Key` 標頭
+> 2. **檔案路徑轉換**: API 現在返回 `file_path`（檔案系統路徑），需要轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）
+
 ---
 
 ### Step 4: 格式化輸出
@@ -248,18 +258,20 @@ return { json: { results } };
 # 語意搜尋
 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": 3}'
 
 # 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": 3}'
 
 # 影片列表
-curl http://localhost:3002/api/v1/videos
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos
 
 # 特定影片區塊
-curl http://localhost:3002/api/v1/videos/a1b10138a6bbb0cd/chunks
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos/a1b10138a6bbb0cd/chunks
 ```
 
 ---