docs: add training manual and workflow guide for marcom team

2026-03-25 15:27:47 +08:00
parent 845704724f
commit f5436c7b63
2 changed files with 459 additions and 0 deletions
--- a/docs/API_WORKFLOW_WORDPRESS_N8N.md
+++ b/docs/API_WORKFLOW_WORDPRESS_N8N.md
@@ -0,0 +1,201 @@
+# Momentry API 使用流程
+
+> **目標**: 從影片上傳到搜尋的完整流程  
+> **適用**: WordPress / n8n 整合
+
+---
+
+## 流程總覽
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  1. 上傳    │ →  │  2. 註冊    │ →  │  3. 確認    │ →  │  4. 處理    │ →  │  5. 搜尋    │
+│  SFTPGo     │    │  自動完成    │    │  UUID       │    │  查詢進度   │    │  測試       │
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+```
+
+---
+
+## Step 1: 上傳影片
+
+### 方式 A: SFTP 上傳（推薦）
+
+```bash
+# 連線資訊
+主機: momentry.ddns.net
+連接埠: 2022
+用戶名: demo
+密碼: demopassword123
+```
+
+使用 FileZilla 或 SFTP 客戶端上傳到 `/` 目錄
+
+### 方式 B: SFTP 命令列
+
+```bash
+sshpass -p "demopassword123" sftp -P 2022 demo@momentry.ddns.net
+```
+
+上傳後確認檔案在 SFTPGo 中的位置
+
+---
+
+## Step 2: 自動註冊
+
+上傳後，系統會自動：
+1. 偵測新檔案
+2. 計算 UUID（SHA256）
+3. 建立資料庫記錄
+
+**無需手動操作**
+
+---
+
+## Step 3: 確認註冊成功
+
+### 查詢所有影片
+
+```bash
+curl -s -H "X-API-Key: YOUR_API_KEY" \
+  "https://api.momentry.ddns.net/api/v1/videos" | jq '.videos | length'
+```
+
+### 查詢特定檔案
+
+```bash
+curl -s -H "X-API-Key: YOUR_API_KEY" \
+  "https://api.momentry.ddns.net/api/v1/videos" | jq '.videos[] | select(.file_name | contains("你的檔案名"))'
+```
+
+### 預期回應
+
+```json
+{
+  "uuid": "952f5854b9febad1",
+  "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/你的檔案.mp4",
+  "file_name": "你的檔案.mp4",
+  "duration": 123.45,
+  "width": 1920,
+  "height": 1080
+}
+```
+
+**確認要點**:
+- ✅ UUID 已產生（16位 hex）
+- ✅ `file_path` 正確
+- ✅ `duration` > 0
+
+---
+
+## Step 4: 查詢處理進度
+
+### 取得任務 UUID
+
+```bash
+# 從影片資訊取得 job_id
+curl -s -H "X-API-Key: YOUR_API_KEY" \
+  "https://api.momentry.ddns.net/api/v1/videos" | \
+  jq '.videos[] | select(.file_name == "你的檔案.mp4") | {uuid, job_id}'
+```
+
+### 查詢任務狀態
+
+```bash
+curl -s -H "X-API-Key: YOUR_API_KEY" \
+  "https://api.momentry.ddns.net/api/v1/jobs/{uuid}"
+```
+
+### 任務狀態說明
+
+| status | 說明 | 動作 |
+|--------|------|------|
+| `pending` | 等待處理 | 等待中 |
+| `processing` | 處理中 | 繼續輪詢 |
+| `completed` | 已完成 | 可進入 Step 5 |
+| `failed` | 處理失敗 | 檢查錯誤 |
+
+### n8n 輪詢範例
+
+```javascript
+// n8n Workflow: 檢查處理狀態
+const jobUuid = $input.item.json.job_uuid;
+
+const response = await fetch(
+  `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`,
+  {
+    headers: {
+      "X-API-Key": "YOUR_API_KEY"
+    }
+  }
+);
+
+const job = await response.json();
+
+// 狀態檢查
+if (job.status === 'completed') {
+  return [{ json: { done: true, video_uuid: job.video_uuid } }];
+} else {
+  return [{ json: { done: false, status: job.status } }];
+}
+```
+
+---
+
+## Step 5: 搜尋測試
+
+處理完成後，資料會入庫到向量資料庫，可進行搜尋測試。
+
+### 測試向量搜尋
+
+```bash
+curl -s -X POST "https://api.momentry.ddns.net/api/v1/search" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "測試關鍵字",
+    "top_k": 5
+  }'
+```
+
+---
+
+## 完整 n8n Workflow 範例
+
+```
+┌──────────────┐
+│  觸發 (定時)  │
+└──────┬───────┘
+       ▼
+┌──────────────┐     ┌──────────────┐
+│  查詢影片     │────►│  比對新檔案   │
+│  /videos     │     │              │
+└──────┬───────┘     └──────────────┘
+       │                   │
+       ▼                   ▼
+┌──────────────┐     ┌──────────────┐
+│  等待處理     │◄────│  輪詢任務狀態  │
+│  /jobs/:uuid │     │  /jobs/:uuid │
+└──────┬───────┘     └──────────────┘
+       │
+       ▼ (completed)
+┌──────────────┐
+│  搜尋測試     │
+│  /search     │
+└──────────────┘
+```
+
+---
+
+## 快速參考
+
+| 步驟 | API | 用途 |
+|------|-----|------|
+| 查詢影片 | `GET /api/v1/videos` | 確認上傳成功 |
+| 查詢任務 | `GET /api/v1/jobs/:uuid` | 查看處理進度 |
+| 搜尋內容 | `POST /api/v1/search` | 測試搜尋功能 |
+
+---
+
+**注意**: 
+- 處理時間視影片長度而定（1分鐘影片約需 2-5 分鐘處理）
+- 大量影片時建議分批上傳