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:
Accusys
2026-05-09 05:32:13 +08:00
parent b220920e64
commit 9f5afd1b86
5 changed files with 328 additions and 2 deletions

View 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 被 killSIGKILL | partial 存為 `.json.partial`(非 `.json` |
## 違規後果
2026-05-09 事故M4 release 打包未含 .json → 跨域操作 → M5 cleanup 誤刪 asr.json
→ 導致 ASR 需重跑(完整電影約 1.5hr
→ YOLO 需重跑
→ 損失已完成的 pipeline 進度
此類違規不可再發生。

View File

@@ -0,0 +1,31 @@
# M4 Release Incident — 2026-05-09
## Summary
M4 在進行 release 打包作業時,未依照計畫包含 output `.json` 檔案,僅在 database 中保留 records。此外 M4 違反操作邊界進入 M5 管轄範圍M5 執行 cleanup 時將已完成的 `asr.json` 一併刪除。
## Impact
| 檔案 | 狀態 | 說明 |
|------|------|------|
| `{uuid}.asr.json` | ❌ 遺失 | 已完成的 ASR 輸出被 M5 cleanup 誤刪 |
| `{uuid}.yolo.json` | ❌ 損毀 | JSON parse error需重跑 |
| DB records | ⚠️ 不一致 | processor_results 狀態與實際檔案不符 |
## Root Cause
1. **M4 release 打包遺漏**: Release 流程未將 `.json` 輸出檔納入打包範圍,只保留了 DB。
2. **M4 越界操作**: M4 在 M5 的目錄/範圍內執行操作,違反開發隔離原則。
3. **M5 cleanup 誤刪**: M5 的 cleanup 機制未預期 M4 的產出,將 `asr.json` 視為無用檔案清除。
## 處理
- ASR: 重跑中asr_processor.py完整電影約 6780s
- YOLO: 重跑中yolo_processor.py
- 已修改 worker 邏輯:開機後以 `.json` 檔案存在為 source of truth不再僅依賴 DB/Redis 狀態
## 預防措施
- Release 流程需明確定義 deliverables 包含 `.json` 檔案
- M4/M5 操作邊界需嚴格遵守,禁止跨域操作
- Cleanup 機制應先確認檔案是否為有效 processor output