# 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 分鐘處理）
- 大量影片時建議分批上傳