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_TRAINING_MARCOM.md
+++ b/docs/API_TRAINING_MARCOM.md
@@ -0,0 +1,258 @@
+# Momentry Core API 教育訓練手冊
+
+> **對象**: marcom 團隊  
+> **版本**: V1.0 | **日期**: 2026-03-25
+
+---
+
+## 1. 快速開始
+
+### 基本資訊
+
+| 項目 | 值 |
+|------|-----|
+| API 網址 | `https://api.momentry.ddns.net` |
+| 認證方式 | Header `X-API-Key` |
+| 格式 | JSON |
+
+### API Key
+
+```
+X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69
+```
+
+---
+
+## 2. 快速範例
+
+### 查詢所有影片
+
+```bash
+curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
+  "https://api.momentry.ddns.net/api/v1/videos"
+```
+
+### 查詢單一影片
+
+```bash
+curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
+  "https://api.momentry.ddns.net/api/v1/videos/{uuid}"
+```
+
+### 查詢處理任務狀態
+
+```bash
+curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
+  "https://api.momentry.ddns.net/api/v1/jobs/{uuid}"
+```
+
+---
+
+## 3. API 端點說明
+
+### 3.1 影片相關
+
+#### GET /api/v1/videos
+取得所有影片列表
+
+**回應範例**:
+```json
+{
+  "videos": [
+    {
+      "uuid": "5dea6618a606e7c7",
+      "filename": "demo_video.mp4",
+      "duration": 123.45,
+      "status": "ready",
+      "created_at": "2026-03-25T10:00:00Z"
+    }
+  ]
+}
+```
+
+#### GET /api/v1/videos/:uuid
+取得單一影片詳情
+
+#### GET /api/v1/videos/:uuid/chunks
+取得影片的分段資訊
+
+**回應範例**:
+```json
+{
+  "chunks": [
+    {
+      "chunk_id": "time_00001",
+      "start_time": 0.0,
+      "end_time": 10.0,
+      "type": "time_based"
+    }
+  ]
+}
+```
+
+### 3.2 任務相關
+
+#### GET /api/v1/jobs/:uuid
+查詢處理任務狀態
+
+**回應範例**:
+```json
+{
+  "uuid": "9760d0820f0cf9a7",
+  "video_uuid": "5dea6618a606e7c7",
+  "status": "completed",
+  "progress": 100,
+  "created_at": "2026-03-25T10:00:00Z",
+  "completed_at": "2026-03-25T10:05:00Z"
+}
+```
+
+#### GET /api/v1/jobs
+查詢所有任務
+
+**查詢參數**:
+| 參數 | 說明 | 範例 |
+|------|------|------|
+| `status` | 篩選狀態 | `pending`, `processing`, `completed`, `failed` |
+| `limit` | 回傳數量 | `10` |
+
+**範例**:
+```bash
+curl -s -H "X-API-Key: ..." \
+  "https://api.momentry.ddns.net/api/v1/jobs?status=completed&limit=5"
+```
+
+### 3.3 健康檢查
+
+#### GET /health
+服務健康狀態（**無需認證**）
+
+**回應**:
+```json
+{
+  "status": "ok",
+  "version": "0.9.20260325_144654"
+}
+```
+
+---
+
+## 4. n8n Workflow 範例
+
+### 4.1 基本設定
+
+在 n8n workflow 中使用 HTTP Request 節點：
+
+```
+┌─────────────────┐
+│  HTTP Request   │
+├─────────────────┤
+│ Method: GET     │
+│ URL: https://api.momentry.ddns.net/api/v1/videos
+│ Headers:        │
+│   X-API-Key:    │
+│   [YOUR_KEY]    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  處理回應資料    │
+└─────────────────┘
+```
+
+### 4.2 範例：檢查任務狀態
+
+```javascript
+// n8n Function Node 範例
+const jobUuid = $input.item.json.uuid;
+
+return [{
+  json: {
+    method: "GET",
+    url: `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`,
+    headers: {
+      "X-API-Key": "YOUR_API_KEY"
+    }
+  }
+}];
+```
+
+### 4.3 範例：擷取影片分段
+
+```javascript
+const videoUuid = $input.item.json.uuid;
+
+return [{
+  json: {
+    method: "GET",
+    url: `https://api.momentry.ddns.net/api/v1/videos/${videoUuid}/chunks`,
+    headers: {
+      "X-API-Key": "YOUR_API_KEY"
+    }
+  }
+}];
+```
+
+---
+
+## 5. 常見問題
+
+### Q: 返回 401 錯誤怎麼辦？
+確認 Header 中有正確的 `X-API-Key` 值
+
+### Q: 如何確認影片處理完成？
+```
+GET /api/v1/jobs/{uuid}
+```
+檢查 `status` 是否為 `completed`
+
+### Q: 查不到資料？
+確認 UUID 格式正確（16碼 hex 字串）
+
+---
+
+## 6. 快速參考卡
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Momentry API 速查                        │
+├─────────────────────────────────────────────────────────────┤
+│  查詢所有影片      GET  /api/v1/videos                       │
+│  查詢單一影片      GET  /api/v1/videos/:uuid                │
+│  查詢影片分段      GET  /api/v1/videos/:uuid/chunks         │
+│  查詢任務狀態      GET  /api/v1/jobs/:uuid                  │
+│  查詢所有任務      GET  /api/v1/jobs                        │
+│  健康檢查          GET  /health (免認證)                    │
+├─────────────────────────────────────────────────────────────┤
+│  Header: X-API-Key: [YOUR_KEY]                             │
+│  URL: https://api.momentry.ddns.net                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 附錄：回應狀態說明
+
+### 任務狀態 (status)
+
+| 狀態 | 說明 |
+|------|------|
+| `pending` | 等待處理 |
+| `processing` | 處理中 |
+| `completed` | 已完成 |
+| `failed` | 處理失敗 |
+
+### 影片狀態 (status)
+
+| 狀態 | 說明 |
+|------|------|
+| `uploading` | 上傳中 |
+| `pending` | 等待處理 |
+| `processing` | 處理中 |
+| `ready` | 已就緒 |
+| `error` | 錯誤 |
+
+---
+
+**文件版本**: V1.0  
+**最後更新**: 2026-03-25