cold_display_guard/docs/superpowers/plans/2026-06-09-alarm-snapshot-upload.md

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