admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
momentry_core/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md

10 KiB
Raw Permalink Blame History

交付程序：M4_workspace → M5 → Public Release

Date: 2026-05-13 Version: 1.1

流程總覽

M4 回報問題 → M5 修復 → M5 自驗 → Release package → Deploy → M4 驗證 → Public Release
                                   ↑                                      ↓
                                   └── 失敗回退 ──────────────────────────┘

Phase 1：M4 回報（M4_workspace/）

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 2.5：M5 內部自驗

Release 前先自驗，降低 M4 測試失敗的機率。

自驗清單

# 項目 方法
2.5.1 Rust build cargo build / cargo test
2.5.2 API 測試 bash api_test.sh → 全 passed
2.5.3 場景驗證 抽 1 個 CUT segment，用 MaskFormer 或 PaliGemma 確認 scene type
2.5.4 SQLite 驗證 python3 export_sqlite.py {uuid} → vec0 tables 正確
2.5.5 Identity 驗證 TMDB 演員 + auto PERSON count 合理
2.5.6 TKG 驗證 edges > 0, nodes > 0
2.5.7 file_info.json momentry_version + momentry_build 正確

自驗不通過

❌ cargo build → 修復編譯錯誤 → 重新 commit
❌ api_test → 修復 → 重新 commit
❌ 場景驗證 → 確認是 bug 還是 flicker → 必要時開 issue

回應文件規範

# {主題} — 回覆

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

前置檢查

# 1. 確認伺服器正常
curl -s http://localhost:3003/health
# 預期: {"status":"ok","version":"1.0.0","build_git_hash":"d34bcae",...}

# 2. 確認資料庫可連線
/Users/accusys/pgsql/18.3/bin/psql -U accusys -d momentry -c "SELECT version()"

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

執行 deploy

bash deploy.sh

預期輸出

  [0/9] Checking system version and build...          ✅ Server v1.0.0 matches
  [1/9] Verifying package...                           ✅
  [2/9] Pre-cleaning existing identities...             ✅
  [3/9] Importing DB data...
        Importing dev_videos.sql...                     COPY 1
        Importing dev_chunk.sql...                      COPY 2407
        Importing dev_chunk_vectors.sql...               COPY 2407
        Importing dev_face_detections.sql...             COPY 70691
        Importing dev_identities.sql...                  COPY 441
        Importing dev_identity_bindings.sql...           COPY 18635
        Importing dev_tkg_nodes.sql...                   COPY 6457
        Importing dev_tkg_edges.sql...                   COPY 21028
  [4/9] Copy video...                                   ✅
  [5/9] Setting status=completed                        ✅
  [6/9] Copying output files...                         ✅ N files
  [7/9] Installing vec0.dylib...                        ✅ /tmp/vec0.dylib
  [8/9] Verify deployment...
        Chunks:    2407
        Faces:     70691
        Identities: 417
        TKG nodes: 6457
        TKG edges: 21028                               ✅

Deploy 失敗處理

失敗點 原因 處理方式
Step 0: 版本檢查 server version ≠ package version 取得 matching upgrade package
Step 3: 任 table 匯入失敗 FK constraint、duplicate key 檢查該 table 的 sql/*.sql 內容，修復後再跑
Step 4: 影片複製 磁碟空間不足 df -h 確認，清理後重跑
Step 8: 驗證 row count 不符 import 不完整 逐 table 比對 COPY count vs actual count

每個 table 獨立 import（各含 auto-commit），單一 table 失敗不會 rollback 其他 table。 重新執行 bash deploy.sh 會先清掉該 file 的 identity 和資料後重新 import。

驗證後確認

# 確認所有 table row count 正確
for tbl in videos chunk chunk_vectors face_detections identities identity_bindings tkg_nodes tkg_edges; do
    echo "$tbl: $(psql -U accusys -d momentry -t -A -c "SELECT COUNT(*) FROM dev.$tbl WHERE file_uuid='$UUID'" 2>/dev/null)"
done

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

版本策略

Bump 幅度 適用時機 範例
patch 0.0.x Bug fix only，無 API 變更 1.0.0 → 1.0.1
minor 0.x.0 新功能、模型替換、API 向後相容 1.0.0 → 1.1.0
major x.0.0 Breaking change、schema 遷移 1.0.0 → 2.0.0

目前版本 1.0.0，所有已完成的變更（YOLO 替換、座標修復、pipeline 重排）尚未 bump。

條件

  • M4 驗證通過（deploy test 全部綠色）
  • 所有 open issues 已回應或關閉
  • API 文件與實際行為一致（或已開 doc issue 追蹤 M4 更新）
  • 版本號已 bump（Cargo.toml → build.rs → BUILD_VERSION）
  • package 已上傳到 release/files/
  • 變更已 git commit + git push

M4 驗證失敗的回退

M4 deploy test ❌
    ↓
M5 分析失敗原因
    ├── Bug → 回到 Phase 2 修復 → 重新 commit（不 bump 版本）
    ├── Script 錯誤 → 修復 deploy.sh → 重新 commit
    └── Package 內容缺漏 → 重新 `cargo run --bin release -- package`
    ↓
M5 重新通知 M4（新 *response.md + git commit）
M4 重新測試

Release Info 產出

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 交付目錄
Reference in New Issue View Git Blame Copy Permalink