feat: Phase 1 handover - schema migration, correction mechanism, API fixes

Schema changes: dev.chunks->dev.chunk, remove old_chunk_id/chunk_index Correction: asr-1.json format, generate/apply scripts API: 37/37 endpoints fixed and tested Docs: HANDOVER_V2.0.md for M4
2026-05-11 07:03:22 +08:00
parent ef894a44ad
commit 39ba5ddf76
147 changed files with 19843 additions and 3053 deletions
--- a/docs_v1.0/M4_workspace/2026-05-07_M4_M5_pipeline_division.md
+++ b/docs_v1.0/M4_workspace/2026-05-07_M4_M5_pipeline_division.md
--- a/docs_v1.0/M4_workspace/2026-05-07_M5_sync_ready.md
+++ b/docs_v1.0/M4_workspace/2026-05-07_M5_sync_ready.md
@@ -0,0 +1,34 @@
+# M5 通知：資料已可 sync
+
+## 已完成
+
+- Git 已初始化，docs 已 commit
+- M5 已產出 PostgreSQL dump（890MB）：`/tmp/momentry_3abeee81.sql`
+- Output JSON 已就緒：`/Users/accusys/momentry/output_dev/`
+- Qdrant face vectors：4873 points（512D）
+
+## M4 執行
+
+```bash
+# 1. 取得 DB dump
+scp accusys@192.168.110.201:/tmp/momentry_3abeee81.sql /tmp/
+
+# 2. 匯入 PostgreSQL
+psql -U accusys -d momentry -c "DROP SCHEMA IF EXISTS dev CASCADE; CREATE SCHEMA dev;"
+psql -U accusys -d momentry -f /tmp/momentry_3abeee81.sql
+
+# 3. 取得輸出檔
+rsync -av accusys@192.168.110.201:/Users/accusys/momentry/output_dev/ \
+  /Users/accusys/momentry/output/
+```
+
+## 待完成
+
+- 5W1H+ 仍在背景跑（~9h），完成後會自動 vectorize 到 Qdrant
+- 屆時會再做一次完整 sync，包含 text vectors
+- 詳細 sync 流程：`M5_workspace/2026-05-07_db_vector_sync_guide.md`
+
+## 現在 Portal 可以測
+
+DB sync 後，M4 可以直接 query PostgreSQL 和 Qdrant 開發 Portal，
+不需等 5W1H+ 完成。基本資料（chunks、faces、identities）都已就緒。
--- a/docs_v1.0/M4_workspace/2026-05-08_physical_feature_anomaly_experiment.md
+++ b/docs_v1.0/M4_workspace/2026-05-08_physical_feature_anomaly_experiment.md
@@ -0,0 +1,114 @@
+# 物理特徵異常分析實驗
+
+**影片**: Charade (1963), 5954s, 25fps
+**工具**: ffmpeg signalstats / silencedetect / volumedetect + PostgreSQL
+
+## 發現
+
+### 1. 黑畫面轉場 (t=170.72s)
+
+```
+signalstats: mean=[16, 128, 128], stdev=[0.0, 0.0, 0.0]
+```
+
+完全平坦的 black frame (Y=16 極暗, UV=128 中性色, stdev=0)。這是經典的 **fade-to-black** 場景轉場。
+
+### 2. 片頭 30 秒靜音
+
+連續 30 秒音量低於 -30dB，為片頭演職員表。
+
+### 3. 極低峰值音量
+
+| 指標 | Charade | 現代動作片 |
+|------|---------|-----------|
+| Max volume | -10.3 dB | > -3 dB |
+| 動態範圍 | 窄 | 寬 |
+| 爆炸/撞擊 | 無 | 頻繁 |
+
+### 4. 前五分鐘場景切換頻率
+
+13 次場景轉換，平均每 23 秒一次剪輯。1963 年電影的標準節奏。
+
+## ffmpeg 內建 Filter 一覽
+
+下列 filter 皆為 ffmpeg 內建，不需額外安裝函式庫，可直接從影片檔案提取物理特徵：
+
+### 視覺
+
+| Filter | 指令 | 產出資料 | 用途 |
+|--------|------|---------|------|
+| `signalstats` | `-vf signalstats` | Y/U/V mean, stdev, per-frame | 亮度、對比度、色偏 |
+| `scene` | `-vf select='gt(scene,X)'` | 場景轉換時間點 | 鏡頭切換偵測、剪輯節奏 |
+| `defect` | `-vf defect` | 影片缺陷偵測 | 髒點、條紋、壞幀 |
+| `histeq` | `-vf histeq` | 色階分布 | 過曝/不足分析 |
+| `gradfun` | `-vf gradfun` | 漸層帶狀偵測 | 壓縮品質 |
+| `frei0r=lightgraffiti` | `-vf frei0r=lightgraffiti` | 光源軌跡 | 燈光動態 |
+| `frei0r=pr0be` | `-vf frei0r=pr0be` | 色塊分析 | 主色調統計 |
+| `thumbnail` | `-vf thumbnail=n` | 代表性幀選取 | 自動生成縮圖 |
+| `fps` + `tblend` | `-vf tblend` | 幀間差異 | 運動量估算 |
+| `fieldmatch` | `-vf fieldmatch` | 交錯偵測 | 轉換 film/video |
+
+### 聽覺
+
+| Filter | 指令 | 產出資料 | 用途 |
+|--------|------|---------|------|
+| `silencedetect` | `-af silencedetect` | 靜音起點/終點/長度 | 對話留白、場景轉換 |
+| `volumedetect` | `-af volumedetect` | 音量分布、峰值 | 動態範圍、最大音量 |
+| `ebur128` | `-af ebur128` | 整合響度 (LUFS) | 廣播標準、情緒曲線 |
+| `astats` | `-af astats` | RMS、峰值、直流偏移 | 整體音訊品質 |
+| `dynaudnorm` | `-af dynaudnorm` | 動態範圍壓縮比 | 對話 vs 爆炸對比 |
+| `speechnorm` | `-af speechnorm` | 語音歸一化係數 | 對話清晰度 |
+| `anlmdn` | `-af anlmdn` | 雜訊殘留量 | 背景雜訊評估 |
+| `highpass` + `lowpass` | `-af highpass=f=200,lowpass=f=4000` | 頻段能量 | 低頻(動作) vs 中頻(對話) vs 高頻(環境) |
+
+### 運動
+
+| Filter | 指令 | 產出資料 | 用途 |
+|--------|------|---------|------|
+| `mestimate` / `flow` | `-vf flow` | 光流向量 (x, y 運動場) | 物體速度、鏡頭晃動 |
+| `deshake` | `-vf deshake` | 相機位移量 | 手持 vs 穩定鏡頭 |
+| `yadif` | `-vf yadif` | 去交錯比率 | 動態模糊程度 |
+
+### 組合範例：單一 ffmpeg 命令產出所有特徵
+
+```bash
+ffmpeg -i input.mp4 \
+  -vf "signalstats,select='gt(scene,0.4)',metadata=print" \
+  -af "ebur128=framelog=verbose,astats=metadata=1" \
+  -f null -
+```
+
+這條命令同時產出：亮度、對比度、場景轉換、響度、音訊統計。
+
+### 標準化 API 設計
+
+```json
+POST /api/v1/file/:file_uuid/physical/analyze
+{
+  "features": ["luminance", "scene", "loudness", "silence", "motion"],
+  "bin_sec": 60,
+  "time_range": [0, 5954]
+}
+```
+
+```json
+{
+  "luminance": [
+    {"t": 0, "Y": 51, "U": 134, "V": 124, "contrast": 23.7},
+    {"t": 60, "Y": 33, "U": 133, "V": 126, "contrast": 12.3}
+  ],
+  "scene_changes": [130.8, 170.72, 197.04, 198.6],
+  "loudness": [
+    {"t": 0, "integrated": -23.1, "range": 8.2},
+    {"t": 60, "integrated": -18.5, "range": 12.4}
+  ],
+  "silence": [
+    {"start": 0, "end": 29.9, "duration": 29.9},
+    {"start": 249.3, "end": 251.7, "duration": 2.4}
+  ]
+}
+```
+
+## 結論
+
+ffmpeg 內建 15+ 個 filter 可以直接從影片檔案提取物理特徵，不需要先經過 processor pipeline。這些資料可以標準化為時間序列 API，與現有的 trace/identity/search 系統正交。
--- a/docs_v1.0/M4_workspace/2026-05-08_release_V1.0.0.md
+++ b/docs_v1.0/M4_workspace/2026-05-08_release_V1.0.0.md
@@ -0,0 +1,21 @@
+# Release v1.0.0
+
+Tag: `v1.0.0` at `d8714aa`
+
+## 同步
+
+```bash
+cd momentry_docs && git pull && git checkout v1.0.0
+```
+
+## 資料
+
+| 檔案 | 位置 | 大小 |
+|------|------|------|
+| DB dump | M5:`/tmp/momentry_3abeee81.sql` | 890MB |
+| Qdrant face | M5:`/tmp/qdrant_face.json` | 30MB |
+
+## 已知
+
+- 5W1H+ 背景跑（明早完成）
+- Text vectors（momentry_dev_rule1）待明早完成後再 sync
--- a/docs_v1.0/M4_workspace/2026-05-08_standardize_list_pagination.md
+++ b/docs_v1.0/M4_workspace/2026-05-08_standardize_list_pagination.md
@@ -0,0 +1,62 @@
+# 標準化 List Endpoint 分頁參數
+
+## 現狀
+
+各 list endpoint 的分頁參數不一致：
+
+| Endpoint | 當前參數 | 問題 |
+|----------|---------|------|
+| `GET /api/v1/files` | `page`, `page_size` | ✅ 符合標準 |
+| `GET /api/v1/identities` | `page`, `page_size` | ✅ 符合標準 |
+| `GET /api/v1/faces/candidates` | `page`, `page_size` | ✅ 符合標準 |
+| `GET /api/v1/jobs` | `page`, `page_size` | ✅ 符合標準 |
+| `GET /api/v1/resources` | `page` only | ⚠️ 缺少 `page_size` |
+| `GET /api/v1/file/:uuid/trace/:trace_id/faces` | `limit`, `offset` | ✅ 有分頁但參數不同 |
+| `POST /api/v1/search/universal` | 混合 `limit`/`offset` + 無分頁 | ❌ 不一致 |
+| `POST /api/v1/file/:uuid/face_trace/sortby` | `limit` only | ❌ 無完整分頁 |
+| `POST /api/v1/search/smart` | `limit` only | ❌ 無完整分頁 |
+| `GET /api/v1/identity/:uuid/files` | `page`, `page_size` | ✅ 符合標準 |
+
+## 建議統一規格
+
+```json
+{
+  "page": 1,
+  "page_size": 20,
+  "limit": null
+}
+```
+
+| 參數 | 類型 | 預設 | 說明 |
+|------|------|------|------|
+| `page` | int | 1 | 頁碼 |
+| `page_size` | int | 20 | 每頁筆數 |
+| `limit` | int | null | 總筆數上限（高峰值場景使用，避免 DB 爆掉） |
+
+## Response 格式
+
+```json
+{
+  "success": true,
+  "data": [...],
+  "total": 100,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+## 受影響檔案
+
+| 檔案 | 說明 | 需修改 |
+|------|------|--------|
+| `src/api/universal_search.rs` | 搜尋 endpoint 混合 `limit`/`offset` | 改為 `page`/`page_size` + 選擇性 `limit` |
+| `src/api/trace_agent_api.rs` | `list_traces_sorted` 只有 `limit` | 加入 `page`、`page_size` |
+| `src/api/search.rs` | `smart_search` 只有 `limit` | 加入 `page`、`page_size` |
+| `src/api/identities.rs` | `list_resources` 只有 `page` | 加入 `page_size` |
+
+## 驗收標準
+
+1. 所有 list endpoint 都支援 `page` + `page_size`
+2. `limit` 作為獨立上限參數，與分頁共存
+3. Response 統一含 `total`, `page`, `page_size`
+4. 向後相容：舊參數 `limit`/`offset` 持續支援至少一個版本
--- a/docs_v1.0/M4_workspace/2026-05-09_M4_status_report.md
+++ b/docs_v1.0/M4_workspace/2026-05-09_M4_status_report.md
@@ -0,0 +1,92 @@
+# M4 Status Report — 2026-05-09
+
+## Overview
+
+M4 testing results and pending actions for M5.
+
+---
+
+## Completed
+
+### DB Sync (M4 → M5)
+| Item | Details |
+|------|---------|
+| Schema | dev → dev (pg_dump + restore) |
+| Videos | 37 (28 mp4 + 3 mov) |
+| Chunks | 14,330 total (incl. 3,710 converted .mov→.mp4) |
+| Face detections | 126,789 |
+| Identities | 2,810 |
+
+### Chunk Conversion (.mov → .mp4)
+- Script: `scripts/migrate_chunks_mov_to_mp4.py`
+- Source: `384b0ff44aaaa1f1` (.mov, 59.94fps, file_id=211)
+- Target: `3abeee81d94597629ed8cb943f182e94` (.mp4, 25fps, file_id=253)
+- 3,714 chunks converted, frame/time alignment verified (0 mismatches)
+- Verification script: `scripts/verify_chunk_migration.sql`
+
+### Portal Fixes (~30 issues)
+- ChunkDetailView API, IdentityDetailView thumbnail/person_id
+- SearchView "All Files", PersonsView search query
+- FilesView search input + status merge
+- VideoDetailView: bitrate NaN, stream index, trace await
+- Router: scrollBehavior, 404 page, Pipeline nav link
+- SettingsView: extracted ServiceStatusCard
+- FaceCandidatesView: thumbnail error handling
+- App.vue: ApiDemo dev-gated (localStorage devMode)
+- HomeView: alert() → inline statusMsg
+- SpaceTimeCube: uses backend `?dimension=3d` z_rel
+
+### Trace V5
+- Backend: `src/api/trace_agent_api.rs` — `?dimension=3d` returns `z_rel` from bbox area
+- Frontend: `portal/src/components/SpaceTimeCube.vue` — Three.js 3D cube rendering
+
+### Large Trace Video Fix
+- `src/api/media_api.rs` — `-vf` → `-filter_complex_script` to bypass ARG_MAX
+- Tested: trace #3128 (1109 detections) → 200 OK, 46s video
+
+### Docs Updated
+- `AGENTS.md`: V5 changelog, operation checklist
+- `TRACE_API_REFERENCE_V1.0.0.md`: dimension=3d param
+- `REFERENCE/DEMO_RUNNER_V1.0.0.md`: ask step type, voice control
+
+---
+
+## Issues Found on M5
+
+### 1. Worker Duplicate Spawn
+- 4 YOLO processes running simultaneously for same file_uuid
+- All writing to same `.yolo.json` → JSON corruption
+- Root cause: worker polls "pending" jobs but doesn't check if processor is already running
+- Needs locking mechanism (e.g., `processor_results.status = 'running'` check before spawn)
+
+### 2. ASR Data Loss
+- File: `aeed71342a899fe4b4c57b7d41bcb692.asr.json` (Charade .mp4)
+- Deleted by M4 during cleanup (mistake)
+- M5 needs to re-run ASR for this file_uuid
+- ASRX ✅ completed (1815 segments, 10 speakers, covers to 6772s)
+- Other processors ✅ all completed
+
+### 3. M4 output/ not synced to M5
+- M4 `output/` has 2523 JSON files (~3.8GB)
+- RELEASE_PLAN specifies rsync between machines
+- DB was synced but output JSON files were not
+- Pending: rsync M4 `output/` → M5 `output_dev/`
+
+---
+
+## Pending Actions for M5
+
+| # | Action | Details |
+|---|--------|---------|
+| 1 | Re-run ASR | file_uuid: `aeed71342a899fe4b4c57b7d41bcb692` |
+| 2 | Fix worker lock | Prevent duplicate spawn |
+| 3 | Sync M4 output/ | rsync to M5 output_dev/ |
+| 4 | Fix YOLO + face JSON | `16ab2c8c3...yolo.json`, `job_77_face_...json` corrupted |
+
+---
+
+## Reports in M4_workspace/
+| File | Content |
+|------|---------|
+| `2026-05-08_standardize_list_pagination.md` | Pagination standardization proposal |
+| `2026-05-09_singular_plural_api_review.md` | Singular/plural naming review (no changes needed) |
--- a/docs_v1.0/M4_workspace/2026-05-09_M5_design_ready.md
+++ b/docs_v1.0/M4_workspace/2026-05-09_M5_design_ready.md
@@ -0,0 +1,35 @@
+# M5 設計方案已備妥
+
+## 請 M4 查閱以下文件
+
+### 核心架構設計
+- `docs_v1.0/M5_workspace/RELEASE_PHASES.md`
+  1. momentry model vs core 架構
+  2. 三階段交付：v1(base) / v2 / v3
+  3. Wiki 機制（非傳統 RAG）
+  4. Object Identity 設計方向
+
+### Pipeline 改動（需手動 apply）
+- `docs_v1.0/M5_workspace/patch_executor.diff` → executor partial output 修復
+- `docs_v1.0/M5_workspace/patch_chunk.diff` → trace chunk ingestion
+- `docs_v1.0/M5_workspace/patch_search.diff` → SearchFilters 擴充
+- `docs_v1.0/M5_workspace/patch_worker_tkg.diff` → TKG builder 整合
+- `docs_v1.0/M5_workspace/patch_release_phases.diff` → 階段 release 打包
+- `docs_v1.0/M5_workspace/release_pack.py` → 自動打包 script
+
+### 協作規則
+- `docs/M4_M5_COLLABORATION_PROTOCOL.md` — 不可刪檔、不可覆蓋、不可跨域
+- `docs/M4_RELEASE_INCIDENT_2026-05-09.md` — 事故記錄
+
+## Apply 順序（M4 端）
+
+```bash
+cd /Users/accusys/momentry_core_0.1
+git apply docs_v1.0/M5_workspace/patch_executor.diff
+git apply docs_v1.0/M5_workspace/patch_chunk.diff
+git apply docs_v1.0/M5_workspace/patch_search.diff
+git apply docs_v1.0/M5_workspace/patch_worker_tkg.diff
+git apply docs_v1.0/M5_workspace/patch_release_phases.diff
+cp docs_v1.0/M5_workspace/release_pack.py scripts/release_pack.py
+cargo build --bin momentry_playground
+```
--- a/docs_v1.0/M4_workspace/2026-05-09_git_pull_instructions.md
+++ b/docs_v1.0/M4_workspace/2026-05-09_git_pull_instructions.md
@@ -0,0 +1,32 @@
+# M4 請執行 git pull
+
+## 步驟
+
+```bash
+cd /Users/accusys/momentry_core_0.1
+
+# 如果有未 commit 的 local 變更，先暫存
+git stash
+
+# 拉取 M5 的最新 commit
+git pull
+
+# 還原暫存的 local 變更
+git stash pop
+```
+
+## 這次 pull 會拿到的內容
+
+| Commit | 內容 |
+|--------|------|
+| `9f5afd1` | Worker file-existence check + backup 機制 |
+| | Executor partial output → `.json.partial` |
+| | `docs/M4_M5_COLLABORATION_PROTOCOL.md` **← 必讀** |
+| | `docs/M4_RELEASE_INCIDENT_2026-05-09.md` |
+
+## 重點提醒
+
+- **不要刪檔**：任何 `{uuid}.{processor}.*` 檔案不可刪
+- **不要覆蓋**：重跑前先 timestamp copy 備份
+- **不要跨域**：M4 操作 M4 機器，M5 操作 M5 機器
+- 檔案是 source of truth，不是 DB 也不是 Redis
--- a/docs_v1.0/M4_workspace/2026-05-09_singular_plural_api_review.md
+++ b/docs_v1.0/M4_workspace/2026-05-09_singular_plural_api_review.md
@@ -0,0 +1,31 @@
+# API Singular/Plural 命名審查
+
+## 結論：符合設計原則，無不一致
+
+根據 `docs_v1.0/STANDARDS/API_DESIGN_PRINCIPLES_V1.0.0.md`：
+
+| 用途 | 規則 | 範例 |
+|------|------|------|
+| Collection list | plural | `/files`, `/identities`, `/resources`, `/faces` |
+| Single resource action | singular | `/file/:uuid`, `/identity/:uuid` |
+| Action verb | singular path segment | `/resource/register`, `/identity/:uuid/bind` |
+
+## 逐項確認
+
+| Endpoint | 命名 | 判定 |
+|----------|------|:----:|
+| `GET /api/v1/files` | plural — collection list | ✅ |
+| `GET /api/v1/file/:file_uuid` | singular — single resource | ✅ |
+| `POST /api/v1/files/register` | plural collection + action verb | ✅ |
+| `GET /api/v1/files/scan` | plural collection + action verb | ✅ |
+| `POST /api/v1/file/:file_uuid/process` | singular + action verb | ✅ |
+| `GET /api/v1/file/:file_uuid/chunks` | singular + sub-collection | ✅ |
+| `GET /api/v1/identities` | plural — collection list | ✅ |
+| `GET /api/v1/identity/:identity_uuid` | singular — single resource | ✅ |
+| `POST /api/v1/identity/:identity_uuid/bind` | singular + action verb | ✅ |
+| `GET /api/v1/faces/candidates` | plural — sub-collection | ✅ |
+| `GET /api/v1/resources` | plural — collection list | ✅ |
+| `POST /api/v1/resource/register` | singular + action verb | ✅ |
+| `POST /api/v1/resource/heartbeat` | singular + action verb | ✅ |
+
+無需修改。
--- a/docs_v1.0/M4_workspace/Momentry_API_Training_Marcom.md
+++ b/docs_v1.0/M4_workspace/Momentry_API_Training_Marcom.md