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
|
|
|
|
- [ ] Create branch for migration work.
|
|
- [ ] Capture one baseline message from MQTT (legacy format).
|
|
- [ ] Implement one canonical payload builder function.
|
|
- [ ] Emit grouped blocks in this order: `message`, `content`, `runtime`, `metadata`.
|
|
- [ ] Add `metadata.schema_version = "2.0"`.
|
|
- [ ] Add `metadata.producer = "simclient"`.
|
|
- [ ] Add `metadata.published_at` in UTC ISO format.
|
|
- [ ] Map capture type to `metadata.capture.type` (`periodic`, `event_start`, `event_stop`).
|
|
- [ ] Map screenshot freshness to `metadata.capture.age_s`.
|
|
- [ ] Keep screenshot object unchanged in semantics (`filename`, `data`, `timestamp`, `size`).
|
|
- [ ] Keep trigger behavior unchanged (periodic and triggered sends still work).
|
|
- [ ] Add publish log fields: schema version, capture type, age.
|
|
- [ ] Validate all 3 paths end-to-end:
|
|
- [ ] periodic
|
|
- [ ] event_start
|
|
- [ ] event_stop
|
|
|
|
## B. Server Migration
|
|
|
|
- [ ] Add grouped v2 parser (`message/content/runtime/metadata`).
|
|
- [ ] Add temporary legacy fallback parser.
|
|
- [ ] Normalize both parsers into one internal server model.
|
|
- [ ] Mark required fields:
|
|
- [ ] `message.client_id`
|
|
- [ ] `message.status`
|
|
- [ ] `metadata.schema_version`
|
|
- [ ] `metadata.capture.type`
|
|
- [ ] Keep optional fields tolerated (`runtime.process_health`, `content.screenshot`).
|
|
- [ ] Update dashboard consumers to use normalized model (not raw legacy keys).
|
|
- [ ] Add migration counters:
|
|
- [ ] v2 parse success
|
|
- [ ] legacy fallback usage
|
|
- [ ] parse failures
|
|
- [ ] Test compatibility matrix:
|
|
- [ ] new client -> new server
|
|
- [ ] legacy client -> new server
|
|
- [ ] 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
|