momentry_core/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md

交付程序：M4_workspace → M5 → Public Release

Date: 2026-05-13 Version: 1.0

---

流程總覽

M4 回報問題 → M5 修復 → 驗證 → Release package → Deploy → Public

---

Phase 1：M4 回報（M4_workspace/）

M4 將問題寫入 docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>.md，格式：

# {問題標題}
**Date**: YYYY-MM-DD
**From**: M4
**To**: M5

---

## Bug / 建議
（問題描述 + 影響分析）

## Fix 建議
（選擇性：程式碼範例或解決方向）

---

Phase 2：M5 處理

步驟	動作	檢查點
2.1	讀取 M4 報告，理解問題	必要時回覆確認
2.2	實作修復	cargo check / cargo test 通過
2.3	更新 Registry（如影響座標、detector）	相關 .md 同步更新
2.4	git commit	commit message 含 M4 issue 參考
2.5	回覆 M4_workspace/YYYY-MM-DD_<topic>_response.md	說明修復方式 + commit hash

修復分類與回應形式

修復類型	回應文件	同步項目
Bug fix（座標、script 錯誤）	*_response.md + git commit	無需額外
模型替換（YOLO v5→v8 等）	*_response.md + Registry 更新	DETECTOR_REGISTRY.md
架構變更（新 module、pipeline 重排）	*_response.md + Registry 更新	SPATIAL_COORDINATE_REGISTRY.md
新功能（heuristic_scene 等）	*_response.md + 新文件	新 REFERENCE/*.md
新測試包	*_test_report.md	上傳至 release/files/

回應文件規範

# {主題} — 回覆

**Date**: YYYY-MM-DD
**From**: M5
**To**: M4
**Ref**: `YYYY-MM-DD_source_file.md`

---

## 修正

| # | 項目 | 狀態 | Commit |
|---|------|:--:|--------|
| 1 | {問題 A 修復} | ✅ | `abc1234` |
| 2 | {功能 B 新增} | ✅ | `abc1234` |

## 檔案變更

| 檔案 | 說明 |
|------|------|
| `path/to/file` | 改動摘要 |

---

Phase 3：Release Package

時機

條件	動作
重大修復完成	產生新 package
M4 要求測試	產生 package，附 *_test_report.md
版本里程碑	正式 release（含 version bump）

產生流程

# 1. 確認所有變更已 commit
git log --oneline -5

# 2. Build release binary
cargo build --bin release

# 3. 產生 package（含 sql/ 目錄、vec0.dylib、deploy.sh、verify.sh）
cargo run --bin release -- package {file_uuid}

# 4. 檢查 output
ls -la release/files/{uuid}_v{timestamp}.tar.gz

# 5. 驗證 package 內容
tar tzf release/files/{uuid}_v{timestamp}.tar.gz

Package 內容規範

{file_uuid}/
├── file_info.json              (含 momentry_version + momentry_build)
├── data.sql                    (→ 指引 sql/)
├── deploy.sh                   (→ 9 步驟)
├── verify.sh
├── vec0.dylib                  (SQLite vector extension)
├── sql/
│   ├── dev_videos.sql
│   ├── dev_chunk.sql
│   ├── dev_chunk_vectors.sql   (768D)
│   ├── dev_face_detections.sql (512D)
│   ├── dev_identities.sql
│   ├── dev_identity_bindings.sql
│   ├── dev_tkg_nodes.sql
│   └── dev_tkg_edges.sql
├── {uuid}.face.json            (landmark 已修復)
├── {uuid}.yolo.json
├── {uuid}.asr.json
├── {uuid}.asrx.json
├── {uuid}.cut.json
├── {uuid}.sqlite               (含 vec0 向量表)
└── *.mp4 / *.mov

---

Phase 4：Deploy

測試環境 (dev, port 3003)

# 解包
tar xzf release/files/{uuid}_v{timestamp}.tar.gz -C /tmp/deploy/
cd /tmp/deploy/{file_uuid}

# 執行 deploy（9 步驟）
bash deploy.sh

預期輸出

  [0/9] Checking system version and build...
  [1/9] Verifying package...
  [2/9] Pre-cleaning existing identities...
  [3/9] Importing DB data...
  [4/9] Copy video...
  [5/9] Setting status=completed
  [6/9] Copying output files...
  [7/9] Installing vec0.dylib...
  [8/9] Verify deployment...

Production (port 3002)

Production deploy 步驟與 dev 相同，但需注意：

項目	Dev (3003)	Production (3002)
Schema	dev.*	public.*（或 dev.* 若已 migration）
Port	3003	3002
Deploy URL	localhost:3003/health	localhost:3002/health
版本檢查	可接受 unknown build	強制匹配 version

# Production deploy 需明確設定 Server URL
SERVER_URL=http://localhost:3002 bash deploy.sh

---

Phase 5：Public Release

條件

• M4 驗證通過（deploy test 全部綠色）
• 所有 open issues 已回應或關閉
• 版本號已 bump（Cargo.toml → build.rs → BUILD_VERSION）
• package 已上傳到 release/files/
• 變更已 git commit + git push

Release Info 產出

# Release v{version} — {YYYY-MM-DD}

## Changes
- {change 1}
- {change 2}

## Files
- release/files/{uuid}_v{timestamp}.tar.gz

## Verification
- Deploy test: ✅ (M4)
- API test: 18/18 ✅
- Chunks: {n}
- Faces: {n}
- Identities: {n}
- TKG nodes/edges: {n}/{n}

保存

# 備份 release 資訊
echo "Release: v{VERSION}" > $RELEASE_DIR/RELEASE_INFO.txt
echo "Date: $(date)" >> $RELEASE_DIR/RELEASE_INFO.txt
echo "Git: $(git rev-parse HEAD)" >> $RELEASE_DIR/RELEASE_INFO.txt
echo "Package: {uuid}_v{timestamp}.tar.gz" >> $RELEASE_DIR/RELEASE_INFO.txt

---

文件對照

文件	用途
M4_workspace/*.md	M4 問題回報
M4_workspace/*_response.md	M5 修復回覆
M4_workspace/*_test_report.md	測試包報表
REFERENCE/DETECTOR_REGISTRY.md	Detector 規格
REFERENCE/DETECTOR_SELECTION_SOP.md	選型標準
REFERENCE/SPATIAL_COORDINATE_REGISTRY.md	座標系統
REFERENCE/IDENTITY_LIFECYCLE.md	Identity 生命週期
M4_HANDOVER/	M4 交付目錄