feat: Initial v0.9 release with API Key authentication

## v0.9.20260325_144654 ### Features - API Key Authentication System - Job Worker System - V2 Backup Versioning ### Bug Fixes - get_processor_results_by_job column mapping Co-authored-by: OpenCode
2026-03-25 14:52:51 +08:00
parent 47e86b696f
commit 383201cacd
193 changed files with 40268 additions and 422 deletions
--- a/docs/API_N8N_GUIDE.md
+++ b/docs/API_N8N_GUIDE.md
@@ -0,0 +1,193 @@
+# n8n 呼叫 Momentry API 指南
+
+| 項目 | 內容 |
+|------|------|
+| 版本 | V1.0 |
+| 日期 | 2026-03-23 |
+| 用途 | 在 n8n workflow 中呼叫 Momentry API |
+
+---
+
+## API URL
+
+在 n8n HTTP Request Node 中，**請使用外部 URL**：
+
+```
+https://api.momentry.ddns.net
+```
+
+> ⚠️ **不要使用** `localhost:3002`，因為 n8n 需要從外部訪問 API。
+
+---
+
+## 常用端點
+
+| 方法 | 端點 | 說明 |
+|------|------|------|
+| GET | `/health` | 健康檢查 |
+| POST | `/api/v1/n8n/search` | 語意搜尋（推薦） |
+| GET | `/api/v1/videos` | 列出所有影片 |
+| GET | `/api/v1/lookup` | 查詢影片 |
+| GET | `/api/v1/progress/:uuid` | 處理進度 |
+
+---
+
+## HTTP Request Node 設定
+
+### 語意搜尋（推薦）
+
+```
+Node: HTTP Request
+├── URL: https://api.momentry.ddns.net/api/v1/n8n/search
+├── Method: POST
+├── Authentication: None
+├── Send Body: ✓ (checked)
+├── Content Type: JSON
+└── Body:
+    {
+      "query": "={{ $json.query }}",
+      "limit": "={{ $json.limit || 10 }}"
+    }
+```
+
+### 測試用（固定關鍵字）
+
+```
+Node: HTTP Request
+├── URL: https://api.momentry.ddns.net/api/v1/n8n/search
+├── Method: POST
+├── Send Body: ✓
+├── Content Type: JSON
+└── Body:
+    {
+      "query": "charade",
+      "limit": 3
+    }
+```
+
+---
+
+## 完整 Workflow 範例
+
+### 基本搜尋 Workflow
+
+```json
+{
+  "name": "Momentry Video Search",
+  "nodes": [
+    {
+      "parameters": {},
+      "name": "Manual Trigger",
+      "type": "n8n-nodes-base.manualTrigger",
+      "position": [250, 300]
+    },
+    {
+      "parameters": {
+        "url": "https://api.momentry.ddns.net/api/v1/n8n/search",
+        "method": "POST",
+        "sendBody": true,
+        "contentType": "json",
+        "body": {
+          "query": "charade",
+          "limit": 3
+        }
+      },
+      "name": "Search Video API",
+      "type": "n8n-nodes-base.httpRequest",
+      "position": [450, 300]
+    }
+  ],
+  "connections": {
+    "Manual Trigger": {
+      "main": [[{"node": "Search Video API"}]]
+    }
+  }
+}
+```
+
+---
+
+## 動態查詢 Workflow
+
+```json
+{
+  "name": "Momentry Dynamic Search",
+  "nodes": [
+    {
+      "parameters": {
+        "httpMethod": "POST",
+        "path": "search",
+        "responseMode": "lastNode"
+      },
+      "name": "Webhook",
+      "type": "n8n-nodes-base.webhook",
+      "position": [250, 300]
+    },
+    {
+      "parameters": {
+        "url": "https://api.momentry.ddns.net/api/v1/n8n/search",
+        "method": "POST",
+        "sendBody": true,
+        "contentType": "json",
+        "body": {
+          "query": "={{ JSON.stringify($json.body.query) }}",
+          "limit": "={{ $json.body.limit || 5 }}"
+        }
+      },
+      "name": "Search API",
+      "type": "n8n-nodes-base.httpRequest",
+      "position": [450, 300]
+    }
+  ],
+  "connections": {
+    "Webhook": {
+      "main": [[{"node": "Search API"}]]
+    }
+  }
+}
+```
+
+---
+
+## 常見錯誤
+
+### 錯誤: 502 Bad Gateway
+
+**原因**: API 服務未啟動
+
+**解決**:
+```bash
+sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
+```
+
+### 錯誤: "Your request is invalid"
+
+**原因**: Body 格式設定錯誤
+
+**正確設定**:
+- `Content Type`: JSON
+- `Body`: 必須是有效的 JSON 物件
+
+---
+
+## curl 測試
+
+在終端機中測試 API：
+
+```bash
+# 健康檢查
+curl https://api.momentry.ddns.net/health
+
+# 搜尋測試
+curl -X POST https://api.momentry.ddns.net/api/v1/n8n/search \
+  -H "Content-Type: application/json" \
+  -d '{"query":"charade","limit":3}'
+```
+
+---
+
+## 相關文件
+
+- [API_INDEX.md](./API_INDEX.md) - 文件總覽
+- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - 端點完整說明
+- [N8N_HTTP_REQUEST_GUIDE.md](./N8N_HTTP_REQUEST_GUIDE.md) - HTTP Request 詳細設定