fix: file-based source of truth for worker + backup protocol
- Worker: check {uuid}.{processor}.json existence before starting processor
- Worker: timestamp-copy backup existing output files before re-run (no delete, no overwrite)
- Executor: partial output saved as .json.partial (not .json) to avoid false completion
- Start script: removed set-e, log dir changed to momentry/logs, Qdrant collection status fix
- docs: M4 release incident report + M4/M5 collaboration protocol
This commit is contained in:
50
docs/M4_M5_COLLABORATION_PROTOCOL.md
Normal file
50
docs/M4_M5_COLLABORATION_PROTOCOL.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# M4 / M5 協作協議
|
||||
|
||||
## 核心原則:檔案是 source of truth
|
||||
|
||||
所有 processor 的產出是 `{uuid}.{processor}.json` 檔案。
|
||||
**檔案存在 = 處理完成**,優先於 DB 或 Redis 的任何狀態記錄。
|
||||
|
||||
## 絕對禁止
|
||||
|
||||
### 1. 不可刪除已存在的輸出檔
|
||||
- 任何 `{uuid}.{processor}.*` 檔案,無論是 `.json`、`.json.tmp`、`.json.partial`、`.json.err`
|
||||
- 一律不允許 `rm`、`unlink`、`delete`
|
||||
- 唯一例外:明確的人工指令 `rm` / `Delete this file`
|
||||
|
||||
### 2. 不可覆蓋已存在的輸出檔
|
||||
- 重新執行 processor 前,必須先 **copy(非 rename)** 加上時間戳備份
|
||||
- 備份命名:`{uuid}.{processor}.{timestamp}.{original_extension}`
|
||||
- 若備份名已存在,跳過(不覆蓋不 counter)
|
||||
- 原檔保留不動
|
||||
|
||||
### 3. 不可跨域操作
|
||||
- M4 只能在 M4 機器(Mac Mini)上操作
|
||||
- M5 只能在 M5 機器(MacBook Pro)上操作
|
||||
- 禁止任何跨機器的檔案操作或 cleanup
|
||||
|
||||
## 重跑 processor 的正確流程
|
||||
|
||||
1. Worker 檢查 `{uuid}.{processor}.json` 是否存在
|
||||
2. **存在 → 跳過**(無論 DB/Redis 狀態)
|
||||
3. 不存在 → copy 備份既有 `{uuid}.{processor}.*` → 執行 processor
|
||||
4. Processor 輸出寫入 `.tmp` → 完成後 rename 為 `.json`
|
||||
|
||||
## 例外處理
|
||||
|
||||
| 狀態 | 行為 |
|
||||
|------|------|
|
||||
| `.json` 存在 | 跳過,視為完成 |
|
||||
| `.json.tmp` 存在(無 `.json`) | 視為未完成,備份後重跑 |
|
||||
| `.json.partial` 存在(無 `.json`) | 視為未完成,備份後重跑 |
|
||||
| `.json.err` 存在(無 `.json`) | 視為未完成,備份後重跑 |
|
||||
| Process 被 kill(SIGKILL) | partial 存為 `.json.partial`(非 `.json`) |
|
||||
|
||||
## 違規後果
|
||||
|
||||
2026-05-09 事故:M4 release 打包未含 .json → 跨域操作 → M5 cleanup 誤刪 asr.json
|
||||
→ 導致 ASR 需重跑(完整電影約 1.5hr)
|
||||
→ YOLO 需重跑
|
||||
→ 損失已完成的 pipeline 進度
|
||||
|
||||
此類違規不可再發生。
|
||||
Reference in New Issue
Block a user