Package Tag Done/Reopen — Device implementation notes

This page describes how baykedfarm-device should implement the platform contract:

Responsibilities (device)

Offline-first durability (use existing Outbox)

  • When the operator taps Done or Reopen, create an Outbox event in the device’s local Postgres.
  • Use the Outbox record’s event_id (UUID) as the idempotency key for the command.
  • Store the exact MQTT payload in the Outbox payload (recommended: payload.mqtt_payload).
  • Rely on the existing Outbox publisher to retry until connected; do not treat MQTT publish-ack as “applied”.
  • Command identity/origin is scale-based: include scale_id in the command payload.

Local tag-state cache (enforcement)

Because the device can be offline, it must locally enforce “no weighing into closed tags”:

  • Maintain a small local table/cache keyed by (client, facility_id, package_tag):
  • is_closed
  • updated_at
  • last_event_id
  • last_action
  • (optional) sync_state / “confirmed” flag

UI rules:

  • Done: set cache to Closed (Pending) immediately (optimistic local UX).
  • Reopen: set cache to Open (Pending) immediately.
  • If tag is closed (pending or confirmed), block weigh flows that attempt to write new_package_tag = tag.

On inbound state_updates:

  • Server state wins; update cache fields from the message.
  • Mark Confirmed when state_updates.last_event_id == local_pending_event_id for that tag.

MQTT wiring

Config

  • MQTT_INVENTORY_TOPIC_PREFIX (recommended default: BayKinetic/inventory/customer)

Publish (via Outbox publisher)

  • Topic: {MQTT_INVENTORY_TOPIC_PREFIX}/{client}/tags/commands
  • QoS: 1
  • Payload: package_tag_command envelope from the platform spec

Subscribe

  • Topic: {MQTT_INVENTORY_TOPIC_PREFIX}/{client}/tags/state_updates
  • (Optional) Topic: {MQTT_INVENTORY_TOPIC_PREFIX}/{client}/tags/command_results/{scale_id}

Suggested test checklist

  • Device offline:
  • Done shows Pending and blocks weighing into the tag.
  • Reopen shows Pending and unblocks weighing into the tag.
  • Device reconnects:
  • Outbox publishes commands.
  • Device receives state_updates and transitions to Confirmed for the matching event_id.
  • Duplicate/offline replay:
  • Re-sending the same event_id should never cause a second waste event (server-side), and device should end in the same final state.