diff --git a/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md b/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md new file mode 100644 index 0000000..8e03cac --- /dev/null +++ b/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md @@ -0,0 +1,242 @@ +# 交付程序: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_.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__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 交付目錄 |