25cf4e3322
- switch dashboard payload to grouped schema v2.0 in simclient - support immediate event-triggered screenshot sends via meta.json signaling - update README and copilot instructions to document v2 payload and trigger behavior - update migration checklist to reflect completed client/server rollout
62 lines
2.3 KiB
Markdown
62 lines
2.3 KiB
Markdown
# MQTT Payload Migration Checklist (One Page)
|
|
|
|
Use this checklist to migrate from legacy flat dashboard payload to grouped v2 payload.
|
|
|
|
## A. Client Implementation
|
|
|
|
- [x] Create branch for migration work.
|
|
- [x] Capture one baseline message from MQTT (legacy format).
|
|
- [x] Implement one canonical payload builder function.
|
|
- [x] Emit grouped blocks in this order: `message`, `content`, `runtime`, `metadata`.
|
|
- [x] Add `metadata.schema_version = "2.0"`.
|
|
- [x] Add `metadata.producer = "simclient"`.
|
|
- [x] Add `metadata.published_at` in UTC ISO format.
|
|
- [x] Map capture type to `metadata.capture.type` (`periodic`, `event_start`, `event_stop`).
|
|
- [x] Map screenshot freshness to `metadata.capture.age_s`.
|
|
- [x] Keep screenshot object unchanged in semantics (`filename`, `data`, `timestamp`, `size`).
|
|
- [x] Keep trigger behavior unchanged (periodic and triggered sends still work).
|
|
- [x] Add publish log fields: schema version, capture type, age.
|
|
- [x] Validate all 3 paths end-to-end:
|
|
- [x] periodic
|
|
- [x] event_start
|
|
- [x] event_stop
|
|
|
|
## B. Server Migration
|
|
|
|
- [x] Add grouped v2 parser (`message/content/runtime/metadata`).
|
|
- [x] Add temporary legacy fallback parser.
|
|
- [x] Normalize both parsers into one internal server model.
|
|
- [x] Mark required fields:
|
|
- [x] `message.client_id`
|
|
- [x] `message.status`
|
|
- [x] `metadata.schema_version`
|
|
- [x] `metadata.capture.type`
|
|
- [x] Keep optional fields tolerated (`runtime.process_health`, `content.screenshot`).
|
|
- [x] Update dashboard consumers to use normalized model (not raw legacy keys).
|
|
- [x] Add migration counters:
|
|
- [x] v2 parse success
|
|
- [x] legacy fallback usage
|
|
- [x] parse failures
|
|
- [x] Test compatibility matrix:
|
|
- [x] new client -> new server
|
|
- [x] legacy client -> new server
|
|
- [x] Run short soak in dev.
|
|
|
|
## C. Cutover and Cleanup
|
|
|
|
- [ ] Set v2 as primary parser path on server.
|
|
- [ ] Confirm fallback usage is near zero for agreed window.
|
|
- [ ] Remove legacy parser/fallback.
|
|
- [ ] Remove client-side temporary compatibility fields (if used).
|
|
- [ ] Keep one canonical schema sample in repo.
|
|
- [ ] Close migration ticket with final validation evidence.
|
|
|
|
## Quick Go/No-Go Gate
|
|
|
|
Go only if all are true:
|
|
|
|
- [ ] No parse failures in dev soak
|
|
- [ ] All 3 capture types visible in dashboard
|
|
- [ ] Screenshot payload integrity unchanged
|
|
- [ ] Metadata group present and complete
|