water/docs/superpowers/specs/2026-07-13-device-status-lwt-mac-design.md

Device Status LWT MAC Resolution Design

Goal

When a device publishes its MQTT last-will status on /MAC/publish/status, resolve the MAC address to the stored deviceNo before updating device status.

Design

• Keep DeviceStatusHandler responsible for parsing status payloads and invoking status updates.
• Reuse DeviceIdentityResolver to translate the Topic identity into an AppDevice and then its deviceNo.
• The resolver first supports an existing deviceNo Topic and falls back to a case-insensitive mac_address lookup. This preserves compatibility while handling LWT Topics that contain a MAC address.
• If no device matches the Topic identity, do not update any record; keep the existing warning log.
• Update the handler documentation to state that the Topic identity may be either a device number or a MAC address.

Verification

Add a focused unit test using the real DeviceIdentityResolver with a mocked AppDeviceMapper. The test publishes an offline status with a MAC identity and verifies that:

1. The mapper looks up the MAC address.
2. MqttDeviceStatusService.markOffline receives the resolved deviceNo.
3. No status update uses the MAC address as a device number.

Scope

This change only covers /MAC/publish/status. Other MQTT communication continues to use deviceNo according to the existing protocol.