# 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 進度

此類違規不可再發生。