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_ACCESS.md
+++ b/docs/API_ACCESS.md
@@ -0,0 +1,193 @@
+# Momentry Core API 存取指南
+
+## 基本網址
+
+| 環境 | URL | 說明 |
+|------|-----|------|
+| **本地開發** | `http://localhost:3002` | 直接訪問 API，繞過反向代理 |
+| **外部訪問** | `https://api.momentry.ddns.net` | 通過 Caddy 反向代理訪問，需網路可達 |
+
+### 何時使用哪個 URL
+
+**使用 `localhost:3002`：**
+- 開發/測試環境
+- 直接在伺服器上操作
+- 當反向代理有問題時
+
+**使用 `api.momentry.ddns.net`：**
+- n8n workflow 中呼叫 API
+- 外部系統整合
+- 生產環境
+
+## 認證
+目前為開放狀態（示範用途無需認證）。正式環境將實作 API Key。
+
+---
+
+## 影片搜尋 API
+
+### 語意搜尋
+
+**端點：** `POST /api/v1/search`
+
+**請求：**
+```json
+{
+  "query": "charade",
+  "limit": 5,
+  "uuid": "a1b10138a6bbb0cd"
+}
+```
+
+| 欄位 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `query` | 字串 | 是 | 搜尋文字 |
+| `limit` | 整數 | 否 | 最大回傳結果數（預設 10） |
+| `uuid` | 字串 | 否 | 依影片 UUID 過濾 |
+
+**回應：**
+```json
+{
+  "results": [
+    {
+      "uuid": "a1b10138a6bbb0cd",
+      "chunk_id": "sentence_0006",
+      "chunk_type": "sentence",
+      "start_time": 48.8,
+      "end_time": 55.44,
+      "text": "fun plot twists, Woody Dialog and charming performances...",
+      "score": 0.526
+    }
+  ],
+  "query": "charade"
+}
+```
+
+---
+
+### n8n 整合搜尋
+
+**端點：** `POST /api/v1/n8n/search`
+
+**請求：**
+```json
+{
+  "query": "charade",
+  "limit": 5
+}
+```
+
+**回應：**
+```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,
+      "media_url": "https://wp.momentry.ddns.net/Old_Time_Movie_Show_-_Charade_1963.HD.mov"
+    }
+  ]
+}
+```
+
+---
+
+## 影片管理 API
+
+### 列出所有影片
+**端點：** `GET /api/v1/videos`
+
+### 查詢影片資訊
+**端點：** `GET /api/v1/lookup?uuid={uuid}` 或 `GET /api/v1/lookup?path={path}`
+
+### 取得處理進度
+**端點：** `GET /api/v1/progress/{uuid}`
+
+---
+
+## 區塊資料結構
+
+每個搜尋結果包含影片播放的時間資訊：
+
+| 欄位 | 說明 |
+|------|------|
+| `uuid` | 影片識別碼 |
+| `chunk_id` | 區塊唯一識別碼 |
+| `chunk_type` | 類型：`sentence`、`cut`、`time_based` |
+| `start_time` | 開始時間（秒） |
+| `end_time` | 結束時間（秒） |
+| `text` | 語音轉文字內容 |
+| `score` | 相關性分數（0-1） |
+
+---
+
+## 整合範例
+
+### JavaScript/fetch
+```javascript
+const response = await fetch('http://localhost:3002/api/v1/search', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ query: 'charade', limit: 5 })
+});
+const data = await response.json();
+console.log(data.results);
+```
+
+### PHP/cURL
+```php
+$ch = curl_init('http://localhost:3002/api/v1/search');
+curl_setopt($ch, CURLOPT_POST, true);
+curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
+  'query' => 'charade',
+  'limit' => 5
+]));
+curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
+$response = curl_exec($ch);
+$data = json_decode($response, true);
+```
+
+---
+
+## 影片嵌入網址
+
+影片可透過 SFTPGo 分享連結存取：
+```
+https://wp.momentry.ddns.net/{檔案名稱}
+```
+
+**手動建立分享連結：**
+1. 開啟 SFTPGo Web UI：`http://localhost:8080`
+2. 使用帳號 `demo` / 密碼 `demopassword123` 登入
+3. 導航至 `Files` → 選擇影片檔案
+4. 點擊 `Share` → `Create Link`
+5. 複製產生的分享連結
+
+使用搜尋結果中的 `start_time` 和 `end_time` 來嵌入影片片段。
+
+---
+
+## 服務列表
+
+| 服務 | 網址 | 用途 |
+|------|------|------|
+| Momentry API | `http://localhost:3002` | 核心 API |
+| SFTPGo | `http://localhost:8080` | 檔案儲存 |
+| Qdrant | `http://localhost:6333` | 向量搜尋 |
+| PostgreSQL | `localhost:5432` | 資料庫 |
+
+---
+
+## 示範影片
+
+- **檔案：** `Old_Time_Movie_Show_-_Charade_1963.HD.mov`
+- **UUID：** `a1b10138a6bbb0cd`
+- **長度：** 約 6879 秒（約 1.9 小時）
+- **區塊數：** 3886 個（句子 + 場景 + 時間）