---
document_type: "guide"
service: "MOMENTRY_CORE"
title: "Portal API Demo 示範指南"
date: "2026-04-30"
version: "V1.0"
status: "active"
current_state: "approved"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "portal"
  - "api-demo"
  - "wordpress"
  - "frontend"
  - "query"
  - "operation"
  - "application"
ai_query_hints:
  - "查詢 Portal API Demo 示範指南的內容"
  - "Portal API Demo 的主要目的是什麼？"
  - "如何使用 Portal API Demo 頁面？"
  - "Portal API Demo 頁面分類與功能"
  - "如何設定 API Demo 頁面"
  - "API Demo 查詢/展示/操作/應用頁面說明"
  - "Momentry Playground 啟動方式"
related_documents:
  - "REFERENCE/API_INDEX.md"
  - "REFERENCE/API_ENDPOINTS.md"
  - "REFERENCE/PORTAL_DEVELOPMENT_PLAN.md"
  - "FILE_UUID_SPEC.md"
---

# Portal API Demo 示範指南

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-30 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-30 | 創建 Portal API Demo 示範指南 | OpenCode | big-pickle |

---

## 概述

本文檔說明 Momentry Portal 中四個 API Demo 頁面的功能、設定方式與使用流程。
Demo 頁面以 **file-centric** 設計理念為核心，將檔案 (file) 作為主要管理目標，
身份 (identity) 為附隨目標，分類系統用於形容主體。

---

## 關鍵術語定義

| 術語 | 定義 |
|------|------|
| file_uuid | 檔案唯一識別碼，由 MAC、Birthday、Path、Filename 計算得出 |
| identity_uuid | 全域人員身份識別碼，跨檔案關聯 |
| file-centric | 以檔案為中心的設計理念，檔案是主要管理目標 |
| Birth/Migration | 檔案註冊與遷移的身份模型 |
| Portal | WordPress 前端展示與操作介面 |
| Playground | Momentry 開發伺服器 (port 3003) |

---

## 頁面分類總覽

Momentry Portal 提供四個 API Demo 頁面，涵蓋查詢、展示、操作、應用四大類別：

| 頁面 | 檔案名稱 | 類別 | 主要功能 |
|------|----------|------|----------|
| API Demo - 查詢 | `page-api-demo-query.php` | 查詢 | 檔案查詢、身份查詢、處理狀態、遷移歷史、語義搜尋 |
| API Demo - 展示 | `page-api-demo-display.php` | 展示 | 檔案詳情儀表板、身份視覺化、片段展示、分類結果 |
| API Demo - 操作 | `page-api-demo-operation.php` | 操作 | 檔案註冊、身份綁定、處理觸發、身份合併、處理器重試 |
| API Demo - 應用 | `page-api-demo-application.php` | 應用 | 完整工作流程、身份追蹤、遷移示範、批次處理、語義搜尋工作流 |

---

## 檔案位置

| 類型 | 路徑 | 說明 |
|------|------|------|
| 查詢頁面 | `/wp-content/themes/momentry/page-api-demo-query.php` | WordPress 頁面模板 |
| 展示頁面 | `/wp-content/themes/momentry/page-api-demo-display.php` | WordPress 頁面模板 |
| 操作頁面 | `/wp-content/themes/momentry/page-api-demo-operation.php` | WordPress 頁面模板 |
| 應用頁面 | `/wp-content/themes/momentry/page-api-demo-application.php` | WordPress 頁面模板 |
| 共用樣式 | `/wp-content/themes/momentry/style.css` | CSS 樣式表 |
| 設定說明 | `/wp-content/themes/momentry/API_DEMO_README.md` | 技術設定文件 |

---

## 環境需求

| 項目 | 狀態 | 說明 |
|------|------|------|
| WordPress | ✅ 已安裝 | 本地 WordPress 環境 |
| Momentry Theme | ✅ 已安裝 | 自定義 momentry 主題 |
| PostgreSQL | ✅ 已安裝 | Momentry Core 資料庫 |
| Momentry Playground | 🔄 需啟動 | 開發伺服器 (port 3003) |

---

## 設定步驟

### Step 1: 啟動 Momentry Playground

API Demo 頁面需要連線到 Momentry Playground API server：

```bash
cd /Users/accusys/momentry_core_0.1
cargo run --bin momentry_playground -- server --host 0.0.0.0 --port 3003
```

驗證伺服器啟動：

```bash
curl http://localhost:3003/api/v1/health
```

### Step 2: 在 WordPress 建立頁面

1. 進入 WordPress 後台：`http://localhost/wp-admin`
2. 點擊 **Pages > Add New**
3. 建立以下四個頁面：

| 頁面標題 | URL Slug | Template |
|----------|----------|----------|
| API Demo - 查詢 | `api-demo-query` | API Demo - 查詢 |
| API Demo - 展示 | `api-demo-display` | API Demo - 展示 |
| API Demo - 操作 | `api-demo-operation` | API Demo - 操作 |
| API Demo - 應用 | `api-demo-application` | API Demo - 應用 |

1. 建立時，在右側 **Page Attributes** 選擇對應的 **Template**
2. 點擊 **Publish**

### Step 3: 訪問示範頁面

| 頁面 | URL |
|------|-----|
| 查詢 | `http://localhost/api-demo-query/` |
| 展示 | `http://localhost/api-demo-display/` |
| 操作 | `http://localhost/api-demo-operation/` |
| 應用 | `http://localhost/api-demo-application/` |

---

## 頁面功能詳解

### 1. 查詢頁面 (Query)

查詢頁面用於示範各類資料查詢 API 的使用方式。

#### 1.1 檔案查詢 (GET /api/v1/files/:uuid)

- **用途**：透過 file_uuid 查詢檔案的完整資訊
- **操作**：輸入 file_uuid，點擊「查詢」
- **回應**：檔案元數據、處理狀態、分類標籤等

#### 1.2 身份查詢 (GET /api/v1/identities/:uuid)

- **用途**：查詢跨檔案的全域身份資訊
- **操作**：輸入 identity_uuid，點擊「查詢」
- **回應**：身份名稱、關聯檔案、臉部特徵、品質分數

#### 1.3 處理狀態查詢 (GET /api/v1/jobs/:uuid/status)

- **用途**：查詢檔案的處理進度與各處理器狀態
- **操作**：輸入 file_uuid，點擊「查詢」
- **回應**：處理進度百分比、已完成/失敗的處理器列表

#### 1.4 檔案遷移歷史 (GET /api/v1/files/:uuid/history)

- **用途**：查詢檔案因移動而產生的身份變更鏈
- **操作**：輸入 file_uuid，點擊「查詢」
- **回應**：parent_uuid 關聯鏈、遷移時間記錄

#### 1.5 語義搜尋 (POST /api/v1/search)

- **用途**：使用自然語言搜尋相關的影片片段或身份
- **操作**：輸入搜尋查詢，選擇搜尋類型，點擊「搜尋」
- **回應**：搜尋結果列表、相似度分數

---

### 2. 展示頁面 (Display)

展示頁面用於示範如何將 API 資料轉化為視覺化的展示元件。

#### 2.1 檔案詳情儀表板

- **用途**：整合展示檔案的元數據、處理進度、分類標籤等完整資訊
- **操作**：輸入 file_uuid，點擊「載入」
- **展示內容**：
  - 基本資訊：檔案名稱、類型、時長、解析度、幀率
  - 處理狀態：狀態徽章、處理進度、已完成處理器
  - 分類標籤：分類標籤、語義標籤
  - 關聯身份：檢測到身份數量、主要身份

#### 2.2 身份視覺化

- **用途**：展示身份的跨檔案關聯、臉部檢測統計、品質分數
- **操作**：輸入 identity_uuid，點擊「視覺化」
- **展示內容**：
  - 身份名稱與品質分數
  - 關聯檔案列表
  - 臉部統計 (檢測次數、平均品質)
  - 角度覆蓋視覺化

#### 2.3 影片片段展示

- **用途**：展示影片的語義片段、說話者分段、鏡頭切換等分類結果
- **操作**：輸入 file_uuid，選擇片段類型，點擊「載入片段」
- **片段類型**：語義片段、鏡頭切換、時間片段

#### 2.4 分類結果展示

- **用途**：展示 YOLO 檢測、姿勢估計、動作識別等視覺分類結果
- **操作**：輸入 file_uuid，選擇處理器類型，點擊「載入結果」
- **處理器類型**：YOLO、Pose、Face、OCR

---

### 3. 操作頁面 (Operation)

操作頁面用於示範各類寫入與修改 API 的實際使用。

#### 3.1 檔案註冊 (POST /api/v1/register)

- **用途**：將新影片或音訊檔案註冊到系統
- **操作**：輸入檔案路徑，點擊「註冊」
- **快速測試**：提供預設測試路徑按鈕

#### 3.2 身份綁定 (POST /api/v1/identities/bind)

- **用途**：將臉部檢測綁定到特定身份
- **操作**：輸入 Face ID 和 Identity UUID，點擊「綁定」

#### 3.3 處理觸發 (POST /api/v1/files/:uuid/process)

- **用途**：手動觸發檔案的處理流程
- **操作**：輸入 file_uuid，選擇要執行的處理器 (ASR、YOLO、Face、OCR、Pose、CUT)，點擊「觸發處理」

#### 3.4 身份合併 (POST /api/v1/identities/merge)

- **用途**：將多個身份合併為單一身份
- **操作**：輸入目標 Identity UUID 和來源 Identity UUIDs (逗號分隔)，點擊「合併」

#### 3.5 處理器重試 (POST /api/v1/jobs/:uuid/retry)

- **用途**：重試失敗的處理器
- **操作**：輸入 file_uuid，選擇要重試的處理器，點擊「重試」

---

### 4. 應用頁面 (Application)

應用頁面示範結合多個 API 的實際應用場景與工作流程。

#### 4.1 完整工作流程示範

端到端展示從檔案註冊到處理完成的完整流程：

| 步驟 | 操作 | 說明 |
|------|------|------|
| 1 | 註冊檔案 | 輸入影片路徑，呼叫 `/register` |
| 2 | 查詢處理狀態 | 定期檢查 `/jobs/:uuid/status` 直到完成 |
| 3 | 查詢檢測結果 | 取得身份和片段資訊 |
| 4 | 搜尋身份 | 展示檔案中檢測到的身份列表 |

每步完成後自動解鎖下一步，狀態以顏色標示 (等待中/執行中/完成)。

#### 4.2 跨檔案身份追蹤

- **用途**：追蹤特定身份在所有檔案中的出現情況
- **操作**：輸入 Identity UUID，點擊「開始追蹤」
- **展示內容**：
  - 身份名稱與關聯檔案數量
  - 時間軸展示各檔案中的出現記錄
  - 統計資訊 (總檢測次數、平均品質、覆蓋角度)

#### 4.3 檔案遷移與身份繼承示範

展示 Birth/Migration 模型的實際運作：

| 步驟 | 操作 | 說明 |
|------|------|------|
| 1 | 原始註冊 | 註冊原始路徑的檔案 |
| 2 | 模擬移動 | 使用新路徑重新註冊，系統產生新的 file_uuid |
| 3 | 查詢歷史 | 透過 `/files/:uuid/history` 查看遷移鏈 |

#### 4.4 批次檔案處理

- **用途**：一次註冊多個檔案，監控批次處理進度
- **操作**：輸入多個檔案路徑 (每行一個)，點擊「批次註冊」
- **展示內容**：進度條、每個檔案的註冊結果

#### 4.5 語義搜尋與片段提取工作流

- **用途**：使用語義搜尋找到相關片段，然後提取詳細資訊
- **操作**：輸入自然語言查詢，點擊「搜尋」
- **展示內容**：搜尋結果摘要、詳細片段列表 (含相似度分數)

---

## API 端點參考

### 查詢類 API

| 端點 | 方法 | 說明 |
|------|------|------|
| `/api/v1/files/:uuid` | GET | 查詢檔案詳細資訊 |
| `/api/v1/files` | GET | 查詢檔案列表 |
| `/api/v1/identities/:uuid` | GET | 查詢身份資訊 |
| `/api/v1/jobs/:uuid/status` | GET | 查詢處理狀態 |
| `/api/v1/files/:uuid/history` | GET | 查詢遷移歷史 |
| `/api/v1/search` | POST | 語義搜尋 |

### 操作類 API

| 端點 | 方法 | 說明 |
|------|------|------|
| `/api/v1/register` | POST | 註冊檔案 |
| `/api/v1/identities/bind` | POST | 綁定身份 |
| `/api/v1/files/:uuid/process` | POST | 觸發處理 |
| `/api/v1/identities/merge` | POST | 合併身份 |
| `/api/v1/jobs/:uuid/retry` | POST | 重試處理器 |

---

## 常見問題

### Q1: 頁面無法連線到 API

- 確認 Playground server 已啟動：`cargo run --bin momentry_playground -- server`
- 檢查 API base URL 設定 (各頁面的 `const API_BASE = 'http://localhost:3003/api/v1'`)
- 確認 CORS 設定允許來自 WordPress 的請求

### Q2: 註冊檔案時返回錯誤

- 確認檔案路徑正確且檔案存在
- 確認 PostgreSQL 資料庫連線正常
- 檢查 Playground server 日誌

### Q3: 遷移歷史查詢無結果

- 確認檔案確實有 parent_uuid 記錄
- 使用 `SELECT file_uuid, parent_uuid FROM dev.videos WHERE parent_uuid IS NOT NULL;` 檢查資料庫

---

## 常用指令

```bash
# 啟動 Playground 伺服器
cargo run --bin momentry_playground -- server --host 0.0.0.0 --port 3003

# 檢查 API 健康狀態
curl http://localhost:3003/api/v1/health

# 查詢檔案列表
curl http://localhost:3003/api/v1/files?limit=5

# 註冊檔案
curl -X POST http://localhost:3003/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/video.mp4"}'

# 查詢檔案詳情
curl http://localhost:3003/api/v1/files/<file_uuid>

# 查詢遷移歷史
curl http://localhost:3003/api/v1/files/<file_uuid>/history
```

---

## 設計理念

### File-Centric 架構

Momentry 系統採用 **file-centric** 設計理念：

| 概念 | 說明 |
|------|------|
| **File (檔案)** | 主要管理目標，file_uuid 為核心識別 |
| **Identity (身份)** | 附隨目標，跨檔案關聯人員身份 |
| **Classification (分類)** | 形容主體的標籤系統 (YOLO、ASR、Face 等處理器結果) |

### Birth/Migration 模型

| 概念 | 說明 |
|------|------|
| **Birth (註冊)** | 檔案首次註冊，產生初始 file_uuid |
| **Migration (遷移)** | 檔案移動後重新註冊，產生新 file_uuid 並記錄 parent_uuid |
| **Birthday (生日)** | 原始註冊時間，遷移時保留以證明身份連續性 |

### UUID 計算公式

```
file_uuid = SHA256(MAC_Address | Birthday | Canonical_Path | Filename)[0:32]
```

---

## 版本資訊

- 版本: V1.0
- 建立日期: 2026-04-30
- 文件更新: 2026-04-30
