From 1e1f1042fed40493741263f3bfbf7f29a74b6344 Mon Sep 17 00:00:00 2001
From: yuhaiming <40624989@qq.com>
Date: Mon, 13 Jul 2026 14:00:50 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=E9=81=97=E5=98=B1?=
 =?UTF-8?q?=E6=B6=88=E6=81=AFMAC=E8=A7=A3=E6=9E=90=E6=96=B9=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...2026-07-13-device-status-lwt-mac-design.md | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-13-device-status-lwt-mac-design.md

diff --git a/docs/superpowers/specs/2026-07-13-device-status-lwt-mac-design.md b/docs/superpowers/specs/2026-07-13-device-status-lwt-mac-design.md
new file mode 100644
index 0000000..9b7603c
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-13-device-status-lwt-mac-design.md
@@ -0,0 +1,25 @@
+# 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.