# Alarm Snapshot Upload Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Capture one current-frame snapshot for alerting runtime events, upload it to the OTA chunk-upload service, and include the returned path in outbound webhook payloads.

**Architecture:** Keep `BatchEngine` unchanged and treat snapshot upload as runtime-side enrichment. Reuse the already captured RGB frame from the active detection loop, encode it to JPEG with `ffmpeg`, upload it through the documented token/init/chunk/complete flow, then merge the returned `object_key` into the webhook payload for alert-level batch events and the derived case events from the same cycle.

**Tech Stack:** Python 3.12 standard library backend, existing `ffmpeg` dependency, JSONL webhook retry flow, unittest.

---

### Task 1: Snapshot Upload Client

**Files:**
- Create: `src/cold_display_guard/alarm_snapshots.py`
- Test: `tests/test_alarm_snapshots.py`

- [ ] **Step 1: Write the failing test**
  Add tests that cover:
  - loading upload settings from config
  - encoding a current RGB frame into JPEG via injected encoder helper
  - successful OTA upload flow returning `object_key`
  - disabled or non-alert events skipping upload

- [ ] **Step 2: Run test to verify it fails**
  Run: `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_alarm_snapshots.py -v`
  Expected: FAIL because the snapshot upload module does not exist yet.

- [ ] **Step 3: Write minimal implementation**
  Implement:
  - upload settings parsing with defaults for `https://ota.zhengxinshipin.com` and secret `change-me-in-production`
  - current-frame JPEG encoding
  - token/init/chunk/complete upload workflow with injectable HTTP helpers for tests
  - per-cycle alert snapshot metadata structure carrying `object_key`, file name, and upload status

- [ ] **Step 4: Run test to verify it passes**
  Run: `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_alarm_snapshots.py -v`
  Expected: PASS

### Task 2: Runtime And Webhook Integration

**Files:**
- Modify: `src/cold_display_guard/main.py`
- Modify: `src/cold_display_guard/webhooks.py`
- Test: `tests/test_main.py`
- Test: `tests/test_webhooks.py`

- [ ] **Step 1: Write the failing test**
  Add tests that cover:
  - runtime uploads one snapshot when a cycle contains alert-severity events
  - webhook payload includes uploaded `object_key` for alert batch events
  - derived case webhook payload includes the same snapshot path for matching case-creation events
  - upload failure does not block webhook delivery and instead records failure metadata in payload

- [ ] **Step 2: Run test to verify it fails**
  Run:
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_main.py -v`
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v`
  Expected: FAIL because runtime/webhook code does not accept snapshot metadata yet.

- [ ] **Step 3: Write minimal implementation**
  Implement:
  - alert event selection based on event severity
  - one-per-cycle snapshot upload using the current frame
  - payload enrichment for batch-event and matching case-event webhooks
  - retry queue persistence of the already enriched payload

- [ ] **Step 4: Run test to verify it passes**
  Run:
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_main.py -v`
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v`
  Expected: PASS

### Task 3: Config, Secrets, Docs, And Final Verification

**Files:**
- Modify: `src/cold_display_guard/config.py`
- Modify: `src/cold_display_guard/manage_api.py`
- Modify: `config/example.toml`
- Modify: `README_zh.md`
- Test: `tests/test_config.py`
- Test: `tests/test_manage_api.py`

- [ ] **Step 1: Write the failing test**
  Extend tests so:
  - config formatting writes snapshot-upload settings
  - management config payload strips sensitive upload secret

- [ ] **Step 2: Run test to verify it fails**
  Run:
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_config.py -v`
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_manage_api.py -v`
  Expected: FAIL because snapshot upload settings are not exposed/formatted yet.

- [ ] **Step 3: Write minimal implementation**
  Implement:
  - config keys for snapshot upload URL, secret, object prefix, enable flag, and timeout/chunk settings
  - config payload secret stripping
  - README updates for alert snapshot upload behavior and returned webhook fields

- [ ] **Step 4: Run targeted and full verification**
  Run:
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_alarm_snapshots.py -v`
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_main.py -v`
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v`
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_config.py -v`
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_manage_api.py -v`
  - `eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest discover -s tests -v`
  - `cd web && pnpm build`
  Expected: PASS