From f8925ab99430abe3ccdcc9c6423d9f4ae3961703 Mon Sep 17 00:00:00 2001 From: Warren Date: Wed, 25 Mar 2026 15:56:29 +0800 Subject: [PATCH] docs: update API docs with cache/unregister endpoints and marcom training refs --- docs/API_ENDPOINTS.md | 40 +++++++++++++++++++++++++++-- docs/API_INDEX.md | 10 ++++++-- docs/API_REFERENCE.md | 60 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 4 deletions(-) diff --git a/docs/API_ENDPOINTS.md b/docs/API_ENDPOINTS.md index 1773b8a..5fc9a9c 100644 --- a/docs/API_ENDPOINTS.md +++ b/docs/API_ENDPOINTS.md @@ -2,8 +2,19 @@ | 項目 | 內容 | |------|------| -| 版本 | V1.1 | -| 日期 | 2026-03-25 | +| 建立者 | Warren | +| 建立時間 | 2026-03-18 | +| 文件版本 | V1.2 | + +--- + +## 版本歷史 + +| 版本 | 日期 | 目的 | 操作人 | +|------|------|------|--------| +| V1.0 | 2026-03-18 | 創建文件 | OpenCode | +| V1.1 | 2026-03-23 | 更新端點與實際一致 | OpenCode | +| V1.2 | 2026-03-25 | 新增快取/刪除 API | OpenCode | --- @@ -154,6 +165,29 @@ curl http://localhost:3002/api/v1/progress/5dea6618a606e7c7 --- +### 系統管理 + +| 方法 | 端點 | 說明 | +|------|------|------| +| POST | `/api/v1/config/cache` | 切換快取功能（管理員） | +| POST | `/api/v1/unregister` | 刪除影片及其所有資料（管理員） | + +**快取設定**: +```bash +curl -X POST http://localhost:3002/api/v1/config/cache \ + -H "Content-Type: application/json" \ + -d '{"enabled": true}' +``` + +**刪除影片**: +```bash +curl -X POST http://localhost:3002/api/v1/unregister \ + -H "Content-Type: application/json" \ + -d '{"uuid": "5dea6618a606e7c7"}' +``` + +--- + ## 端點對照表 | 功能 | n8n 使用 | WordPress 使用 | curl 測試 | @@ -165,6 +199,8 @@ curl http://localhost:3002/api/v1/progress/5dea6618a606e7c7 | 列出影片 | ✓ | ✓ | ✓ | | 查詢影片 | ✓ | ✓ | ✓ | | 處理進度 | ✓ | ✓ | ✓ | +| 快取設定 | ✓ (管理員) | ✓ (管理員) | ✓ (管理員) | +| 刪除影片 | ✓ (管理員) | ✓ (管理員) | ✓ (管理員) | --- diff --git a/docs/API_INDEX.md b/docs/API_INDEX.md index 8a112d9..422c405 100644 --- a/docs/API_INDEX.md +++ b/docs/API_INDEX.md @@ -2,7 +2,7 @@ | 項目 | 內容 | |------|------| -| 版本 | V2.1 | +| 版本 | V2.2 | | 日期 | 2026-03-25 | --- @@ -14,11 +14,15 @@ docs/ ├── API_INDEX.md ← 本文件：總覽與入口 ├── API_ENDPOINTS.md ← API 端點完整說明 ├── API_EXAMPLES.md ← 完整範例總覽（curl / n8n / WordPress） +├── API_REFERENCE.md ← 詳細技術參考 ├── DEMO_MANUAL.md ← ⭐ 示範手冊（含 Demo API Key） ├── API_N8N_GUIDE.md ← n8n 詳細指南 ├── API_WORDPRESS_GUIDE.md ← WordPress 詳細指南 ├── API_CURL_EXAMPLES.md ← curl 快速範例 -└── API_REFERENCE.md ← 詳細技術參考 +│ +├── API_TRAINING_MARCOM.md ← ⭐ marcom 團隊教育訓練手冊 +├── API_WORKFLOW_WORDPRESS_N8N.md ← WordPress/n8n 完整工作流程 +└── CHUNK_DATA_STRUCTURE.md ← Chunk 資料結構說明 ``` --- @@ -29,7 +33,9 @@ docs/ |------|----------| | **我要快速開始測試** | ⭐ [DEMO_MANUAL.md](./DEMO_MANUAL.md) | | **我要查看所有範例** | [API_EXAMPLES.md](./API_EXAMPLES.md) | +| **我是 marcom 團隊** | ⭐ [API_TRAINING_MARCOM.md](./API_TRAINING_MARCOM.md) | | 我想了解有哪些 API 端點 | [API_ENDPOINTS.md](./API_ENDPOINTS.md) | +| 我要整合 WordPress/n8n | [API_WORKFLOW_WORDPRESS_N8N.md](./API_WORKFLOW_WORDPRESS_N8N.md) | | 我要在 n8n workflow 中呼叫 API | [DEMO_MANUAL.md](./DEMO_MANUAL.md#2-n8n-範例) | | 我要在 WordPress 中呼叫 API | [DEMO_MANUAL.md](./DEMO_MANUAL.md#3-wordpress-範例) | | 我要用 curl 快速測試 | [DEMO_MANUAL.md](./DEMO_MANUAL.md#1-curl-範例) | diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 835226a..f52c417 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -14,6 +14,7 @@ |------|------|------|--------|-----------| | V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 | | V1.1 | 2026-03-23 | 更新端點與實際一致 | OpenCode | - | +| V1.2 | 2026-03-25 | 新增快取/刪除 API | OpenCode | - | --- @@ -384,6 +385,63 @@ curl http://localhost:3002/api/v1/videos --- +## Cache Toggle + +Toggle caching at runtime. + +**Endpoint:** `POST /api/v1/config/cache` + +**Request Body:** +```json +{ + "enabled": true +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `enabled` | boolean | Yes | Enable (true) or disable (false) cache | + +**Response (200):** +```json +{ + "cache_enabled": true, + "message": "Cache toggled successfully" +} +``` + +--- + +## Unregister Video + +Delete a video and all associated data (chunks, processor results, thumbnails). + +**Endpoint:** `POST /api/v1/unregister` + +**Request Body:** +```json +{ + "uuid": "5dea6618a606e7c7" +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `uuid` | string | Yes | Video UUID (16 character hex) | + +**Response (200):** +```json +{ + "success": true, + "message": "Video unregistered successfully", + "uuid": "5dea6618a606e7c7" +} +``` + +**Warning:** This operation is irreversible and will delete all associated chunks, processor results, and thumbnails. + +--- + ## Error Responses **400 Bad Request** @@ -445,3 +503,5 @@ cargo run --bin momentry -- server --host 127.0.0.1 --port 3002 | Search | `POST /api/v1/search` | | List videos | `GET /api/v1/videos` | | Lookup | `GET /api/v1/lookup?uuid=` | +| Toggle cache | `POST /api/v1/config/cache` | +| Delete video | `POST /api/v1/unregister` |