momentry_core/docs/RELEASE_PACKAGING.md

Release Packaging Design

三類包：開發系統升級包 + 生產系統升級包 + 檔案內容包，完全獨立。

1. 開發系統升級包 (System/Dev)

給 playground（port 3003, dev schema）使用。

release/system/dev/{version}/
├── RELEASE_INFO.txt
├── source.tar.gz           ← Rust + scripts source code
├── .env.development        ← DATABASE_SCHEMA=dev, port 3003
├── schema_dev.sql          ← dev schema DDL
├── scripts/
│   ├── pipeline_status.py
│   ├── generate_asr1.py
│   ├── apply_asr_corrections.py
│   ├── clean_sentence_text.py
│   └── import_file_package.py    ← 匯入檔案內容包
├── test/
│   └── api_test.sh
└── migration/
    └── {prev}_to_{version}.sql

升級：覆蓋 code + 執行 migration → cargo build --bin momentry_playground → 重啟 3003

2. 生產系統升級包 (System/Prod)

給 production（port 3002, public schema）使用。

release/system/prod/{version}/
├── RELEASE_INFO.txt
├── source.tar.gz           ← Rust + scripts source code
├── .env                    ← DATABASE_SCHEMA=public, port 3002
├── schema_public.sql       ← public schema DDL
├── scripts/ (same as dev)
├── test/
│   └── api_test.sh
└── migration/
    └── {prev}_to_{version}.sql

3. 檔案內容包 (File)

一個影片的完整資料，開發與生產環境共用。

release/files/{file_uuid}/{version}/
├── metadata.json            ← Registration info
├── RELEASE_INFO.txt
├── processors/              ← output_dev/{uuid}.*.json
│   ├── asr.json
│   ├── asrx.json
│   ├── asr-1.json
│   ├── yolo.json
│   ├── face.json
│   ├── pose.json
│   ├── ocr.json
│   ├── cut.json
│   └── scene.json
├── face_detections.csv      ← 該檔案的所有 face detections
├── identities.csv           ← 關聯的 identities
├── tkg_nodes.csv            ← TKG nodes
├── tkg_edges.csv            ← TKG edges
├── qdrant/                  ← Qdrant snapshots for this file
│   ├── momentry_dev_v1.snapshot
│   ├── sentence_story.snapshot
│   └── ...
└── RELEASE_INFO.txt

匯入流程

1. POST /api/v1/files/register  → 取得 file_uuid
2. python3 scripts/import_file_package.py --uuid {uuid} --package path/
3. 檔案狀態更新為「已註冊已處理」