135 lines
5.3 KiB
Markdown
135 lines
5.3 KiB
Markdown
# Device Status LWT MAC Resolution Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Verify and document that `/MAC/publish/status` last-will messages resolve the MAC address to `deviceNo` before updating device status.
|
|
|
|
**Architecture:** Keep `DeviceStatusHandler` focused on status parsing and delegate Topic identity resolution to the existing `DeviceIdentityResolver`. Add a focused integration-style unit test using the real resolver and a mocked mapper so the complete MAC-to-device-number path is covered without duplicating database access in the handler.
|
|
|
|
**Tech Stack:** Java 17, Spring Boot, JUnit 5, Mockito, AssertJ, MyBatis-Plus
|
|
|
|
## Global Constraints
|
|
|
|
- Only `/MAC/publish/status` may use a MAC address for this change.
|
|
- Other MQTT communication continues to use `deviceNo`.
|
|
- A missing MAC mapping must not update device status.
|
|
- Preserve all existing uncommitted workspace changes.
|
|
|
|
---
|
|
|
|
### Task 1: Cover MAC Last-Will Resolution
|
|
|
|
**Files:**
|
|
- Modify: `water-modules/water-app/src/test/java/org/dromara/app/handler/DeviceStatusHandlerTest.java`
|
|
|
|
**Interfaces:**
|
|
- Consumes: `DeviceIdentityResolver(AppDeviceMapper)` and `DeviceStatusHandler.handle(String, String, boolean)`
|
|
- Produces: Regression coverage proving a Topic MAC is converted to `AppDevice.deviceNo`
|
|
|
|
- [ ] **Step 1: Add the mapper mock and MAC last-will test**
|
|
|
|
Add imports and a mapper mock:
|
|
|
|
```java
|
|
import org.dromara.app.domain.AppDevice;
|
|
import org.dromara.app.mapper.AppDeviceMapper;
|
|
|
|
@Mock
|
|
private AppDeviceMapper appDeviceMapper;
|
|
```
|
|
|
|
Add this test:
|
|
|
|
```java
|
|
@Test
|
|
void handleResolvesLastWillTopicMacToDeviceNo() {
|
|
String macAddress = "DC:DA:0C:FA:29:5E";
|
|
AppDevice device = new AppDevice();
|
|
device.setDeviceNo("D01");
|
|
when(appDeviceMapper.selectById(macAddress)).thenReturn(null);
|
|
when(appDeviceMapper.selectByMac("dc:da:0c:fa:29:5e")).thenReturn(device);
|
|
DeviceIdentityResolver resolver = new DeviceIdentityResolver(appDeviceMapper);
|
|
DeviceStatusHandler handler = new DeviceStatusHandler(resolver, deviceStatusService, new ObjectMapper());
|
|
|
|
handler.handle(macAddress, "{\"status\":\"offline\"}", false);
|
|
|
|
verify(appDeviceMapper).selectByMac("dc:da:0c:fa:29:5e");
|
|
verify(deviceStatusService).markOffline("D01", "设备 MQTT 状态离线");
|
|
verify(deviceStatusService, never()).markOffline(macAddress, "设备 MQTT 状态离线");
|
|
}
|
|
```
|
|
|
|
Add the missing-device guard test:
|
|
|
|
```java
|
|
@Test
|
|
void handleDoesNotUpdateStatusWhenLastWillMacIsUnknown() {
|
|
String macAddress = "DC:DA:0C:FA:29:5E";
|
|
when(appDeviceMapper.selectById(macAddress)).thenReturn(null);
|
|
when(appDeviceMapper.selectByMac("dc:da:0c:fa:29:5e")).thenReturn(null);
|
|
DeviceIdentityResolver resolver = new DeviceIdentityResolver(appDeviceMapper);
|
|
DeviceStatusHandler handler = new DeviceStatusHandler(resolver, deviceStatusService, new ObjectMapper());
|
|
|
|
handler.handle(macAddress, "{\"status\":\"offline\"}", false);
|
|
|
|
verify(deviceStatusService, never()).markOffline(anyString(), anyString());
|
|
verify(deviceStatusService, never()).markOnline(anyString());
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run the focused test**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
mvn -pl water-modules/water-app -am "-DskipTests=false" "-Dmaven.test.skip=false" "-Dprofiles.active=dev" "-Dtest=DeviceStatusHandlerTest#handleResolvesLastWillTopicMacToDeviceNo+handleDoesNotUpdateStatusWhenLastWillMacIsUnknown" "-Dsurefire.failIfNoSpecifiedTests=false" test
|
|
```
|
|
|
|
Expected: both tests PASS. The requested production path already exists in `DeviceIdentityResolver`; these characterization tests make that behavior explicit and prevent regression.
|
|
|
|
### Task 2: Clarify Device Status Topic Identity
|
|
|
|
**Files:**
|
|
- Modify: `water-modules/water-app/src/main/java/org/dromara/app/handler/DeviceStatusHandler.java:15-19`
|
|
|
|
**Interfaces:**
|
|
- Consumes: Existing `DeviceIdentityResolver.resolveDeviceNo(String)` behavior
|
|
- Produces: Javadoc that accurately documents device-number and MAC Topic identities
|
|
|
|
- [ ] **Step 1: Update handler Javadoc**
|
|
|
|
Replace the class description with:
|
|
|
|
```java
|
|
/**
|
|
* 设备在线/离线状态处理器，匹配 /{deviceIdentity}/publish/status。
|
|
* <p>
|
|
* deviceIdentity 支持设备编号；设备遗嘱消息允许使用 MAC 地址，处理前统一解析为设备编号。
|
|
* 设备通过 status=online 标记上线，通过 LWT status=offline 标记异常离线。
|
|
*/
|
|
```
|
|
|
|
- [ ] **Step 2: Run all handler tests**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
mvn -pl water-modules/water-app -am "-DskipTests=false" "-Dmaven.test.skip=false" "-Dprofiles.active=dev" "-Dtest=DeviceStatusHandlerTest" "-Dsurefire.failIfNoSpecifiedTests=false" test
|
|
```
|
|
|
|
Expected: all `DeviceStatusHandlerTest` tests PASS with zero failures and errors.
|
|
|
|
- [ ] **Step 3: Check the final diff**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git diff --check -- water-modules/water-app/src/main/java/org/dromara/app/handler/DeviceStatusHandler.java water-modules/water-app/src/test/java/org/dromara/app/handler/DeviceStatusHandlerTest.java
|
|
```
|
|
|
|
Expected: exit code 0 and no whitespace errors.
|
|
|
|
- [ ] **Step 4: Leave implementation changes uncommitted for review**
|
|
|
|
Both implementation files already contain user changes. Do not create a commit that would mix those changes with this task.
|