# 交付程序：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`，格式：

```markdown
# {問題標題}
**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/` |

### 回應文件規範

```markdown
# {主題} — 回覆

**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） |

### 產生流程

```bash
# 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)

```bash
# 解包
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 |

```bash
# 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 產出

```markdown
# 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}
```

### 保存

```bash
# 備份 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 交付目錄 |