docs: file_uuid generation rules for M4
This commit is contained in:
Accusys
371
docs_v1.0/OPERATIONS/DELIVERY_PROCEDURE.md
Normal file
371
docs_v1.0/OPERATIONS/DELIVERY_PROCEDURE.md
Normal file
@@ -0,0 +1,371 @@
|
||||
# 交付程序：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`，格式：
|
||||
|
||||
```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 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
|
||||
|
||||
### 時機
|
||||
|
||||
| 條件 | 動作 |
|
||||
|------|------|
|
||||
| 重大修復完成 | 產生新 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
|
||||
|
||||
### 前置檢查
|
||||
|
||||
```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
|
||||
|
||||
```bash
|
||||
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。
|
||||
|
||||
### 驗證後確認
|
||||
|
||||
```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)
|
||||
|
||||
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
|
||||
|
||||
### 版本策略
|
||||
|
||||
| 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 產出
|
||||
|
||||
```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 交付目錄 |
|
||||
Reference in New Issue
Block a user