feat: add migrations, test scripts, and utility tools

- Add database migrations (006-028) for face recognition, identity, file_uuid - Add test scripts for ASR, face, search, processing - Add portal frontend (Tauri) - Add config, benchmark, and monitoring utilities - Add model checkpoints and pretrained model references
2026-04-30 15:11:53 +08:00
parent 4d75b2e251
commit b54c2def30
192 changed files with 46721 additions and 0 deletions
--- a/release/RELEASE_INFO.txt
+++ b/release/RELEASE_INFO.txt
@@ -0,0 +1,29 @@
+Release: v1.0.0
+Date: Thu Apr 30 2026
+Git Commit: 5e896fb509547972b28a8a3eea5357ee36d93831
+Binary: target/release/momentry
+Port: 3002 (production)
+
+## Package Contents
+- Source code (excludes .git, target, node_modules)
+- Dev output data (output_dev/)
+- Architecture documentation (docs_v1.0/)
+- API documentation (API_DOCUMENTATION.md)
+- Public schema backup (public_schema_v1.0.0.sql)
+- Dev data backup (dev_data_v1.0.0.sql)
+
+## Key Changes
+- V4.0 architecture: Face → Identity direct binding
+- person_identities table removed
+- ASR PyAV decode fallback (v2.1)
+- Snapshot agent implementation
+- Complete API documentation
+
+## Deployment
+- Port 3002 (production)
+- Redis prefix: momentry:
+- Environment: .env
+
+## API Summary
+- 50+ endpoints across 7 categories
+- Health & Auth, Asset Management, Search, Video Details, Identity & Binding, Jobs & Rules, Stats & Config
--- a/release/RELEASE_SOP.md
+++ b/release/RELEASE_SOP.md
@@ -0,0 +1,235 @@
+# Release SOP: 先打包後部署
+
+**Version**: v1.0.0
+**Date**: 2026-04-30
+**Status**: Active
+
+---
+
+## 流程概覽
+
+```
+1. 預檢 (Pre-flight) → 2. 打包 (Package) → 3. Schema 同步 → 4. 部署 (Deploy) → 5. 驗證 (Verify)
+```
+
+---
+
+## Phase 1: 預檢 (Pre-flight Checks)
+
+### 1.1 服務檢查
+```bash
+bash scripts/release_preflight_check.sh
+```
+
+**檢查項目**：
+- PostgreSQL, Redis, MongoDB, Qdrant
+- Ollama (nomic-embed-text), llama-server (gemma4_e4b_q5)
+- ffmpeg, ffprobe, Python 3.11
+- SFTPGo
+- Disk space < 90%
+
+### 1.2 程式碼檢查
+```bash
+cargo clippy --lib && cargo test --lib && cargo fmt -- --check
+```
+
+### 1.3 Schema 版本檢查
+```bash
+# 檢查 public schema 是否有遺漏欄位
+psql -U accusys -d momentry -c "
+SELECT column_name FROM information_schema.columns 
+WHERE table_schema = 'public' AND table_name = 'videos' 
+AND column_name = 'parent_uuid';
+"
+```
+
+---
+
+## Phase 2: 打包 (Packaging)
+
+| 步驟 | 輸出 | 位置 |
+|------|------|------|
+| 2.1 建立 Release Tag | Git tag | `git tag -a v1.0.0` |
+| 2.2 備份 DB Schema | `public_schema_v1.0.0.sql` | `release/` |
+| 2.3 備份 DB Data | `dev_data_v1.0.0.sql` | `release/` |
+| 2.4 備份 API 文件 | `API_DOCUMENTATION.md` | `docs_v1.0/` |
+| 2.5 建立 Release 目錄 | 完整 release 結構 | `release/` |
+| 2.6 打包原始碼 | `momentry_core_v1.0.0_source.zip` | `release/` |
+| 2.7 打包 Dev Output | `output_json_v1.0.0.zip` | `release/` |
+| 2.8 打包架構文件 | `docs_v1.0_v1.0.0.zip` | `release/` |
+| 2.9 建立 Release Manifest | `RELEASE_INFO.txt` | `release/` |
+| 2.10 建立 Migration 腳本 | `migrate_public_schema_v4.sql` | `release/` |
+
+---
+
+## Phase 3: Schema 同步 (Schema Synchronization)
+
+**⚠️ 這是最容易被忽略的步驟！**
+
+### 3.1 檢查 Schema 差異
+```bash
+# 比較 public vs dev schema
+diff <(psql -U accusys -d momentry -c "\dt public.*" -t) \
+     <(psql -U accusys -d momentry -c "\dt dev.*" -t)
+```
+
+### 3.2 執行 Migration
+```bash
+# 備份當前 public schema
+pg_dump -U accusys -d momentry --schema=public > release/public_schema_backup_$(date +%Y%m%d_%H%M%S).sql
+
+# 執行 migration
+psql -U accusys -d momentry -f release/migrate_public_schema_v4.sql
+```
+
+### 3.3 驗證 Migration
+```bash
+# 檢查關鍵欄位
+psql -U accusys -d momentry -c "
+SELECT table_name, column_name 
+FROM information_schema.columns 
+WHERE table_schema = 'public' 
+AND column_name IN ('parent_uuid', 'summary_text', 'file_uuid', 'bbox')
+ORDER BY table_name, column_name;
+"
+```
+
+---
+
+## Phase 4: 部署 (Deployment)
+
+### 4.1 停止現有服務
+```bash
+sudo launchctl stop com.momentry.api
+sleep 2
+lsof -i :3002  # 確認 port 已釋放
+```
+
+### 4.2 備份現有 Binary
+```bash
+cp target/release/momentry release/momentry_v$(prev_version)_backup
+```
+
+### 4.3 建立新 Binary
+```bash
+cargo build --release --bin momentry
+cp target/release/momentry release/momentry_v$(version)
+```
+
+### 4.4 啟動服務
+```bash
+sudo launchctl start com.momentry.api
+sleep 3
+curl -s http://localhost:3002/health | jq .
+```
+
+---
+
+## Phase 5: 驗證 (Post-deployment Verification)
+
+### 5.1 健康檢查
+```bash
+curl -s http://localhost:3002/health | jq .
+curl -s http://localhost:3002/health/detailed | jq .
+curl -s http://localhost:3002/api/v1/stats/inference | jq .
+```
+
+### 5.2 API 測試
+```bash
+# 影片列表
+curl -s "http://localhost:3002/api/v1/videos?page=1&page_size=5" -H "X-API-Key: $API_KEY" | jq .count
+
+# 搜索功能
+curl -s -X POST http://localhost:3002/api/v1/search \
+  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
+  -d '{"query":"test","limit":5}' | jq .results | length
+
+# 身份列表
+curl -s "http://localhost:3002/api/v1/identities?page=1" -H "X-API-Key: $API_KEY" | jq .count
+```
+
+### 5.3 關鍵 Endpoint 檢查清單
+| Endpoint | 預期 | 實際 |
+|----------|------|------|
+| `GET /health` | 200 OK | |
+| `GET /health/detailed` | 200 OK, 4 services ok | |
+| `GET /api/v1/videos` | 200 OK, count > 0 | |
+| `GET /api/v1/identities` | 200 OK | |
+| `POST /api/v1/search` | 200 OK, results | |
+| `GET /api/v1/stats/ingest` | 200 OK | |
+| `GET /api/v1/videos/:uuid/details` | 200 OK | |
+| `GET /api/v1/faces/candidates` | 200 OK | |
+
+---
+
+## Phase 6: 清理 (Cleanup)
+
+### 6.1 更新 RELEASE_INFO.txt
+```bash
+# 記錄 git commit, binary hash, deployment time
+echo "Deployed: $(date)" >> release/RELEASE_INFO.txt
+echo "Commit: $(git rev-parse HEAD)" >> release/RELEASE_INFO.txt
+```
+
+### 6.2 建立 Release Tag
+```bash
+git tag -a v1.0.0 -m "Release v1.0.0 - V4.0 Architecture"
+git push origin v1.0.0
+```
+
+### 6.3 存檔 Release Package
+```bash
+mkdir -p ~/.momentry_snapshots/v1.0.0
+cp release/* ~/.momentry_snapshots/v1.0.0/
+```
+
+---
+
+## 常見問題
+
+### Q: Schema migration 失敗怎麼辦？
+A: 執行 rollback：
+```bash
+psql -U accusys -d momentry < release/public_schema_backup_YYYYMMDD_HHMMSS.sql
+```
+
+### Q: 服務啟動後 port 3002 仍被佔用？
+A: 使用 `sudo launchctl bootout gui/$(id -u)/com.momentry.api` 強制停止。
+
+### Q: API 回應 500 錯誤？
+A: 依序檢查：
+1. Schema 版本：`psql -U accusys -d momentry -c "\d public.videos" | grep parent_uuid`
+2. SQL 查詢欄位是否與 struct 匹配
+3. 檢查 server logs
+
+---
+
+## 經驗教訓 (Lessons Learned)
+
+### v1.0.0 Release 發現的問題
+
+1. **Schema 同步機制缺失**
+   - 問題：開發期間 public schema 沒有同步更新
+   - 影響：release binary 無法正常運行
+   - 修正：建立 migration 腳本，納入 SOP Phase 3
+
+2. **SQL 查詢欄位不完整**
+   - 問題：`search_videos` 的 `columns` 字串缺少 `parent_uuid`
+   - 影響：sqlx 映射失敗，所有 videos 相關 API 500 錯誤
+   - 修正：添加缺少的欄位，未來新增欄位時需同步更新 queries
+
+3. **Pre-flight 檢查不足**
+   - 問題：只檢查服務狀態，沒有檢查 schema 版本
+   - 修正：添加 schema 驗證步驟
+
+---
+
+## Release Checklist
+
+- [ ] Phase 1: 預檢通過 (services, code, schema)
+- [ ] Phase 2: 打包完成 (source, data, docs, binary)
+- [ ] Phase 3: Schema 同步完成且驗證通過
+- [ ] Phase 4: 部署完成，服務啟動正常
+- [ ] Phase 5: API 測試通過 (所有關鍵 endpoint)
+- [ ] Phase 6: 清理完成 (tag, archive, manifest)
+- [ ] Release report 已建立 (`release/RELEASE_TEST_REPORT.md`)
--- a/release/RELEASE_TEST_REPORT.md
+++ b/release/RELEASE_TEST_REPORT.md
@@ -0,0 +1,163 @@
+# Release v1.0.0 測試報告
+
+**測試日期**: 2026-04-30
+**Binary Build**: 2026-04-30 14:44:33
+**Port**: 3002
+**Schema**: public (已同步 V4.0)
+
+---
+
+## 測試結果摘要
+
+| # | Category | Endpoint | Status | 說明 |
+|---|----------|----------|--------|------|
+| 1 | Health | `GET /health` | ✅ PASS | 正常回應 |
+| 2 | Health | `GET /health/detailed` | ✅ PASS | 4 服務全部正常 |
+| 3 | Videos | `GET /api/v1/videos` | ✅ PASS | 20 筆影片 |
+| 4 | Stats | `GET /api/v1/stats/ingest` | ✅ PASS | 20 videos, 4018 chunks |
+| 5 | Identity | `GET /api/v1/identities` | ✅ PASS | 2 筆身份 |
+| 6 | Search | `POST /api/v1/search` | ✅ PASS | 3 筆結果 |
+| 7 | PreChunks | `GET /api/v1/videos/:uuid/pre_chunks` | ✅ PASS | 0 筆 (正常) |
+| 8 | Faces | `GET /api/v1/faces/candidates` | ✅ PASS | 78 筆候選 |
+| 9 | Details | `GET /api/v1/videos/:uuid/details` | ✅ PASS | chunk 正常 |
+| 10 | Stats | `GET /api/v1/stats/inference` | ✅ PASS | Ollama + llama-server OK |
+| 11 | Stats | `GET /api/v1/stats/sftpgo` | ✅ PASS | 103 檔案 |
+| 12 | Jobs | `GET /api/v1/jobs` | ✅ PASS | 9 筆工作 |
+
+**總結**: 12/12 通過 ✅
+
+---
+
+## 問題與修正
+
+### 問題 1: Schema 不同步 (計劃缺失)
+
+**根本原因**: 開發期間沒有建立 public schema 同步機制。
+
+**修正**:
+1. 建立 `migrate_public_v4_complete.sql` migration 腳本
+2. 新增 missing columns: `parent_uuid`, `summary_text`, `metadata_version`, `content_version`, `file_uuid`, `bbox`
+3. 新增 missing tables: `file_identities`, `pre_chunks` (已存在)
+
+### 問題 2: `parent_uuid` 欄位遺失於 SQL 查詢
+
+**根本原因**: `search_videos` 函式的 `columns` 字串缺少 `parent_uuid`，但 `VideoRow` struct 有該欄位，導致 sqlx 映射失敗。
+
+**修正**: 在 `src/core/db/postgres_db.rs` 的 `columns` 字串添加 `parent_uuid`。
+
+```rust
+// Before
+let columns = "id, file_uuid, ..., total_frames";
+
+// After
+let columns = "id, file_uuid, ..., total_frames, parent_uuid";
+```
+
+### 計劃缺失分析
+
+開發期間沒有明確的 schema 同步策略：
+
+1. **雙 schema 策略未定義**：`dev` schema 用於 playground (3003)，`public` schema 用於 production (3002)，但沒有明確規定何時同步。
+2. **開發集中在 dev schema**：所有新功能、處理器、API 都在 dev schema 上開發和測試。
+3. **沒有 migration 腳本**：V3.x → V4.0 的 schema 變更沒有自動化 migration 腳本。
+4. **release 前未檢查**：沒有檢查 public schema 是否符合程式碼預期的欄位結構。
+5. **測試隔離不足**：pre-flight check 只檢查服務狀態，沒有檢查 schema 版本。
+
+### 具體差異
+
+| Table | public (V3.x) 缺少 | dev (V4.0) 有 |
+|-------|-------------------|---------------|
+| videos | `parent_uuid` | ✅ |
+| chunks | `summary_text`, `metadata_version`, `content_version` | ✅ |
+| face_detections | `file_uuid` (用 `video_uuid`), `bbox` (用 x/y/width/height) | ✅ |
+
+---
+
+## 解決方案
+
+### 方案 A: 更新 .env（快速修復）
+```bash
+# 在 .env 中添加
+DATABASE_SCHEMA=dev
+```
+
+**效果**：Production binary 將連接 dev schema，該 schema 已符合 V4.0 結構。
+
+### 方案 B: Migration public schema（正式方案）
+執行 schema migration 將 public schema 更新為 V4.0 結構，然後再部署。
+
+---
+
+## Release Package 清單
+
+| 檔案 | 大小 | 狀態 |
+|------|------|------|
+| `momentry_core_v1.0.0_source.zip` | 5.9M | ✅ 已打包 |
+| `output_json_v1.0.0.zip` | 9.5M | ✅ 已打包 |
+| `docs_v1.0.zip` | 1.4M | ✅ 已打包 |
+| `dev_data_v1.0.0.sql` | 7.3M | ✅ 已打包 |
+| `public_schema_v1.0.0.sql` | 134K | ✅ 已打包 |
+| `momentry_v1.0.0` | 27M | ✅ 已建置 |
+| `momentry_v0_backup` | 26M | ✅ 已備份 |
+| `RELEASE_INFO.txt` | - | ✅ 已建立 |
+
+---
+
+## Pre-flight Check 結果
+
+| Service | Status |
+|---------|--------|
+| PostgreSQL | ✅ |
+| Redis | ✅ |
+| MongoDB | ✅ |
+| Qdrant | ✅ |
+| Ollama (nomic-embed-text) | ✅ |
+| llama-server (gemma4_e4b_q5) | ✅ |
+| ffmpeg/ffprobe | ✅ |
+| Python 3.11 | ✅ |
+| SFTPGo | ✅ |
+| Disk Usage (1%) | ✅ |
+
+**總結**: 16 passed, 0 failed, 1 warning (port 3002 in use)
+
+---
+
+## 建議動作
+
+1. ~~在 .env 添加 `DATABASE_SCHEMA=dev`~~ (已修正，不再需要)
+2. ~~執行 schema migration~~ (已完成)
+3. ~~修復 `parent_uuid` SQL 查詢~~ (已完成)
+4. ✅ **更新 Release SOP** - 添加 schema 同步為必要步驟
+5. ✅ **建立 migration 腳本** - `migrate_public_v4_complete.sql`
+6. **下次 release 前**：執行 `release_preflight_check.sh` 並確認 schema 版本
+
+---
+
+## Release Package 清單
+
+| 檔案 | 大小 | 狀態 |
+|------|------|------|
+| `momentry_core_v1.0.0_source.zip` | 5.9M | ✅ 已打包 |
+| `output_json_v1.0.0.zip` | 9.5M | ✅ 已打包 |
+| `docs_v1.0.zip` | 1.4M | ✅ 已打包 |
+| `dev_data_v1.0.0.sql` | 7.3M | ✅ 已打包 |
+| `public_schema_v1.0.0.sql` | 134K | ✅ 已打包 |
+| `momentry_v1.0.0` | 27M | ✅ 已建置 (含修正) |
+| `momentry_v0_backup` | 26M | ✅ 已備份 |
+| `migrate_public_v4_complete.sql` | - | ✅ 已建立 |
+| `RELEASE_INFO.txt` | - | ✅ 已建立 |
+| `RELEASE_SOP.md` | - | ✅ 已建立 |
+| `RELEASE_TEST_REPORT.md` | - | ✅ 已建立 |
+
+---
+
+## Release Checklist
+
+- [x] Phase 1: 預檢通過 (services, code)
+- [x] Phase 2: 打包完成 (source, data, docs, binary)
+- [x] Phase 3: Schema 同步完成且驗證通過
+- [x] Phase 4: 部署完成，服務啟動正常
+- [x] Phase 5: API 測試通過 (12/12 endpoints)
+- [x] Phase 6: 清理完成 (manifest, reports)
+- [x] Release SOP 已更新
+- [x] Lessons Learned 已記錄