feat: backup architecture docs, source code, and scripts

2026-04-25 17:15:45 +08:00
parent 59809dae1f
commit 1f84e5469f
368 changed files with 146329 additions and 261 deletions
@@ -0,0 +1,266 @@
+---
+document_type: "implementation_guide"
+service: "N8N"
+title: "n8n 整合範例"
+date: "2026-03-18"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+  - "整合範例"
+ai_query_hints:
+  - "查詢 n8n 整合範例 的內容"
+  - "n8n 整合範例 的主要目的是什麼？"
+  - "如何操作或實施 n8n 整合範例？"
+---
+
+# n8n 整合範例
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | Warren |
+| 建立時間 | 2026-03-18 |
+| 文件版本 | V1.1 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
+| V1.1 | 2026-03-25 | 更新API回應格式 (media_url→file_path) 與認證標頭 | OpenCode | deepseek-reasoner |
+
+---
+
+## 基本設定
+
+### API 端點
+- **Base URL:** `http://localhost:3002/api/v1`
+- **Method:** `POST`
+- **Content-Type:** `application/json`
+- **Authentication:** `X-API-Key: YOUR_API_KEY` (所有 `/api/v1/*` 端點皆需要)
+
+---
+
+## Workflow 1: 基礎搜尋
+
+### Trigger: Manual / Webhook
+
+```
+[Manual Trigger] 
+     ↓
+[HTTP Request] → POST http://localhost:3002/api/v1/search
+     ↓
+[Set] → 設定搜尋詞 "charade"
+     ↓
+[Code] → 處理回傳結果
+     ↓
+[Respond]
+```
+
+### HTTP Request 設定
+```json
+{
+  "url": "http://localhost:3002/api/v1/search",
+  "method": "POST",
+  "body": {
+    "query": "={{ $json.searchTerm }}",
+    "limit": 5
+  },
+  "options": {
+    "headers": {
+      "Content-Type": "application/json",
+      "X-API-Key": "YOUR_API_KEY"
+    }
+  }
+}
+```
+
+### Code (處理結果)
+```javascript
+const results = $input.first().json.results;
+
+const videoUrl = "https://wp.momentry.ddns.net/Old_Time_Movie_Show_-_Charade_1963.HD.mov";
+
+return results.map(r => ({
+  chunk_id: r.chunk_id,
+  text: r.text,
+  start: r.start_time,
+  end: r.end_time,
+  score: r.score,
+  video_url: `${videoUrl}#t=${r.start_time},${r.end_time}`
+}));
+```
+
+---
+
+## Workflow 2: n8n 專用格式
+
+使用 `/n8n/search` 端點（已包含 file_path）
+
+### HTTP Request
+```json
+{
+  "url": "http://localhost:3002/api/v1/n8n/search",
+  "method": "POST",
+  "body": {
+    "query": "={{ $json.searchTerm }}",
+    "limit": 5
+  },
+  "options": {
+    "headers": {
+      "Content-Type": "application/json",
+      "X-API-Key": "YOUR_API_KEY"
+    }
+  }
+}
+```
+
+### 回傳格式
+```json
+{
+  "query": "charade",
+  "count": 5,
+  "hits": [
+    {
+      "id": "sentence_0006",
+      "vid": "a1b10138a6bbb0cd",
+      "start": 48.8,
+      "end": 55.44,
+      "title": "Chunk sentence_0006",
+      "text": "fun plot twists...",
+      "score": 0.526,
+      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
+    }
+  ]
+}
+```
+
+> **注意**: API 現在返回 `file_path`（檔案系統路徑）而非 `media_url`（網頁 URL）。如需在網頁中播放影片，請將檔案路徑轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）。
+
+---
+
+## Workflow 3: 訊息機器人整合
+
+### Telegram Bot 範例
+
+```
+[Webhook: Telegram]
+     ↓
+[Extract: /search charade]
+     ↓
+[HTTP Request] → POST /api/v1/search
+     ↓
+[Format Response]
+     ↓
+[Telegram: Send Message]
+```
+
+### 回傳格式
+```
+🎬 搜尋結果: "charade"
+
+1. "fun plot twists, Woody Dialog and charming performances..."
+   ⏱ 48.8s - 55.4s
+   📊 分數: 0.526
+   
+2. "Don't you like me to say that a pretty girl..."
+   ⏱ 4745.6s - 4748.6s
+   📊 分數: 0.525
+```
+
+---
+
+## Workflow 4: 多影片搜尋
+
+### 取得所有影片
+```
+[HTTP Request]
+GET http://localhost:3002/api/v1/videos
+```
+
+### 依 UUID 篩選
+```json
+{
+  "query": "charade",
+  "limit": 5,
+  "uuid": "a1b10138a6bbb0cd"
+}
+```
+
+---
+
+## Workflow 5: 定時更新
+
+```
+[Cron: 每小時]
+     ↓
+[HTTP Request] → GET /api/v1/videos
+     ↓
+[Loop Over Items]
+     ↓
+[Check: 新影片?]
+     ↓
+[Process: 執行 vectorize]
+```
+
+---
+
+## 實用場景
+
+### 1. 客服機器人
+用戶問「這部片在哪一段有談到 charade？」
+→ 搜尋 API → 回傳時戳 → 直接播放該片段
+
+### 2. 內容推薦
+根據用戶輸入的關鍵字，找到相關影片片段
+
+### 3. 自動化剪輯
+搜尋多個片段 → 組合成精華影片
+
+---
+
+## 錯誤處理
+
+```javascript
+const response = $input.first();
+
+if (!response.json.results || response.json.results.length === 0) {
+  return {
+    success: false,
+    message: "找不到相關結果"
+  };
+}
+
+return {
+  success: true,
+  count: response.json.results.length,
+  data: response.json.results
+};
+```
+
+---
+
+## 測試用 cURL
+
+```bash
+# 基本搜尋
+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 -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos
+
+# 取得特定影片的區塊
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos/a1b10138a6bbb0cd/chunks
+```