# 檔案歷程打包機制設計討論

**作者**：M4  
**日期**：2026-05-07  

---

## 目標

將一支檔案從註冊到處理完成的所有產出打包成一個可攜帶的封包，可在另一台 Momentry 實例上還原，不需重新處理。

---

## 打包內容

一個檔案在 Momentry 中的完整歷程包含：

| 類別 | 內容 | 來源 | 大小估計 |
|------|------|------|---------|
| **原始檔** | 影片/照片原始檔案 | `videos.file_path` | 596MB~2.2GB |
| **Metadata** | probe JSON, duration, fps, resolution | `videos` table | < 1MB |
| **Output JSON** | face.json, asr.json, cut.json, yolo.json 等 | `output_dev/` directory | 1MB~100MB |
| **Processor results** | 狀態、時間、版本、產出量 | `processor_results` table | < 1MB |
| **Pre-chunks** | 各 processor 原始 frame 級資料 | `pre_chunks` table | 10MB~500MB |
| **Chunks** | sentence chunks, scene chunks, story chunks | `chunks` table | 1MB~50MB |
| **Face detections** | 人臉追蹤結果 + embeddings | `face_detections` table | 5MB~50MB |
| **Qdrant vectors** | face, voice, rule1 向量 | Qdrant collections | 10MB~200MB |
| **Identities** | 人物身份綁定 | `identities` + `identity_bindings` | < 1MB |
| **5W1H summaries** | LLM 產生的場景摘要 | `chunks.summary_text` | < 1MB |

---

## 打包格式提案

```
file_uuid.tar.gz
├── metadata.json              # videos table row + probe_json
├── output/                    # output JSON 檔案
│   ├── face.json
│   ├── asr.json
│   ├── cut.json
│   └── ...
├── data/                      # DB 資料（JSON 格式）
│   ├── processor_results.json
│   ├── pre_chunks.json
│   ├── chunks.json
│   ├── face_detections.json
│   └── identities.json
├── vectors/                   # Qdrant 向量（NPZ 或 JSON）
│   ├── face_vectors.npz
│   ├── voice_vectors.npz
│   └── rule1_vectors.npz
├── manifest.json              # 版本資訊 + checksum
└── original/                  # 原始檔案（可選）
    └── video.mp4
```

## 關鍵設計問題

| 問題 | 討論 |
|------|------|
| **向量如何打包？** | Qdrant 無原生匯出 API。需從 PG `face_detections.embedding` 讀取，或直接 query Qdrant |
| **UUID 衝突？** | 還原時 file_uuid 可能與目標系統重複。需支援 UUID remapping |
| **原始檔超大？** | 可選是否包含原始檔。不含時需在新系統重新註冊同一路徑 |
| **Identity 整合？** | 打包中的 identity 是否要 merge 到目標系統的 identity 池？ |
| **PG 與 Qdrant 一致性？** | 向量同時存在 PG 和 Qdrant，需確保兩者同步 |

---

## 使用場景

```
場景 A：M5 處理 → 打包 → M4 匯入驗證
  M5 跑完 Charade pipeline
  → momentry export aeed71342a89 --output charade.tar.gz
  → scp charade.tar.gz M4
  → momentry import charade.tar.gz
  → M4 可直接搜尋、查 face、看 chunks（不需重跑）

場景 B：開發環境 → 正式環境
  dev playground → export → import → production

場景 C：備份歸檔
  已完成處理的檔案 → export → 儲存 → 日後可還原查詢
```

---

## API 設計草案

```bash
# 匯出
POST /api/v1/file/{uuid}/export
→ 回傳下載 URL 或直接下載 tar.gz

# 匯入
POST /api/v1/files/import
Content-Type: multipart/form-data
file=@charade.tar.gz
→ 回還原後的 file_uuid
```

---

## 優先級

| 項目 | 優先級 | 說明 |
|------|--------|------|
| Output JSON 打包 | 🟢 Easy | 直接 tar output_dev 中該 uuid 的檔案 |
| DB data 匯出 | 🟡 Medium | 需 pg_dump 或 JSON serialization |
| Qdrant 向量匯出 | 🔴 Hard | 需逐條讀取 Qdrant points |
| 匯入還原 | 🔴 Hard | 需處理 UUID remapping + identity merge |
| 含原始檔 | 🟡 Medium | 大檔案傳輸，可選 |
