From 2cf962bc701a171d5b3d6db7fde2c097f976857f Mon Sep 17 00:00:00 2001 From: Accusys Date: Wed, 13 May 2026 20:54:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20update=20DELIVERY=5FPROCEDURE=20to=20v1?= =?UTF-8?q?.1=20=E2=80=94=20add=20self-verify,=20version=20strategy,=20rol?= =?UTF-8?q?lback,=20deploy=20details?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 6 + docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md | 155 ++++++++++++++++++++-- 2 files changed, 148 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 24680d5..f5dd539 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -672,3 +672,9 @@ docs_v1.0/M4_workspace/YYYY-MM-DD__test_report.md (測試報告) 4. M4 透過 git log 查看 詳細規範見 `docs_v1.0/M4_workspace/M4_NOTIFICATION_PROTOCOL.md`。 + +## Delivery Procedure + +完整交付程序（M4_workspace → M5 → Release → Deploy → Public）見： + +`docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md` diff --git a/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md b/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md index 8e03cac..40b3a00 100644 --- a/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md +++ b/docs_v1.0/REFERENCE/DELIVERY_PROCEDURE.md @@ -1,20 +1,26 @@ # 交付程序：M4_workspace → M5 → Public Release **Date**: 2026-05-13 -**Version**: 1.0 +**Version**: 1.1 --- ## 流程總覽 ``` -M4 回報問題 → M5 修復 → 驗證 → Release package → Deploy → Public +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_.md`，格式： ```markdown @@ -82,6 +88,58 @@ M4 將問題寫入 `docs_v1.0/M4_workspace/YYYY-MM-DD_.md`，格式： --- +## 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 +``` + +### 回應文件規範 + +```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 ### 時機 @@ -142,29 +200,73 @@ tar tzf release/files/{uuid}_v{timestamp}.tar.gz ## Phase 4：Deploy -### 測試環境 (dev, port 3003) +### 前置檢查 ```bash -# 解包 +# 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（9 步驟） +### 執行 deploy + +```bash bash deploy.sh ``` ### 預期輸出 ``` - [0/9] Checking system version and build... - [1/9] Verifying package... - [2/9] Pre-cleaning existing identities... + [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... - [4/9] Copy video... - [5/9] Setting status=completed - [6/9] Copying output files... - [7/9] Installing vec0.dylib... + 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。 + +### 驗證後確認 + +```bash +# 確認所有 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) @@ -187,14 +289,41 @@ 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 已回應或關閉 -- [ ] 版本號已 bump（Cargo.toml → build.rs → BUILD_VERSION） +- [ ] 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 產出 ```markdown