docs: file_uuid generation rules for M4

docs_v1.0/GUIDES/API_INDEX.md

@@ -0,0 +1,129 @@
+---
+document_type: "reference_doc"
+service: "MOMENTRY_CORE"
+title: "Momentry Core API 文件總覽"
+date: "2026-04-23"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+  - "momentry"
+  - "文件總覽"
+  - "core"
+ai_query_hints:
+  - "查詢 Momentry Core API 文件總覽 的內容"
+  - "Momentry Core API 文件總覽 的主要目的是什麼？"
+  - "如何操作或實施 Momentry Core API 文件總覽？"
+---
+
+# Momentry Core API 文件總覽
+
+> **Version**: 3.0 | **Updated**: 2026-04-23
+> **Source**: Generated from actual Rust code (`src/api/`)
+
+---
+
+## 📁 文件結構
+
+```
+docs_v1.0/
+├── REFERENCE/
+│   ├── API_REFERENCE.md      ← 主要 API 參考文件（71 個端點）
+│   ├── API_KEY_DESIGN.md     ← API Key 系統設計文件
+│   └── API_TRAINING_MARCOM.md ← marcom 團隊教育訓練手冊
+├── IMPLEMENTATION/
+│   ├── API_EXAMPLES.md       ← 完整範例（curl / n8n / WordPress）
+│   ├── API_CURL_EXAMPLES.md  ← curl 快速範例
+│   ├── API_WORDPRESS_GUIDE.md ← WordPress 整合指南
+│   └── API_N8N_GUIDE.md      ← n8n 整合指南
+└── ARCHITECTURE/
+    └── API_KEY_ARCHITECTURE.md ← API Key 架構圖
+```
+
+---
+
+## 快速選擇指南
+
+| 需求 | 閱讀文件 |
+|------|----------|
+| **我要查看所有 API 端點** | [API_REFERENCE.md](./API_REFERENCE.md) |
+| **我要 curl 範例** | [API_EXAMPLES.md](../IMPLEMENTATION/API_EXAMPLES.md) |
+| **我是 marcom 團隊** | [API_TRAINING_MARCOM.md](./API_TRAINING_MARCOM.md) |
+| **我要整合 n8n** | [API_N8N_GUIDE.md](../IMPLEMENTATION/API_N8N_GUIDE.md) |
+| **我要整合 WordPress** | [API_WORDPRESS_GUIDE.md](../IMPLEMENTATION/API_WORDPRESS_GUIDE.md) |
+| **我要了解 API Key 設計** | [API_KEY_DESIGN.md](./API_KEY_DESIGN.md) |
+
+---
+
+## 認證
+
+### 使用方式
+
+```bash
+export API_KEY="your_api_key_here"
+curl -H "X-API-Key: $API_KEY" http://localhost:3002/api/v1/videos
+```
+
+### 環境
+
+| 環境 | URL | 使用時機 |
+|------|-----|----------|
+| **本地開發** | `http://localhost:3002` | 開發/測試 |
+| **Playground** | `http://localhost:3003` | 開發測試（dev 模式） |
+| **外部訪問** | `https://api.momentry.ddns.net` | n8n、WordPress、遠端 |
+
+---
+
+## API 端點總覽
+
+| 類別 | 端點數 | 說明 |
+|------|--------|------|
+| Health & Stats | 5 | 健康檢查與統計（公開） |
+| Core Asset | 6 | 影片註冊、查詢、進度 |
+| Processing | 7 | 探針、處理、任務 |
+| Search | 7 | 向量、BM25、混合搜索 |
+| Visual Chunk | 5 | 視覺分片搜索 |
+| Face Recognition | 7 | 人臉識別 |
+| Person Identity | 21 | 人物身份管理 |
+| Global Identities | 6 | 全局身份 |
+| Identity Binding | 6 | 身份綁定 |
+| Configuration | 1 | 緩存配置 |
+| **Total** | **71** | **可達端點** |
+
+### ⚠️ 未掛載端點
+
+以下端點已定義但**未在 router 中掛載**：
+
+| 端點 | 定義位置 |
+|------|----------|
+| `/api/v1/search/universal` | `universal_search.rs` |
+| `/api/v1/search/frames` | `universal_search.rs` |
+| `/api/v1/search/persons` | `universal_search.rs` |
+| `/api/v1/who` | `who.rs` |
+| `/api/v1/who/candidates` | `who.rs` |
+
+---
+
+## 常見問題
+
+### Q: API 返回 401 錯誤？
+API Key 無效或過期。請檢查 `X-API-Key` header。
+
+### Q: API 返回 502 錯誤？
+```bash
+# 檢查服務狀態
+launchctl list | grep momentry.api
+
+# 重啟服務
+sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
+sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
+```
+
+---
+
+## 相關文件
+
+- [API_REFERENCE.md](./API_REFERENCE.md) - 完整 API 參考
+- [INSTALL_MOMENTRY_API.md](../IMPLEMENTATION/INSTALL_MOMENTRY_API.md) - 安裝指南
+- [API_KEY_DESIGN.md](./API_KEY_DESIGN.md) - API Key 設計