diff --git a/.env.development b/.env.development
index eb0822b..b457003 100644
--- a/.env.development
+++ b/.env.development
@@ -10,7 +10,7 @@ MOMENTRY_REDIS_PREFIX=momentry_dev:
# Worker Configuration (enabled for development)
MOMENTRY_WORKER_ENABLED=true
-MOMENTRY_MAX_CONCURRENT=1
+MOMENTRY_MAX_CONCURRENT=6
MOMENTRY_POLL_INTERVAL=10
MOMENTRY_WORKER_BATCH_SIZE=5
diff --git a/.gitignore b/.gitignore
index f38c930..20904b0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,92 +1,79 @@
-# Environment - Local configs (NEVER commit these)
-.env
-.env.local
-.env.*.local
-# Build artifacts
-target/
-venv/
-
-# Generated files
-thumbnails/
-*.asr.json
-*.probe.json
-test_asr.json
-
-# Local output (machine learning results)
-output/
-*.pt
-
-# Cache
-.ruff_cache/
-
-# OS files
-.DS_Store
-.Spotlight-V100
-.Trashes
-
-# Logs
-*.log
-
-# SSH keys (NEVER commit)
-id_*
-!id_*.pub
-
-# IDE and editor
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# Documentation backups
-# docs_v1.0/ (Moved to active tracking)
-
-# Frontend dependencies
-node_modules/
-portal/src-tauri/target/
-
-# Python cache
__pycache__/
-*.pyc
-*.pyo
-
-# Test artifacts
-test_output/
-test_output_simple/
-test_output_v2/
-*.mp4
-*.pt
-server.pid
-server.pid.*
-
-# Backup files
-*.bak
-*.backup
-*.bak[0-9]
-
-# Model files
-models/
-model_checkpoints/
-pretrained_models/
-
-# Desktop app
-momentry_desktop/
-
-# Release artifacts (track docs, ignore binaries)
-release/*.zip
-release/momentry_v*
-release/*.sql
-release/dev_data_*.sql
-release/public_schema_*.sql
-release/migrate_*.sql
-
-# But track release documentation
+!id_*.pub
!release/*.md
!release/*.txt
-
+.DS_Store
+.env
+.env.*.local
+.env.local
+.idea/
+.ruff_cache/
+.Spotlight-V100
+.Trashes
+.vscode/
+*.asr.json
+*.backup
+*.bak
+*.bak[0-9]
+*.log
+*.mp4
+*.probe.json
+*.pt
+*.pyc
+*.pyo
+*.swo
+*.swp
+*~
+# Backup files
+# Build artifacts
+# But track release documentation
+# Cache
# Data directories
-data/
-
+# Desktop app
+# docs_v1.0/ (Moved to active tracking)
+# Documentation backups
+# Environment - Local configs (NEVER commit these)
+# Frontend dependencies
+# Generated files
+# IDE and editor
+# Local output (machine learning results)
+# Logs
+# Model files
+# OS files
+# Portal build artifacts
+# Python cache
+# Release and output directories
+# Release artifacts (track docs, ignore binaries)
+# SSH keys (NEVER commit)
# System status
+# Test artifacts
+data/
+id_*
+model_checkpoints/
+models/
+momentry_desktop/
+momentry_runtime/
+node_modules/
+output/
+portal/dist/
+portal/node_modules/
+portal/src-tauri/target/
+pretrained_models/
+release/
+release/*.sql
+release/*.zip
+release/dev_data_*.sql
+release/migrate_*.sql
+release/momentry_v*
+release/public_schema_*.sql
+server.pid
+server.pid.*
system_status_*.md
+target/
+test_asr.json
+test_output_simple/
+test_output_v2/
+test_output/
+thumbnails/
+venv/
diff --git a/AGENTS.md b/AGENTS.md
index 921102a..30d7872 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,10 +29,16 @@ Rust-based digital asset management system with video analysis and RAG capabilit
| Production | 3002 | ❌ 禁止修改 | `cargo run -- server` (僅 release 時) |
| Portal (Tauri) | 1420 | 前端開發 | `npm run tauri dev` |
+### ⛔ 嚴格測試隔離規則 (Strict Test Isolation)
+- **所有測試 (Test) 必須在 Dev (3003) 進行**。
+- **絕對禁止 (ABSOLUTELY FORBIDDEN)** 在任何測試指令、Demo 流程或 API 檢查中使用 `localhost:3002`。
+- 即使是「測試 Unregister」或「檢查版本」，若未明確標示為 "Production Deployment"，一律視為違規。
+- **預設行為**: 所有 curl, CLI, 或程式碼測試指令，預設 URL 必須為 `http://localhost:3003`。
+
### 違反後果
- 修改 WordPress/n8n 可能影響 marcom 團隊工作與生產環境
- 修改 WordPress/n8n 資料庫 table 可能破壞自動化流程與資料完整性
-- 修改 port 3002 可能中斷正在使用的服務
+- 修改 port 3002 可能中斷正在使用的服務 (這是非常嚴重的錯誤)
- 所有 dev 測試必須在 playground (3003) 進行
---
diff --git a/Cargo.lock b/Cargo.lock
index c5abea1..293490d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2369,6 +2369,7 @@ dependencies = [
"qdrant-client",
"ratatui",
"redis",
+ "regex",
"reqwest",
"sdl2",
"serde",
diff --git a/Cargo.toml b/Cargo.toml
index 7a57be3..f7be791 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -26,6 +26,7 @@ futures-util = "0.3"
# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
+regex = "1"
chrono = { version = "0.4", features = ["serde"] }
# UUID
@@ -98,6 +99,10 @@ optional = true
name = "momentry"
path = "src/main.rs"
+[[bin]]
+name = "momentry-cli"
+path = "src/bin/cli.rs"
+
[[bin]]
name = "momentry_player"
path = "src/player/main.rs"
diff --git a/a1b10138a6bbb0cd.cut.json b/a1b10138a6bbb0cd.cut.json
deleted file mode 120000
index 31c7e3c..0000000
--- a/a1b10138a6bbb0cd.cut.json
+++ /dev/null
@@ -1 +0,0 @@
-/Users/accusys/momentry_core_0.1/output/a1b10138a6bbb0cd.cut.json
\ No newline at end of file
diff --git a/a1b10138a6bbb0cd.face.json b/a1b10138a6bbb0cd.face.json
deleted file mode 120000
index e481d5e..0000000
--- a/a1b10138a6bbb0cd.face.json
+++ /dev/null
@@ -1 +0,0 @@
-/Users/accusys/momentry_core_0.1/output/a1b10138a6bbb0cd.face.json
\ No newline at end of file
diff --git a/a1b10138a6bbb0cd.ocr.json b/a1b10138a6bbb0cd.ocr.json
deleted file mode 120000
index edfdb5a..0000000
--- a/a1b10138a6bbb0cd.ocr.json
+++ /dev/null
@@ -1 +0,0 @@
-/Users/accusys/momentry_core_0.1/output/a1b10138a6bbb0cd.ocr.json
\ No newline at end of file
diff --git a/a1b10138a6bbb0cd.pose.json b/a1b10138a6bbb0cd.pose.json
deleted file mode 120000
index fb33446..0000000
--- a/a1b10138a6bbb0cd.pose.json
+++ /dev/null
@@ -1 +0,0 @@
-/Users/accusys/momentry_core_0.1/output/a1b10138a6bbb0cd.pose.json
\ No newline at end of file
diff --git a/a1b10138a6bbb0cd.story.json b/a1b10138a6bbb0cd.story.json
deleted file mode 120000
index 392fd81..0000000
--- a/a1b10138a6bbb0cd.story.json
+++ /dev/null
@@ -1 +0,0 @@
-/Users/accusys/momentry_core_0.1/output/a1b10138a6bbb0cd.story.json
\ No newline at end of file
diff --git a/a1b10138a6bbb0cd.yolo.json b/a1b10138a6bbb0cd.yolo.json
deleted file mode 120000
index 2423006..0000000
--- a/a1b10138a6bbb0cd.yolo.json
+++ /dev/null
@@ -1 +0,0 @@
-/Users/accusys/momentry_core_0.1/output/a1b10138a6bbb0cd.yolo.json
\ No newline at end of file
diff --git a/benchmark_asr.py b/benchmark_asr.py
deleted file mode 100644
index ceab604..0000000
--- a/benchmark_asr.py
+++ /dev/null
@@ -1,161 +0,0 @@
-#!/usr/bin/env python3
-"""Benchmark ASR processor direct vs chunked transcription overhead."""
-
-import sys
-import os
-import subprocess
-import json
-import tempfile
-import time
-import shutil
-import statistics
-
-# Use a small video clip for consistent benchmarking
-VIDEO_SOURCE = "../test_video/BigBuckBunny_320x180.mp4" # 10 minutes, 62MB
-if not os.path.exists(VIDEO_SOURCE):
- print(f"Video not found: {VIDEO_SOURCE}")
- sys.exit(1)
-
-# Create temporary directory for all test runs
-temp_dir = tempfile.mkdtemp(prefix="asr_bench_")
-print(f"Benchmark directory: {temp_dir}")
-
-
-def run_asr_mode(mode_name, max_direct_duration, chunk_duration=600):
- """Run ASR processor with given parameters, return timing and resource stats."""
- clip_path = os.path.join(temp_dir, f"clip_{mode_name}.mp4")
- output_path = os.path.join(temp_dir, f"output_{mode_name}.json")
-
- # Copy source video to clip path (no transcoding)
- shutil.copy2(VIDEO_SOURCE, clip_path)
-
- env = os.environ.copy()
- env["MOMENTRY_ASR_MAX_DIRECT_DURATION"] = str(max_direct_duration)
- env["MOMENTRY_ASR_CHUNK_DURATION"] = str(chunk_duration)
- env["MOMENTRY_ASR_MODEL_SIZE"] = "tiny"
- env["MOMENTRY_ASR_COMPUTE_TYPE"] = "int8"
-
- cmd = [
- "/opt/homebrew/bin/python3.11",
- "scripts/asr_processor.py",
- clip_path,
- output_path,
- "--uuid",
- f"bench_{mode_name}",
- ]
-
- # Start monitoring (external)
- import psutil
-
- start_time = time.time()
- proc = subprocess.Popen(
- cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=env
- )
-
- # Monitor CPU and memory of child process
- cpu_percents = []
- memory_mbs = []
-
- while True:
- try:
- p = psutil.Process(proc.pid)
- cpu = p.cpu_percent(interval=0.1)
- mem = p.memory_info().rss / (1024 * 1024)
- cpu_percents.append(cpu)
- memory_mbs.append(mem)
- except (psutil.NoSuchProcess, psutil.AccessDenied):
- break
- if proc.poll() is not None:
- # Process ended, wait a bit for final stats
- time.sleep(0.1)
- break
-
- stdout, stderr = proc.communicate(timeout=1)
- elapsed = time.time() - start_time
- returncode = proc.returncode
-
- # Read output
- segments = []
- if os.path.exists(output_path):
- with open(output_path, "r") as f:
- data = json.load(f)
- segments = data.get("segments", [])
-
- # Clean up temporary files
- try:
- os.unlink(clip_path)
- os.unlink(output_path)
- except:
- pass
-
- return {
- "mode": mode_name,
- "elapsed": elapsed,
- "returncode": returncode,
- "segments": len(segments),
- "cpu_avg": statistics.mean(cpu_percents) if cpu_percents else 0,
- "cpu_max": max(cpu_percents) if cpu_percents else 0,
- "memory_avg": statistics.mean(memory_mbs) if memory_mbs else 0,
- "memory_max": max(memory_mbs) if memory_mbs else 0,
- "stderr": stderr.decode() if stderr else "",
- }
-
-
-try:
- # Run direct transcription (clip duration ~600s, max_direct=1800)
- print("Running direct transcription benchmark...")
- direct = run_asr_mode("direct", max_direct_duration=1800, chunk_duration=600)
-
- # Run chunked transcription (force chunked with max_direct=300, chunk=120)
- print("Running chunked transcription benchmark...")
- chunked = run_asr_mode("chunked", max_direct_duration=300, chunk_duration=120)
-
- # Calculate overhead
- overhead = (chunked["elapsed"] - direct["elapsed"]) / direct["elapsed"] * 100
-
- # Print results
- print("\n" + "=" * 60)
- print("ASR PROCESSOR BENCHMARK RESULTS")
- print("=" * 60)
- print(f"Test video: {VIDEO_SOURCE}")
- print(f"Video duration: ~10 minutes (600 seconds)")
- print()
- print("Direct Transcription:")
- print(f" Time: {direct['elapsed']:.1f}s")
- print(f" Segments: {direct['segments']}")
- print(f" CPU avg/max: {direct['cpu_avg']:.1f}% / {direct['cpu_max']:.1f}%")
- print(
- f" Memory avg/max: {direct['memory_avg']:.1f} MB / {direct['memory_max']:.1f} MB"
- )
- print()
- print("Chunked Transcription:")
- print(f" Time: {chunked['elapsed']:.1f}s")
- print(f" Segments: {chunked['segments']}")
- print(f" CPU avg/max: {chunked['cpu_avg']:.1f}% / {chunked['cpu_max']:.1f}%")
- print(
- f" Memory avg/max: {chunked['memory_avg']:.1f} MB / {chunked['memory_max']:.1f} MB"
- )
- print()
- print("OVERHEAD ANALYSIS:")
- print(f" Time overhead: {overhead:.2f}%")
- if overhead <= 5:
- print(f" ✅ PASS: Overhead ≤5% requirement")
- else:
- print(f" ❌ FAIL: Overhead exceeds 5% limit")
- print()
-
- # Check for errors
- if direct["returncode"] != 0:
- print(f"WARNING: Direct transcription returned {direct['returncode']}")
- if chunked["returncode"] != 0:
- print(f"WARNING: Chunked transcription returned {chunked['returncode']}")
-
-except Exception as e:
- print(f"Benchmark failed: {e}")
- import traceback
-
- traceback.print_exc()
-finally:
- # Clean up directory
- shutil.rmtree(temp_dir, ignore_errors=True)
- print(f"Cleaned up {temp_dir}")
diff --git a/benchmark_realistic.py b/benchmark_realistic.py
deleted file mode 100644
index 6884a6d..0000000
--- a/benchmark_realistic.py
+++ /dev/null
@@ -1,151 +0,0 @@
-#!/usr/bin/env python3
-"""Benchmark ASR with realistic chunk sizes."""
-
-import sys
-import os
-import subprocess
-import json
-import tempfile
-import time
-import shutil
-import statistics
-
-VIDEO_SOURCE = "../test_video/BigBuckBunny_320x180.mp4" # 10 minutes, 62MB
-if not os.path.exists(VIDEO_SOURCE):
- print(f"Video not found: {VIDEO_SOURCE}")
- sys.exit(1)
-
-
-def run_asr_mode(mode_name, max_direct_duration, chunk_duration, description):
- """Run ASR processor with given parameters, return timing."""
- clip_path = os.path.join(temp_dir, f"clip_{mode_name}.mp4")
- output_path = os.path.join(temp_dir, f"output_{mode_name}.json")
-
- # Copy source video to clip path
- shutil.copy2(VIDEO_SOURCE, clip_path)
-
- env = os.environ.copy()
- env["MOMENTRY_ASR_MAX_DIRECT_DURATION"] = str(max_direct_duration)
- env["MOMENTRY_ASR_CHUNK_DURATION"] = str(chunk_duration)
- env["MOMENTRY_ASR_MODEL_SIZE"] = "tiny"
- env["MOMENTRY_ASR_COMPUTE_TYPE"] = "int8"
-
- cmd = [
- "/opt/homebrew/bin/python3.11",
- "scripts/asr_processor.py",
- clip_path,
- output_path,
- "--uuid",
- f"bench_{mode_name}",
- ]
-
- start_time = time.time()
- proc = subprocess.run(cmd, capture_output=True, env=env, text=True)
- elapsed = time.time() - start_time
- returncode = proc.returncode
-
- # Read output
- segments = []
- language = ""
- if os.path.exists(output_path):
- with open(output_path, "r") as f:
- data = json.load(f)
- segments = data.get("segments", [])
- language = data.get("language", "")
-
- # Clean up
- try:
- os.unlink(clip_path)
- os.unlink(output_path)
- except:
- pass
-
- return {
- "mode": mode_name,
- "description": description,
- "elapsed": elapsed,
- "returncode": returncode,
- "segments": len(segments),
- "language": language,
- "stderr": proc.stderr[:200] if proc.stderr else "",
- }
-
-
-# Create temporary directory
-temp_dir = tempfile.mkdtemp(prefix="asr_bench_real_")
-print(f"Benchmark directory: {temp_dir}")
-
-try:
- # Test 1: Direct transcription (video is 10 min, max_direct=30 min)
- print("\n1. Direct transcription (max_direct=1800s, chunk=600s):")
- direct = run_asr_mode(
- "direct",
- max_direct_duration=1800,
- chunk_duration=600,
- description="Direct (video < 30min threshold)",
- )
- print(f" Time: {direct['elapsed']:.1f}s, Segments: {direct['segments']}")
-
- # Test 2: Chunked with 1 chunk (force chunked but chunk size = video duration)
- print("\n2. Chunked with 1 chunk (max_direct=300s, chunk=600s):")
- chunked1 = run_asr_mode(
- "chunked1",
- max_direct_duration=300,
- chunk_duration=600,
- description="Chunked with 1 chunk (10 min)",
- )
- print(f" Time: {chunked1['elapsed']:.1f}s, Segments: {chunked1['segments']}")
-
- # Test 3: Chunked with 2 chunks (5 min each)
- print("\n3. Chunked with 2 chunks (max_direct=300s, chunk=300s):")
- chunked2 = run_asr_mode(
- "chunked2",
- max_direct_duration=300,
- chunk_duration=300,
- description="Chunked with 2 chunks (5 min each)",
- )
- print(f" Time: {chunked2['elapsed']:.1f}s, Segments: {chunked2['segments']}")
-
- # Test 4: Chunked with 5 chunks (2 min each) - worst case
- print("\n4. Chunked with 5 chunks (max_direct=300s, chunk=120s):")
- chunked5 = run_asr_mode(
- "chunked5",
- max_direct_duration=300,
- chunk_duration=120,
- description="Chunked with 5 chunks (2 min each)",
- )
- print(f" Time: {chunked5['elapsed']:.1f}s, Segments: {chunked5['segments']}")
-
- # Calculate overheads
- print("\n" + "=" * 60)
- print("OVERHEAD ANALYSIS (compared to direct transcription)")
- print("=" * 60)
-
- for test in [chunked1, chunked2, chunked5]:
- if direct["elapsed"] > 0:
- overhead = (test["elapsed"] - direct["elapsed"]) / direct["elapsed"] * 100
- status = "✅ ≤5%" if overhead <= 5 else "❌ >5%"
- print(f"\n{test['description']}:")
- print(f" Time: {test['elapsed']:.1f}s (direct: {direct['elapsed']:.1f}s)")
- print(f" Overhead: {overhead:.2f}% {status}")
- print(f" Segments: {test['segments']} (direct: {direct['segments']})")
- if test["segments"] != direct["segments"]:
- print(f" ⚠️ Segment count mismatch!")
-
- # Summary
- print("\n" + "=" * 60)
- print("SUMMARY")
- print("=" * 60)
- print(f"Video: {os.path.basename(VIDEO_SOURCE)} (~10 minutes)")
- print(f"\nKey finding: Overhead depends heavily on chunk count.")
- print(f"With realistic chunk sizes (10 min), overhead should be minimal.")
-
-except Exception as e:
- print(f"Benchmark failed: {e}")
- import traceback
-
- traceback.print_exc()
-finally:
- # Clean up directory
- shutil.rmtree(temp_dir, ignore_errors=True)
- print(f"\nCleaned up {temp_dir}")
diff --git a/build.rs b/build.rs
index 83882e8..43fd11b 100644
--- a/build.rs
+++ b/build.rs
@@ -1,19 +1,4 @@
-use chrono::Local;
-use std::env;
-
fn main() {
- let now = Local::now();
- let build_time = now.format("%Y-%m-%d %H:%M:%S").to_string();
-
- // Get version from Cargo.toml
- let version = env!("CARGO_PKG_VERSION");
- let full_version = format!("{} (build: {})", version, build_time);
-
- // Set build-time environment variables
- println!("cargo:rustc-env=BUILD_VERSION={}", full_version);
- println!("cargo:rustc-env=BUILD_TIME={}", build_time);
- println!("cargo:rustc-env=VERSION={}", version);
-
- // Also print for debugging
- println!("cargo:warning=Building version: {}", full_version);
+ let version = std::env::var("CARGO_PKG_VERSION").unwrap_or_else(|_| "unknown".to_string());
+ println!("cargo:rustc-env=BUILD_VERSION={}", version);
}
diff --git a/check_whisper.py b/check_whisper.py
deleted file mode 100644
index 4d03213..0000000
--- a/check_whisper.py
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/opt/homebrew/bin/python3.11
-try:
- import whisper
-
- print("whisper available")
-except ImportError as e:
- print(f"whisper not available: {e}")
diff --git a/chunked_transcribe.py b/chunked_transcribe.py
deleted file mode 100644
index 2044b40..0000000
--- a/chunked_transcribe.py
+++ /dev/null
@@ -1,200 +0,0 @@
-#!/usr/bin/env python3
-"""
-Chunked transcription to handle large audio files.
-"""
-
-import sys
-import time
-import tempfile
-import json
-import subprocess
-from pathlib import Path
-import numpy as np
-
-
-def split_audio(input_path, chunk_duration=1800, output_dir=None):
- """Split audio into chunks using ffmpeg."""
- if output_dir is None:
- output_dir = Path(tempfile.mkdtemp(prefix="audio_chunks_"))
- else:
- output_dir = Path(output_dir)
- output_dir.mkdir(exist_ok=True, parents=True)
-
- # Get total duration
- cmd = [
- "ffprobe",
- "-v",
- "error",
- "-show_entries",
- "format=duration",
- "-of",
- "csv=p=0",
- str(input_path),
- ]
- result = subprocess.run(cmd, capture_output=True, text=True)
- total_duration = float(result.stdout.strip())
-
- print(
- f"Total audio duration: {total_duration:.1f}s ({total_duration / 3600:.1f} hrs)"
- )
- print(f"Splitting into {chunk_duration}s chunks...")
-
- chunks = []
- start = 0
- chunk_idx = 0
- while start < total_duration:
- chunk_path = output_dir / f"chunk_{chunk_idx:04d}.wav"
- cmd = [
- "ffmpeg",
- "-i",
- str(input_path),
- "-ss",
- str(start),
- "-t",
- str(chunk_duration),
- "-acodec",
- "pcm_s16le",
- "-ar",
- "16000",
- "-ac",
- "1",
- "-y",
- str(chunk_path),
- ]
- subprocess.run(cmd, capture_output=True)
- if chunk_path.exists() and chunk_path.stat().st_size > 0:
- chunks.append(
- {
- "path": chunk_path,
- "start_time": start,
- "end_time": min(start + chunk_duration, total_duration),
- }
- )
- else:
- print(f"Warning: Chunk {chunk_idx} may be empty")
- start += chunk_duration
- chunk_idx += 1
-
- print(f"Created {len(chunks)} chunks in {output_dir}")
- return chunks, output_dir
-
-
-def transcribe_chunk(chunk_info, model, chunk_idx, total_chunks):
- """Transcribe a single chunk."""
- print(
- f"[{chunk_idx + 1}/{total_chunks}] Transcribing chunk {chunk_info['start_time']:.1f}-{chunk_info['end_time']:.1f}"
- )
- start_time = time.time()
-
- segments, info = model.transcribe(str(chunk_info["path"]), beam_size=5)
- results = []
- for segment in segments:
- # Adjust timestamps by chunk start time
- results.append(
- {
- "start": segment.start + chunk_info["start_time"],
- "end": segment.end + chunk_info["start_time"],
- "text": segment.text.strip(),
- }
- )
-
- elapsed = time.time() - start_time
- print(f" → {len(results)} segments in {elapsed:.1f}s")
- return results, info
-
-
-def main():
- import argparse
-
- parser = argparse.ArgumentParser(description="Chunked transcription")
- parser.add_argument("audio_path", help="Audio file path")
- parser.add_argument(
- "--chunk-duration",
- type=int,
- default=1800,
- help="Chunk duration in seconds (default: 1800 = 30 min)",
- )
- parser.add_argument("--model-size", default="tiny", help="Whisper model size")
- parser.add_argument("--compute-type", default="int8", help="Compute type")
- parser.add_argument(
- "--output", "-o", default="chunked_transcription.json", help="Output JSON path"
- )
- args = parser.parse_args()
-
- audio_path = Path(args.audio_path)
- if not audio_path.exists():
- print(f"Error: File not found: {audio_path}")
- sys.exit(1)
-
- print(f"Chunked Transcription for {audio_path}")
- print(f"Model: {args.model_size}, Compute: {args.compute_type}")
- print(
- f"Chunk duration: {args.chunk_duration}s ({args.chunk_duration / 60:.1f} min)"
- )
-
- # Split audio
- chunks, temp_dir = split_audio(audio_path, chunk_duration=args.chunk_duration)
- if not chunks:
- print("No chunks created")
- sys.exit(1)
-
- # Load model once
- print("Loading Whisper model...")
- from faster_whisper import WhisperModel
-
- model_start = time.time()
- model = WhisperModel(args.model_size, device="cpu", compute_type=args.compute_type)
- print(f"Model loaded in {time.time() - model_start:.1f}s")
-
- # Process each chunk
- all_segments = []
- language = None
- language_prob = None
-
- for i, chunk in enumerate(chunks):
- try:
- segments, info = transcribe_chunk(chunk, model, i, len(chunks))
- all_segments.extend(segments)
- if language is None:
- language = info.language
- language_prob = info.language_probability
- except Exception as e:
- print(f"Error transcribing chunk {i}: {e}")
- import traceback
-
- traceback.print_exc()
- # Continue with next chunk
-
- # Sort segments by start time
- all_segments.sort(key=lambda x: x["start"])
-
- # Save results
- output = {
- "language": language or "unknown",
- "language_probability": language_prob or 0.0,
- "segments": all_segments,
- "chunk_count": len(chunks),
- "chunk_duration": args.chunk_duration,
- "total_segments": len(all_segments),
- }
-
- output_path = Path(args.output)
- output_path.parent.mkdir(exist_ok=True, parents=True)
- with open(output_path, "w") as f:
- json.dump(output, f, indent=2)
-
- print(f"\nTranscription completed:")
- print(f" Total segments: {len(all_segments)}")
- print(
- f" Language: {output['language']} (prob {output['language_probability']:.2f})"
- )
- print(f" Results saved to: {output_path}")
-
- # Cleanup temp directory
- import shutil
-
- shutil.rmtree(temp_dir, ignore_errors=True)
-
-
-if __name__ == "__main__":
- main()
diff --git a/com.momentry.api.updated.plist b/com.momentry.api.updated.plist
deleted file mode 100644
index 341fbd2..0000000
--- a/com.momentry.api.updated.plist
+++ /dev/null
@@ -1,64 +0,0 @@
-
-
-
-
- Label
- com.momentry.api
-
- UserName
- accusys
-
- GroupName
- staff
-
- WorkingDirectory
- /Users/accusys/momentry_core_0.1
-
- ProgramArguments
-
- /Users/accusys/momentry_core_0.1/target/release/momentry
- server
- --port
- 3002
-
-
- EnvironmentVariables
-
- PATH
- /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
-
- DATABASE_URL
- postgres://accusys@localhost:5432/momentry
-
- DB_MAX_CONNECTIONS
- 50
-
- DB_ACQUIRE_TIMEOUT
- 30
-
- REDIS_URL
- redis://:accusys@localhost:6379
-
- REDIS_PASSWORD
- accusys
-
- OLLAMA_HOST
- http://localhost:11434
-
- QDRANT_URL
- http://127.0.0.1:6333
-
-
- RunAtLoad
-
-
- KeepAlive
-
-
- StandardOutPath
- /Users/accusys/momentry/log/momentry_api.log
-
- StandardErrorPath
- /Users/accusys/momentry/log/momentry_api.error.log
-
-
\ No newline at end of file
diff --git a/create_job.rs b/create_job.rs
deleted file mode 100644
index fa3f0ec..0000000
--- a/create_job.rs
+++ /dev/null
@@ -1,98 +0,0 @@
-use anyhow::Result;
-use sqlx::postgres::PgPoolOptions;
-
-#[tokio::main]
-async fn main() -> Result<()> {
- // Database connection
- let pool = PgPoolOptions::new()
- .max_connections(5)
- .connect("postgres://accusys@localhost:5432/momentry")
- .await?;
-
- let video_uuid = "9760d0820f0cf9a7";
- let video_id = 28;
- let video_path = "/Users/accusys/momentry/var/sftpgo/data/demo/ExaSAN PCIe series - Director Ou Yu-Zhi Shares His Experience.mp4";
-
- println!("Creating monitor job for video:");
- println!(" UUID: {}", video_uuid);
- println!(" ID: {}", video_id);
- println!(" Path: {}", video_path);
-
- // 1. Create monitor job
- let job_row = sqlx::query(
- r#"
- INSERT INTO monitor_jobs (uuid, video_path, status)
- VALUES ($1, $2, 'pending')
- RETURNING id, uuid, video_path, status
- "#
- )
- .bind(video_uuid)
- .bind(video_path)
- .fetch_one(&pool)
- .await?;
-
- let job_id: i32 = job_row.get(0);
- let job_uuid: String = job_row.get(1);
- let job_status: String = job_row.get(3);
-
- println!("\nCreated monitor job:");
- println!(" Job ID: {}", job_id);
- println!(" Job UUID: {}", job_uuid);
- println!(" Status: {}", job_status);
-
- // 2. Update video with job_id
- sqlx::query(
- r#"
- UPDATE videos
- SET job_id = $1, updated_at = CURRENT_TIMESTAMP
- WHERE id = $2
- "#
- )
- .bind(job_id)
- .bind(video_id)
- .execute(&pool)
- .await?;
-
- println!("Updated video {} with job_id {}", video_id, job_id);
-
- // 3. Update monitor_jobs with video_id
- sqlx::query(
- r#"
- UPDATE monitor_jobs
- SET video_id = $1, updated_at = CURRENT_TIMESTAMP
- WHERE id = $2
- "#
- )
- .bind(video_id)
- .bind(job_id)
- .execute(&pool)
- .await?;
-
- println!("Updated monitor_jobs {} with video_id {}", job_id, video_id);
-
- // 4. Create processor results for this job
- let processors = vec!["asr", "cut", "yolo", "ocr", "face", "pose", "asrx"];
-
- for processor in processors {
- sqlx::query(
- r#"
- INSERT INTO processor_results (job_id, video_id, processor, status)
- VALUES ($1, $2, $3, 'pending')
- ON CONFLICT (job_id, processor) DO NOTHING
- "#
- )
- .bind(job_id)
- .bind(video_id)
- .bind(processor)
- .execute(&pool)
- .await?;
-
- println!("Created processor result for {}: {}", processor, job_id);
- }
-
- println!("\n✅ Job creation completed successfully!");
- println!("Job ID: {}", job_id);
- println!("The worker should now pick up this job and start processing.");
-
- Ok(())
-}
diff --git a/create_job.sql b/create_job.sql
deleted file mode 100644
index f345734..0000000
--- a/create_job.sql
+++ /dev/null
@@ -1,7 +0,0 @@
--- 1. Create monitor job
-INSERT INTO monitor_jobs (uuid, video_path, status)
-VALUES ('9760d0820f0cf9a7', '/Users/accusys/momentry/var/sftpgo/data/demo/ExaSAN PCIe series - Director Ou Yu-Zhi Shares His Experience.mp4', 'pending')
-RETURNING id;
-
--- Note: The job_id will be returned. Let's assume it's 18 for now.
--- We'll run these commands step by step.
diff --git a/debug_asr.py b/debug_asr.py
deleted file mode 100644
index 1cfd581..0000000
--- a/debug_asr.py
+++ /dev/null
@@ -1,150 +0,0 @@
-#!/usr/bin/env python3
-"""
-Debug ASR processing stages for large video.
-"""
-
-import os
-import sys
-import time
-import subprocess
-import tempfile
-import json
-from pathlib import Path
-
-
-def run_ffmpeg_extract(video_path, audio_path):
- """Extract audio using ffmpeg."""
- cmd = [
- "ffmpeg",
- "-i",
- str(video_path),
- "-vn",
- "-acodec",
- "pcm_s16le",
- "-ar",
- "16000",
- "-ac",
- "1",
- "-y",
- str(audio_path),
- ]
- print(f"Running ffmpeg: {' '.join(cmd)}")
- start = time.time()
- proc = subprocess.run(cmd, capture_output=True, text=True)
- elapsed = time.time() - start
- print(f"ffmpeg completed in {elapsed:.1f}s, return code: {proc.returncode}")
- if proc.returncode != 0:
- print(f"stderr: {proc.stderr[:500]}")
- return proc.returncode == 0, elapsed
-
-
-def test_asr_stages(video_path):
- """Test ASR stages step by step."""
- video_path = Path(video_path)
- print(f"Testing video: {video_path}")
- print(f"Size: {video_path.stat().st_size / 1024 / 1024:.1f} MB")
-
- # Stage 1: Check audio streams
- print("\n=== Stage 1: Check audio streams ===")
- cmd = [
- "ffprobe",
- "-v",
- "error",
- "-select_streams",
- "a",
- "-show_entries",
- "stream=codec_name,channels,sample_rate,duration",
- "-of",
- "csv=p=0",
- str(video_path),
- ]
- proc = subprocess.run(cmd, capture_output=True, text=True)
- print(f"Audio streams: {proc.stdout.strip()}")
-
- # Stage 2: Extract audio
- print("\n=== Stage 2: Extract audio ===")
- with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
- audio_path = f.name
- try:
- success, extract_time = run_ffmpeg_extract(video_path, audio_path)
- if success:
- print(f"Audio extracted to {audio_path}")
- print(f"Audio size: {Path(audio_path).stat().st_size / 1024 / 1024:.1f} MB")
- else:
- print("Audio extraction failed")
- os.unlink(audio_path)
- return
- except Exception as e:
- print(f"Error extracting audio: {e}")
- return
-
- # Stage 3: Load faster_whisper model (just import)
- print("\n=== Stage 3: Test faster_whisper import ===")
- try:
- start = time.time()
- from faster_whisper import WhisperModel
-
- elapsed = time.time() - start
- print(f"Import faster_whisper: {elapsed:.1f}s")
- except Exception as e:
- print(f"Import failed: {e}")
- os.unlink(audio_path)
- return
-
- # Stage 4: Transcribe a small segment (first 30 seconds)
- print("\n=== Stage 4: Transcribe first 30 seconds ===")
- try:
- # Trim audio to first 30 seconds
- trim_path = audio_path + ".trim.wav"
- cmd = [
- "ffmpeg",
- "-i",
- audio_path,
- "-t",
- "30",
- "-acodec",
- "pcm_s16le",
- "-ar",
- "16000",
- "-ac",
- "1",
- "-y",
- trim_path,
- ]
- subprocess.run(cmd, capture_output=True)
-
- # Load model with small model
- start = time.time()
- model = WhisperModel("tiny", device="cpu", compute_type="int8")
- load_time = time.time() - start
- print(f"Model loaded in {load_time:.1f}s")
-
- # Transcribe
- start = time.time()
- segments, info = model.transcribe(trim_path, beam_size=5)
- segments = list(segments) # Force processing
- transcribe_time = time.time() - start
- print(f"Transcription of 30s audio: {transcribe_time:.1f}s")
- print(
- f"Detected language: {info.language} with probability {info.language_probability}"
- )
- print(f"Segments found: {len(segments)}")
-
- # Cleanup
- os.unlink(trim_path)
- except Exception as e:
- print(f"Transcription test failed: {e}")
- import traceback
-
- traceback.print_exc()
- finally:
- os.unlink(audio_path)
-
- print("\n=== Debug complete ===")
-
-
-if __name__ == "__main__":
- if len(sys.argv) != 2:
- print(f"Usage: {sys.argv[0]} ")
- sys.exit(1)
- test_asr_stages(sys.argv[1])
diff --git a/debug_chunked_hang.py b/debug_chunked_hang.py
deleted file mode 100644
index 7b617ad..0000000
--- a/debug_chunked_hang.py
+++ /dev/null
@@ -1,85 +0,0 @@
-#!/usr/bin/env python3
-import sys
-import time
-
-print("Start")
-print("Importing faster_whisper...")
-try:
- from faster_whisper import WhisperModel
-
- print("Import successful")
-except Exception as e:
- print(f"Import failed: {e}")
- sys.exit(1)
-
-print("Loading model...")
-try:
- model = WhisperModel("tiny", device="cpu", compute_type="int8")
- print("Model loaded")
-except Exception as e:
- print(f"Model load failed: {e}")
- sys.exit(1)
-
-import subprocess
-
-print("Getting duration...")
-cmd = [
- "ffprobe",
- "-v",
- "error",
- "-show_entries",
- "format=duration",
- "-of",
- "csv=p=0",
- "/tmp/test_audio.wav",
-]
-result = subprocess.run(cmd, capture_output=True, text=True)
-print(f"ffprobe output: {result.stdout}")
-duration = float(result.stdout.strip())
-print(f"Duration: {duration}")
-
-# Extract first chunk
-print("Extracting first chunk...")
-chunk_path = "/tmp/debug_chunk.wav"
-cmd = [
- "ffmpeg",
- "-i",
- "/tmp/test_audio.wav",
- "-t",
- "60",
- "-acodec",
- "pcm_s16le",
- "-ar",
- "16000",
- "-ac",
- "1",
- "-y",
- chunk_path,
-]
-result = subprocess.run(cmd, capture_output=True, text=True)
-print(f"ffmpeg return code: {result.returncode}")
-if result.returncode != 0:
- print(f"stderr: {result.stderr[:200]}")
-
-import os
-
-print(f"Chunk exists: {os.path.exists(chunk_path)}")
-if os.path.exists(chunk_path):
- print(f"Chunk size: {os.path.getsize(chunk_path)}")
-
- print("Transcribing chunk...")
- start = time.time()
- try:
- segments, info = model.transcribe(chunk_path, beam_size=5)
- segments = list(segments)
- elapsed = time.time() - start
- print(f"Transcription succeeded in {elapsed}s, segments: {len(segments)}")
- except Exception as e:
- print(f"Transcription failed: {e}")
- import traceback
-
- traceback.print_exc()
-else:
- print("Chunk not created")
-
-print("Script finished")
diff --git a/docs_v1.0/API/PEOPLE_API_MARCOM_MAPPING.md b/docs_v1.0/API/PEOPLE_API_MARCOM_MAPPING.md
deleted file mode 100644
index 2625833..0000000
--- a/docs_v1.0/API/PEOPLE_API_MARCOM_MAPPING.md
+++ /dev/null
@@ -1,442 +0,0 @@
-# People API 设计方案 (marcom 需求等效映射)
-
-**日期**: 2026-04-28
-**状态**: 设计阶段
-**目的**: 根据 marcom 团队需求，在符合现有架构的前提下提供等效 API
-
----
-
-## 设计原则
-
-1. **遵循 RESTful 规范**: 使用标准 HTTP 方法 (GET, POST, PATCH, DELETE)
-2. **统一路径前缀**: `/api/v1/people`
-3. **响应格式统一**: `{ success: bool, message: string, data: any }`
-4. **向后兼容**: 现有 API 保持不变，新 API 扩展功能
-5. **符合 Identity 系统**: 与 `identities` 表和 `identity_bindings` 表集成
-
----
-
-## API 对照表
-
-### 1. GET /people/candidates (候选人物)
-
-**marcom 需求**: 获取待确认的人物候选列表
-
-**等效 API**:
-```
-GET /api/v1/people/candidates?file_uuid={uuid}&limit={n}
-```
-
-**功能**:
-- 返回待确认的人物身份候选
-- 包含 face cluster、speaker cluster 的匹配建议
-- 状态: `pending`, `suggested`, `unmatched`
-
-**响应示例**:
-```json
-{
- "success": true,
- "message": "Found 15 candidates",
- "data": {
- "candidates": [
- {
- "candidate_id": "face_cluster_1",
- "type": "face",
- "suggested_identity": {
- "id": 123,
- "name": "张曼玉",
- "confidence": 0.92
- },
- "appearance_count": 45,
- "status": "pending"
- }
- ],
- "total": 15
- }
-}
-```
-
-**实现**: 扩展现有 `/api/v1/people/suggest`
-
----
-
-### 2. GET /people (人物列表)
-
-**marcom 需求**: 获取所有人物列表
-
-**等效 API**:
-```
-GET /api/v1/people?file_uuid={uuid}&limit={n}&offset={n}&status={status}
-```
-
-**功能**:
-- 返回人物身份列表
-- 支持按 file_uuid 筛选
-- 支持分页
-- 支持按状态筛选 (confirmed, pending, all)
-
-**响应示例**:
-```json
-{
- "success": true,
- "message": "Found 8 persons",
- "data": {
- "persons": [
- {
- "identity_id": "Person_17",
- "name": "张曼玉",
- "appearance_count": 45,
- "total_duration": 350.2,
- "is_confirmed": true
- }
- ],
- "total": 8
- }
-}
-```
-
-**实现**: 现有 `/api/v1/people/list` 已支持
-
----
-
-### 3. GET /people/{identity_id} (人物详情)
-
-**marcom 需求**: 获取人物详情
-
-**等效 API**:
-```
-GET /api/v1/people/{identity_id}?file_uuid={uuid}
-```
-
-**功能**:
-- 返回人物详细信息
-- 包含出场时间线
-- 包含关联的 face/speaker
-- 包含缩略图
-
-**响应示例**:
-```json
-{
- "success": true,
- "data": {
- "identity_id": "Person_17",
- "name": "张曼玉",
- "face_identity_id": 123,
- "speaker_id": "SPEAKER_00",
- "appearance_count": 45,
- "total_duration": 350.2,
- "first_appearance_time": 10.5,
- "last_appearance_time": 360.2,
- "timeline": [...],
- "thumbnails": [...]
- }
-}
-```
-
-**实现**: 现有 `/api/v1/people/:person_id` 已支持
-
----
-
-### 4. POST /people (创建人物)
-
-**marcom 需求**: 手动创建新人物
-
-**等效 API**:
-```
-POST /api/v1/people
-Body: { "name": "张曼玉", "file_uuid": "xxx", "metadata": {...} }
-```
-
-**功能**:
-- 创建新人物身份
-- 关联到指定视频
-- 支持添加 metadata (角色名、演员名等)
-
-**响应示例**:
-```json
-{
- "success": true,
- "message": "Person created",
- "data": {
- "identity_id": "Person_99",
- "name": "张曼玉",
- "file_uuid": "xxx"
- }
-}
-```
-
-**实现**: 需新增，参考 `CreatePersonIdentityRequest`
-
----
-
-### 5. PATCH /people/{identity_id} (更新人物)
-
-**marcom 需求**: 更新人物信息
-
-**等效 API**:
-```
-PATCH /api/v1/people/{identity_id}
-Body: { "name": "新名字", "is_confirmed": true, "metadata": {...} }
-```
-
-**功能**:
-- 更新人物名称
-- 确认人物身份
-- 更新 metadata
-
-**实现**: 现有 `/api/v1/people/:person_id` (PATCH) 已支持
-
----
-
-### 6. POST /people/merge (合并人物)
-
-**marcom 需求**: 合并多个人物为一个
-
-**等效 API**:
-```
-POST /api/v1/people/merge
-Body: {
- "target_identity_id": "Person_17",
- "source_identity_ids": ["Person_18", "Person_19"]
-}
-```
-
-**功能**:
-- 合并多个人物身份
-- 转移所有出场记录
-- 更新统计数据
-
-**实现**: 现有 `/api/v1/people/merge` 已支持
-
----
-
-### 7. POST /people/skip (跳过人物)
-
-**marcom 需求**: 跳过某个候选人物（不处理）
-
-**等效 API**:
-```
-POST /api/v1/people/skip
-Body: { "candidate_id": "face_cluster_2", "reason": "非人物" }
-```
-
-**功能**:
-- 标记候选为"已跳过"
-- 记录跳过原因
-- 不创建人物身份
-
-**响应示例**:
-```json
-{
- "success": true,
- "message": "Candidate skipped",
- "data": {
- "candidate_id": "face_cluster_2",
- "status": "skipped",
- "reason": "非人物"
- }
-}
-```
-
-**实现**: 需新增，扩展候选管理功能
-
----
-
-### 8. POST /people/{identity_id}/remove-face (移除人脸)
-
-**marcom 需求**: 从人物身份中移除特定人脸绑定
-
-**等效 API**:
-```
-POST /api/v1/people/{identity_id}/unbind
-Body: { "binding_type": "face", "binding_value": "face_123" }
-```
-
-**功能**:
-- 解绑人脸与人物身份的关联
-- 人脸回到候选状态
-- 更新人物出场统计
-
-**响应示例**:
-```json
-{
- "success": true,
- "message": "Face unbound",
- "data": {
- "identity_id": "Person_17",
- "unbound_face": "face_123",
- "updated_appearance_count": 42
- }
-}
-```
-
-**实现**: 需新增，参考现有 `UnbindIdentityRequest`
-
----
-
-### 9. POST /people/split-face (分离人脸)
-
-**marcom 需求**: 将人脸从现有人物分离为新人物
-
-**等效 API**:
-```
-POST /api/v1/people/split
-Body: {
- "source_identity_id": "Person_17",
- "face_ids": ["face_123", "face_124"],
- "new_identity_name": "新人物"
-}
-```
-
-**功能**:
-- 从现有人物分离指定人脸
-- 创建新人物身份
-- 转移出场记录
-
-**实现**: 现有 `/api/v1/people/:person_id/split` 部分支持
-
----
-
-### 10. GET /people/{identity_id}/resolve (解决冲突)
-
-**marcom 需求**: 获取人物的冲突/歧义信息
-
-**等效 API**:
-```
-GET /api/v1/people/{identity_id}/conflicts
-```
-
-**功能**:
-- 返回人物身份的潜在冲突
-- 显示相似人脸/声音的匹配
-- 提供解决方案建议
-
-**响应示例**:
-```json
-{
- "success": true,
- "data": {
- "identity_id": "Person_17",
- "conflicts": [
- {
- "type": "similar_face",
- "conflicting_identity": "Person_18",
- "similarity": 0.85,
- "suggestion": "merge"
- }
- ],
- "resolution_options": ["merge", "keep_separate", "skip"]
- }
-}
-```
-
-**实现**: 需新增
-
----
-
-### 11. POST /search (搜索)
-
-**marcom 需求**: 搜索人物
-
-**等效 API**:
-```
-POST /api/v1/people/search
-Body: {
- "query": "张",
- "filters": { "type": "people", "file_uuid": "xxx" },
- "limit": 20
-}
-```
-
-**功能**:
-- 搜索人物身份
-- 支持按名称、类型、视频筛选
-- 返回匹配结果
-
-**实现**: 现有 `/api/v1/identities/search` 已支持，建议扩展
-
----
-
-### 12. GET /people/status (人物状态)
-
-**marcom 需求**: 获取人物处理状态统计
-
-**等效 API**:
-```
-GET /api/v1/people/status?file_uuid={uuid}
-```
-
-**功能**:
-- 返回人物处理统计
-- 待确认数量、已确认数量、跳过数量
-- 合并历史
-
-**响应示例**:
-```json
-{
- "success": true,
- "data": {
- "file_uuid": "xxx",
- "total_candidates": 15,
- "confirmed": 8,
- "pending": 5,
- "skipped": 2,
- "merge_count": 3,
- "split_count": 1
- }
-}
-```
-
-**实现**: 需新增
-
----
-
-## 实现优先级
-
-| 优先级 | API | 状态 | 预估工时 |
-|--------|-----|------|----------|
-| **P0** | GET /people | ✅ 已有 | 0h |
-| **P0** | GET /people/{identity_id} | ✅ 已有 | 0h |
-| **P0** | PATCH /people/{identity_id} | ✅ 已有 | 0h |
-| **P0** | POST /people/merge | ✅ 已有 | 0h |
-| **P1** | GET /people/candidates | ⚠️ 扩展 | 2h |
-| **P1** | POST /people | ❌ 新增 | 2h |
-| **P1** | POST /people/search | ⚠️ 扩展 | 1h |
-| **P2** | POST /people/skip | ❌ 新增 | 2h |
-| **P2** | POST /people/{identity_id}/unbind | ❌ 新增 | 2h |
-| **P2** | POST /people/split | ⚠️ 扩展 | 1h |
-| **P2** | GET /people/{identity_id}/conflicts | ❌ 新增 | 3h |
-| **P2** | GET /people/status | ❌ 新增 | 2h |
-
-**总预估**: ~13h (P1+P2)
-
----
-
-## 数据库表需求
-
-现有表结构支持大部分需求，可能需要扩展：
-
-```sql
--- 建议新增: candidates 表 (候选管理)
-CREATE TABLE person_candidates (
- id BIGSERIAL PRIMARY KEY,
- file_uuid VARCHAR(36) NOT NULL,
- candidate_type VARCHAR(20), -- 'face', 'speaker'
- candidate_id VARCHAR(50), -- 'face_cluster_1', 'speaker_2'
- suggested_identity_id BIGINT,
- confidence FLOAT,
- status VARCHAR(20), -- 'pending', 'confirmed', 'skipped'
- skip_reason TEXT,
- created_at TIMESTAMP,
- updated_at TIMESTAMP
-);
-```
-
----
-
-## 参考文档
-
-- `docs_v1.0/ARCHITECTURE/MOMENTRY_CORE_ARCHITECTURE_V2.md` - Identity 系统设计
-- `docs_v1.0/ARCHITECTURE/PERSON_IDENTITY_INTEGRATION.md` - Person Identity 整合
-- `src/api/person_identity.rs` - 现有 API 实现
-- `src/api/identity_binding.rs` - 身份绑定 API
diff --git a/docs_v1.0/API_DOCUMENTATION.md b/docs_v1.0/API_DOCUMENTATION.md
deleted file mode 100644
index 7306170..0000000
--- a/docs_v1.0/API_DOCUMENTATION.md
+++ /dev/null
@@ -1,699 +0,0 @@
-# Momentry Core API Documentation v1.0.0
-
-## Overview
-Momentry Core is a digital asset management system with video analysis, RAG, and face recognition capabilities. This document covers all API endpoints available in v1.0.0.
-
-**Base URL**: `http://:`
-- Production: Port 3002
-- Development (Playground): Port 3003
-
-**Authentication**: All protected routes require API key validation via `X-API-Key` header.
-
----
-
-## API Classification
-
-The API is organized into 7 categories:
-
-| Category | Prefix | Description |
-|----------|--------|-------------|
-| **Health & Auth** | `/health`, `/api/v1/auth` | System health, authentication |
-| **Asset Management** | `/api/v1/register`, `/api/v1/files`, `/api/v1/assets` | File registration, probing, processing |
-| **Search** | `/api/v1/search`, `/api/v1/n8n` | Text, hybrid, visual, and n8n search |
-| **Video Details** | `/api/v1/videos`, `/api/v1/progress` | Video listing, details, chunks |
-| **Identity & Binding** | `/api/v1/identities`, `/api/v1/signals` | Face/speaker identity management |
-| **Jobs & Rules** | `/api/v1/jobs`, `/api/v1/rules` | Processing job monitoring |
-| **Stats & Config** | `/api/v1/stats`, `/api/v1/config` | System statistics, configuration |
-
----
-
-## 1. Health & Authentication
-
-### `GET /health`
-Basic health check.
-
-**Response**:
-```json
-{
- "status": "ok",
- "version": "v1.0.0",
- "uptime_ms": 12345
-}
-```
-
-### `GET /health/detailed`
-Detailed health check with service status (PostgreSQL, Redis, Qdrant, MongoDB).
-
-**Response**:
-```json
-{
- "status": "ok",
- "version": "v1.0.0",
- "uptime_ms": 12345,
- "services": {
- "postgres": { "status": "ok", "latency_ms": 5 },
- "redis": { "status": "ok", "latency_ms": 2 },
- "qdrant": { "status": "ok", "latency_ms": 10 },
- "mongodb": { "status": "ok", "latency_ms": 8 }
- }
-}
-```
-
-### `POST /api/v1/auth/login`
-Authenticate and obtain API key.
-
-**Request**:
-```json
-{
- "username": "demo",
- "password": "demo"
-}
-```
-
-**Response**:
-```json
-{
- "success": true,
- "message": "Login successful",
- "api_key": "muser_test_001",
- "user": { "username": "demo" }
-}
-```
-
-### `POST /api/v1/auth/logout`
-Logout session.
-
-**Response**:
-```json
-{ "success": true }
-```
-
----
-
-## 2. Asset Management
-
-### `POST /api/v1/register`
-Register a video file (legacy path-based).
-
-**Request**:
-```json
-{ "path": "./demo/video.mp4" }
-```
-
-**Response**:
-```json
-{
- "file_uuid": "384b0ff44aaaa1f1",
- "file_id": 1,
- "job_id": 1,
- "file_name": "video.mp4",
- "duration": 120.5,
- "width": 1920,
- "height": 1080,
- "already_exists": false
-}
-```
-
-### `POST /api/v1/files/register`
-Register a file with full metadata (recommended). Supports move detection.
-
-**Request**:
-```json
-{
- "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4",
- "user_id": null
-}
-```
-
-**Response**:
-```json
-{
- "success": true,
- "file_uuid": "384b0ff44aaaa1f1",
- "file_name": "video.mp4",
- "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4",
- "file_type": "video",
- "duration": 120.5,
- "width": 1920,
- "height": 1080,
- "fps": 30.0,
- "total_frames": 3615,
- "registration_time": null,
- "already_exists": false,
- "message": "File registered successfully"
-}
-```
-
-### `GET /api/v1/files/scan`
-Scan filesystem for unregistered files.
-
-### `POST /api/v1/unregister`
-Unregister a video file.
-
-**Request**:
-```json
-{ "uuid": "384b0ff44aaaa1f1" }
-```
-
-### `POST /api/v1/probe`
-Probe a video file for metadata.
-
-**Request**:
-```json
-{ "path": "./demo/video.mp4" }
-```
-
-**Response**:
-```json
-{
- "uuid": "384b0ff44aaaa1f1",
- "file_name": "video.mp4",
- "duration": 120.5,
- "width": 1920,
- "height": 1080,
- "fps": 30.0,
- "cached": true,
- "format": { ... },
- "streams": [ ... ]
-}
-```
-
-### `GET /api/v1/assets/:uuid/probe`
-Probe a video by UUID.
-
-### `POST /api/v1/assets/:uuid/process`
-Trigger processing pipeline for an asset.
-
-**Request**:
-```json
-{
- "processors": ["asr", "cut", "yolo", "ocr", "face", "pose", "asrx", "visual_chunk"]
-}
-```
-
-**Response**:
-```json
-{
- "job_id": 1,
- "asset_uuid": "384b0ff44aaaa1f1",
- "status": "PENDING",
- "message": "Processing triggered for video.mp4"
-}
-```
-
-### `GET /api/v1/assets/:uuid/status`
-Get asset processing status with frame progress.
-
-**Response**:
-```json
-{
- "uuid": "384b0ff44aaaa1f1",
- "file_name": "video.mp4",
- "registration_time": "2026-04-30T10:00:00Z",
- "processing_status": "processing",
- "current_job_id": "abc-123",
- "frame_progress": {
- "total_frames": 3615,
- "processed_frames": 1200,
- "progress_percent": 33.2
- }
-}
-```
-
----
-
-## 3. Search
-
-### `POST /api/v1/search`
-Vector/smart search across chunks.
-
-**Request**:
-```json
-{
- "query": "person talking about AI",
- "mode": "smart",
- "uuid": "384b0ff44aaaa1f1",
- "limit": 10
-}
-```
-
-**Response**:
-```json
-{
- "results": [
- {
- "uuid": "384b0ff44aaaa1f1",
- "chunk_id": "chunk_1",
- "chunk_type": "sentence",
- "start_time": 10.5,
- "end_time": 15.2,
- "text": "AI is transforming...",
- "score": 0.85
- }
- ],
- "query": "person talking about AI"
-}
-```
-
-### `POST /api/v1/search/hybrid`
-Hybrid search (vector + BM25).
-
-**Request**:
-```json
-{
- "query": "search term",
- "limit": 10,
- "uuid": "384b0ff44aaaa1f1",
- "vector_weight": 0.7,
- "bm25_weight": 0.3
-}
-```
-
-### `POST /api/v1/search/bm25`
-BM25 full-text search.
-
-### `POST /api/v1/search/visual`
-Search visual chunks by criteria.
-
-**Request**:
-```json
-{
- "uuid": "384b0ff44aaaa1f1",
- "criteria": {
- "object_class": "person",
- "min_count": 1
- }
-}
-```
-
-### `POST /api/v1/search/visual/class`
-Search by object class.
-
-**Request**:
-```json
-{
- "uuid": "384b0ff44aaaa1f1",
- "object_class": "person",
- "min_count": 1,
- "max_count": null
-}
-```
-
-### `POST /api/v1/search/visual/density`
-Search by object density.
-
-**Request**:
-```json
-{
- "uuid": "384b0ff44aaaa1f1",
- "min_density": 0.5,
- "max_density": null
-}
-```
-
-### `POST /api/v1/search/visual/combination`
-Search by object combination.
-
-**Request**:
-```json
-{
- "uuid": "384b0ff44aaaa1f1",
- "combination": [["person", 2], ["car", 1]]
-}
-```
-
-### `POST /api/v1/search/visual/stats`
-Get visual chunk statistics.
-
-**Request**:
-```json
-{ "uuid": "384b0ff44aaaa1f1" }
-```
-
-### `POST /api/v1/n8n/search`
-Search via n8n integration.
-
-### `POST /api/v1/n8n/search/bm25`
-BM25 search via n8n.
-
-### `POST /api/v1/n8n/search/hybrid`
-Hybrid search via n8n.
-
-### `POST /api/v1/n8n/search/smart`
-Smart search via n8n.
-
----
-
-## 4. Video Details
-
-### `GET /api/v1/videos`
-List all registered videos with pagination.
-
-**Query Parameters**:
-- `page`: Page number (default: 1)
-- `page_size`: Items per page (default: 20)
-- `status`: Filter by status
-- `q`: Search query
-- `uuid`: Filter by UUID
-
-**Response**:
-```json
-{
- "files": [
- {
- "file_uuid": "384b0ff44aaaa1f1",
- "file_path": "/path/to/video.mp4",
- "file_name": "video.mp4",
- "file_type": "video",
- "duration": 120.5,
- "width": 1920,
- "height": 1080,
- "status": "completed",
- "created_at": "2026-04-30T10:00:00Z",
- "file_size": 52428800,
- "total_frames": 3615
- }
- ],
- "count": 1,
- "page": 1,
- "page_size": 20
-}
-```
-
-### `DELETE /api/v1/videos/:uuid`
-Delete a video and all associated data (faces, chunks, processor results).
-
-**Response**:
-```json
-{
- "success": true,
- "message": "File 384b0ff44aaaa1f1 unregistered successfully...",
- "file_uuid": "384b0ff44aaaa1f1",
- "deleted_face_detections": 150,
- "deleted_processor_results": 8,
- "deleted_chunks": 45
-}
-```
-
-### `GET /api/v1/videos/:uuid/details`
-Get detailed chunk information.
-
-**Query Parameters**:
-- `chunk_id`: Specific chunk ID (required)
-- `parent_id`: Parent chunk ID
-
-**Response**:
-```json
-{
- "uuid": "384b0ff44aaaa1f1",
- "chunk_id": "chunk_1",
- "chunk_type": "sentence",
- "frame_range": {
- "start_frame": 315,
- "end_frame": 456,
- "duration_frames": 141,
- "fps": 30.0
- },
- "reference_time": {
- "start": 10.5,
- "end": 15.2
- },
- "text_content": "AI is transforming...",
- "summary_text": "Discussion about AI impact",
- "speaker_ids": ["SPEAKER_0"],
- "person_ids": ["face_100"]
-}
-```
-
-### `GET /api/v1/videos/:uuid/pre_chunks`
-List pre-processor chunks.
-
-**Query Parameters**:
-- `processor_type`: Filter by processor (asr, yolo, face, etc.)
-- `page`: Page number
-- `page_size`: Items per page
-
-### `GET /api/v1/progress/:uuid`
-Get processing progress for a video.
-
----
-
-## 5. Identity & Binding
-
-### `POST /api/v1/identities/from-face`
-Register a global identity from face.json with multi-angle reference vectors.
-
-**Request**:
-```json
-{
- "face_json_path": "/path/to/face.json",
- "identity_name": "John Doe",
- "schema": "dev"
-}
-```
-
-### `POST /api/v1/identities/from-person`
-Register identity from a person in a video.
-
-**Request**:
-```json
-{
- "file_uuid": "384b0ff44aaaa1f1",
- "person_id": "person_1",
- "identity_name": "John Doe"
-}
-```
-
-### `GET /api/v1/identities`
-List all global identities.
-
-**Query Parameters**:
-- `page`: Page number
-- `page_size`: Items per page
-
-### `GET /api/v1/faces/candidates`
-List unbound face candidates.
-
-**Query Parameters**:
-- `file_uuid`: Filter by file
-- `min_confidence`: Minimum confidence (default: 0.5)
-- `page`, `page_size`: Pagination
-
-### `GET /api/v1/identities/:identity_id/faces`
-Get all faces for an identity.
-
-### `GET /api/v1/faces/:face_id/thumbnail`
-Get face thumbnail image (JPEG).
-
-### `POST /api/v1/identities/bind`
-Bind a face/speaker to an identity.
-
-**Request**:
-```json
-{
- "identity_id": 1,
- "binding_type": "face",
- "binding_value": "face_100",
- "source": "manual"
-}
-```
-
-### `POST /api/v1/identities/unbind`
-Unbind an identity.
-
-**Request**:
-```json
-{
- "binding_type": "face",
- "binding_value": "face_100"
-}
-```
-
-### `GET /api/v1/identity/:binding_type/:binding_value`
-Get identity info by binding.
-
-### `GET /api/v1/signals/unbound`
-List unbound signals.
-
-**Query Parameters**:
-- `uuid`: File UUID
-- `binding_type`: "face" or "speaker"
-
-### `GET /api/v1/signals/:uuid/:binding_type/:binding_value/timeline`
-Get signal timeline (all chunks for a face/speaker).
-
-### `POST /api/v1/identities/suggest-av`
-Suggest audio-visual bindings based on temporal overlap.
-
-**Request**:
-```json
-{
- "file_uuid": "384b0ff44aaaa1f1",
- "overlap_threshold": 0.6
-}
-```
-
----
-
-## 6. Jobs & Rules
-
-### `GET /api/v1/jobs`
-List all monitor jobs.
-
-**Query Parameters**:
-- `page`, `page_size`: Pagination
-- `status`: Filter by status
-
-### `GET /api/v1/jobs/:job_id`
-Get job details with processor information.
-
-**Response**:
-```json
-{
- "job_id": "1",
- "asset_uuid": "384b0ff44aaaa1f1",
- "rule": "default",
- "status": "RUNNING",
- "current_processor_id": "asr",
- "frame_progress": {
- "total_frames": 3615,
- "processed_frames": 1200,
- "progress_percent": 33.2
- }
-}
-```
-
-### `GET /api/v1/rules/:rule/status`
-Get rule status with active jobs.
-
----
-
-## 7. Stats & Configuration
-
-### `GET /api/v1/stats/ingest`
-Get ingestion statistics.
-
-**Response**:
-```json
-{
- "total_videos": 50,
- "total_chunks": 1200,
- "sentence_chunks": 800,
- "cut_chunks": 300,
- "time_chunks": 100,
- "searchable_chunks": 1150,
- "chunks_with_visual": 450,
- "chunks_with_summary": 200,
- "pending_videos": 5
-}
-```
-
-### `GET /api/v1/stats/sftpgo`
-Get SFTPGo status and registered videos.
-
-### `GET /api/v1/stats/inference`
-Check inference engine health (Ollama, llama-server).
-
-**Response**:
-```json
-{
- "ollama": {
- "engine": "Ollama",
- "model": "nomic-embed-text",
- "status": "ok",
- "latency_ms": 15
- },
- "llama_server": {
- "engine": "llama-server",
- "model": "gemma4_e4b_q5",
- "status": "ok",
- "latency_ms": 25
- }
-}
-```
-
-### `POST /api/v1/config/cache`
-Toggle MongoDB cache.
-
-**Request**:
-```json
-{ "enabled": false }
-```
-
-**Response**:
-```json
-{
- "success": true,
- "cache_enabled": false,
- "message": "Cache disabled"
-}
-```
-
----
-
-## API Usage Patterns
-
-### 1. List Pattern
-```
-GET /api/v1/videos?page=1&page_size=20
-```
-- Supports pagination
-- Optional filters via query parameters
-- Returns `{ items: [...], count, page, page_size }`
-
-### 2. Detail Pattern
-```
-GET /api/v1/videos/:uuid/details?chunk_id=chunk_1
-```
-- Path parameter for resource identifier
-- Query parameters for sub-resource selection
-- Returns detailed object with nested structures
-
-### 3. Operation Pattern
-```
-POST /api/v1/assets/:uuid/process
-```
-- Action-oriented endpoint
-- Request body contains operation parameters
-- Returns operation status and job ID
-
-### 4. Application Pattern
-```
-POST /api/v1/identities/bind
-POST /api/v1/identities/suggest-av
-```
-- Complex workflows with multiple steps
-- Often involve external services (Python scripts, FFmpeg)
-- Return comprehensive results with metadata
-
----
-
-## Error Responses
-
-| Status Code | Description |
-|-------------|-------------|
-| `400` | Bad Request - Invalid parameters |
-| `404` | Not Found - Resource doesn't exist |
-| `500` | Internal Server Error - Database/service failure |
-
----
-
-## V4.0 Architecture Notes
-
-### Key Changes from V3.x
-- `video_uuid` → `file_uuid` (terminology update)
-- `person_identities` table **removed**
-- Face → Identity direct binding (no intermediate person_id)
-- 28 person_id APIs removed (except register/bind)
-- Chunk binding auto via time alignment
-
-### Identity Model
-```
-Face Detection → Identity (direct binding)
-Speaker Detection → Identity (direct binding)
-```
-
-### Processing Pipeline
-```
-Register → Probe → ASR → CUT → YOLO → OCR → Face → Pose → ASRX → Visual Chunk
-```
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/API_DICTIONARY_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/API_DICTIONARY_V1.0.0.md
new file mode 100644
index 0000000..5f5be85
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/API_DICTIONARY_V1.0.0.md
@@ -0,0 +1,183 @@
+---
+document_type: "reference_doc"
+service: "MOMENTRY_CORE"
+title: "Momentry Core API 字典 V1.0.0"
+date: "2026-05-01"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "momentry"
+ - "core"
+ - "api"
+ - "dictionary"
+ - "v1.0.0"
+ai_query_hints:
+ - "Momentry Core API 字典查詢"
+ - "API 端點與參數說明"
+ - "API 回應格式定義"
+ - "查詢所有 Public/Internal/Admin API 端點列表"
+ - "API 端點的 HTTP 方法與路徑結構"
+ - "搜尋 API 有哪些端點（search/bm25/hybrid/visual）"
+ - "API 端點的狀態分類（Public/Internal/Admin）"
+related_documents:
+ - "API_V1.0.0/MOMENTRY_CORE_API_V1.0.0.md"
+ - "API_V1.0.0/API_USAGE_DEMO_V1.0.0.md"
+ - "API_V1.0.0/API_REFERENCE_v1.0.0.20260501md.md"
+ - "API_V1.0.0/CHUNK_DEFINITION_V1.0.0.md"
+ - "API_V1.0.0/VECTOR_SPEC_V1.0.0.md"
+---
+
+# Momentry Core API 字典級全量文件 V1.0.0
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Public API | 供前端與外部系統使用的標準介面（58 個端點） |
+| Internal API | 系統內部流程或狀態查詢用（5 個端點） |
+| Admin API | 管理員專用（5 個端點） |
+| file_uuid | 32 碼 SHA256 檔案識別碼 |
+| RESTful | 以資源為中心的 API 設計風格 |
+
+## 📊 端點統計 (Endpoint Statistics)
+
+| 分類 | 數量 | 說明 |
+|---|---|---|
+| ✅ **Public** | 58 | 供前端與外部系統使用的標準介面 |
+| ⚠️ **Internal** | 5 | 系統內部流程或狀態查詢 (如 Probe, SFTPGo) |
+| 🔒 **Admin** | 5 | 管理員專用 (如 Resources, Config Cache) |
+| **總計** | **67** | 所有已註冊路由 (`gen-traces` 已移除) |
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-01 |
+| 端點總數 | **68** |
+| 文件版本 | V1.1 (Route Fixes + Arch Notes) |
+
+---
+
+## 🚀 設計原則 (Design Principles)
+
+### 1. Clear API (介面清晰化)
+* **去蕪存菁**: 嚴格區分 **Public** (公開) 與 **Internal** (內部) 端點。舊版冗餘路徑（如 `/api/v1/videos`, `/api/v1/probe`）已全面移除或合併。
+* **標準化回應**: 所有列表型 API 均回傳統一結構 `{ "success": true, "data": [...], "total": N }`。
+* **命名規範**: 採用 RESTful 風格，資源以複數名詞或明確動作命名（如 `files`, `identities`）。
+
+### 2. File-Centric (以檔案為核心)
+* **唯一識別**: 每個媒體檔案（影片/圖片/音訊）均由 **32 碼 UUID** (`file_uuid`) 唯一標識。
+* **生命週期**: `File` 是所有資料的根節點。所有的 `Chunk` (片段), `Snapshot` (快照), `Jobs` (任務) 皆隸屬於特定的 `File`。
+* **操作模式**: 前端應優先呼叫 `GET /api/v1/files` 取得清單，再透過 `POST /api/v1/files/:uuid/snapshots/migrate` 載入詳細資源。
+
+### 4. Trace Aggregation (軌跡聚合獨立化)
+* **架構**: `trace_face` 聚合由獨立 Python 腳本 `scripts/trace_face_aggregator.py` 處理，**不**內嵌於 Rust DB 層。
+* **流程**: Face Processor (Python) 輸出離散幀級資料到 `face_detections` 表 → Rust Worker 排程 `trace_face_aggregator.py` → 該腳本讀取 DB、按 `face_id` 分組聚合、寫入 `pre_chunks` (source_type=`trace_face`)。
+* **設計理由**: 保持 Rust 排程層輕量化，軌跡聚合邏輯留在 Python 層統一維護，便於未來調整聚合演算法 (如 IOU 門檻、時間間隔合併等) 而無需重新編譯 Rust。
+
+### 5. Global Identity (全域身份識別)
+* **跨檔案關聯**: `Identity` 代表一個獨立的人物或角色，不受單一檔案限制。
+* **綁定機制 (Binding)**: 透過 `POST /api/v1/identities/bind`，我們可以將多個檔案中偵測到的臉部 (`face`) 或聲音 (`speaker`) 聚合到同一個 `Identity` 下。
+* **資料聚合**: 查詢某個 `Identity` 即可看到該人物在所有歷史檔案中的軌跡 (`/api/v1/identities/:uuid/files`)。
+
+---
+
+## 1. 系統與認證 (System & Auth)
+| 方法 | 路徑 | 狀態 |
+|---|---|---|
+| `GET` | `/health` | ✅ Public |
+| `GET` | `/health/detailed` | ✅ Public |
+| `POST` | `/api/v1/auth/login` | ✅ Public |
+| `POST` | `/api/v1/auth/logout` | ✅ Public |
+
+## 2. 檔案管理 (Files & Assets)
+| 方法 | 路徑 | 狀態 |
+|---|---|---|
+| `GET` | `/api/v1/files` | ✅ Public |
+| `GET` | `/api/v1/files/scan` | ✅ Public |
+| `POST` | `/api/v1/files/register` | ✅ Public |
+| `POST` | `/api/v1/unregister` | ✅ Public |
+| `GET` | `/api/v1/files/:file_uuid` | ✅ Public |
+| `GET` | `/api/v1/files/:file_uuid/identities` | ✅ Public |
+| `GET` | `/api/v1/files/:file_uuid/snapshots` | ✅ Public |
+| `GET` | `/api/v1/files/:file_uuid/snapshots/status` | ✅ Public |
+| `POST` | `/api/v1/files/:file_uuid/snapshots/migrate` | ✅ Public |
+| `POST` | `/api/v1/files/:file_uuid/snapshots/teardown` | ✅ Public |
+
+## 3. 影片與任務 (Videos & Jobs)
+| 方法 | 路徑 | 狀態 |
+|---|---|---|
+| `DELETE` | `/api/v1/videos/:file_uuid` | ✅ Public |
+| `GET` | `/api/v1/videos/:file_uuid/details` | ✅ Public |
+| `GET` | `/api/v1/videos/:file_uuid/pre_chunks` | ✅ Public |
+| `GET` | `/api/v1/progress/:file_uuid` | ✅ Public |
+| `GET` | `/api/v1/jobs` | ✅ Public |
+| `GET` | `/api/v1/jobs/:job_id` | ✅ Public |
+| `GET` | `/api/v1/rules/:rule/status` | ✅ Public |
+| `GET` | `/api/v1/files/:file_uuid/probe` | ✅ Public |
+| `POST` | `/api/v1/files/:file_uuid/process` | ✅ Public |
+| `GET` | `/api/v1/assets/:uuid/status` | ⚠️ Internal |
+| `POST` | `/api/v1/resources/register` | 🔒 Internal |
+| `POST` | `/api/v1/resources/heartbeat` | 🔒 Internal |
+| `GET` | `/api/v1/resources` | 🔒 Internal |
+
+## 4. 搜尋 (Search)
+| 方法 | 路徑 | 狀態 |
+|---|---|---|
+| `POST` | `/api/v1/search` | ✅ Public |
+| `POST` | `/api/v1/search/bm25` | ✅ Public |
+| `POST` | `/api/v1/search/hybrid` | ✅ Public |
+| `POST` | `/api/v1/search/visual` | ✅ Public |
+| `POST` | `/api/v1/search/visual/class` | ✅ Public |
+| `POST` | `/api/v1/search/visual/density` | ✅ Public |
+| `POST` | `/api/v1/search/visual/combination` | ✅ Public |
+| `POST` | `/api/v1/search/visual/stats` | ✅ Public |
+
+## 5. 身份與綁定 (Identity & Binding)
+| 方法 | 路徑 | 狀態 |
+|---|---|---|
+| `GET` | `/api/v1/identities` | ✅ Public |
+| `GET` | `/api/v1/identities/:uuid` | ✅ Public |
+| `GET` | `/api/v1/identities/:uuid/files` | ✅ Public |
+| `GET` | `/api/v1/identities/:uuid/chunks` | ✅ Public |
+| `GET` | `/api/v1/identities/:identity_id/faces` | ✅ Public |
+| `POST` | `/api/v1/identities/from-person` | ✅ Public |
+| `POST` | `/api/v1/identities/from-face` | ✅ Public |
+| `POST` | `/api/v1/identities/bind` | ✅ Public |
+| `POST` | `/api/v1/identities/unbind` | ✅ Public |
+
+## 6. 臉部 (Face)
+| 方法 | 路徑 | 狀態 |
+|---|---|---|
+| `GET` | `/api/v1/face/list` | ✅ Public |
+| `GET` | `/api/v1/face/:face_id` | ✅ Public |
+| `DELETE` | `/api/v1/face/:face_id` | ✅ Public |
+| `POST` | `/api/v1/face/recognize` | ✅ Public |
+| `POST` | `/api/v1/face/register` | ✅ Public |
+| `POST` | `/api/v1/face/search` | ✅ Public |
+| `GET` | `/api/v1/faces/candidates` | ✅ Public |
+| `GET` | `/api/v1/files/:file_uuid/faces/:face_id/thumbnail` | ✅ Public |
+| `GET` | `/api/v1/signals/unbound` | ✅ Public |
+| `GET` | `/api/v1/signals/:uuid/:binding_type/:binding_value/timeline` | ✅ Public |
+
+## 7. 代理人 (Agents)
+| 方法 | 路徑 | 狀態 |
+|---|---|---|
+| `POST` | `/api/v1/agents/translate` | ✅ Public |
+| `POST` | `/api/v1/agents/5w1h/analyze` | ✅ Public |
+| `POST` | `/api/v1/agents/5w1h/batch` | ✅ Public |
+| `GET` | `/api/v1/agents/5w1h/status` | ✅ Public |
+| `POST` | `/api/v1/agents/identity/analyze` | ✅ Public |
+| `POST` | `/api/v1/agents/identity/suggest` | ✅ Public |
+| `GET` | `/api/v1/agents/identity/status` | ✅ Public |
+| `POST` | `/api/v1/agents/suggest/merge` | ✅ Public |
+
+## 8. 狀態與統計 (Stats)
+| 方法 | 路徑 | 狀態 |
+|---|---|---|
+| `GET` | `/api/v1/stats/ingest` | ✅ Public |
+| `GET` | `/api/v1/stats/sftpgo` | ⚠️ Internal |
+| `GET` | `/api/v1/stats/inference` | ⚠️ Internal |
+| `POST` | `/api/v1/config/cache` | 🔒 Internal |
+| `GET` | `/api/v1/lookup` | ✅ Public |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/API_REFERENCE_v1.0.0.20260501md.md b/docs_v1.0/API_V1.0.0/INTERNAL/API_REFERENCE_v1.0.0.20260501md.md
new file mode 100644
index 0000000..0ccd574
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/API_REFERENCE_v1.0.0.20260501md.md
@@ -0,0 +1,310 @@
+---
+document_type: "reference_doc"
+service: "MOMENTRY_CORE"
+title: "Momentry Core API 參考文件 V1.0.0 (Demo 完整指南)"
+date: "2026-05-01"
+version: "V3.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "api"
+ - "reference"
+ - "v1.0.0"
+ - "demo"
+ - "marcom"
+ai_query_hints:
+ - "查詢 V1.0.0 Demo 所需 API 列表"
+ - "Momentry Core Demo 流程如何使用 API？"
+ - "API 的檔案註冊、處理、臉部綁定流程"
+ - "Demo 流程中 Scan → Unregister → Register → Probe → Process → Faces → Bind 的完整步驟"
+ - "API 的 curl 範例與回應格式"
+ - "Process 回傳 400 Bad Request 的常見原因與解決方法"
+ - "臉部查詢回傳空結果的疑難排解步驟"
+related_documents:
+ - "STANDARDS/DOCS_STANDARD.md"
+ - "API_V1.0.0/MOMENTRY_CORE_API_V1.0.0.md"
+ - "TEST_REPORT_CLI.md"
+---
+
+# Momentry Core API 參考文件 V1.0.0 (Demo 完整指南)
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| file_uuid | 32 碼 SHA256 檔案識別碼 |
+| X-API-Key | API 認證方式，透過 HTTP Header 傳遞 |
+| Scan | 掃描檔案系統，列出所有檔案及當前狀態 |
+| Register | 將檔案加入資料庫系統 |
+| Probe | 讀取檔案 metadata（時長、解析度、幀率） |
+| Bind | 將臉部綁定到指定身份 |
+| Progress | 獲取處理進度與目前階段 |
+
+## 📊 文件統計 (Document Statistics)
+
+| 項目 | 數值 |
+|---|---|
+| **收錄端點** | 15+ (Demo 核心流程) |
+| **涵蓋率** | Demo 流程 100% |
+| **測試狀態** | ✅ CLI Verified |
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-01 |
+| 文件版本 | V3.0 |
+
+---
+
+## 1. Demo 流程總覽 (Demo Workflow)
+
+本文件專注於 **Demo 測試計畫** 所需的 API。以下是完整流程與對應 API：
+
+```
+1. 掃描狀態 (Scan) → GET /api/v1/files/scan
+2. 檔案重置 (Unregister) → POST /api/v1/unregister
+3. 檔案註冊 (Register) → POST /api/v1/files/register
+4. 檔案探測 (Probe) → GET /api/v1/files/:file_uuid/probe
+5. 開始處理 (Process) → POST /api/v1/files/:file_uuid/process
+6. 監控進度 (Progress) → GET /api/v1/progress/:file_uuid**
+7. 查詢臉部 (Faces) → GET /api/v1/faces/candidates
+8. 綁定身份 (Bind) → POST /api/v1/identities/bind
+```
+
+---
+
+## 2. 快速資訊
+
+- **Base URL (Dev)**: `http://localhost:3003`
+- **Base URL (Prod)**: `http://localhost:3002`
+- **認證方式**: Header `X-API-Key: muser_test_001`
+- **測試 Key**: `muser_test_001`
+
+---
+
+## 3. API 詳細說明 (依 Demo 順序)
+
+### 3.1 掃描檔案系統 (Scan Files)
+**路徑**: `GET /api/v1/files/scan`
+
+**用途**: 列出檔案系統中所有檔案及當前狀態，**是 Demo 流程的第一步**。
+
+**Response**:
+```json
+{
+ "files": [
+ {
+ "file_name": "A12T3-Share-User Experience of Thunderbolt 3 Shareable Storage.mp4",
+ "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/A12T3-Share-User Experience of Thunderbolt 3 Shareable Storage.mp4",
+ "file_uuid": "7ab7e25f48b58675e33aca44d15c1ecc",
+ "is_registered": true,
+ "status": "processing"
+ }
+ ],
+ "total": 20,
+ "registered_count": 20,
+ "unregistered_count": 0
+}
+```
+
+---
+
+### 3.2 取消註冊 (Unregister File)
+**路徑**: `POST /api/v1/unregister`
+
+**用途**: 從 Scan 結果中選取 `file_uuid`，對該檔案執行取消註冊。
+
+**Request**:
+```json
+{
+ "uuid": "53e3a229bf68878b7a799e811e097f9c"
+}
+```
+
+**Response**:
+```json
+{
+ "success": true,
+ "uuid": "53e3a229bf68878b7a799e811e097f9c",
+ "message": "File unregistered successfully"
+}
+```
+
+---
+
+### 3.3 註冊檔案 (Register File)
+**路徑**: `POST /api/v1/files/register`
+
+**用途**: 從 Scan 結果中選取 `file_path`，將檔案加入資料庫系統。
+
+**Request**:
+```json
+{
+ "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/view15.mp4"
+}
+```
+
+**Response**:
+```json
+{
+ "success": true,
+ "file_uuid": "53e3a229bf68878b7a799e811e097f9c",
+ "file_name": "view15.mp4",
+ "file_path": "/Users/.../demo/view15.mp4",
+ "already_exists": false
+}
+```
+
+---
+
+### 3.4 檔案探測 (Probe File)
+**路徑**: `GET /api/v1/files/:file_uuid/probe`
+
+**用途**: 讀取檔案的 metadata (時長、解析度、幀率)。**必須在 Process 前執行**。
+
+**Response**:
+```json
+{
+ "file_uuid": "7ab7e25f48b58675e33aca44d15c1ecc",
+ "file_name": "A12T3-Share-User Experience of Thunderbolt 3 Shareable Storage.mp4",
+ "duration": 621.55,
+ "width": 1920,
+ "height": 1080,
+ "fps": 29.97,
+ "cached": true
+}
+```
+
+---
+
+### 3.5 觸發處理 (Process File)
+**路徑**: `POST /api/v1/files/:file_uuid/process`
+
+**用途**: 啟動後端 Worker 進行分析 (ASR, Face, YOLO, 等)。
+
+**Request**:
+```json
+{}
+```
+
+**Response**:
+```json
+{
+ "success": true,
+ "message": "Processing started"
+}
+```
+
+---
+
+### 3.6 查詢進度 (Progress)
+**路徑**: `GET /api/v1/progress/:file_uuid`
+
+**用途**: 獲取處理進度與目前階段。
+
+**Response**:
+```json
+{
+ "file_uuid": "53e3a229bf68878b7a799e811e097f9c",
+ "overall_progress": 65,
+ "current_processor": "face",
+ "status": "running",
+ "processors": [
+ { "name": "probe", "status": "completed" },
+ { "name": "asr", "status": "completed" },
+ { "name": "face", "status": "running" }
+ ]
+}
+```
+
+---
+
+### 3.6 查詢未綁定臉部 (List Face Candidates)
+**路徑**: `GET /api/v1/faces/candidates`
+
+**用途**: 列出檔案中尚未綁定身份的臉部。
+
+**Query Parameters**:
+- `file_uuid` (必填): 檔案 UUID
+- `min_confidence` (選填): 最低信心值 (預設 0.5)
+- `page_size` (選填): 每頁數量 (預設 20)
+
+**Response**:
+```json
+{
+ "candidates": [
+ {
+ "id": 123,
+ "face_id": "123_RoleA",
+ "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
+ "frame_number": 115,
+ "confidence": 0.98,
+ "bbox": { "x": 50, "y": 50, "w": 100, "h": 100 }
+ }
+ ],
+ "total": 1,
+ "page": 1,
+ "page_size": 20
+}
+```
+
+---
+
+### 3.7 綁定身份 (Bind Identity)
+**路徑**: `POST /api/v1/identities/bind`
+
+**用途**: 將臉部綁定到指定身份 (或建立新身份)。
+
+**Request**:
+```json
+{
+ "identity_id": 22,
+ "binding_type": "face",
+ "binding_value": "123_RoleA"
+}
+```
+
+**Response**:
+```json
+{
+ "success": true,
+ "message": "Bound face '123_RoleA' to Identity 'Cary Grant'"
+}
+```
+
+---
+
+## 4. 補充 API (Demo 選用)
+
+### 4.1 列出身份 (List Identities)
+**路徑**: `GET /api/v1/identities`
+
+**用途**: 列出系統中所有已建立的身份。
+
+---
+
+## 5. 常見問題 (FAQ)
+
+### Q1: 為什麼 Process 回傳 400 Bad Request？
+**Ans**: 必須先執行 **Probe** (`GET /api/v1/files/:file_uuid/probe`)，確保系統已知曉檔案的幀數資訊。
+
+### Q2: 為什麼 Unregister 回傳 404？
+**Ans**: 確認伺服器是否已更新至最新版本。舊版可能尚未包含此路由。
+
+### Q3: 臉部查詢回傳空結果？
+**Ans**:
+1. 確認檔案已**處理完成** (Progress = 100%)。
+2. 嘗試降低 `min_confidence` 參數 (例如設為 0.0)。
+3. 確認該檔案內容確實包含可辨識的臉部。
+
+---
+
+## 6. 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 |
+|------|------|------|--------|
+| V1.0 | 2026-04-30 | 初始 API 列表 | OpenCode |
+| V2.0 | 2026-05-01 | 基於 Production 測試結果補足文件 | OpenCode |
+| V3.0 | 2026-05-01 | 重構為 Demo 流程導向，補齊 Probe/Unregister 說明 | OpenCode |
+| V3.1 | 2026-05-01 | 修正 `:uuid`→`:file_uuid`，修正 port 3002→3003，移除重複 Scan 章節 | OpenCode |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/API_USAGE_DEMO_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/API_USAGE_DEMO_V1.0.0.md
new file mode 100644
index 0000000..35fa355
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/API_USAGE_DEMO_V1.0.0.md
@@ -0,0 +1,376 @@
+---
+document_type: "develop_guide"
+service: "MOMENTRY_CORE"
+title: "Momentry Core V1.0.0 API 示範與整合指南"
+date: "2026-05-01"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "momentry"
+ - "core"
+ - "api-usage"
+ - "demo"
+ - "n8n"
+ - "wordpress"
+ai_query_hints:
+ - "查詢 V1.0.0 API 示範與整合指南的內容"
+ - "如何使用 n8n 呼叫 V1.0.0 API？"
+ - "如何整合 V1.0.0 API 到 WordPress？"
+ - "V1.0.0 API 的 curl 範例"
+ - "PHP 整合 V1.0.0 API 的方式（wp_remote_request）"
+ - "n8n 工作流如何串接 V1.0.0 API"
+ - "Face 綁定錯誤修正的 API 操作步驟"
+ - "前端 Face Interpolation 的實作方式"
+related_documents:
+ - "API_V1.0.0/MOMENTRY_CORE_API_V1.0.0.md"
+ - "API_V1.0.0/API_DICTIONARY_V1.0.0.md"
+ - "API_V1.0.0/API_REFERENCE_v1.0.0.20260501md.md"
+ - "API_V1.0.0/CHUNK_DEFINITION_V1.0.0.md"
+ - "API_V1.0.0/PROCESSOR_SELECTION_V1.0.0.md"
+---
+
+# Momentry Core V1.0.0 API 示範與整合指南
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-01 |
+| 文件版本 | V1.0 |
+| 適用版本 | Momentry Core V1.0.0+ |
+
+---
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| file_uuid | 32 碼 SHA256 檔案識別碼 |
+| X-API-Key | API 認證方式，透過 HTTP Header 傳遞 |
+| face_id | 單一幀中的人臉偵測 ID，格式為 `<檢測ID>_<角色後綴>` |
+| Identity | 全域人物身份，跨檔案關聯同一人物 |
+| Face Interpolation | 前端線性插值，補足非逐幀臉部標記的顯示 |
+| Scan | 掃描檔案系統，列出所有檔案及當前狀態 |
+
+## 1. 快速開始 (Quick Start)
+
+### 1.1 環境 URL
+
+| 環境 | URL | 用途 |
+|------|-----|------|
+| **對外 URL** | `https://api.momentry.ddns.net` | 外部存取 |
+| **Dev Server** | `http://localhost:3003` | **開發環境，所有測試用** |
+| **Local Server** | `http://localhost:3002` | Production，僅 release 用 |
+
+### 1.2 測試連線
+
+```bash
+curl http://localhost:3003/health
+```
+
+```json
+{
+ "status": "ok",
+ "version": "1.0.0 (build: ...)",
+ "uptime_ms": 64880
+}
+```
+
+---
+
+## 2. 核心 API 工作流 (Workflows)
+
+### 2.1 掃描檔案系統 (Scan Files)
+**入口 API**: `GET /api/v1/files/scan` — 所有 Demo 流程從這裡開始。
+
+**掃描檔案**:
+```bash
+curl -s "http://localhost:3003/api/v1/files/scan" \
+ -H "X-API-Key: "
+```
+
+**列出檔案 (分頁)**:
+```bash
+curl -s "http://localhost:3003/api/v1/files?page=1&page_size=10" \
+ -H "X-API-Key: "
+```
+
+**取得單一檔案詳情**:
+```bash
+curl -s "http://localhost:3003/api/v1/files/" \
+ -H "X-API-Key: "
+```
+
+### 2.2 搜尋 (Search)
+支援語意搜尋、混合搜尋與視覺搜尋。
+
+```bash
+curl -X POST "http://localhost:3003/api/v1/search" \
+ -H "X-API-Key: " \
+ -H "Content-Type: application/json" \
+ -d '{"query": "尋找紅色信封", "uuid": ""}'
+```
+
+### 2.3 單獨 Face 綁定流程 (Single Face Binding Workflow)
+
+此流程適用於手動將特定臉部關聯到已知人物或建立新人物的場景。系統支援**一人分飾多角**，透過 `face_id` 加上角色後綴來區分。
+
+#### 步驟 1: 選定 Face (Input Format)
+使用者需提供一個 **`file_uuid`** 搭配 **`face_id`** 來鎖定目標。
+選定的意思是輸入 **`:`** 的組合。
+
+* **命名規則**: `face_id` 格式通常為 `<原始檢測 ID>_<後綴>`，用於區分同一人的不同臉部實體或角色。
+ * **有角色名稱**: 使用角色名 (如 `123_PeterJoshua`)。
+ * **無角色名稱**: 使用通用代號 (如 `123_RoleA`, `123_RoleB`)。
+
+#### 步驟 2: 列出 Identities 或新增 Identity
+使用者決定將該 Face 綁定到系統中已存在的全域人物 (Identity)，或是建立一個新人物。
+* **Identity 特性**: 代表現實世界中的真實人物，具備**全域唯一性** (如 "Cary Grant")。
+
+- **選項 A: 列出人物清單**
+ ```bash
+ curl -s "http://localhost:3003/api/v1/identities?page=1&page_size=20" \
+ -H "X-API-Key: "
+ ```
+
+- **選項 B: 決定新增人物名稱**
+ 若列表中沒有對應人物，使用者需準備一個新名稱（如 "Cary Grant"）。
+
+#### 步驟 3: 確認綁定
+透過 `POST /api/v1/identities/bind` 完成綁定。
+* **若提供 `identity_id`**: 將帶有後綴的 `face_id` 綁定至該人物。
+* **若提供 `name`**: 系統自動建立新人物 (Identity)，並將該臉部綁定上去。
+
+- **綁定至現有身份 (範例)**:
+ 假設我們要綁定的目標是檔案 `file_uuid_abc` 中的臉部 `123_PeterJoshua`。
+ ```bash
+ curl -X POST "http://localhost:3003/api/v1/identities/bind" \
+ -H "X-API-Key: " \
+ -H "Content-Type: application/json" \
+ -d '{
+ "identity_id": 101,
+ "binding_type": "face",
+ "binding_value": "123_PeterJoshua"
+ }'
+ ```
+ *註: 雖然 API 接收的是 `binding_value`，但系統內部會根據選定的 `file_uuid` 與 `face_id` 組合來精確鎖定目標。*
+
+#### 步驟 4: 循環
+完成綁定後，返回列表處理下一個未綁定的 Face。
+
+---
+
+### 2.4 取得 Face 截圖 (Retrieve Face Snapshots)
+
+在確認綁定前，通常需要檢視臉部截圖。根據使用場景，取得截圖有兩種方式：
+
+#### 1. Local Path / Filename (本地路徑)
+* **適用**: Tauri 桌面應用、本機腳本。
+* **說明**: 直接從硬碟讀取圖片檔案，速度最快，無需經過網路層。
+* **路徑**: `//snapshots/faces/.jpg`
+
+#### 2. URL (網路存取)
+* **適用**: Web 前端、外部系統。
+* **說明**: 透過 HTTP GET 請求取得影像串流。
+* **API Endpoint**: `GET /api/v1/files//faces//thumbnail`
+* **範例**:
+ ```bash
+ curl -s -o face.jpg \
+ "http://localhost:3003/api/v1/files//faces//thumbnail" \
+ -H "X-API-Key: "
+ ```
+
+---
+
+### 2.4.1 前端動態辨識與插值 (Face Interpolation Logic)
+
+由於系統對臉部標記並非逐幀 (Frame-by-Frame) 進行（為節省運算資源或受限於取樣率），在 Client 端進行**逐幀播放**或**時間軸拖曳**時，若直接顯示會導致臉部框選忽閃忽滅。
+
+#### 運作邏輯
+前端需實作**線性插值 (Linear Interpolation)** 機制：
+
+1. **取得資料**：從 API 取得該 `face_id` 在所有 `frame_number` 的座標列表（例如：Frame 10, Frame 15 有資料）。
+2. **插值計算**：
+ * 當使用者停在 **Frame 12** 時，系統無直接資料。
+ * 前端應找出前後最近的有資料幀（Frame 10 與 Frame 15）。
+ * 根據時間差比例，動態計算出 Frame 12 的座標 `x, y, w, h`。
+
+#### 實作範例 (JavaScript/TypeScript)
+
+```typescript
+// 假設 API 回傳該 Face 的軌跡點
+const detections = [
+ { frame: 10, bbox: { x: 100, y: 100, w: 50, h: 60 } },
+ { frame: 15, bbox: { x: 110, y: 105, w: 50, h: 60 } },
+];
+
+// 計算 Frame 12 的預測框選
+function getInterpolatedBBox(frameIndex: number, detections) {
+ // 找到前一幀與後一幀
+ const prev = detections.find(d => d.frame <= frameIndex); // Frame 10
+ const next = detections.find(d => d.frame > frameIndex); // Frame 15
+
+ if (!prev) return null; // 還沒開始出現
+ if (!next) return prev.bbox; // 結束了，維持最後位置
+
+ // 計算比例 (0.0 - 1.0)
+ const ratio = (frameIndex - prev.frame) / (next.frame - prev.frame);
+
+ return {
+ x: prev.bbox.x + (next.bbox.x - prev.bbox.x) * ratio,
+ y: prev.bbox.y + (next.bbox.y - prev.bbox.y) * ratio,
+ // w, h 亦可依此邏輯進行縮放插值
+ w: prev.bbox.w,
+ h: prev.bbox.h,
+ };
+}
+```
+
+---
+
+### 2.5 Face 綁定錯誤修正 (Face Binding Error Correction)
+
+此流程適用於移除錯誤綁定的臉部資料，使其恢復為未綁定狀態。
+
+1. **選定 Face**: 確認需要解除綁定的臉部 `face_id` 以及所屬的 `file_uuid`。
+2. **解除綁定 (Unbind)**:
+ ```bash
+ curl -X POST "http://localhost:3003/api/v1/identities/unbind" \
+ -H "X-API-Key: " \
+ -H "Content-Type: application/json" \
+ -d '{
+ "binding_type": "face",
+ "binding_value": ""
+ }'
+ ```
+
+---
+
+## 3. n8n 整合範例
+
+### 3.1 HTTP Request 設定
+
+| 欄位 | 值 |
+|---|---|
+| Method | `GET` 或 `POST` |
+| URL | `http://localhost:3003/api/v1/files` (Dev) 或 `https://` (Prod) |
+| Header `X-API-Key` | `` |
+
+### 3.2 列出檔案 Workflow (JSON)
+使用 `GET /api/v1/files/scan` 作為入口。
+
+```json
+{
+ "nodes": [
+ {
+ "name": "Get Files",
+ "type": "n8n-nodes-base.httpRequest",
+ "parameters": {
+ "method": "GET",
+ "url": "http://localhost:3003/api/v1/files/scan",
+ "sendHeaders": true,
+ "headerParameters": {
+ "parameters": [{ "name": "X-API-Key", "value": "{{ $env.API_KEY }}" }]
+ },
+ "options": { "qs": { "page": 1, "page_size": 10 } }
+ },
+ "position": [450, 300]
+ },
+ {
+ "name": "Extract List",
+ "type": "n8n-nodes-base.code",
+ "parameters": {
+ "jsCode": "return $input.first().json.data.map(f => ({\n json: {\n uuid: f.file_uuid,\n name: f.file_name,\n status: f.status\n }\n}));"
+ },
+ "position": [650, 300]
+ }
+ ]
+}
+```
+
+---
+
+## 4. WordPress / PHP 整合範例
+
+### 4.1 PHP Client Library (V1.0.0 相容)
+
+```php
+';
+
+ private function request(string $endpoint, array $data = [], string $method = 'GET'): array {
+ $url = self::API_URL . $endpoint;
+ $args = [
+ 'headers' => [
+ 'X-API-Key' => self::API_KEY,
+ 'Content-Type' => 'application/json',
+ ],
+ 'timeout' => 30,
+ ];
+
+ if ($method === 'POST') {
+ $args['method'] = 'POST';
+ $args['body'] = json_encode($data);
+ }
+
+ $response = wp_remote_request($url, $args);
+ if (is_wp_error($response)) {
+ throw new Exception($response->get_error_message());
+ }
+ return json_decode(wp_remote_retrieve_body($response), true);
+ }
+
+ // 掃描檔案
+ public function scan_files(): array {
+ return $this->request('/api/v1/files/scan');
+ }
+
+ // 列出檔案
+ public function list_files(): array {
+ return $this->request('/api/v1/files');
+ }
+
+ // 搜尋
+ public function search(string $query): array {
+ return $this->request('/api/v1/search', ['query' => $query], 'POST');
+ }
+}
+?>
+```
+
+---
+
+## 5. 疑難排解
+
+| 錯誤 | 原因 | 解決方案 |
+|------|------|----------|
+| `401 Unauthorized` | API Key 無效 | 檢查 Key 格式與權限 |
+| `404 Not Found` | 端點不存在 | 確認是否使用了舊版 `/api/v1/videos`，應改為 `/api/v1/files` |
+| `400 Bad Request on Process` | 缺少 Probe 資料 | 先執行 `GET /api/v1/files/:file_uuid/probe` |
+| `500 Error` | 伺服器錯誤 | 檢查資料庫連線與 Schema 版本 |
+
+---
+
+## 6. 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-01 | 初始版本 | OpenCode | deepseek-chat |
+| V1.1 | 2026-05-01 | 修正 port 為 Dev(3003)，更新 API 路徑與掃描入口 | OpenCode | deepseek-chat |
+
+---
+
+## 7. 附錄：UUID 格式說明
+
+V1.0.0 使用 **32 碼 SHA256** 作為 `file_uuid`。
+
+```
+/Users/.../demo/video.mp4
+ ↓
+SHA256 Hash (前 32 字元)
+ ↓
+53e3a229bf68878b7a799e811e097f9c
+```
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/CHUNK_DEFINITION_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/CHUNK_DEFINITION_V1.0.0.md
new file mode 100644
index 0000000..fa8ec73
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/CHUNK_DEFINITION_V1.0.0.md
@@ -0,0 +1,198 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "Chunk 定義 V1.0.0"
+date: "2026-05-01"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "momentry"
+ - "core"
+ - "chunk"
+ - "v1.0.0"
+ - "chunk-type"
+ - "pre-chunk"
+ - "parent-child"
+ - "data-structure"
+ai_query_hints:
+ - "chunk 的定義與結構"
+ - "pre_chunk 與 chunk 的關係"
+ - "parent_chunk 與 child_chunk 的關係"
+ - "ChunkType 包含哪些類型（Sentence/Cut/Visual/Trace/Story）"
+ - "chunk 的巢狀結構與 Rule 組合規則"
+ - "chunk 如何對應到 file_uuid 與幀區間"
+ - "chunk 的搜尋用途與向量儲存方式"
+ - "chunk 與 pre_chunk 的雙層資料架構"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "VECTOR_SPEC_V1.0.0.md"
+ - "PROCESSORS/ASR_V1.0.0.md"
+ - "PROCESSORS/CUT_V1.0.0.md"
+ - "PROCESSORS/FACE_V1.0.0.md"
+---
+
+# Chunk 定義 V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-01 |
+| 文件版本 | V1.0 |
+
+## 名詞定義
+
+| 名詞 | 定義 | 範例 |
+|------|------|------|
+| **Processor JSON** | Processor 腳本的第一層產出檔案 | `384b0ff44aaaa1f14cb2cd63b3fea966.face.json` |
+| **pre_chunk** | 從 Processor JSON 匯入 DB 的最低層元件（`pre_chunks` 表） | 單幀 face detection、單句 ASR text |
+| **chunk** | 可搜尋單位（`chunks` 表），由 Rule 組合 pre_chunks 產出，`start_frame` ~ `end_frame` 定義區間 | sentence chunk, visual chunk, scene chunk |
+| **parent_chunk** | chunk 的一種，包含 `child_chunk_ids`，其區間涵蓋多個 child_chunks，由 Summary Agent 產出統整描述 | scene chunk, story chunk |
+| **child_chunk** | chunk 的一種，被 parent_chunk 參照為子元素 | sentence chunk, visual chunk |
+
+---
+
+## Chunk 結構
+
+```rust
+Chunk {
+ uuid: String, // file_uuid (32-char hex)
+ chunk_id: String, // "{uuid}_{chunk_index}"
+ chunk_index: u32, // 0-based 序號
+ chunk_type: ChunkType, // Sentence | Cut | Visual | Trace | Story
+ rule: ChunkRule, // Rule1 (直接組合) | Rule2 (聚合)
+ start_frame: i64, // 起始幀（0-based，唯一時間參考）
+ end_frame: i64, // 結束幀（exclusive）
+ fps: f64, // 該區間的 fps
+ content: JSON, // 主要內容
+ text_content: Option, // 純文字內容（供搜尋用）
+ metadata: Option, // speaker, face_ids, yolo_objects 等
+ pre_chunk_ids: Vec, // 來源 pre_chunks（原始元件追溯）
+ parent_chunk_id: Option, // 父 chunk ID（如存在）
+ child_chunk_ids: Vec, // 子 chunk IDs（如為 parent_chunk）
+ vector_id: Option, // 向量儲存參考
+}
+```
+
+---
+
+## ChunkType
+
+| 類型 | 說明 | 範例 |
+|------|------|------|
+| `Sentence` | ASR 句子 chunk | 一句話對應一個 chunk |
+| `Cut` | 場景切換 chunk | PySceneDetect 輸出的場景邊界 |
+| `Visual` | 視覺物件 chunk | YOLO/OCR/Face/Pose 聚合 |
+| `Trace` | 追蹤 chunk | face_trace / yolo_trace |
+| `Story` | 敘事 chunk（parent） | 5W1H Agent 產出的統整描述 |
+
+---
+
+## Chunk 特性
+
+- **區間定義**: `start_frame` / `end_frame`（frames 為唯一時間座標）
+- **可重疊**: 不同類型的 chunk 可以覆蓋相同區間
+- **可不連續**: chunk 之間不需要連續
+- **巢狀**: parent_chunk 包含 child_chunk_ids，子區間不須填滿父區間
+- **單幀 chunk**: `start_frame == end_frame`（如 frame-level detection）
+
+---
+
+## 資料流
+
+```
+Processor JSON ({file_uuid}.{type}.json)
+ │
+ ▼ 匯入
+pre_chunks (原始元件, start_frame / end_frame / data)
+ │
+ ▼ Rule 組合 (Rule1 / Rule2 / Rule3)
+chunks (可搜尋單位)
+ ├── child_chunk (基礎搜尋單位)
+ │ └── 5W1H: 該 chunk 的摘要描述（3~5 句話）
+ │
+ └── parent_chunk (較大區間, Summary Agent 產出)
+ ├── child_chunk_ids: [內含的所有 child_chunks]
+ └── summary: (child_chunks 的 5W1H + parent_chunk 補充描述)
+ via Summary Agent (如 5W1H Agent)
+ summary 為 3~5 句話，統整區間內所有內容
+ 用於 embedding 成向量，確保搜尋時涵蓋足夠語意
+```
+
+---
+
+## 與 pre_chunk 的關係
+
+| 層級 | 產生方式 | 目的 |
+|------|----------|------|
+| pre_chunk | 直接從 Processor JSON 匯入 | 保留原始資料，供 Rule 加工 |
+| chunk | Rule 組合 pre_chunks | 成為可搜尋單位 |
+| child_chunk | chunk 的一種 | 基礎搜尋目標 |
+| parent_chunk | Summary Agent 產出 | 補足單一 child_chunk 資訊量不足 |
+
+---
+
+## 範例
+
+### Sentence Chunk (child_chunk)
+
+```json
+{
+ "chunk_id": "384b0ff44aaaa1f14cb2cd63b3fea966_42",
+ "chunk_index": 42,
+ "chunk_type": "sentence",
+ "rule": "rule_1",
+ "start_frame": 1260,
+ "end_frame": 1350,
+ "fps": 29.97,
+ "content": {
+ "text": "今天天氣很好，我們決定去公園走走。",
+ "speaker": "SPEAKER_00"
+ },
+ "text_content": "今天天氣很好，我們決定去公園走走。",
+ "metadata": {
+ "speaker": "SPEAKER_00",
+ "face_ids": ["face_42", "face_43"],
+ "5w1h": "講者 SPEAKER_00 在室內提到今天天氣很好。他建議大家一起到公園散步。同伴們同意這個提議。大家開始準備出發。整個對話顯示團隊氣氛融洽。"
+ },
+ "pre_chunk_ids": [101, 102, 103],
+ "parent_chunk_id": "384b0ff44aaaa1f14cb2cd63b3fea966_scene_3"
+}
+```
+
+### Scene Chunk (parent_chunk)
+
+```json
+{
+ "chunk_id": "384b0ff44aaaa1f14cb2cd63b3fea966_scene_3",
+ "chunk_index": 3,
+ "chunk_type": "cut",
+ "rule": "rule_3",
+ "start_frame": 1200,
+ "end_frame": 1800,
+ "fps": 29.97,
+ "content": {
+ "scene_number": 3,
+ "scene_type": "dialogue"
+ },
+ "text_content": "今天天氣很好，我們決定去公園走走。之後我們在公園裡散步，看到很多花。",
+ "metadata": {
+ "summary": "講者和同伴在室內討論天氣狀況，提到今天陽光明媚。他們決定到附近的公園散步享受好天氣。抵達公園後，他們沿著步道行走，觀察到許多盛開的花朵。其中一人用手機拍攝了花朵的照片。整個對話氣氛輕鬆愉快。"
+ },
+ "pre_chunk_ids": [98, 99, 100],
+ "child_chunk_ids": [
+ "384b0ff44aaaa1f14cb2cd63b3fea966_42",
+ "384b0ff44aaaa1f14cb2cd63b3fea966_43",
+ "384b0ff44aaaa1f14cb2cd63b3fea966_44"
+ ]
+}
+```
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-01 | 初始版本 | OpenCode | deepseek-chat |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/MOMENTRY_CORE_API_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/MOMENTRY_CORE_API_V1.0.0.md
new file mode 100644
index 0000000..94118a0
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/MOMENTRY_CORE_API_V1.0.0.md
@@ -0,0 +1,240 @@
+---
+document_type: "reference_doc"
+service: "MOMENTRY_CORE"
+title: "Momentry Core V1.0.0 API 參考文件"
+date: "2026-04-30"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "api"
+ - "reference"
+ - "v1.0.0"
+ - "marcom"
+ - "restful"
+ - "endpoint"
+ - "file-centric"
+ai_query_hints:
+ - "Momentry Core V1.0.0 API 參考文件的主要內容是什麼？"
+ - "查詢 V1.0.0 API 列表包含哪些端點？"
+ - "Marcom 團隊如何使用 API Reference？"
+ - "API 的 Progressive Workflow 範例"
+ - "Momentry API 的檔案管理與搜尋功能"
+ - "API 的 Progressive Workflow 操作步驟"
+ - "API 的檔案管理與搜尋功能"
+related_documents:
+ - "STANDARDS/DOCS_STANDARD.md"
+ - "DEV_API_V1.0/API_REFERENCE_v1.0.0.md"
+ - "API_DICTIONARY_V1.0.0.md"
+ - "API_USAGE_DEMO_V1.0.0.md"
+ - "PRODUCTION_VERIFICATION_V1.0.0.md"
+---
+
+# Momentry Core V1.0.0 API 參考文件
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-04-30 |
+| 文件版本 | V1.0 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-04-30 | 創建 V1.0.0 API 列表，移除過時端點 | OpenCode | OpenCode |
+
+---
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| file_uuid | 媒體檔案（影片/圖片/音訊）的唯一 32 碼 SHA256 識別碼 |
+| identity_uuid | 全域人物身份識別碼，跨檔案關聯同一人物 |
+| Chunk | 可搜尋單位，由 Rule 組合 pre_chunks 產出 |
+| Snapshot | 臉部或場景的快取快照，需 migrate 後供 UI 使用 |
+| API Key | 認證方式，透過 Header `X-API-Key` 傳遞 |
+
+## 概述
+
+本文檔定義 Momentry Core **V1.0.0** 版本供 **Marcom 團隊** 使用的 API 列表與開發範例。此列表已移除舊版、冗餘及內部使用的端點，確保前端開發使用的是標準且穩定的介面。
+
+---
+
+## 🚀 設計原則 (Design Principles)
+
+### 1. Clear API (介面清晰化)
+* **去蕪存菁**: 嚴格區分 **Public** (公開) 與 **Internal** (內部) 端點。舊版冗餘路徑（如 `/api/v1/videos`, `/api/v1/probe`）已全面移除或合併。
+* **標準化回應**: 所有列表型 API 均回傳統一結構 `{ "success": true, "data": [...], "total": N }`。
+* **命名規範**: 採用 RESTful 風格，資源以複數名詞或明確動作命名（如 `files`, `identities`）。
+
+### 2. File-Centric (以檔案為核心)
+* **唯一識別**: 每個媒體檔案（影片/圖片/音訊）均由 **32 碼 UUID** (`file_uuid`) 唯一標識。
+* **生命週期**: `File` 是所有資料的根節點。所有的 `Chunk` (片段), `Snapshot` (快照), `Jobs` (任務) 皆隸屬於特定的 `File`。
+* **操作模式**: 前端應優先呼叫 `GET /api/v1/files` 取得清單，再透過 `POST /api/v1/files/:uuid/snapshots/migrate` 載入詳細資源。
+
+### 3. Global Identity (全域身份識別)
+* **跨檔案關聯**: `Identity` 代表一個獨立的人物或角色，不受單一檔案限制。
+* **綁定機制 (Binding)**: 透過 `POST /api/v1/identities/bind`，我們可以將多個檔案中偵測到的臉部 (`face`) 或聲音 (`speaker`) 聚合到同一個 `Identity` 下。
+* **資料聚合**: 查詢某個 `Identity` 即可看到該人物在所有歷史檔案中的軌跡 (`/api/v1/identities/:uuid/files`)。
+
+---
+
+## 當前狀態
+
+| 項目 | 狀態 |
+|------|------|
+| API 版本 | V1.0.0 |
+| 開發環境 Port | 3003 |
+| 正式環境 Port | 3002 |
+| 認證方式 | Header `X-API-Key` |
+
+---
+
+## 1. API Dictionary (端點清單)
+
+### 1.1 系統與認證 (System & Auth)
+| Method | Endpoint | 說明 |
+| :--- | :--- | :--- |
+| `GET` | `/health` | 基本健康檢查 |
+| `POST` | `/api/v1/auth/login` | 登入以取得 API Key |
+
+### 1.2 檔案管理 (File Management)
+*主要入口：瀏覽與管理資產*
+| Method | Endpoint | 說明 |
+| :--- | :--- | :--- |
+| `GET` | `/api/v1/files` | **列出所有檔案** (支援分頁) |
+| `GET` | `/api/v1/files/:uuid` | 取得檔案詳情 (包含 probe_json, metadata) |
+| `POST` | `/api/v1/files/register` | 從磁碟註冊新檔案 |
+| `DELETE`| `/api/v1/videos/:uuid` | **刪除影片** 及其關聯資料 |
+
+### 1.3 搜尋與檢索 (Search & Retrieval)
+| Method | Endpoint | 說明 |
+| :--- | :--- | :--- |
+| `POST` | `/api/v1/search` | **語意搜尋** (Text-based, 使用 Embedding) |
+| `POST` | `/api/v1/search/hybrid` | 混合搜尋 (Vector + BM25 關鍵字) |
+| `POST` | `/api/v1/search/visual` | 視覺搜尋 (尋找物件/形狀) |
+| `POST` | `/api/v1/search/visual/class`| 依物件類別過濾 (如 "person", "car") |
+
+### 1.4 身份與人物管理 (Identity Management)
+*跨影片的人物/角色關聯*
+| Method | Endpoint | 說明 |
+| :--- | :--- | :--- |
+| `GET` | `/api/v1/identities` | **列出所有身份** (人物/角色) |
+| `GET` | `/api/v1/identities/:uuid` | 取得身份詳情 (名稱, 品質, 來源) |
+| `GET` | `/api/v1/identities/:uuid/files`| 列出該身份出現的所有檔案 |
+| `GET` | `/api/v1/identities/:uuid/chunks`| 列出特定的時間軸片段 (Chunks) |
+| `POST` | `/api/v1/identities/bind` | 將臉部/聲音訊號綁定至身份 |
+
+### 1.5 臉部與快照 (Face & Snapshots)
+| Method | Endpoint | 說明 |
+| :--- | :--- | :--- |
+| `GET` | `/api/v1/face/list` | 列出特定影片中偵測到的所有臉部 |
+| `POST` | `/api/v1/face/recognize` | 對指定影片觸發臉部辨識流程 |
+| `GET` | `/api/v1/files/:uuid/snapshots` | 檢查快照快取狀態 (Hot/Cold) |
+| `POST` | `/api/v1/files/:uuid/snapshots/migrate`| **載入快照至記憶體** (UI 顯示快圖前需呼叫) |
+
+### 1.6 任務與代理人 (Jobs & Agents)
+| Method | Endpoint | 說明 |
+| :--- | :--- | :--- |
+| `GET` | `/api/v1/progress/:uuid` | 檢查即時處理進度 |
+| `POST` | `/api/v1/assets/:uuid/process` | 觸發處理流程 (ASR, YOLO, 等) |
+| `POST` | `/api/v1/agents/identity/analyze` | AI Agent: 分析身份重複情況 |
+
+---
+
+## 2. Progressive Workflow Examples (操作範例)
+
+此章節展示典型的使用者操作情境：**尋找影片 → 處理 → 搜尋 → 人物綁定**。
+
+### Phase 1: 瀏覽與檢視
+*使用者瀏覽檔案庫以尋找目標影片。*
+
+**Step 1: 登入**
+```bash
+curl -s -X POST http://localhost:3003/api/v1/auth/login \
+ -H "Content-Type: application/json" \
+ -d '{"username": "demo", "password": "demo"}'
+# 回應範例: { "api_key": "muser_test_001..." }
+```
+
+**Step 2: 列出檔案**
+```bash
+curl -s "http://localhost:3003/api/v1/files?page=1&page_size=5" \
+ -H "X-API-Key: muser_test_001"
+# 回應範例: { "success": true, "data": [ { "file_uuid": "...", "file_name": "Demo.mp4" ... } ] }
+```
+
+### Phase 2: 處理與監控
+*使用者決定分析該影片的臉部與語音內容。*
+
+**Step 3: 觸發處理**
+```bash
+curl -s -X POST "http://localhost:3003/api/v1/assets/{file_uuid}/process" \
+ -H "X-API-Key: muser_test_001" \
+ -H "Content-Type: application/json" \
+ -d '{}'
+# 啟動 ASR, 臉部偵測等處理器
+```
+
+**Step 4: 檢查進度**
+```bash
+curl -s "http://localhost:3003/api/v1/progress/{file_uuid}" \
+ -H "X-API-Key: muser_test_001"
+# 回應範例: { "overall_progress": 50, "processors": [...] }
+```
+
+### Phase 3: 搜尋內容
+*使用者搜尋影片中的特定內容。*
+
+**Step 5: 語意搜尋 (文字描述)**
+```bash
+curl -s -X POST "http://localhost:3003/api/v1/search" \
+ -H "X-API-Key: muser_test_001" \
+ -H "Content-Type: application/json" \
+ -d '{"query": "一個人拿著紅色的信封", "uuid": "{file_uuid}"}'
+# 回應範例: 符合文字描述的片段列表
+```
+
+### Phase 4: 身份管理 (GUI 開發重點)
+*使用者發現了一張臉，確認該人物，並將其綁定到已知身份。*
+
+**Step 6: 載入快照 (Migrate Snapshots)**
+*在 GUI 渲染大量臉部縮圖前，必須先將快取載入記憶體以加速讀取。*
+```bash
+curl -s -X POST "http://localhost:3003/api/v1/files/{file_uuid}/snapshots/migrate" \
+ -H "X-API-Key: muser_test_001" \
+ -H "Content-Type: application/json" \
+ -d '{"parent_uuid": "{file_uuid}"}'
+# 回應範例: { "success": true, "migrated_types": ["faces", ...] }
+```
+
+**Step 7: 綁定臉部到身份 (Bind Face)**
+*假設偵測到臉部 `face_123`，欲綁定至身份 `uuid_identity`。*
+```bash
+curl -s -X POST "http://localhost:3003/api/v1/identities/bind" \
+ -H "X-API-Key: muser_test_001" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "identity_id": null,
+ "name": "Cary Grant",
+ "binding_type": "face",
+ "binding_value": "face_123"
+ }'
+```
+
+---
+
+## 3. 棄用聲明 (Deprecation Notices)
+
+以下端點已在 V1.0.0 移除或棄用，**請勿**在新的開發中使用。
+
+* `GET /api/v1/videos` (列表) → 已取代為 `GET /api/v1/files`
+* `POST /api/v1/register` → 已取代為 `POST /api/v1/files/register`
+* `POST /api/v1/probe` → 已取代為 `GET /api/v1/files/:uuid`
+* `GET /api/v1/people/...` → 已合併為 `GET /api/v1/identities/...`
+* `/api/v1/n8n/search/...` → 僅供內部 n8n 工作流使用 (請使用標準 `/api/v1/search`)
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/ASRX_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/ASRX_V1.0.0.md
new file mode 100644
index 0000000..c46c5bf
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/ASRX_V1.0.0.md
@@ -0,0 +1,102 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "ASRX Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "asrx"
+ - "speaker-diarization"
+ - "speechbrain"
+ - "v1.0.0"
+ai_query_hints:
+ - "ASRX 使用 SpeechBrain ECAPA-TDNN 進行說話者日誌化"
+ - "ASRX 從 Pyannote 遷移至自定義 SpeechBrain，快 6 倍"
+ - "ASRX 不需要 HuggingFace token（相較 Pyannote）"
+ - "ASRX Charade 6879s 長片輸出 1118 segments, 8 說話人"
+ - "ASRX 依賴 ASR processor 的轉錄結果"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../ASR_V1.0.0.md"
+ - "../CUT_V1.0.0.md"
+ - "../VOICE_EMBEDDING_FLOW_V1.0.0.md"
+ - "../VECTOR_SPEC_V1.0.0.md"
+---
+
+# ASRX Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ⚠️ 80% | **模型**: SpeechBrain ECAPA-TDNN | **GPU**: 否
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| ASRX | 進階語音處理，包含說話者日誌化（Speaker Diarization） |
+| Speaker Diarization | 說話者日誌化，區分「誰在什麼時候說話」 |
+| ECAPA-TDNN | SpeechBrain 提供的說話人辨識模型，產出 192-D embedding |
+| VAD | Voice Activity Detection，語音活動檢測（使用 Silero） |
+| Spectral Clustering | 頻譜聚類，將 embedding 分群以區分不同說話人 |
+
+---
+
+## 選型過程
+
+| 指標 | Pyannote-based（原始） | Custom SpeechBrain（新） |
+|------|----------------------|------------------------|
+| Pipeline | VAD → Whisper → Align → Diarize | VAD (Silero) → ECAPA-TDNN → Spectral Clustering |
+| 處理時間 | 4.79s（輸出為空） | **1.66s** (96.25x) |
+| 比 Pyannote 快 | 基準 | **6x 更快** |
+| HuggingFace token | ✅ **需要** | ❌ **不需要** |
+| 重疊語音 | ✅ 支援 | ❌ 不支援 |
+
+**決策**: 因 pyannote.audio 需要 HuggingFace token、import 錯誤頻繁、輸出為空，已改為自定義 SpeechBrain 實作。
+
+---
+
+## 處理時間分解（Custom SpeechBrain）
+
+| 步驟 | 時間 | 佔比 |
+|------|------|------|
+| VAD (Silero) | 0.41s | 24.7% |
+| Speaker embedding (ECAPA-TDNN) | 1.15s | 69.3% |
+| Spectral clustering | 0.10s | 6.0% |
+
+---
+
+## Charade 長片（6879s）
+
+| 指標 | 值 |
+|------|-----|
+| Segments | 1118 |
+| 說話人數 | 8 |
+| 匹配率 | 99.82% |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 0.8 |
+| 記憶體 | 2048 MB |
+| GPU | 不使用 |
+| 依賴 | ASR |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/ASR_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/ASR_V1.0.0.md
new file mode 100644
index 0000000..098f0f0
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/ASR_V1.0.0.md
@@ -0,0 +1,117 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "ASR Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "asr"
+ - "whisper"
+ - "speech-recognition"
+ - "v1.0.0"
+ai_query_hints:
+ - "ASR 使用 faster-whisper/small 模型及 INT8 CPU 量化"
+ - "ASR 以 CUT 場景邊界為基礎分段處理長片"
+ - "ASR 每個 segment 記錄 scene_number 對應 CUT 場景序號"
+ - "ASR 處理 159.6s 影片約 12.68s，即時倍率 12.6x"
+ - "ASR 依賴 CUT processor 的場景邊界輸出"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../CUT_V1.0.0.md"
+ - "../ASRX_V1.0.0.md"
+ - "../STORY_V1.0.0.md"
+ - "../CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# ASR Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: faster-whisper/small | **GPU**: 否
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| ASR | Automatic Speech Recognition，自動語音辨識 |
+| faster-whisper | 基於 OpenAI Whisper 的優化版本，支援 INT8 CPU 量化 |
+| segment | Whisper 輸出的語音片段，包含 start/end/time/text |
+| scene_number | CUT 場景序號（1-based），標示 segment 所屬場景 |
+| real-time factor | 即時倍率，處理時間與影片時長的比值 |
+
+---
+
+## 選型過程
+
+| 模型 | 參數 | 大小 | English WER | Chinese CER | 速度 |
+|------|------|------|-------------|-------------|------|
+| tiny | 39M | ~40MB | 9.5% | 15.0% | ~1x RT |
+| base | 74M | ~75MB | 7.3% | 11.2% | ~1.5x RT |
+| **small** | **244M** | **~250MB** | **5.5%** | **8.4%** | **~2x RT** |
+| medium | 769M | ~800MB | 4.3% | 6.4% | ~3x RT |
+| large-v3 | 1.5B | ~1.5GB | 3.5% | 4.9% | ~5x RT |
+
+**決策**: small 在準確率與速度間取得最佳平衡，經實驗驗證最少要使用 small 才能較好處理多語種及台灣腔國語。
+
+---
+
+## 效能實測（ExaSAN 159.6s 影片）
+
+| 指標 | 值 |
+|------|-----|
+| 處理時間 | 12.68s |
+| 即時倍率 | 12.6x |
+| 輸出 | 78~79 segments, ~15KB |
+
+---
+
+## 長片分段處理
+
+對於長片（如 Charade 6879s），ASR 以 CUT processor 產出的場景邊界為基礎分段處理：
+
+1. CUT 先產出 `{file_uuid}.cut.json`（含 `scenes[]`，每個有 `start_time`/`end_time`）
+2. ASR 讀取 CUT JSON，依 `scene_number` 順序對每個場景萃取音訊
+3. 每個場景分別用 Whisper 轉錄
+4. 合併結果，每個 segment 記錄所屬的 `scene_number`
+
+每個 segment 的 JSON 格式：
+```json
+{
+ "start": 12.5,
+ "end": 15.3,
+ "text": "Hello world",
+ "scene_number": 42
+}
+```
+
+`scene_number` 是在該 `file_uuid` 下的 CUT 場景序號（1-based）。
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+---
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 1.0（一個完整核心） |
+| 記憶體 | 2048 MB（長片因分段處理，實際低於此值） |
+| GPU | 不使用（INT8 CPU 量化） |
+| 依賴 | 無 |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/CAPTION_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/CAPTION_V1.0.0.md
new file mode 100644
index 0000000..d2f51a1
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/CAPTION_V1.0.0.md
@@ -0,0 +1,80 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "Caption Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "caption"
+ - "moondream2"
+ - "image-captioning"
+ - "v1.0.0"
+ai_query_hints:
+ - "Caption 使用 Moondream2 進行本地圖像描述生成"
+ - "Caption 已從 GPT-4o 雲端 API 本地化為 Moondream2"
+ - "Caption Moondream2 模型約 1.8GB，完全本地執行"
+ - "Caption 處理速度約 5s/frame"
+ - "Caption 備援方案為 YOLO + OCR + Scene 串接"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../SCENE_V1.0.0.md"
+ - "../STORY_V1.0.0.md"
+ - "../YOLO_V1.0.0.md"
+ - "../OCR_V1.0.0.md"
+---
+
+# Caption Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: Moondream2 | **GPU**: 否
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Caption | 圖像描述生成，為每個場景產出文字敘述 |
+| Moondream2 | HuggingFace transformers 提供的本地圖像描述模型 |
+| GPT-4o | （已移除）先前使用的雲端 API 方案 |
+| local deployment | 完全本地執行，不依賴任何雲端 API |
+| fallback | 備援方案：YOLO + OCR + Scene 結果串接 |
+
+---
+
+## 選型過程
+
+| 指標 | GPT-4o（已移除） | Moondream2（新） |
+|------|-----------------|-----------------|
+| 速度 | 2s/frame | 5s/frame |
+| 品質 | 高 | 良好 |
+| 依賴 | ✅ 雲端 API Key | ❌ 完全本地 |
+
+**決策**: 已從 GPT-4o 雲端 API 本地化為 Moondream2（HuggingFace transformers, ~1.8GB）。備援方案為 YOLO + OCR + Scene 結果串接。
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | - |
+| 記憶體 | ~1.8 GB（模型載入後） |
+| GPU | 不使用 |
+| 依賴 | Scene |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/CUT_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/CUT_V1.0.0.md
new file mode 100644
index 0000000..c17e3af
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/CUT_V1.0.0.md
@@ -0,0 +1,135 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "CUT Processor (Scene Cut Detection) V1.0.0"
+date: "2026-05-03"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "cut"
+ - "scene-detection"
+ - "pyscenedetect"
+ - "v1.0.0"
+ai_query_hints:
+ - "CUT 場景檢測的輸出結構與檔案後綴規則"
+ - "CUT 的 cut_count 與 cut_max_duration 用途"
+ - "長影片動態調度如何將 Face 移到 ASR 前"
+ - "CUT 與 Scene 的執行階段（register 同步）"
+ - "CUT 輸出 JSON 結構（start_time/end_time）"
+related_documents:
+ - "PROCESSORS/SCENE_V1.0.0.md"
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "PROCESSORS/ASR_V1.0.0.md"
+ - "PROCESSORS/FACE_V1.0.0.md"
+ - "CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# CUT Processor (Scene Cut Detection) V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-03 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: PySceneDetect (ContentDetector) | **GPU**: 否
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| CUT | 場景切換檢測，使用 PySceneDetect ContentDetector |
+| scene boundary | 場景邊界，以 start_time/end_time 定義 |
+| cut_count | 場景數量，register 階段寫入 DB |
+| cut_max_duration | 最長場景秒數，用於長影片動態調度 |
+| ContentDetector | 基於幀差異的場景切換檢測演算法 |
+
+---
+
+## 選型過程
+
+無 ML 模型，基於幀差異的場景切換檢測。門檻值 threshold=27 為實驗最佳值。
+
+---
+
+## 輸出結構
+
+CUT 產出 `{file_uuid}.cut.json`，結構如下：
+
+```json
+{
+ "scenes": [
+ { "start_time": 0.0, "end_time": 120.5 },
+ { "start_time": 120.5, "end_time": 245.0 }
+ ]
+}
+```
+
+---
+
+## 執行階段
+
+CUT 在 **register 階段同步執行**（`register_single_file`），不做 worker pipeline 排程。完成後寫入 DB 欄位：
+- `cut_done: bool` — 是否完成
+- `cut_count: i32` — 場景數量
+- `cut_max_duration: f64` — 最長場景秒數
+
+---
+
+## 狀態後綴
+
+| 後綴 | 意義 | 行為 |
+|------|------|------|
+| `.cut.json` | 完成 | 直接載入使用 |
+| `.cut.json.tmp` | 執行中 | 跳過、等待 |
+| `.cut.json.err` | 失敗 | 跳過、不重試 |
+
+---
+
+## 長影片動態調度
+
+當 `cut_count ≤ 3 && cut_max_duration > 600s`（如會議紀錄長鏡頭），Worker 自動調整 pipeline 順序：
+- **Face 移到 ASR 前面**，先用 face detection 找出人物進出點
+- 後續可用 face 分佈切分長 scene，輔助 ASR 分段
+
+---
+
+## 效能實測
+
+**ExaSAN 159.6s 影片**:
+| 指標 | 值 |
+|------|-----|
+| 處理時間 | 0.08s |
+| 即時倍率 | 2036.5x（最快的 processor） |
+| 輸出 | 52 bytes |
+
+**Charade 長片（6879s, 412343 幀）**:
+| 指標 | 值 |
+|------|-----|
+| 場景數 | 1331 |
+| 輸出 | 217 KB |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-03 | 初始版本 | OpenCode | deepseek-chat |
+
+---
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 0.5 |
+| 記憶體 | 512 MB |
+| GPU | 不使用 |
+| 依賴 | 無 |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/FACE_EMBEDDING_FLOW_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/FACE_EMBEDDING_FLOW_V1.0.0.md
new file mode 100644
index 0000000..a4e1b25
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/FACE_EMBEDDING_FLOW_V1.0.0.md
@@ -0,0 +1,133 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "Face Embedding 產出流程 V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "momentry"
+ - "core"
+ - "face"
+ - "embedding"
+ - "qdrant"
+ - "v1.0.0"
+ai_query_hints:
+ - "Face Embedding 的完整處理流程（Frame → InsightFace → Qdrant）"
+ - "Face processor 的輸出結構與 embedding 欄位說明"
+ - "Worker store_face_chunks 與 store_face_embeddings_to_qdrant 的步驟"
+ - "Qdrant face collection 的 payload 結構與點位 ID 規則"
+ - "Face embedding 的 512-D ArcFace w600k_r50 向量規格"
+ - "Face embedding 使用 Cosine 距離計算"
+ - "InsightFace buffalo_l 的資源預估與 GPU 加速資訊"
+ - "face_detections 表與 Qdrant 的資料同步方式"
+related_documents:
+ - "../VECTOR_SPEC_V1.0.0.md"
+ - "../PROCESSORS/FACE_V1.0.0.md"
+ - "../PROCESSOR_SELECTION_V1.0.0.md"
+ - "../CHUNK_DEFINITION_V1.0.0.md"
+ - "../MOMENTRY_CORE_API_V1.0.0.md"
+---
+
+# Face Embedding 產出流程 V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Face Embedding | 人臉向量嵌入，由 InsightFace ArcFace 產出 512-D 向量 |
+| SCRFD-10G | InsightFace 的人臉檢測模型 |
+| ArcFace w600k_r50 | InsightFace 的人臉辨識模型，產出 512-D embedding |
+| point_id | Qdrant 中向量的唯一 ID，使用幀編號 (frame number) |
+| Cosine distance | 餘弦距離，用於向量相似度計算 |
+| payload | Qdrant 向量的附帶 metadata 欄位 |
+
+## 處理流程
+
+```
+1. Video Frame (取樣)
+ │
+ ▼
+2. Face Processor (face_processor.py)
+ ├── InsightFace buffalo_l
+ │ ├── SCRFD-10G 人臉檢測
+ │ ├── ArcFace w600k_r50 512-D embedding
+ │ ├── 年齡/性別預測
+ │ └── 2D106 landmarks
+ │
+ ├── 輸出: job_{id}_face_{ts}.json → {file_uuid}.face.json
+ │ └── FaceResult { frame_count, fps, frames: [FaceFrame] }
+ │
+ ▼
+3. Worker store_face_chunks()
+ ├── 解析 FaceResult
+ ├── 寫入 pre_chunks 表 (file_uuid, processor_type='face', data)
+ └── 寫入 face_detections 表
+ │
+ ▼
+4. Worker store_face_embeddings_to_qdrant()
+ ├── 對每個 face frame 的每個 face
+ │ └── 若有 embedding (512-D)：
+ │ ├── point_id = frame number (u64)
+ │ ├── vector = 512-D float array
+ │ └── payload (見下方)
+ └── 寫入 Qdrant collection `momentry_dev_face`
+```
+
+## Qdrant Payload 結構
+
+```json
+{
+ "file_uuid": "dd61fda85fee441fdd00ab5528213ff7",
+ "face_id": null,
+ "frame": 15,
+ "timestamp": 0.68,
+ "x": 328,
+ "y": 88,
+ "width": 63,
+ "height": 75,
+ "confidence": 0.83
+}
+```
+
+| 欄位 | 型別 | 說明 |
+|------|------|------|
+| `file_uuid` | string | 來源影片識別碼 |
+| `face_id` | string|null | 臉部追蹤 ID（尚未分配時為 null） |
+| `frame` | integer | 幀編號 |
+| `timestamp` | float | 時間戳（秒） |
+| `x, y, width, height` | integer | 人臉邊界框 |
+| `confidence` | float | 檢測信心度 (0~1) |
+
+## Vector 規格
+
+| 屬性 | 值 |
+|------|-----|
+| 模型 | InsightFace ArcFace w600k_r50 |
+| 維度 | 512 |
+| 距離計算 | Cosine |
+| 歸一化 | 否 (raw output) |
+
+## 來源 Processor 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| 模型 | InsightFace buffalo_l (~150MB) |
+| CPU | 0.6 |
+| 記憶體 | 1536 MB |
+| GPU | 支援（CoreML 50-80 FPS, CUDA 80-120 FPS） |
+| 處理速度 | 130.5x real-time (M4 Mac Mini) |
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/FACE_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/FACE_V1.0.0.md
new file mode 100644
index 0000000..8dc02e7
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/FACE_V1.0.0.md
@@ -0,0 +1,104 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "Face Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "face"
+ - "insightface"
+ - "face-detection"
+ - "v1.0.0"
+ai_query_hints:
+ - "Face 使用 InsightFace buffalo_l 進行人臉偵測與辨識"
+ - "Face 在 ExaSAN 159.6s 影片上僅需 1.22s，即時倍率 130.5x"
+ - "Face 支援 GPU 加速，CoreML 可達 50~80 FPS"
+ - "Face 輸出 512-D embedding 用於比對"
+ - "Face 不再使用 Haar Cascade fallback，強制使用 InsightFace"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../FACE_EMBEDDING_FLOW_V1.0.0.md"
+ - "../CUT_V1.0.0.md"
+ - "../VECTOR_SPEC_V1.0.0.md"
+ - "../CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# Face Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: InsightFace buffalo_l | **GPU**: 是
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Face Detection | 人臉偵測，使用 InsightFace SCRFD-10G |
+| Face Recognition | 人臉辨識，使用 ArcFace w600k_r50 產出 512-D embedding |
+| embedding | 向量嵌入，用於人臉比對與搜尋 |
+| CoreML | Apple Silicon 上的 GPU 加速方案 |
+| LFW | Labeled Faces in the Wild，人臉辨識基準資料集 |
+
+---
+
+## 選型過程
+
+| 模型 | 類型 | 大小 | 檢測率 | 辨識率 | Embedding |
+|------|------|------|--------|--------|-----------|
+| **InsightFace Buffalo_l** | **完整套件** | **~150MB** | **97.3% mAP** | **99.77% (LFW)** | **512-D ✅** |
+| MediaPipe BlazeFace | 輕量檢測 | 1~2MB | 95.2% mAP | 無 | ❌ |
+| OpenCV Haar Cascade | 傳統 ML | 900KB | 70~85% | 無 | ❌ |
+
+**關鍵決策**: 舊版 Haar Cascade fallback 會產生全鏈路失敗（0 embeddings），已改為強制使用 InsightFace。
+
+---
+
+## 效能實測（ExaSAN 159.6s 影片）
+
+| 指標 | 值 |
+|------|-----|
+| 處理時間 | 1.22s |
+| 即時倍率 | 130.5x |
+| 輸出 | 49 frames, 67 faces |
+
+---
+
+## GPU 加速
+
+| 平台 | FPS |
+|------|-----|
+| CoreML (Apple Silicon) | 50~80 FPS |
+| CUDA (NVIDIA) | 80~120 FPS |
+| CPU | 15~20 FPS |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+---
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 0.6 |
+| 記憶體 | 1536 MB |
+| GPU | 支援（`uses_gpu = true`） |
+| 依賴 | 無 |
+
+---
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/OCR_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/OCR_V1.0.0.md
new file mode 100644
index 0000000..00d208a
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/OCR_V1.0.0.md
@@ -0,0 +1,87 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "OCR Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "ocr"
+ - "paddleocr"
+ - "optical-character-recognition"
+ - "v1.0.0"
+ai_query_hints:
+ - "OCR 使用 PaddleOCR PP-OCRv4 模型支援 80+ 語言"
+ - "OCR 處理 159.6s 影片全幀約 36.87s，即時倍率 4.3x"
+ - "OCR 輸出 102 frames, 234 texts, 65KB"
+ - "OCR 不使用 GPU，CPU 使用率 0.8"
+ - "OCR 精度 > 95%，支援繁體中文"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../YOLO_V1.0.0.md"
+ - "../CAPTION_V1.0.0.md"
+ - "../VISUAL_CHUNK_V1.0.0.md"
+ - "../CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# OCR Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: PaddleOCR PP-OCRv4 | **GPU**: 否
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| OCR | Optical Character Recognition，光學字元辨識 |
+| PaddleOCR | 百度開發的 OCR 引擎，PP-OCRv4 為最新版本 |
+| PP-OCRv4 | PaddleOCR 第四代模型，支援 80+ 語言 |
+| real-time factor | 即時倍率，處理時間與影片時長的比值 |
+| full-frame processing | 全幀處理模式，對影片每一幀進行 OCR |
+
+---
+
+## 選型過程
+
+選擇 PaddleOCR 原因：
+- 支援 80+ 語言（含繁體中文）
+- 精度 > 95%
+- EasyOCR 經測試不如 PaddleOCR
+
+---
+
+## 效能實測（ExaSAN 159.6s 影片, 全幀處理）
+
+| 指標 | 值 |
+|------|-----|
+| 處理時間 | 36.87s |
+| 即時倍率 | 4.3x |
+| 輸出 | 102 frames, 234 texts, 65KB |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 0.8 |
+| 記憶體 | 1024 MB |
+| GPU | 不使用 |
+| 依賴 | 無 |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/POSE_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/POSE_V1.0.0.md
new file mode 100644
index 0000000..9e76a0d
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/POSE_V1.0.0.md
@@ -0,0 +1,84 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "Pose Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "pose"
+ - "mediapipe"
+ - "pose-estimation"
+ - "v1.0.0"
+ai_query_hints:
+ - "Pose 使用 MediaPipe Pose (pose_landmarker_heavy, 33 keypoints)"
+ - "Pose 處理 159.6s 影片全幀約 65.87s，即時倍率 2.4x"
+ - "Pose 輸出 1853 frames, 2341 persons, 603KB"
+ - "Pose 支援 GPU 加速（uses_gpu = true）"
+ - "Pose 與 YOLO 同為處理瓶頸之一"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../YOLO_V1.0.0.md"
+ - "../FACE_V1.0.0.md"
+ - "../CUT_V1.0.0.md"
+ - "../CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# Pose Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: MediaPipe Pose | **GPU**: 是
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Pose Estimation | 姿態估計，偵測人體關鍵點位置 |
+| MediaPipe | Google 開發的跨平台 ML 解決方案 |
+| keypoint | 關鍵點，pose_landmarker_heavy 輸出 33 個關鍵點 |
+| landmarker_heavy | MediaPipe 的精確模式，準確度最高但速度較慢 |
+| bottleneck | 處理瓶頸，Pose 與 YOLO 同為最耗時的 processor |
+
+---
+
+## 選型過程
+
+使用 MediaPipe Pose（pose_landmarker_heavy, 33 keypoints）。
+
+---
+
+## 效能實測（ExaSAN 159.6s 影片, 全幀處理）
+
+| 指標 | 值 |
+|------|-----|
+| 處理時間 | 65.87s |
+| 即時倍率 | 2.4x（瓶頸之一，與 YOLO 相當） |
+| 輸出 | 1853 frames, 2341 persons, 603KB |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 0.4 |
+| 記憶體 | 1024 MB |
+| GPU | 支援（`uses_gpu = true`） |
+| 依賴 | 無 |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/SCENE_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/SCENE_V1.0.0.md
new file mode 100644
index 0000000..3cbaa6e
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/SCENE_V1.0.0.md
@@ -0,0 +1,95 @@
+---
+document_type: "processor-spec"
+service: "MOMENTRY_CORE"
+title: "Scene Processor (Scene Classification) V1.0.0"
+date: "2026-05-03"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "scene"
+ - "places365"
+ - "scene-classification"
+ - "v1.0.0"
+ai_query_hints:
+ - "Scene 分類的模型選型與效能實測"
+ - "Scene 的執行階段與檔案後綴檢查規則"
+ - "Scene 與 CUT 的依賴關係（已移除 ASR）"
+ - "Scene 輸出為 pre_chunks 供 Rule 3 parent chunk 使用"
+ - "load_scene_from_file 直接載入 JSON 不入庫"
+related_documents:
+ - "PROCESSORS/CUT_V1.0.0.md"
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "PROCESSORS/CAPTION_V1.0.0.md"
+ - "PROCESSORS/STORY_V1.0.0.md"
+ - "CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# Scene Processor (Scene Classification) V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-03 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: MIT Places365 (ResNet18) | **GPU**: 否
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Scene Classification | 場景分類，辨識影片畫面的場景類型 |
+| Places365 | MIT 開發的場景辨識資料集與模型（365 個場景類別） |
+| ResNet18 | 殘差網路架構，輕量級分類模型 |
+| pre_chunks | 原始元件的資料表，Scene 輸出供 Rule 3 使用 |
+| parent chunk | 聚合多個 child chunks 的上層 chunk，由 Rule 3 產出 |
+
+## 選型過程
+
+初始使用 ImageNet（產生 scene_XXX 類別索引），後升級至 Places365 以獲得具名場景類別（如 living_room, beach, airport），準確率 85~90%。
+
+## 執行階段
+
+Scene 在 **register 階段同步執行**（`register_single_file`）。Worker 中重入時檢查後綴：
+- `.scene.json` → 從檔案載入（不入庫 pre_chunks）
+- `.scene.json.tmp` → 跳過（回傳空結果）
+- `.scene.json.err` → 跳過（回傳空結果）
+
+載入函數：`load_scene_from_file(path: &str) -> SceneClassificationResult`
+
+## 與 CUT 的關係
+
+Scene 與 ASR 無關（純視覺分類），已移除對 ASR 的依賴。CUT 為 Scene 的唯一前置依賴。
+
+## 輸出用途
+
+Scene 為 **pre_chunks**（scene boundary），供 Rule 3 產生 parent chunk。Rule 3 需要 CUT + Scene 的 boundary 來產生複合 parent chunk。
+
+## 效能實測（ExaSAN 159.6s 影片, 取樣間隔=2s）
+
+| 指標 | 值 |
+|------|-----|
+| 處理時間 | 4.09s |
+| 即時倍率 | 39.0x |
+| 取樣數 | 79 samples |
+
+## Charade 長片（6879s）
+
+| 指標 | 值 |
+|------|-----|
+| 處理時間 | 313.3s（5.2 分鐘） |
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 0.3 |
+| 記憶體 | 512 MB |
+| GPU | 不使用 |
+| 依賴 | CUT, ASR |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/STORY_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/STORY_V1.0.0.md
new file mode 100644
index 0000000..a8edd6f
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/STORY_V1.0.0.md
@@ -0,0 +1,80 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "Story Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "story"
+ - "template-aggregator"
+ - "narrative"
+ - "v1.0.0"
+ai_query_hints:
+ - "Story 使用模板聚合從 ASR+YOLO+Scene 產生結構化敘述"
+ - "Story 已從 GPT-4 雲端 API 本地化為模板聚合"
+ - "Story 處理速度 <0.1s/chunk，極快"
+ - "Story 完全不依賴雲端 API，完全本地執行"
+ - "Story 依賴 Scene 和 Caption processor 的輸出"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../SCENE_V1.0.0.md"
+ - "../CAPTION_V1.0.0.md"
+ - "../ASR_V1.0.0.md"
+ - "../CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# Story Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: 模板聚合 | **GPU**: 否
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Story Processor | 從 ASR + YOLO + Scene 結果產生結構化敘述的處理器 |
+| Template Aggregation | 使用預定義模板組合資料，非 LLM 生成 |
+| GPT-4 | （已移除）先前使用的雲端 API 方案 |
+| local deployment | 完全本地執行，不依賴任何雲端 API |
+| structured narrative | 結構化敘述，以固定格式組織的故事描述 |
+
+---
+
+## 選型過程
+
+| 指標 | GPT-4（已移除） | 模板（新） |
+|------|----------------|------------|
+| 速度 | 3s/chunk | **<0.1s/chunk** |
+| 品質 | 自然語言 | 結構化格式 |
+| 依賴 | ✅ 雲端 API Key | ❌ 完全本地 |
+
+**決策**: 已從 GPT-4 雲端 API 本地化為模板聚合，從 ASR + YOLO + Scene 結果產生結構化敘述。
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | - |
+| 記憶體 | - |
+| GPU | 不使用 |
+| 依賴 | Scene, Caption |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/VISUAL_CHUNK_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/VISUAL_CHUNK_V1.0.0.md
new file mode 100644
index 0000000..103d4bb
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/VISUAL_CHUNK_V1.0.0.md
@@ -0,0 +1,74 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "VisualChunk Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "visual-chunk"
+ - "rule-aggregator"
+ - "yolo"
+ - "v1.0.0"
+ai_query_hints:
+ - "VisualChunk 是規則驅動的聚合器，非 ML 模型"
+ - "VisualChunk 將 YOLO 結果組合成視覺分片"
+ - "VisualChunk 依賴 YOLO processor 的偵測結果"
+ - "VisualChunk CPU 使用率低（0.3），記憶體 512 MB"
+ - "VisualChunk 是 Scene 和 Story processor 的前置依賴"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../YOLO_V1.0.0.md"
+ - "../SCENE_V1.0.0.md"
+ - "../STORY_V1.0.0.md"
+ - "../CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# VisualChunk Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 整合 | **模型**: 無（規則聚合） | **GPU**: 否
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| VisualChunk | 規則驅動的聚合器，將 YOLO 結果組合成視覺分片 |
+| Rule Aggregation | 使用預設規則而非 ML 模型進行資料組合 |
+| Visual Chunk | 視覺分片，包含 YOLO 偵測物件的時間區間 |
+| pre_chunks | 原始元件表，VisualChunk 的輸出會寫入此表 |
+| dependency chain | 依賴鏈：YOLO → VisualChunk → Scene → Story |
+
+---
+
+## 說明
+
+非 ML 模型，是規則驅動的聚合器，將 YOLO 結果組合成視覺分片。
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 0.3 |
+| 記憶體 | 512 MB |
+| GPU | 不使用 |
+| 依賴 | YOLO |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/VOICE_EMBEDDING_FLOW_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/VOICE_EMBEDDING_FLOW_V1.0.0.md
new file mode 100644
index 0000000..18ba79e
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/VOICE_EMBEDDING_FLOW_V1.0.0.md
@@ -0,0 +1,139 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "Voice Embedding 產出流程 V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "momentry"
+ - "core"
+ - "voice"
+ - "embedding"
+ - "asrx"
+ - "qdrant"
+ - "v1.0.0"
+ai_query_hints:
+ - "Voice Embedding 的完整處理流程（音軌 → ECAPA-TDNN → Qdrant）"
+ - "ASRX Processor 的三階段處理：音軌預處理 → ASR segments 載入 → Speaker Diarization"
+ - "Worker store_asrx_chunks 的步驟與 pre_chunks 寫入規則"
+ - "Qdrant voice collection 的 payload 結構與欄位定義"
+ - "Voice embedding 的 192-D ECAPA-TDNN 向量規格（L2 normalize）"
+ - "Voice embedding 使用 Cosine 距離計算與 L2 歸一化"
+ - "SpeechBrain ECAPA-TDNN 的資源預估與處理速度"
+ - "Voice embedding 與 ASR 處理器的依賴關係"
+related_documents:
+ - "../VECTOR_SPEC_V1.0.0.md"
+ - "../PROCESSORS/ASRX_V1.0.0.md"
+ - "../PROCESSORS/ASR_V1.0.0.md"
+ - "../PROCESSOR_SELECTION_V1.0.0.md"
+ - "../MOMENTRY_CORE_API_V1.0.0.md"
+---
+
+# Voice Embedding 產出流程 V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Voice Embedding | 語音向量嵌入，由 ECAPA-TDNN 產出 192-D 向量 |
+| ECAPA-TDNN | SpeechBrain 提供的說話人辨識模型 |
+| L2 normalize | 向量歸一化，確保所有向量單位長度 |
+| Spectral Clustering | 頻譜聚類，將語音 embedding 分群以區分說話人 |
+| segment_index | 在 asrx 輸出 segments 中的索引編號 |
+| speaker_id | 說話人標籤（如 SPEAKER_0, SPEAKER_1） |
+
+## 處理流程
+
+```
+1. Video → ffmpeg 萃取音軌 → 16kHz mono WAV
+ │
+ ▼
+2. ASRX Processor (asrx_processor_custom.py)
+ │
+ ├── Stage 1: 音軌預處理
+ │ ├── ffprobe 列出所有音軌
+ │ ├── 選擇最佳音軌（優先英語）
+ │ └── ffmpeg 轉為 16kHz mono WAV
+ │
+ ├── Stage 2: 載入 ASR segments
+ │ └── 從 {file_uuid}.asr.json 讀取 segments
+ │
+ ├── Stage 3: Speaker Diarization (SelfASRXFixed.process_with_segments)
+ │ ├── 對每個 ASR segment 取出音訊片段
+ │ ├── ECAPA-TDNN 產出 192-D embedding
+ │ ├── 正規化 embeddings
+ │ └── 譜聚類 → speaker label
+ │
+ ├── 輸出: {file_uuid}.asrx.json
+ │ ├── segments: [start_time, end_time, speaker_id]
+ │ └── embeddings: [[192-D float array], ...]
+ │
+ ▼
+3. Worker store_asrx_chunks()
+ ├── 解析 AsrxResult
+ ├── 寫入 pre_chunks 表
+ └── 寫入 voice embeddings 到 Qdrant
+ │
+ ▼
+4. Qdrant `momentry_dev_voice`
+ └── 每個 segment 一個 vector
+```
+
+## Qdrant Payload 結構
+
+```json
+{
+ "file_uuid": "dd61fda85fee441fdd00ab5528213ff7",
+ "speaker_id": "SPEAKER_0",
+ "segment_index": 0,
+ "start_frame": 9,
+ "end_frame": 441,
+ "start_time": 0.3,
+ "end_time": 14.7
+}
+```
+
+| 欄位 | 型別 | 說明 |
+|------|------|------|
+| `file_uuid` | string | 來源影片識別碼 |
+| `speaker_id` | string | 說話人標籤（如 SPEAKER_0） |
+| `segment_index` | integer | 在 segments 中的索引 |
+| `start_frame` | integer | 起始幀 |
+| `end_frame` | integer | 結束幀 |
+| `start_time` | float | 起始時間（秒） |
+| `end_time` | float | 結束時間（秒） |
+
+## Vector 規格
+
+| 屬性 | 值 |
+|------|-----|
+| 模型 | SpeechBrain ECAPA-TDNN |
+| 維度 | 192 |
+| 距離計算 | Cosine |
+| 歸一化 | 是（L2 normalize） |
+
+## 來源 Processor 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| 模型 | SpeechBrain ECAPA-TDNN (~80MB) |
+| CPU | 0.8 |
+| 記憶體 | 2048 MB |
+| GPU | 不使用 |
+| 處理速度 | 57x real-time (M4 Mac Mini) |
+| 依賴 | ASR（需 ASR JSON 完成後才能啟動） |
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/YOLO_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/YOLO_V1.0.0.md
new file mode 100644
index 0000000..2cb088b
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSORS/YOLO_V1.0.0.md
@@ -0,0 +1,92 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "YOLO Processor V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+parent: "PROCESSOR_SELECTION_V1.0.0.md"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "yolo"
+ - "object-detection"
+ - "yolov8"
+ - "v1.0.0"
+ai_query_hints:
+ - "YOLO 使用 yolov8n (nano) 模型進行物件偵測"
+ - "YOLO 在 M4 Mac Mini 上可達 100~200 FPS"
+ - "YOLO 支援 GPU 加速（MPS），可快 2~5 倍"
+ - "YOLO 輸出 4.3 MB 含偵測結果"
+ - "YOLO 是 VisualChunk 和 Scene 的依賴"
+related_documents:
+ - "PROCESSOR_SELECTION_V1.0.0.md"
+ - "../VISUAL_CHUNK_V1.0.0.md"
+ - "../POSE_V1.0.0.md"
+ - "../OCR_V1.0.0.md"
+ - "../CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# YOLO Processor V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+**狀態**: ✅ 100% | **模型**: YOLOv8n (nano) | **GPU**: 是
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| YOLO | You Only Look Once，即時物件偵測演算法 |
+| YOLOv8n | Ultralytics YOLO 第八代 nano 版本，最小最快 |
+| object detection | 物件偵測，辨識影像中的物體類別與位置 |
+| MPS | Metal Performance Shaders，Apple Silicon GPU 加速 |
+| bottleneck | 處理瓶頸，YOLO 與 Pose 同為最耗時的 processor |
+
+---
+
+## 選型過程
+
+| 模型 | 參數 | 大小 | 速度 | 精度 |
+|------|------|------|------|------|
+| **yolov8n (nano)** | **3.2M** | **6.2MB** | **最快** | **較低** |
+| yolov8s (small) | 11.2M | - | 快 | 中等 |
+| yolov8m (medium) | 25.9M | - | 中 | 高 |
+| yolov8l (large) | 43.7M | - | 慢 | 很高 |
+| yolov8x (x-large) | 68.2M | - | 最慢 | 最高 |
+
+**決策**: 預設使用 `yolov8n.pt`（nano），在 M4 Mac Mini 上可達 100~200 FPS。可透過配置檔切換至更大模型。
+
+---
+
+## 效能實測（ExaSAN 159.6s 影片, 全幀處理）
+
+| 指標 | 值 |
+|------|-----|
+| 處理時間 | 65.72s |
+| 即時倍率 | 2.4x（瓶頸之一） |
+| 輸出 | 4.3 MB |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
+
+## 資源預估
+
+| 資源 | 值 |
+|------|-----|
+| CPU | 0.3 |
+| 記憶體 | 1024 MB |
+| GPU | 支援（`yolo_processor_mps.py` 可使用 MPS，快 2~5 倍） |
+| 依賴 | 無 |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSOR_SELECTION_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSOR_SELECTION_V1.0.0.md
new file mode 100644
index 0000000..67e7f93
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/PROCESSOR_SELECTION_V1.0.0.md
@@ -0,0 +1,108 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "Processor 選型與資源預估 V1.0.0"
+date: "2026-05-02"
+version: "V1.1"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "momentry"
+ - "core"
+ - "processor"
+ - "model-selection"
+ - "resource-estimation"
+ - "v1.0.0"
+ai_query_hints:
+ - "processor 的選型原因與實驗報告"
+ - "各 processor 的資源預估與模型資訊"
+ - "processor 之間的依賴關係"
+ - "模型選擇的比較與決策"
+ - "processor 檔案狀態後綴規則（json/tmp/err）"
+ - "Job 完成條件與必要 processor 定義"
+related_documents:
+ - "PROCESSORS/ASR_V1.0.0.md"
+ - "PROCESSORS/FACE_V1.0.0.md"
+ - "PROCESSORS/YOLO_V1.0.0.md"
+ - "PROCESSORS/CUT_V1.0.0.md"
+ - "CHUNK_DEFINITION_V1.0.0.md"
+---
+
+# Processor 選型與資源預估 V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.1 |
+
+---
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| Processor | 處理器，負責特定類型媒體分析的 Python 腳本 |
+| Pipeline | 處理管線，定義 processor 的執行順序與依賴關係 |
+| PythonExecutor | 統一執行 Python 腳本的 Rust 封裝層 |
+| real-time factor | 即時倍率，處理時間與影片時長的比值 |
+| resource estimation | 資源預估，包含 CPU/記憶體/GPU 的使用量 |
+| Job | 處理任務，包含多個 processor 的執行與狀態管理 |
+
+## 總覽
+
+| Processor | 狀態 | 模型 | 依賴 | GPU | CPU | 記憶體 | 文件 |
+|-----------|------|------|------|-----|-----|--------|------|
+| ASR | ✅ 100% | faster-whisper (small) | 無 | 否 | 1.0 | 2048 MB | [詳細](./PROCESSORS/ASR_V1.0.0.md) |
+| CUT | ✅ 100% | PySceneDetect | 無 | 否 | 0.5 | 512 MB | [詳細](./PROCESSORS/CUT_V1.0.0.md) |
+| YOLO | ✅ 100% | YOLOv8n | 無 | 是 | 0.3 | 1024 MB | [詳細](./PROCESSORS/YOLO_V1.0.0.md) |
+| OCR | ✅ 100% | PaddleOCR PP-OCRv4 | 無 | 否 | 0.8 | 1024 MB | [詳細](./PROCESSORS/OCR_V1.0.0.md) |
+| Face | ✅ 100% | InsightFace buffalo_l | 無 | 是 | 0.6 | 1536 MB | [詳細](./PROCESSORS/FACE_V1.0.0.md) |
+| Pose | ✅ 100% | MediaPipe Pose | 無 | 是 | 0.4 | 1024 MB | [詳細](./PROCESSORS/POSE_V1.0.0.md) |
+| ASRX | ⚠️ 80% | SpeechBrain ECAPA-TDNN | ASR | 否 | 0.8 | 2048 MB | [詳細](./PROCESSORS/ASRX_V1.0.0.md) |
+| Scene | ✅ 100% | MIT Places365 | CUT | 否 | 0.3 | 512 MB | [詳細](./PROCESSORS/SCENE_V1.0.0.md) |
+| VisualChunk | ✅ 整合 | 規則聚合（無模型） | YOLO | 否 | 0.3 | 512 MB | [詳細](./PROCESSORS/VISUAL_CHUNK_V1.0.0.md) |
+| Caption | ✅ 100% (本地化) | Moondream2 | Scene | 否 | - | - | [詳細](./PROCESSORS/CAPTION_V1.0.0.md) |
+| Story | ✅ 100% (本地化) | 模板聚合 | Scene, Caption | 否 | - | - | [詳細](./PROCESSORS/STORY_V1.0.0.md) |
+
+---
+
+## Processor 依賴關係圖 （V4.1）
+
+```
+CUT ───→ Scene
+ │
+ASR ───→ ASRX
+ │
+YOLO ─→ VisualChunk
+```
+
+> **註（V4.1）**：CUT 和 Scene 在 register 階段同步執行，Worker pipeline 中 Scene 依賴僅 CUT（已移除 ASR）。長影片（scene ≤ 3, max > 600s）時 Face 動態移到 ASR 前。
+
+## 檔案狀態後綴
+
+所有 processor 輸出檔案使用統一的後綴規則：
+
+| 後綴 | 意義 | 行為 |
+|------|------|------|
+| `.json` | 完成 | 直接載入使用 |
+| `.json.tmp` | 執行中 | 跳過、等待 |
+| `.json.err` | 失敗 | 跳過、不重試 |
+
+此規則由 `PythonExecutor` 統一處理（`executor.rs:150-279`）。
+
+## Job 完成條件（V4.1）
+
+| 條件 | 結果 |
+|------|------|
+| 所有 processor 完成 | ✅ Job completed |
+| 必要 processor (cut/asr/yolo) 完成，其餘失敗 | ✅ Job completed（非必要失敗不卡住） |
+| 必要 processor 任一失敗 | ❌ Job failed |
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本，含選型實驗報告與資源預估 | OpenCode | deepseek-chat |
+| V1.1 | 2026-05-03 | CUT 新增 cut_count/cut_max_duration；Scene 移除 ASR 依賴；長影片 Face 動態調度；Job 完成條件放寬 | OpenCode | deepseek-chat |
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/VECTOR_SPEC_V1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/VECTOR_SPEC_V1.0.0.md
new file mode 100644
index 0000000..fe23a11
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/VECTOR_SPEC_V1.0.0.md
@@ -0,0 +1,129 @@
+---
+document_type: "spec"
+service: "MOMENTRY_CORE"
+title: "向量化規範 V1.0.0"
+date: "2026-05-02"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+ - "momentry"
+ - "core"
+ - "vector-embedding"
+ - "qdrant"
+ - "v1.0.0"
+ - "face-embedding"
+ - "voice-embedding"
+ - "text-embedding"
+ai_query_hints:
+ - "向量化規範的向量類型與維度說明"
+ - "Face/Voice/Text 三種 embedding 的處理流程"
+ - "Qdrant collection 的名稱與 payload 結構"
+ - "Face embedding 的 512-D 向量規格（InsightFace ArcFace）"
+ - "Voice embedding 的 192-D 向量規格（ECAPA-TDNN）"
+ - "Text embedding 的 768-D 向量規格（nomic-embed-text-v2-moe）"
+ - "Qdrant Payload 中 face 與 voice 的欄位定義"
+ - "向量化流程中 child chunk 與 parent chunk 的 collection 區別"
+related_documents:
+ - "PROCESSORS/FACE_EMBEDDING_FLOW_V1.0.0.md"
+ - "PROCESSORS/VOICE_EMBEDDING_FLOW_V1.0.0.md"
+ - "CHUNK_DEFINITION_V1.0.0.md"
+ - "PROCESSORS/FACE_V1.0.0.md"
+ - "PROCESSORS/ASRX_V1.0.0.md"
+---
+
+# 向量化規範 V1.0.0
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-05-02 |
+| 文件版本 | V1.0 |
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| embedding | 向量嵌入，將非結構化資料轉換為數值向量 |
+| Qdrant | 向量資料庫，用於儲存與檢索 embedding |
+| collection | Qdrant 中的向量集合，類似資料庫中的資料表 |
+| 768-D | Text embedding 的維度，由 nomic-embed-text-v2-moe 產出 |
+| 512-D | Face embedding 的維度，由 InsightFace ArcFace 產出 |
+| 192-D | Voice embedding 的維度，由 SpeechBrain ECAPA-TDNN 產出 |
+
+## 向量類型
+
+| 類型 | 來源 | 維度 | Collection | 用途 |
+|------|------|------|------------|------|
+| Text (child) | sentence chunk | 768-D | `momentry_dev_rule1` | 語意搜尋 |
+| Text (parent) | scene chunk summary | 768-D | `momentry_dev_chunk_summaries` | 場景語意搜尋 |
+| **Face** | Face processor (InsightFace) | **512-D** | `momentry_dev_face` | 人臉比對 |
+| **Voice** | ASRX processor (ECAPA-TDNN) | **192-D** | `momentry_dev_voice` | 說話人比對 |
+
+## 向量化流程
+
+### Text Embedding
+
+```
+chunk (sentence / scene)
+ → text_content / summary_text
+ → nomic-embed-text-v2-moe (Ollama)
+ → 768-D vector
+ → Qdrant momentry_dev_rule1 / momentry_dev_chunk_summaries
+```
+
+### Face Embedding
+
+```
+Face processor (InsightFace buffalo_l)
+ → face_detections.embedding (512-D)
+ → Qdrant momentry_dev_face
+ → 用於 1:N 人臉比對
+```
+
+### Voice Embedding
+
+```
+ASRX processor (ECAPA-TDNN)
+ → speaker embedding (192-D)
+ → Qdrant momentry_dev_voice
+ → 用於跨影片說話人辨識
+```
+
+## Qdrant Payload 結構
+
+### Face Payload
+
+```json
+{
+ "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
+ "face_id": "face_42",
+ "frame": 1260,
+ "timestamp": 42.0,
+ "x": 328,
+ "y": 88,
+ "width": 63,
+ "height": 75,
+ "confidence": 0.83
+}
+```
+
+### Voice Payload
+
+```json
+{
+ "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
+ "speaker_id": "SPEAKER_0",
+ "start_frame": 9,
+ "end_frame": 441,
+ "start_time": 0.3,
+ "end_time": 14.7
+}
+```
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
diff --git a/docs_v1.0/ARCHITECTURE/DOCUMENT_EMBEDDING_STRATEGY.md b/docs_v1.0/ARCHITECTURE/DOCUMENT_EMBEDDING_STRATEGY.md
deleted file mode 100644
index 4d6597d..0000000
--- a/docs_v1.0/ARCHITECTURE/DOCUMENT_EMBEDDING_STRATEGY.md
+++ /dev/null
@@ -1,167 +0,0 @@
-# Document Embedding Strategy - Parent-Child Chunks
-
-| Item | Content |
-|------|---------|
-| Author | Warren |
-| Created | 2026-03-23 |
-| Document Version | V1.0 |
-
----
-
-## Version History
-
-| Version | Date | Purpose | Operator | Tool/Model |
-|---------|------|---------|----------|------------|
-| V1.0 | 2026-03-23 | Create document embedding strategy | Warren | OpenCode |
-
----
-
-## Overview
-
-Momentry uses a **parent-child chunk hierarchy** for improved RAG retrieval. This document describes the embedding strategy for this hierarchy.
-
-## Chunk Structure
-
-### Parent Chunk
-- **Purpose**: Summarize multiple child chunks with narrative description
-- **Content**: High-level description of multiple scenes/segments
-- **Example**:
-```json
-{
- "chunk_id": "story_asr_0000",
- "chunk_type": "story",
- "text_content": "[0s-125s] A man enters a building. He walks down a hallway.",
- "child_chunk_ids": ["asr_0001", "asr_0002", "asr_0003", "asr_0004", "asr_0005"]
-}
-```
-
-### Child Chunk
-- **Purpose**: Individual segments from ASR, scenes from CUT, etc.
-- **Content**: Raw transcription or detection results
-- **Example**:
-```json
-{
- "chunk_id": "asr_0001",
- "chunk_type": "sentence",
- "text_content": "Hello world",
- "parent_chunk_id": "story_asr_0000"
-}
-```
-
-## Embedding Strategy
-
-### For Vector Search
-
-When embedding chunks for vector search, we combine **parent description + child content** to provide both context and detail.
-
-#### Parent Chunk Embedding
-```
-embedding_text = f"Summary: {parent.text_content}
-Children: {child_text_1}. {child_text_2}. {child_text_3}..."
-```
-
-**Prefix**: `search_document:` (for documents in Qdrant)
-
-**Example**:
-```
-search_document: Summary: A man enters a building. He walks down a hallway.
-Children: Hello, how are you? I'm fine thank you. The weather is nice today.
-```
-
-#### Child Chunk Embedding
-```
-embedding_text = f"[{child.chunk_type}] {child.text_content}
-Parent: {parent.description}"
-```
-
-**Prefix**: `search_document:`
-
-**Example**:
-```
-search_document: [sentence] Hello, how are you?
-Parent: A man enters a building. He walks down a hallway.
-```
-
-### For BM25 Text Search
-
-BM25 operates on raw text with PostgreSQL full-text search.
-
-- **Index**: `search_vector` (TSVECTOR) on `chunks.text_content`
-- **Search**: Uses `ts_rank_cd()` for ranking
-
-## Hybrid Search Ranking
-
-Combined score = `(vector_score * 0.7) + (bm25_score * 0.3)`
-
-### Why 0.7/0.3?
-
-| Weight | Vector | BM25 |
-|--------|--------|------|
-| Pros | Semantic similarity | Exact keyword match |
-| Cons | May miss specific terms | No semantic understanding |
-| Best for | Thematic queries | Fact lookup |
-
-## Query Patterns
-
-### Thematic Query ("What are the main themes?")
-- Use higher `vector_weight` (0.8-0.9)
-- Vector search finds semantically similar content
-
-### Fact Lookup ("Who said X?")
-- Use higher `bm25_weight` (0.5-0.7)
-- BM25 finds exact matches
-
-### Balanced ("Tell me about scene 5")
-- Use default 0.7/0.3
-
-## Implementation
-
-### Embedding Generation
-```rust
-fn build_embedding_text(chunk: &Chunk, parent_text: Option<&str>) -> String {
- match chunk.chunk_type {
- ChunkType::Story => {
- format!(
- "Summary: {}\nChildren: {}",
- chunk.text_content,
- get_children_text(chunk)
- )
- }
- _ => {
- format!(
- "[{}] {}\nParent: {}",
- chunk.chunk_type.as_str(),
- chunk.text_content,
- parent_text.unwrap_or("N/A")
- )
- }
- }
-}
-```
-
-### Storage
-- Parent chunks stored with their `child_chunk_ids`
-- Child chunks reference `parent_chunk_id`
-- Both stored in PostgreSQL with full-text index
-- Vectors stored in Qdrant
-
-## Example Flow
-
-1. **Story Processing** generates parent-child hierarchy
-2. **Embedding** creates vector for each chunk
-3. **Storage** saves to PostgreSQL + Qdrant
-4. **Search** retrieves using hybrid search
-5. **Results** include both parent context and child details
-
-## Best Practices
-
-1. **Chunk Size**: 5 child chunks per parent (configurable)
-2. **Text Length**: Keep embeddings under 512 tokens
-3. **Parent Description**: Include temporal markers (timestamps)
-4. **Child Content**: Preserve original transcription
-
-## Future Enhancements
-
-- [ ] GraphRAG integration for relationship traversal
-- [ ] Cross-chunk entity linking
-- [ ] Temporal graph building
diff --git a/docs_v1.0/ARCHITECTURE/PLAYGROUND_BINARY_IMPLEMENTATION.md b/docs_v1.0/ARCHITECTURE/PLAYGROUND_BINARY_IMPLEMENTATION.md
deleted file mode 100644
index 4f0bc2c..0000000
--- a/docs_v1.0/ARCHITECTURE/PLAYGROUND_BINARY_IMPLEMENTATION.md
+++ /dev/null
@@ -1,392 +0,0 @@
-# Playground Binary Implementation Plan
-
-| Item | Content |
-|------|---------|
-| Author | Warren |
-| Created | 2026-03-23 |
-| Document Version | V1.0 |
-
----
-
-## Version History
-
-| Version | Date | Purpose | Operator | Tool/Model |
-|---------|------|---------|----------|------------|
-| V1.0 | 2026-03-23 | Create implementation plan | Warren | OpenCode |
-
----
-
-## Overview
-
-Create separate `momentry_playground` binary with distinct configuration from `momentry` (production).
-
-| Aspect | Production (`momentry`) | Development (`momentry_playground`) |
-|--------|------------------------|-------------------------------------|
-| **Port** | 3002 | 3003 |
-| **Redis Prefix** | `momentry:` | `momentry_dev:` |
-| **Worker** | Enabled | Disabled |
-| **Purpose** | Production deployment | Testing/Development |
-
----
-
-## Files to Modify
-
-```
-Files Changed: 6 files (+1 new)
-├── src/core/config.rs ← Add server_port(), redis_key_prefix()
-├── src/core/db/redis_client.rs ← Replace hardcoded prefixes
-├── src/core/cache/redis_cache.rs ← Use configurable prefix
-├── src/main.rs ← Update CLI defaults
-├── src/playground.rs ← NEW: Development binary
-├── Cargo.toml ← Add new binary
-└── .env.development ← NEW: Dev environment config
-```
-
----
-
-## Implementation Steps
-
-### Step 1: Update `src/core/config.rs`
-
-Add after line 51 (after `MEDIA_BASE_URL`):
-
-```rust
-pub static SERVER_PORT: Lazy = Lazy::new(|| {
- env::var("MOMENTRY_SERVER_PORT")
- .unwrap_or_else(|_| "3002".to_string())
- .parse()
- .unwrap_or(3002)
-});
-
-pub static REDIS_KEY_PREFIX: Lazy = Lazy::new(|| {
- env::var("MOMENTRY_REDIS_PREFIX")
- .unwrap_or_else(|_| "momentry:".to_string())
-});
-```
-
----
-
-### Step 2: Update `src/core/db/redis_client.rs`
-
-Replace all hardcoded `momentry:` prefixes with configurable prefix.
-
-**Import at top:**
-```rust
-use crate::core::config::REDIS_KEY_PREFIX;
-```
-
-**Pattern for each method:**
-```rust
-let prefix = REDIS_KEY_PREFIX.as_str();
-let key = format!("{}job:{}", prefix, uuid);
-```
-
-**Affected lines:**
-
-| Line | Key Pattern |
-|------|-------------|
-| 47 | `job:{uuid}` |
-| 81, 109 | `job:{uuid}:processor:{processor}` |
-| 136, 146 | `progress:{uuid}` |
-| 172 | `jobs:active` |
-| 179 | `jobs:active` → `jobs:completed` |
-| 187 | `jobs:active` → `jobs:failed` |
-| 194 | `jobs:active` |
-| 201, 208 | `health:momentry_core` |
-| 214 | `monitor:job:{uuid}` |
-| 242, 300 | `errors:{uuid}` |
-| 258, 281 | `anomaly:alerts`, `anomaly:key:{key_id}` |
-| 317, 346, 364, 392, 397 | `worker:job:{uuid}...` |
-| 406, 410 | `worker:job:*` |
-
----
-
-### Step 3: Update `src/core/cache/redis_cache.rs`
-
-**Import:**
-```rust
-use crate::core::config::REDIS_KEY_PREFIX;
-```
-
-**Replace line 10:**
-```rust
-// Remove: const KEY_PREFIX: &str = "momentry:cache:";
-```
-
-**Update `prefixed_key` method (line 24):**
-```rust
-fn prefixed_key(&self, key: &str) -> String {
- format!("{}cache:{}", REDIS_KEY_PREFIX.as_str(), key)
-}
-```
-
-**Update tests (lines 161-162):**
-```rust
-#[test]
-fn test_prefixed_key() {
- // Note: This test will use the configured prefix
- let cache = RedisCache::new().unwrap();
- // With default prefix "momentry:"
- assert_eq!(cache.prefixed_key("test"), "momentry:cache:test");
- assert_eq!(cache.prefixed_key("video:abc"), "momentry:cache:video:abc");
-}
-```
-
----
-
-### Step 4: Update `src/main.rs`
-
-**Change CLI defaults (Lines 691-695):**
-
-```rust
-// Before:
-#[arg(long, default_value = "3000")]
-port: u16,
-
-// After:
-#[arg(long)]
-port: Option,
-```
-
-**Update Server match arm (around line 2398):**
-
-```rust
-Commands::Server { host, port } => {
- let port = port.unwrap_or_else(|| *crate::core::config::SERVER_PORT);
- momentry_core::api::start_server(&host, port).await?;
- Ok(())
-}
-```
-
-**Update Redis key usage (Line 1098):**
-
-```rust
-// Before:
-let key = format!("momentry:job:{}:processor:{}", uuid, processor);
-
-// After:
-let key = format!(
- "{}job:{}:processor:{}",
- crate::core::config::REDIS_KEY_PREFIX.as_str(),
- uuid,
- processor
-);
-```
-
----
-
-### Step 5: Create `src/playground.rs`
-
-```rust
-use anyhow::{Context, Result};
-use clap::{Parser, Subcommand};
-// ... same imports as main.rs ...
-
-fn main() -> Result<()> {
- // Load development environment first
- dotenv::from_filename(".env.development").ok();
-
- tracing_subscriber::fmt::init();
- tracing::info!("Starting momentry_playground (development binary)");
- tracing::info!("Port: {}", *momentry_core::core::config::SERVER_PORT);
- tracing::info!("Redis prefix: {}", *momentry_core::core::config::REDIS_KEY_PREFIX);
-
- let cli = Cli::parse();
- // ... rest identical to main.rs ...
-}
-```
-
----
-
-### Step 6: Update `Cargo.toml`
-
-**Add after line 90:**
-
-```toml
-[[bin]]
-name = "momentry_playground"
-path = "src/playground.rs"
-```
-
-**Add dependency (if not present):**
-
-```toml
-dotenv = "0.15"
-```
-
----
-
-### Step 7: Create `.env.development`
-
-```bash
-# Development Environment Configuration
-# Used by: momentry_playground binary
-
-# Server Configuration
-MOMENTRY_SERVER_PORT=3003
-MOMENTRY_REDIS_PREFIX=momentry_dev:
-
-# Worker Configuration (disabled for development)
-MOMENTRY_WORKER_ENABLED=false
-MOMENTRY_MAX_CONCURRENT=1
-MOMENTRY_POLL_INTERVAL=10
-
-# Database (can use separate dev database)
-DATABASE_URL=postgres://accusys@localhost:5432/momentry
-MONGODB_URL=mongodb://accusys:Test3200Test3200@localhost:27017/admin
-
-# Redis
-REDIS_URL=redis://:accusys@localhost:6379
-```
-
----
-
-### Step 8: Update `.env` (Production)
-
-Add these lines:
-
-```bash
-# Production Environment Configuration
-# Used by: momentry binary
-
-# Server Configuration
-MOMENTRY_SERVER_PORT=3002
-MOMENTRY_REDIS_PREFIX=momentry:
-
-# Worker Configuration
-MOMENTRY_WORKER_ENABLED=true
-MOMENTRY_MAX_CONCURRENT=2
-MOMENTRY_POLL_INTERVAL=5
-```
-
----
-
-## Testing Checklist
-
-### 1. Build and Run Production Binary
-
-```bash
-cargo build --release --bin momentry
-cargo run --bin momentry -- server
-# Expected: Listening on http://127.0.0.1:3002
-
-cargo run --bin momentry -- worker
-# Expected: Worker started with momentry: prefix
-```
-
-### 2. Build and Run Development Binary
-
-```bash
-cargo build --bin momentry_playground
-cargo run --bin momentry_playground -- server
-# Expected: Listening on http://127.0.0.1:3003
-```
-
-### 3. Verify Redis Key Isolation
-
-```bash
-# Production data
-redis-cli KEYS "momentry:*"
-# Development data
-redis-cli KEYS "momentry_dev:*"
-# Should be separate
-```
-
-### 4. Run Both Simultaneously
-
-```bash
-# Terminal 1: Production
-cargo run --bin momentry -- server
-
-# Terminal 2: Development
-cargo run --bin momentry_playground -- server
-
-# Both should run without port conflicts
-```
-
-### 5. Unit Tests
-
-```bash
-cargo test --lib
-# All tests should pass
-```
-
----
-
-## Redis Key Structure
-
-### Production (`momentry:`)
-
-```
-momentry:job:{uuid} # Job status
-momentry:job:{uuid}:processor:{name} # Processor progress
-momentry:progress:{uuid} # Progress pub/sub
-momentry:jobs:active # Active job set
-momentry:jobs:completed # Completed job set
-momentry:jobs:failed # Failed job set
-momentry:health:momentry_core # Health status
-momentry:cache:{key} # Cache entries
-momentry:worker:job:{uuid} # Worker job
-momentry:worker:job:{uuid}:processor:{name}
-```
-
-### Development (`momentry_dev:`)
-
-```
-momentry_dev:job:{uuid}
-momentry_dev:job:{uuid}:processor:{name}
-momentry_dev:progress:{uuid}
-momentry_dev:jobs:active
-momentry_dev:jobs:completed
-momentry_dev:jobs:failed
-momentry_dev:health:momentry_core
-momentry_dev:cache:{key}
-momentry_dev:worker:job:{uuid}
-momentry_dev:worker:job:{uuid}:processor:{name}
-```
-
----
-
-## Potential Issues & Solutions
-
-| Issue | Solution |
-|-------|----------|
-| `dotenv` crate not in dependencies | Add to Cargo.toml |
-| Tests use hardcoded prefix | Update tests to use config, or use `#[cfg(test)]` defaults |
-| Worker starts in playground | Check `MOMENTRY_WORKER_ENABLED=false` in `.env.development` |
-| Port already in use | Graceful error message with suggestion to use `--port` flag |
-| Mixed data in Redis | Ensure prefix is loaded before any Redis operations |
-
----
-
-## Files Summary
-
-| File | Lines Changed | Purpose |
-|------|---------------|---------|
-| `src/core/config.rs` | +15 | Add SERVER_PORT and REDIS_KEY_PREFIX |
-| `src/core/db/redis_client.rs` | ~50 | Replace hardcoded prefixes |
-| `src/core/cache/redis_cache.rs` | ~10 | Use configurable prefix |
-| `src/main.rs` | ~15 | Update CLI defaults, Redis key usage |
-| `src/playground.rs` | NEW (~2800) | Development binary |
-| `Cargo.toml` | +4 | Add binary definition |
-| `.env.development` | NEW (~20) | Development environment |
-
-**Total**: ~60 lines modified + ~2800 lines new file
-
----
-
-## Reference Documents
-
-| Document | Purpose |
-|----------|---------|
-| `docs/SERVICES.md` | Port allocations |
-| `docs/MOMENTRY_CORE_REDIS_KEYS.md` | Redis key design |
-| `AGENTS.md` | Code style and conventions |
-
----
-
-## Version History
-
-| Version | Date | Author | Changes |
-|---------|------|--------|---------|
-| 1.0 | 2025-03-25 | OpenCode | Initial implementation plan |
diff --git a/docs_v1.0/ARCHITECTURE/ROOT_API_KEY_ARCHITECTURE.md b/docs_v1.0/ARCHITECTURE/ROOT_API_KEY_ARCHITECTURE.md
deleted file mode 100644
index ff0a4d1..0000000
--- a/docs_v1.0/ARCHITECTURE/ROOT_API_KEY_ARCHITECTURE.md
+++ /dev/null
@@ -1,195 +0,0 @@
-# API Key Management System Architecture
-
-## System Overview
-
-```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│ API Key Management System │
-├─────────────────────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
-│ │ CLI │ │ HTTP API │ │ Service │ │ External │ │
-│ │ Layer │────▶│ Layer │────▶│ Layer │────▶│ Services │ │
-│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
-│ │ │ │ │ │
-│ │ │ │ │ │
-│ ▼ ▼ ▼ ▼ │
-│ ┌─────────────────────────────────────────────────────────────────────────┐ │
-│ │ Core Modules │ │
-│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
-│ │ │ Service │ │Validator│ │ Anomaly │ │Rotation │ │ Cleanup │ │ │
-│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
-│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
-│ │ │ Webhook │ │Encrypt │ │Blacklist│ │ Report │ │ Error │ │ │
-│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
-│ └─────────────────────────────────────────────────────────────────────────┘ │
-│ │ │ │ │
-│ ▼ ▼ ▼ │
-│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
-│ │ PostgreSQL │ │ Redis │ │ External │ │
-│ │ (Storage) │ │ (Cache) │ │ (Gitea/n8n)│ │
-│ └─────────────┘ └─────────────┘ └─────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────────────────────┘
-```
-
-## Module Dependencies
-
-```
- ┌──────────────┐
- │ models.rs │
- │ (Types) │
- └──────┬───────┘
- │
- ┌──────────────────┼──────────────────┐
- │ │ │
- ▼ ▼ ▼
-┌───────────────┐ ┌───────────────┐ ┌───────────────┐
-│ service.rs │ │ error.rs │ │ validator.rs │
-│ (Core CRUD) │ │ (Errors) │ │ (Cache+Rate) │
-└───────┬───────┘ └───────────────┘ └───────────────┘
- │
- │ ┌───────────────────────────────┐
- │ │ │
- ▼ ▼ ▼
-┌───────────────┐ ┌───────────────┐ ┌───────────────┐
-│ anomaly.rs │ │ rotation.rs │ │ blacklist.rs │
-│ (Detection) │ │ (Rotation) │ │ (IP Block) │
-└───────────────┘ └───────────────┘ └───────────────┘
-```
-
-## Request Flow
-
-```
-Client Request
- │
- ▼
-┌─────────────┐
-│ CLI/API │
-└──────┬──────┘
- │
- ▼
-┌─────────────┐ ┌─────────────┐
-│ Rate Limit │────▶│ IP Blacklist│
-│ Check │ │ Check │
-└──────┬──────┘ └──────┬──────┘
- │ │
- └─────────┬─────────┘
- │
- ▼
- ┌───────────────┐
- │ Hash API Key │
- └───────┬───────┘
- │
- ▼
- ┌───────────────┐ ┌───────────────┐
- │ Cache Lookup │────▶│ PostgreSQL │
- └───────┬───────┘ │ Lookup │
- │ └───────┬───────┘
- │ │
- └──────────┬──────────┘
- │
- ▼
- ┌───────────────┐
- │ Validate │
- │ (Status, │
- │ Expiry) │
- └───────┬───────┘
- │
- ┌─────────────┼─────────────┐
- │ │ │
- ▼ ▼ ▼
- ┌──────────┐ ┌──────────┐ ┌──────────┐
- │ Valid │ │ Invalid │ │ Error │
- │ Response│ │ Response │ │ Response │
- └──────────┘ └──────────┘ └──────────┘
-```
-
-## Database Schema
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ PostgreSQL │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────────┐ ┌─────────────────┐ │
-│ │ api_keys │ │ api_key_audit_ │ │
-│ ├─────────────────┤ │ log │ │
-│ │ id │ ├─────────────────┤ │
-│ │ key_id │─────▶│ id │ │
-│ │ key_hash │ │ key_id (FK) │ │
-│ │ name │ │ action │ │
-│ │ key_type │ │ ip_address │ │
-│ │ status │ │ details │ │
-│ │ expires_at │ └─────────────────┘ │
-│ │ ... │ │
-│ └─────────────────┘ ┌─────────────────┐ │
-│ │ api_key_anomalies│ │
-│ ┌─────────────────┐ ├─────────────────┤ │
-│ │ gitea_tokens │ │ id │ │
-│ ├─────────────────┤ │ key_id (FK) │ │
-│ │ id │ │ anomaly_type │ │
-│ │ gitea_token_id │ │ severity │ │
-│ │ token_name │ │ details │ │
-│ │ scopes │ └─────────────────┘ │
-│ └─────────────────┘ │
-│ │
-│ ┌─────────────────┐ │
-│ │ n8n_api_keys │ │
-│ ├─────────────────┤ │
-│ │ id │ │
-│ │ n8n_key_id │ │
-│ │ label │ │
-│ └─────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## External Integrations
-
-```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│ External Integrations │
-├─────────────────────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
-│ │ Gitea │ │ n8n │ │ Webhook │ │
-│ ├─────────────────┤ ├─────────────────┤ ├─────────────────┤ │
-│ │ • Create Token │ │ • Create API Key│ │ • Key Created │ │
-│ │ • List Tokens │ │ • List API Keys │ │ • Key Revoked │ │
-│ │ • Delete Token │ │ • Delete API Key│ │ • Anomaly │ │
-│ │ • Verify Token │ │ • Verify │ │ • Rate Limited │ │
-│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────────────────────┘
-```
-
-## Security Layers
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Security Layers │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ Layer 1: Network │
-│ ┌─────────────────────────────────────────────────────────┐ │
-│ │ • IP Blacklist │ │
-│ │ • Rate Limiting │ │
-│ └─────────────────────────────────────────────────────────┘ │
-│ │
-│ Layer 2: Authentication │
-│ ┌─────────────────────────────────────────────────────────┐ │
-│ │ • API Key Hash (SHA256) │ │
-│ │ • Constant-time Comparison │ │
-│ │ • Key Validation (Status, Expiry) │ │
-│ └─────────────────────────────────────────────────────────┘ │
-│ │
-│ Layer 3: Monitoring │
-│ ┌─────────────────────────────────────────────────────────┐ │
-│ │ • Anomaly Detection │ │
-│ │ • Audit Logging (Encrypted) │ │
-│ │ • Webhook Notifications │ │
-│ └─────────────────────────────────────────────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
diff --git a/docs_v1.0/ARCHITECTURE/ROOT_API_WORKFLOW_WORDPRESS_N8N.md b/docs_v1.0/ARCHITECTURE/ROOT_API_WORKFLOW_WORDPRESS_N8N.md
deleted file mode 100644
index 44d40e4..0000000
--- a/docs_v1.0/ARCHITECTURE/ROOT_API_WORKFLOW_WORDPRESS_N8N.md
+++ /dev/null
@@ -1,461 +0,0 @@
-# Momentry API 使用流程
-
-> **目標**: 從影片上傳到搜尋的完整流程
-> **適用**: WordPress / n8n 整合
-> **版本**: V1.0 | **日期**: 2026-03-25
-
----
-
-## 流程總覽
-
-```
-┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
-│ 1. 上傳 │ → │ 2. 註冊 │ → │ 3. 確認 │ → │ 4. 處理 │ → │ 5. 搜尋 │
-│ SFTPGo │ │ 自動完成 │ │ UUID │ │ 查詢進度 │ │ 測試 │
-└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
-```
-
----
-
-## Step 1: 上傳影片
-
-### 方式 A: SFTP 上傳（推薦）
-
-```bash
-# 連線資訊
-主機: sftpgo.momentry.ddns.net
-連接埠: 2022
-用戶名: demo
-密碼: demopassword123
-```
-
-使用 FileZilla 或 SFTP 客戶端上傳到 `/` 目錄
-
-### 方式 B: SFTP 命令列
-
-```bash
-sshpass -p "demopassword123" sftp -P 2022 demo@sftpgo.momentry.ddns.net
-```
-
-上傳後確認檔案在 SFTPGo 中的位置
-
----
-
-## Step 2: 自動註冊
-
-上傳後，系統會自動：
-1. 偵測新檔案
-2. 計算 UUID（SHA256）
-3. 建立資料庫記錄
-
-**無需手動操作**
-
----
-
-## Step 3: 確認註冊成功
-
-### 查詢所有影片
-
-```bash
-curl -s -H "X-API-Key: YOUR_API_KEY" \
- "https://api.momentry.ddns.net/api/v1/videos" | jq '.videos | length'
-```
-
-### 查詢特定檔案
-
-```bash
-curl -s -H "X-API-Key: YOUR_API_KEY" \
- "https://api.momentry.ddns.net/api/v1/videos" | jq '.videos[] | select(.file_name | contains("你的檔案名"))'
-```
-
-### 預期回應
-
-```json
-{
- "uuid": "952f5854b9febad1",
- "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/你的檔案.mp4",
- "file_name": "你的檔案.mp4",
- "duration": 123.45,
- "width": 1920,
- "height": 1080
-}
-```
-
-**確認要點**:
-- ✅ UUID 已產生（16位 hex）
-- ✅ `file_path` 正確
-- ✅ `duration` > 0
-
----
-
-## Step 4: 查詢處理進度
-
-### 取得任務 UUID
-
-```bash
-# 從影片資訊取得 job_id
-curl -s -H "X-API-Key: YOUR_API_KEY" \
- "https://api.momentry.ddns.net/api/v1/videos" | \
- jq '.videos[] | select(.file_name == "你的檔案.mp4") | {uuid, job_id}'
-```
-
-### 查詢任務狀態
-
-```bash
-curl -s -H "X-API-Key: YOUR_API_KEY" \
- "https://api.momentry.ddns.net/api/v1/jobs/{uuid}"
-```
-
-### 任務狀態說明
-
-| status | 說明 | 動作 |
-|--------|------|------|
-| `pending` | 等待處理 | 等待中 |
-| `processing` | 處理中 | 繼續輪詢 |
-| `completed` | 已完成 | 可進入 Step 5 |
-| `failed` | 處理失敗 | 檢查錯誤 |
-
-### n8n 輪詢範例
-
-```javascript
-// n8n Workflow: 檢查處理狀態
-const jobUuid = $input.item.json.job_uuid;
-
-const response = await fetch(
- `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`,
- {
- headers: {
- "X-API-Key": "YOUR_API_KEY"
- }
- }
-);
-
-const job = await response.json();
-
-// 狀態檢查
-if (job.status === 'completed') {
- return [{ json: { done: true, file_uuid: job.file_uuid } }];
-} else {
- return [{ json: { done: false, status: job.status } }];
-}
-```
-
----
-
-## Step 5: 搜尋測試
-
-處理完成後，資料會入庫到向量資料庫，可進行搜尋測試。
-
-### 測試向量搜尋
-
-```bash
-curl -s -X POST "https://api.momentry.ddns.net/api/v1/search" \
- -H "X-API-Key: YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "query": "測試關鍵字",
- "limit": 5
- }'
-```
-
-### 取得分段（Chunk）內容
-
-搜尋結果會返回影片分段（Chunk），包含可播放的時間軸資訊：
-
-```json
-{
- "results": [
- {
- "uuid": "39567a0eb16f39fd",
- "chunk_id": "sentence_1471",
- "chunk_type": "sentence",
- "start_time": 5309.08,
- "end_time": 5311.08,
- "text": "influenced by a vital way,",
- "score": 0.68
- }
- ]
-}
-```
-
-**Chunk 欄位說明**:
-| 欄位 | 說明 |
-|------|------|
-| `uuid` | 影片 UUID（用於取得影片網址） |
-| `chunk_id` | 分段 ID |
-| `chunk_type` | 分段類型（sentence/cut/time/trace/story） |
-| `start_time` | 開始時間（秒） |
-| `end_time` | 結束時間（秒） |
-| `text` | 語音內容文字 |
-| `score` | 相似度分數（0-1） |
-
-### 播放分段
-
-取得 Chunk 後可組合成播放網址：
-
-```
-影片網址?start={start_time}&end={end_time}
-```
-
-範例：
-```
-https://wp.momentry.ddns.net/video.mp4?start=5309.08&end=5311.08
-```
-
----
-
-## 完整 n8n Workflow 範例
-
-```
-┌──────────────┐
-│ 觸發 (定時) │
-└──────┬───────┘
- ▼
-┌──────────────┐ ┌──────────────┐
-│ 查詢影片 │────►│ 比對新檔案 │
-│ /videos │ │ │
-└──────┬───────┘ └──────────────┘
- │ │
- ▼ ▼
-┌──────────────┐ ┌──────────────┐
-│ 等待處理 │◄────│ 輪詢任務狀態 │
-│ /jobs/:uuid │ │ /jobs/:uuid │
-└──────┬───────┘ └──────────────┘
- │
- ▼ (completed)
-┌──────────────┐
-│ 搜尋測試 │
-│ /search │
-└──────────────┘
-```
-
----
-
-## 快速參考
-
-| 步驟 | API | 用途 |
-|------|-----|------|
-| 查詢影片 | `GET /api/v1/videos` | 確認上傳成功 |
-| 查詢任務 | `GET /api/v1/jobs/:uuid` | 查看處理進度 |
-| 搜尋內容 | `POST /api/v1/search` | 測試搜尋功能 |
-
----
-
-## WordPress PHP 範例
-
-### 基本設定
-
-```php
- $method,
- 'headers' => [
- 'X-API-Key' => self::API_KEY,
- 'Content-Type' => 'application/json',
- ],
- 'timeout' => 30,
- ];
-
- if ($data !== null) {
- $args['body'] = json_encode($data);
- }
-
- $response = wp_remote_request($url, $args);
-
- if (is_wp_error($response)) {
- throw new Exception($response->get_error_message());
- }
-
- return json_decode(wp_remote_retrieve_body($response), true);
- }
-
- public static function getVideos(): array {
- return self::request('GET', '/api/v1/videos');
- }
-
- public static function getVideo(string $uuid): array {
- return self::request('GET', "/api/v1/videos/{$uuid}");
- }
-
- public static function getJob(string $uuid): array {
- return self::request('GET', "/api/v1/jobs/{$uuid}");
- }
-
- public static function search(string $query, int $topK = 5): array {
- return self::request('POST', '/api/v1/search', [
- 'query' => $query,
- 'top_k' => $topK,
- ]);
- }
-}
-```
-
-### Step 3: 確認註冊成功
-
-```php
- '',
- 'limit' => 10,
- ], $atts);
-
- if (empty($atts['query'])) {
- return '請輸入搜尋關鍵字
';
- }
-
- try {
- $results = Momentry_API::search($atts['query'], $atts['limit']);
-
- if (empty($results['results'])) {
- return '找不到相關結果
';
- }
-
- $html = '';
- $html .= '
搜尋結果: ' . esc_html($atts['query']) . '
';
- $html .= '
';
-
- foreach ($results['results'] as $result) {
- $file_uuid = $result['uuid'];
- $start = $result['start_time'] ?? 0;
- $end = $result['end_time'] ?? 0;
- $text = $result['text'] ?? '無文字描述';
-
- $html .= '- ';
- $html .= '';
- $html .= '播放 ' . $start . 's - ' . $end . 's';
- $html .= '';
- $html .= '
';
- $html .= '相似度: ' . round($result['score'] * 100) . '%';
- $html .= '
';
- $html .= esc_html($text);
- $html .= ' ';
- }
-
- $html .= '
搜尋服務暫時無法使用
';
- }
-});
-```
-
-**使用方式**:
-```html
-[momentry_search query="關鍵字" limit="5"]
-```
-
----
-
-## 完整 n8n Workflow 範例
-
-```
-┌──────────────┐
-│ 觸發 (定時) │
-└──────┬───────┘
- ▼
-┌──────────────┐ ┌──────────────┐
-│ 查詢影片 │────►│ 比對新檔案 │
-│ /videos │ │ │
-└──────┬───────┘ └──────────────┘
- │ │
- ▼ ▼
-┌──────────────┐ ┌──────────────┐
-│ 等待處理 │◄────│ 輪詢任務狀態 │
-│ /jobs/:uuid │ │ /jobs/:uuid │
-└──────┬───────┘ └──────────────┘
- │
- ▼ (completed)
-┌──────────────┐
-│ 搜尋測試 │
-│ /search │
-└──────────────┘
-```
-
----
-
-**注意**:
-- 處理時間視影片長度而定（1分鐘影片約需 2-5 分鐘處理）
-- 大量影片時建議分批上傳
-
----
-
-## 附錄：版本歷史
-
-| 版本 | 日期 | 內容 | 操作人 |
-|------|------|------|--------|
-| V1.0 | 2026-03-25 | 初版建立 | OpenCode |
-| V1.1 | 2026-03-25 | 新增 Chunk 取得與播放說明、Shortcode 範例 | OpenCode |
-| V1.2 | 2026-03-25 | 修正 SFTPGo 主機名稱為 sftpgo.momentry.ddns.net | OpenCode |
diff --git a/docs_v1.0/ARCHITECTURE/ROOT_ARCHITECTURE_EVALUATION.md b/docs_v1.0/ARCHITECTURE/ROOT_ARCHITECTURE_EVALUATION.md
deleted file mode 100644
index ca95826..0000000
--- a/docs_v1.0/ARCHITECTURE/ROOT_ARCHITECTURE_EVALUATION.md
+++ /dev/null
@@ -1,331 +0,0 @@
-# 架構優化待評估事項
-
-| 項目 | 內容 |
-|------|------|
-| 建立者 | OpenCode |
-| 建立時間 | 2026-03-21 |
-| 文件版本 | V1.0 |
-
----
-
-## 版本歷史
-
-| 版本 | 日期 | 目的 | 操作人 |
-|------|------|------|--------|
-| V1.0 | 2026-03-21 | 創建文件 | OpenCode |
-| V1.1 | 2026-03-22 | 新增 TigerGraph/GraphRAG 說故事評估 | OpenCode |
-
----
-
-## 架構優化項目
-
-### 1. PostgreSQL → Redis 故障轉移
-
-**說明**: 當 PostgreSQL 不可用時，降級到 Redis 作為臨時存儲
-
-**複雜度**: 中
-
-**影響範圍**:
-- `src/core/db/postgres_db.rs`
-- `src/core/db/redis_client.rs`
-
-**風險**:
-- 數據一致性問題
-- 需要定義轉移策略
-
-**優先級**: 待評估
-
----
-
-### 2. 連接池監控
-
-**說明**: 添加 PostgreSQL 和 Redis 連接池指標到 Prometheus
-
-**複雜度**: 低
-
-**影響範圍**:
-- `src/core/db/postgres_db.rs`
-- `src/core/db/redis_client.rs`
-- `src/api/` (新增 metrics endpoint)
-
-**風險**: 低
-
-**優先級**: 待評估
-
----
-
-### 3. Processor 重試機制
-
-**說明**: 當 processor 失敗時自動重試
-
-**複雜度**: 中
-
-**影響範圍**:
-- `src/core/processor/executor.rs` (新增 `run_with_retry` 方法)
-- `src/core/processor/mod.rs` (導出 `RetryConfig`)
-
-**風險**:
-- 無限重試風險 → 已通過 `max_attempts` 控制
-- 需要指數退避 → 已實現
-
-**優先級**: ✅ 已完成 (2026-03-21)
-
-**實作內容**:
-- `RetryConfig` 結構體 (可配置重試次數、初始延遲、最大延遲、退避倍數)
-- `run_with_retry()` 方法 (自動重試 + 指數退避)
-- 單元測試覆蓋
-
-**使用範例**:
-```rust
-use crate::core::processor::{PythonExecutor, RetryConfig};
-
-let executor = PythonExecutor::new()?;
-let config = RetryConfig::new(3).with_delay(1000).with_max_delay(30000);
-
-executor.run_with_retry(
- "asr_processor.py",
- &["--input", "/path/to/video"],
- Some(&uuid),
- "asr",
- Some(Duration::from_secs(3600)),
- Some(config),
-).await?;
-```
-
----
-
-### 4. PyO3 整合
-
-**說明**: Python/Rust 直接調用，移除子進程調用
-
-**複雜度**: 高
-
-**影響範圍**:
-- `src/core/processor/executor.rs` (重寫)
-- Python 模組 (修改為可直接 import)
-
-**風險**:
-- Python GIL 問題
-- 依賴版本兼容性
-- 需要大量重寫
-
-**優先級**: 低 (長期目標)
-
----
-
-### 5. HTTP 健康端點
-
-**說明**: 添加 `/health` API 用於外部監控
-
-**複雜度**: 低
-
-**影響範圍**:
-- `src/api/server.rs` (新增路由)
-
-**風險**: 低
-
-**優先級**: ✅ 已完成 (2026-03-21)
-
-**實作內容**:
-- `GET /health` - 基本健康檢查 (status, version, uptime)
-- `GET /health/detailed` - 詳細健康檢查 (PostgreSQL, Redis, Qdrant 狀態和延遲)
-
----
-
-### 6. Gitea Actions CI/CD
-
-**說明**: 配置 Gitea Actions 自動化 CI/CD，在合併前執行檢查
-
-**複雜度**: 中
-
-**影響範圍**:
-- `.gitea/workflows/` (新增 workflow 文件)
-
-**優點**:
-- 強制執行檢查，無法跳過
-- 跨設備一致
-- PR 審查前自動檢查
-
-**風險**: 低
-
-**優先級**: 待評估
-
----
-
-### 7. Commit Message Lint
-
-**說明**: 規範化提交訊息格式 (Conventional Commits)
-
-**複雜度**: 低
-
-**影響範圍**:
-- `.git/hooks/commit-msg` (新增 hook)
-- `~/dotfiles/hooks/commit-msg`
-
-**風險**: 低
-
-**優先級**: ✅ 已完成 (2026-03-21)
-
-**實作內容**:
-- 驗證格式: `(): `
-- 有效類型: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
-- 警告: 第一行超過 72 字符
-
-**範例**:
-```
-feat(api): add health check endpoint
-fix(db): resolve connection pool issue
-docs: update README
-```
-
----
-
-### 8. 自動化安裝腳本
-
-**說明**: 創建腳本一次安裝所有開發工具
-
-**複雜度**: 低
-
-**影響範圍**:
-- `scripts/install-dev-tools.sh` (新增)
-
-**風險**: 低
-
-**優先級**: 待評估
-
----
-
-## 評估標準
-
-| 標準 | 說明 |
-|------|------|
-| 業務價值 | 對用戶有何幫助 |
-| 技術風險 | 實現難度和潛在問題 |
-| 維護成本 | 未來維護負擔 |
-| 依賴性 | 對其他系統的影響 |
-
----
-
-## 評估記錄
-
-| 項目 | 評估日期 | 決策 | 原因 |
-|------|----------|------|------|
-| PostgreSQL → Redis 故障轉移 | 待評估 | - | - |
-| 連接池監控 | 待評估 | - | - |
-| Processor 重試機制 | 2026-03-21 | 已完成 | - |
-| PyO3 整合 | 待評估 | - | - |
-| HTTP 健康端點 | 2026-03-21 | 已完成 | - |
-| Gitea Actions CI/CD | 待評估 | - | - |
-| Commit Message Lint | 2026-03-21 | 已完成 | - |
-| 自動化安裝腳本 | 待評估 | - | - |
-
----
-
-## 9. TigerGraph / Knowledge Graph 圖譜說故事
-
-**說明**: 使用知識圖譜 (Knowledge Graph) 增強視頻敘事 (Storytelling) 和 RAG 檢索
-
-**複雜度**: 高
-
-**研究來源**:
-- [TigerGraph Agentic GraphRAG](https://www.tigergraph.com/blog/agentic-graphrag-gives-ai-a-playbook-for-smarter-retrieval/) (2025-12-15)
-- [TigerGraph GraphRAG GitHub](https://github.com/tigergraph/graphrag) (v1.2.0, 2026-03-11)
-- [GraphRAG in 2026: Practitioner's Guide](https://medium.com/graph-praxis/graph-rag-in-2026-a-practitioners-guide-to-what-actually-works-dca4962e7517) (2026-02-22)
-- [GraphRAG Complete Guide](https://medium.com/@brian-curry-research/graphrag-the-complete-guide-to-graph-powered-retrieval-augmented-generation-eeb58a6bb4d1) (2026-02-11)
-
-### 核心概念
-
-| 概念 | 說明 |
-|------|------|
-| **GraphRAG** | 結合知識圖譜與 RAG，比傳統向量檢索更智能 |
-| **知識圖譜** | 實體 (Entity) + 關係 (Relationship) 的結構化表示 |
-| **多跳推理** | Multi-hop traversal，可連接多個相關節點 |
-| **混合檢索** | Graph traversal + Vector similarity 結合 |
-
-### 對 Momentry 的潛在應用
-
-```
-視頻場景 → 實體識別 → 關係建立 → 故事圖譜
- ↓ ↓ ↓ ↓
- CUT [人物, 物品, 動作] [誰做了什麼, 什麼導致什麼] [敘事鏈]
-```
-
-**1. 敘事圖譜構建 (Narrative Graph)**
-- 從 Story/Chunks 模組提取實體
-- 建立場景之間的因果關係
-- 追蹤角色互動和情節發展
-
-**2. 故事檢索增強**
-```python
-# 現有: Parent-child chunks
-parent_chunk: "場景描述"
-child_chunks: [詳細內容]
-
-# 加入圖譜:
-場景A --led_to--> 場景B
-角色X --interacted_with--> 角色Y
-主題Y --related_to--> 主題Z
-```
-
-**3. 查詢模式**
-
-| 查詢類型 | 傳統 RAG | GraphRAG |
-|----------|----------|----------|
-| 事實查找 | ✅ "這個場景在說什麼" | ✅ |
-| 主題推理 | ❌ "這個視頻的主要情節" | ✅ Global search |
-| 多跳關係 | ❌ | ✅ "A導致B，B導致C" |
-| 可解釋性 | ❌ | ✅ 關係路徑可追溯 |
-
-### 實作方案
-
-**方案 A: TigerGraph Cloud (推薦)**
-- ✅ 原生 Graph + Vector 混合查詢
-- ✅ GraphRAG 官方支援
-- ✅ 200GB 免費額度
-- ❌ 雲端依賴，延遲敏感場景需考慮
-
-**方案 B: Neo4j + Qdrant**
-- ✅ 成熟開源生態
-- ✅ LangChain/LlamaIndex 整合
-- ❌ 需要維護兩個系統
-
-**方案 C: 自建混合架構**
-- PostgreSQL + Neo4j (或Typesense)
-- 利用現有 BM25 + 向量檢索基礎
-- ❌ 開發成本高
-
-### 技術棧整合建議
-
-```rust
-// 現有架構
-Vector Search (Qdrant) ← BM25 (PostgreSQL)
-
-// 加入 GraphRAG
-Knowledge Graph (TigerGraph/Neo4j)
- ↓
- 混合檢索 ← Vector + Graph traversal
-```
-
-### 優先級: 待評估
-
-**考慮因素**:
-- 用戶是否需要複雜的故事情節查詢？
-- 實體識別 (NER) 成本是否可以接受？
-- 與現有 BM25 + Vector 混合搜索的比較優勢？
-
----
-
-## 10. LazyGraphRAG / FastGraphRAG 成本優化
-
-**說明**: GraphRAG 索引成本高昂，LazyGraphRAG 推遲圖譜構建到查詢時
-
-**來源**: [GraphRAG in 2026](https://medium.com/graph-praxis/graph-rag-in-2026-a-practitioners-guide-to-what-actually-works-dca4962e7517)
-
-**Microsoft GraphRAG 問題**: $33K 索引大型數據集
-
-**替代方案**:
-- **LazyGraphRAG**: 按需構建，查詢時再建立子圖
-- **FastGraphRAG**: 優化索引管道，10-90% 成本節省
-- **HippoRAG**: 使用 Personalised PageRank 優化遍歷
-
-**優先級**: 待評估 (作為 GraphRAG 的一部分)
diff --git a/docs_v1.0/ARCHITECTURE/ROOT_CACHE_ARCHITECTURE_PLAN.md b/docs_v1.0/ARCHITECTURE/ROOT_CACHE_ARCHITECTURE_PLAN.md
deleted file mode 100644
index 7d9001e..0000000
--- a/docs_v1.0/ARCHITECTURE/ROOT_CACHE_ARCHITECTURE_PLAN.md
+++ /dev/null
@@ -1,1106 +0,0 @@
-# Momentry Core 分層緩存架構開發計劃
-
-**版本**: V1.0
-**日期**: 2026-03-24
-**目標**: 實現 Redis + MongoDB 分層緩存架構
-
----
-
-## 1. 概述
-
-### 1.1 目標
-
-在 Momentry Core 中實現分層緩存架構：
-- **小型、高頻存取** → Redis
-- **中型、查詢導向** → MongoDB
-
-### 1.2 現有架構
-
-| 組件 | 現況 | 用途 |
-|------|------|------|
-| Redis | ✅ 已實現 | Job 進度、Pub/Sub、健康檢查、API Key（Moka） |
-| MongoDB | ⚠️ HTTP 驅動 | 僅用於存儲 chunks |
-| 內存緩存 | Moka + RwLock | API Key、視頻記錄 |
-
-### 1.3 目標架構
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ Layer 1: Redis Cache │
-│ ┌─────────────────┐ ┌─────────────────┐ │
-│ │ Job Progress │ │ Health Status │ │
-│ │ (已有) │ │ (新增) │ │
-│ └─────────────────┘ └─────────────────┘ │
-│ ┌─────────────────┐ │
-│ │ Video Meta 熱讀 │ │
-│ │ (新增) │ │
-│ └─────────────────┘ │
-└─────────────────────────────────────────────────────────────┘
- │ Cache Miss
- ▼
-┌─────────────────────────────────────────────────────────────┐
-│ Layer 2: MongoDB Cache │
-│ Collection: momento.cache │
-│ ┌─────────────────┐ ┌─────────────────┐ │
-│ │ Videos List │ │ Search Results │ │
-│ │ (新增) │ │ (新增) │ │
-│ └─────────────────┘ └─────────────────┘ │
-│ ┌─────────────────┐ ┌─────────────────┐ │
-│ │ Hybrid Search │ │ N8n Search │ │
-│ │ (新增) │ │ (新增) │ │
-│ └─────────────────┘ └─────────────────┘ │
-└─────────────────────────────────────────────────────────────┘
- │ Cache Miss
- ▼
-┌─────────────────────────────────────────────────────────────┐
-│ PostgreSQL / Qdrant │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 2. 技術棧變更
-
-### 2.1 Cargo.toml 變更
-
-```toml
-# 現有
-mongodb = { version = "2", features = ["tokio-sync"] }
-
-# 變更為
-mongodb = { version = "2", features = ["tokio-comp", "bson"] }
-```
-
-**說明**：
-- `tokio-comp`: 啟用 async tokio runtime 支持
-- `bson`: BSON 序列化/反序列化支持
-
----
-
-## 3. 新增模組結構
-
-### 3.1 目錄結構
-
-```
-src/core/
-├── cache/ # 新增目錄
-│ ├── mod.rs # 模組入口
-│ ├── mongo_cache.rs # MongoDB 緩存實現
-│ ├── redis_cache.rs # Redis 緩存封裝
-│ ├── keys.rs # Cache Key 工具函數
-│ └── config.rs # 緩存配置
-├── db/
-│ ├── mod.rs # 新增 cache 導出
-│ ├── mongodb_db.rs # 重構為原生驅動
-│ └── ...
-└── ...
-```
-
-### 3.2 文件清單
-
-| 操作 | 文件路徑 | 說明 |
-|------|----------|------|
-| 新增 | `src/core/cache/mod.rs` | Cache 模組入口 |
-| 新增 | `src/core/cache/mongo_cache.rs` | MongoDB 緩存實現 |
-| 新增 | `src/core/cache/redis_cache.rs` | Redis 緩存封裝 |
-| 新增 | `src/core/cache/keys.rs` | Cache Key 工具函數 |
-| 新增 | `src/core/cache/config.rs` | 緩存配置 |
-| 修改 | `src/core/db/mongodb_db.rs` | 改用原生 `mongodb` crate |
-| 修改 | `src/core/db/mod.rs` | 導出新增模組 |
-| 修改 | `src/api/server.rs` | 整合緩存到 API handlers |
-| 修改 | `src/core/config.rs` | 添加 MongoDB 緩存配置 |
-| 修改 | `Cargo.toml` | 更新 mongodb feature |
-
----
-
-## 4. 配置設計
-
-### 4.1 環境變數
-
-```bash
-# MongoDB Cache 配置 (新增)
-MONGODB_URL=mongodb://localhost:27017
-MONGODB_CACHE_ENABLED=true
-MONGODB_CACHE_TTL_VIDEOS=300 # 5 分鐘
-MONGODB_CACHE_TTL_SEARCH=300 # 5 分鐘
-MONGODB_CACHE_TTL_HYBRID_SEARCH=600 # 10 分鐘
-MONGODB_CACHE_TTL_VIDEO_META=3600 # 60 分鐘
-
-# Redis Cache 配置 (新增)
-REDIS_CACHE_TTL_HEALTH=30 # 30 秒
-REDIS_CACHE_TTL_VIDEO_META=3600 # 60 分鐘
-```
-
-### 4.2 config.rs 結構
-
-```rust
-// src/core/config.rs
-
-pub mod cache {
- use super::*;
-
- pub static MONGODB_URL: Lazy = Lazy::new(|| {
- env::var("MONGODB_URL")
- .unwrap_or_else(|_| "mongodb://localhost:27017".to_string())
- });
-
- pub static MONGODB_CACHE_ENABLED: Lazy = Lazy::new(|| {
- env::var("MONGODB_CACHE_ENABLED")
- .unwrap_or_else(|_| "true".to_string())
- .parse()
- .unwrap_or(true)
- });
-
- pub static MONGODB_CACHE_TTL_VIDEOS: Lazy = Lazy::new(|| {
- env::var("MONGODB_CACHE_TTL_VIDEOS")
- .unwrap_or_else(|_| "300".to_string())
- .parse()
- .unwrap_or(300)
- });
-
- pub static MONGODB_CACHE_TTL_SEARCH: Lazy = Lazy::new(|| {
- env::var("MONGODB_CACHE_TTL_SEARCH")
- .unwrap_or_else(|_| "300".to_string())
- .parse()
- .unwrap_or(300)
- });
-
- pub static MONGODB_CACHE_TTL_HYBRID_SEARCH: Lazy = Lazy::new(|| {
- env::var("MONGODB_CACHE_TTL_HYBRID_SEARCH")
- .unwrap_or_else(|_| "600".to_string())
- .parse()
- .unwrap_or(600)
- });
-
- pub static MONGODB_CACHE_TTL_VIDEO_META: Lazy = Lazy::new(|| {
- env::var("MONGODB_CACHE_TTL_VIDEO_META")
- .unwrap_or_else(|_| "3600".to_string())
- .parse()
- .unwrap_or(3600)
- });
-
- pub static REDIS_CACHE_TTL_HEALTH: Lazy = Lazy::new(|| {
- env::var("REDIS_CACHE_TTL_HEALTH")
- .unwrap_or_else(|_| "30".to_string())
- .parse()
- .unwrap_or(30)
- });
-}
-```
-
----
-
-## 5. MongoDB Cache 設計
-
-### 5.1 Collection 結構
-
-```javascript
-// Collection: momento.cache
-// Database: momento
-
-{
- "_id": ObjectId("..."),
- "key": "videos:list:page=1:limit=20",
- "value": {
- "videos": [
- {
- "uuid": "xxx",
- "file_path": "/path/to/video.mp4",
- "file_name": "video.mp4",
- "duration": 120.5,
- "width": 1920,
- "height": 1080
- }
- ]
- },
- "category": "videos",
- "created_at": ISODate("2026-03-24T08:00:00Z"),
- "expires_at": ISODate("2026-03-24T08:05:00Z"),
- "hit_count": 0,
- "last_access": ISODate("2026-03-24T08:00:00Z")
-}
-```
-
-### 5.2 索引設計
-
-```javascript
-// TTL Index - 自動刪除過期文檔
-db.momento.cache.createIndex(
- { "expires_at": 1 },
- { expireAfterSeconds: 0 }
-)
-
-// 唯一索引 - 防止重複 key
-db.momento.cache.createIndex(
- { "key": 1 },
- { unique: true }
-)
-
-// 分類索引 - 批量失效用
-db.momento.cache.createIndex({ "category": 1 })
-```
-
-### 5.3 CacheEntry 結構
-
-```rust
-// src/core/cache/mongo_cache.rs
-
-use serde::{Deserialize, Serialize};
-use bson::oid::ObjectId;
-use chrono::{DateTime, Utc};
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct CacheEntry {
- #[serde(rename = "_id", skip_serializing_if = "Option::is_none")]
- pub id: Option,
-
- pub key: String,
- pub value: serde_json::Value,
- pub category: String,
-
- pub created_at: DateTime,
- pub expires_at: DateTime,
-
- #[serde(default)]
- pub hit_count: i64,
-
- #[serde(default)]
- pub last_access: DateTime,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct CacheConfig {
- pub enabled: bool,
- pub ttl_videos: u64,
- pub ttl_search: u64,
- pub ttl_hybrid_search: u64,
- pub ttl_video_meta: u64,
-}
-```
-
----
-
-## 6. API 緩存策略
-
-### 6.1 緩存矩陣
-
-| API | Cache Layer | Key Pattern | TTL | 失效時機 |
-|-----|-------------|-------------|-----|----------|
-| `GET /api/v1/videos` | MongoDB | `videos:list:page={p}:limit={l}` | 5min | register/delete |
-| `GET /api/v1/lookup` | Redis | `momentry:cache:video:{uuid}` | 60min | update/delete |
-| `POST /api/v1/search` | MongoDB | `search:{hash}` | 5min | vectorize |
-| `POST /api/v1/search/hybrid` | MongoDB | `search:hybrid:{hash}` | 10min | vectorize |
-| `POST /api/v1/n8n/search` | MongoDB | `search:n8n:{hash}` | 5min | vectorize |
-| `GET /health` | Redis | `momentry:cache:health` | 30s | - |
-
-### 6.2 Cache Key 命名規範
-
-```rust
-// src/core/cache/keys.rs
-
-pub mod keys {
- pub const CATEGORY_VIDEOS: &str = "videos";
- pub const CATEGORY_SEARCH: &str = "search";
- pub const CATEGORY_HYBRID_SEARCH: &str = "hybrid_search";
- pub const CATEGORY_N8N_SEARCH: &str = "n8n_search";
- pub const CATEGORY_VIDEO_META: &str = "video_meta";
- pub const CATEGORY_HEALTH: &str = "health";
-
- pub fn videos_list(page: usize, limit: usize) -> String {
- format!("videos:list:page={}:limit={}", page, limit)
- }
-
- pub fn video_meta(uuid: &str) -> String {
- format!("video:{}", uuid)
- }
-
- pub fn search(query_hash: &str) -> String {
- format!("search:{}", query_hash)
- }
-
- pub fn hybrid_search(query_hash: &str) -> String {
- format!("search:hybrid:{}", query_hash)
- }
-
- pub fn n8n_search(query_hash: &str) -> String {
- format!("search:n8n:{}", query_hash)
- }
-
- pub fn health() -> String {
- "health:basic".to_string()
- }
-}
-```
-
----
-
-## 7. 實現細節
-
-### 7.1 MongoCache 實現
-
-```rust
-// src/core/cache/mongo_cache.rs
-
-use anyhow::Result;
-use bson::{doc, oid::ObjectId};
-use chrono::{Duration, Utc};
-use mongodb::{Client, Collection, Database};
-use serde::{de::DeserializeOwned, Serialize};
-use std::sync::Arc;
-
-use super::keys;
-use super::config::CacheConfig;
-use crate::core::config::cache as cache_config;
-
-#[derive(Clone)]
-pub struct MongoCache {
- client: Client,
- db: Database,
- collection: Collection,
- config: CacheConfig,
-}
-
-impl MongoCache {
- pub async fn init() -> Result {
- let uri = cache_config::MONGODB_URL.as_str();
- let client = Client::uri(uri).await?;
- let db = client.database("momento");
- let collection = db.collection::("cache");
-
- let config = CacheConfig {
- enabled: *cache_config::MONGODB_CACHE_ENABLED,
- ttl_videos: *cache_config::MONGODB_CACHE_TTL_VIDEOS,
- ttl_search: *cache_config::MONGODB_CACHE_TTL_SEARCH,
- ttl_hybrid_search: *cache_config::MONGODB_CACHE_TTL_HYBRID_SEARCH,
- ttl_video_meta: *cache_config::MONGODB_CACHE_TTL_VIDEO_META,
- };
-
- // Ensure indexes exist
- Self::ensure_indexes(&collection).await?;
-
- Ok(Self {
- client,
- db,
- collection,
- config,
- })
- }
-
- async fn ensure_indexes(collection: &Collection) -> Result<()> {
- use mongodb::IndexModel;
-
- // TTL Index
- let ttl_index = IndexModel::builder()
- .keys(doc! { "expires_at": 1 })
- .options(
- mongodb::options::IndexOptions::builder()
- .expire_after(std::time::Duration::from_secs(0))
- .build()
- )
- .build();
-
- // Unique key index
- let key_index = IndexModel::builder()
- .keys(doc! { "key": 1 })
- .options(
- mongodb::options::IndexOptions::builder()
- .unique(true)
- .build()
- )
- .build();
-
- collection.create_indexes([ttl_index, key_index]).await?;
- Ok(())
- }
-
- pub async fn get(&self, key: &str) -> Result> {
- if !self.config.enabled {
- return Ok(None);
- }
-
- let filter = doc! { "key": key };
- let result = self.collection.find_one(filter).await?;
-
- if let Some(entry) = result {
- // Update hit count and last_access
- let update = doc! {
- "$inc": { "hit_count": 1 },
- "$set": { "last_access": Utc::now() }
- };
- self.collection.update_one(doc! { "_id": entry.id }, update).await?;
-
- // Deserialize value
- let value = serde_json::from_value(entry.value)?;
- Ok(Some(value))
- } else {
- Ok(None)
- }
- }
-
- pub async fn set(&self, key: &str, value: &T, ttl_secs: u64, category: &str) -> Result<()> {
- if !self.config.enabled {
- return Ok(());
- }
-
- let now = Utc::now();
- let expires_at = now + Duration::seconds(ttl_secs as i64);
- let json_value = serde_json::to_value(value)?;
-
- let entry = CacheEntry {
- id: None,
- key: key.to_string(),
- value: json_value,
- category: category.to_string(),
- created_at: now,
- expires_at,
- hit_count: 0,
- last_access: now,
- };
-
- let filter = doc! { "key": key };
- let update = doc! {
- "$set": {
- "value": &entry.value,
- "category": &entry.category,
- "expires_at": entry.expires_at,
- "last_access": entry.last_access,
- },
- "$setOnInsert": {
- "key": &entry.key,
- "created_at": entry.created_at,
- "hit_count": 0i64,
- }
- };
-
- self.collection.update_one(filter, update).await?;
- Ok(())
- }
-
- pub async fn invalidate_category(&self, category: &str) -> Result {
- if !self.config.enabled {
- return Ok(0);
- }
-
- let result = self.collection.delete_many(doc! { "category": category }).await?;
- Ok(result.deleted_count)
- }
-
- pub async fn invalidate_prefix(&self, prefix: &str) -> Result {
- if !self.config.enabled {
- return Ok(0);
- }
-
- let filter = doc! { "key": { "$regex": &format!("^{}", prefix) } };
- let result = self.collection.delete_many(filter).await?;
- Ok(result.deleted_count)
- }
-
- pub async fn get_or_fetch(&self, key: &str, ttl_secs: u64, category: &str, fetcher: F) -> Result
- where
- F: FnOnce() -> Fut,
- Fut: std::future::Future