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_WORDPRESS_GUIDE.md
+++ b/docs/API_WORDPRESS_GUIDE.md
@@ -0,0 +1,270 @@
+# WordPress 呼叫 Momentry API 指南
+
+| 項目 | 內容 |
+|------|------|
+| 版本 | V1.0 |
+| 日期 | 2026-03-23 |
+| 用途 | 在 WordPress 中呼叫 Momentry API |
+
+---
+
+## API URL
+
+在 WordPress 中呼叫 API，**請使用外部 URL**：
+
+```
+https://api.momentry.ddns.net
+```
+
+> ⚠️ WordPress 運行於瀏覽器端，無法直接訪問 `localhost`。
+
+---
+
+## 常用端點
+
+| 方法 | 端點 | 說明 |
+|------|------|------|
+| GET | `/health` | 健康檢查 |
+| POST | `/api/v1/search` | 語意搜尋（標準格式） |
+| GET | `/api/v1/videos` | 列出所有影片 |
+| GET | `/api/v1/lookup` | 查詢影片 |
+
+---
+
+## PHP 範例
+
+### 基本搜尋
+
+```php
+<?php
+$api_url = 'https://api.momentry.ddns.net/api/v1/n8n/search';
+
+$data = [
+    'query' => 'charade',
+    'limit' => 10
+];
+
+$response = wp_remote_post($api_url, [
+    'headers' => ['Content-Type' => 'application/json'],
+    'body'    => json_encode($data),
+    'timeout' => 30
+]);
+
+if (is_wp_error($response)) {
+    echo '錯誤: ' . $response->get_error_message();
+} else {
+    $body = json_decode(wp_remote_retrieve_body($response), true);
+    print_r($body['hits']);
+}
+?>
+```
+
+### 列出所有影片
+
+```php
+<?php
+$api_url = 'https://api.momentry.ddns.net/api/v1/videos';
+
+$response = wp_remote_get($api_url, ['timeout' => 30]);
+
+if (!is_wp_error($response)) {
+    $body = json_decode(wp_remote_retrieve_body($response), true);
+    foreach ($body['videos'] as $video) {
+        echo $video['file_name'] . "\n";
+    }
+}
+?>
+```
+
+### 查詢特定影片
+
+```php
+<?php
+$uuid = '5dea6618a606e7c7';
+$api_url = 'https://api.momentry.ddns.net/api/v1/lookup?uuid=' . $uuid;
+
+$response = wp_remote_get($api_url, ['timeout' => 30]);
+
+if (!is_wp_error($response)) {
+    $video = json_decode(wp_remote_retrieve_body($response), true);
+    echo '檔案: ' . $video['file_name'] . "\n";
+    echo '時長: ' . $video['duration'] . ' 秒';
+}
+?>
+```
+
+---
+
+## JavaScript 範例
+
+### 使用 fetch
+
+```javascript
+// 搜尋影片
+async function searchVideos(query, limit = 10) {
+    const response = await fetch('https://api.momentry.ddns.net/api/v1/n8n/search', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ query, limit })
+    });
+    
+    if (!response.ok) {
+        throw new Error('API 請求失敗');
+    }
+    
+    return await response.json();
+}
+
+// 使用範例
+searchVideos('charade', 5)
+    .then(data => {
+        data.hits.forEach(hit => {
+            console.log(`${hit.text} (score: ${hit.score})`);
+        });
+    });
+```
+
+---
+
+## WordPress Shortcode 範例
+
+在 `functions.php` 中註冊短碼：
+
+```php
+<?php
+// 註冊短碼
+add_shortcode('momentry_search', function($atts) {
+    $atts = shortcode_atts([
+        'query' => '',
+        'limit' => '10'
+    ], $atts);
+    
+    if (empty($atts['query'])) {
+        return '<p>請提供搜尋關鍵字</p>';
+    }
+    
+    $response = wp_remote_post('https://api.momentry.ddns.net/api/v1/n8n/search', [
+        'headers' => ['Content-Type' => 'application/json'],
+        'body'    => json_encode([
+            'query' => $atts['query'],
+            'limit' => (int)$atts['limit']
+        ]),
+        'timeout' => 30
+    ]);
+    
+    if (is_wp_error($response)) {
+        return '<p>搜尋服務暫時無法使用</p>';
+    }
+    
+    $data = json_decode(wp_remote_retrieve_body($response), true);
+    
+    if (empty($data['hits'])) {
+        return '<p>找不到相關結果</p>';
+    }
+    
+    $output = '<ul class="momentry-results">';
+    foreach ($data['hits'] as $hit) {
+        $output .= sprintf(
+            '<li>%s <a href="%s?start=%s">播放</a></li>',
+            esc_html($hit['text']),
+            $hit['media_url'],
+            $hit['start']
+        );
+    }
+    $output .= '</ul>';
+    
+    return $output;
+});
+?>
+```
+
+**使用方式**:
+```
+[momentry_search query="charade" limit="5"]
+```
+
+---
+
+## REST API Endpoint (WP >= 5.0)
+
+在 WordPress REST API 中註冊自定義端點：
+
+```php
+<?php
+// 註冊 REST API 端點
+add_action('rest_api_init', function() {
+    register_rest_route('momentry/v1', '/search', [
+        'methods'  => 'POST',
+        'callback' => function($request) {
+            $response = wp_remote_post(
+                'https://api.momentry.ddns.net/api/v1/n8n/search',
+                [
+                    'headers' => ['Content-Type' => 'application/json'],
+                    'body'    => json_encode([
+                        'query' => $request->get_param('query'),
+                        'limit' => $request->get_param('limit', 10)
+                    ])
+                ]
+            );
+            
+            if (is_wp_error($response)) {
+                return new WP_Error('api_error', 'API 請求失敗');
+            }
+            
+            return json_decode(wp_remote_retrieve_body($response));
+        }
+    ]);
+});
+?>
+```
+
+**呼叫方式**:
+```
+POST /wp-json/momentry/v1/search
+Body: {"query": "charade", "limit": 5}
+```
+
+---
+
+## 常見錯誤
+
+### 錯誤: cURL error 7
+
+**原因**: 無法連接到 API
+
+**檢查**:
+1. API 服務是否啟動
+2. 網路是否可達
+
+### 錯誤: 502 Bad Gateway
+
+**原因**: API 服務未啟動
+
+**解決**:
+```bash
+sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
+```
+
+---
+
+## curl 測試
+
+在終端機中測試：
+
+```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":5}'
+```
+
+---
+
+## 相關文件
+
+- [API_INDEX.md](./API_INDEX.md) - 文件總覽
+- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - 端點完整說明
+- [API_N8N_GUIDE.md](./API_N8N_GUIDE.md) - n8n 使用範例