xiaoyang/smart-home

Fork 0

小羊肉肉. 00c4b9d098 xiaoyang

2026-02-26 09:16:34 +08:00

6.1 KiB

Raw Permalink Blame History

云端报警查询接口说明

🎯 新增功能

为支持APP省电模式，新增了设备报警查询接口，允许APP通过设备MAC地址（physicalUid）查询报警记录。

📡 API接口

1. 查询设备报警记录（新增）

接口: GET /device-alarms

用途: APP轮询查询设备的报警记录

请求参数:

参数	类型	必填	说明	示例
`physicalUid`	String	是	设备物理UID（MAC地址）	`A1B2C3D4E5F6`
`limit`	Integer	否	返回记录数（默认20，最大100）	`20`
`since`	Long	否	时间戳（毫秒），只返回此时间之后的报警	`1737518400000`

请求示例:

GET /device-alarms?physicalUid=A1B2C3D4E5F6&limit=20&since=1737518400000

响应格式:

{
  "success": true,
  "data": [
    {
      "id": 123,
      "deviceUid": "device-001",
      "sourceEventId": "A1B2C3D4E5F6:1737518400000",
      "alarmType": "high_temp",
      "level": "danger",
      "title": "高温报警",
      "message": "检测到危险高温，平均温度达到85.5°C",
      "temp": 85.5,
      "occurredAt": "2026-01-22T11:00:00Z",
      "isRead": false,
      "readAt": null
    }
  ],
  "message": "success"
}

错误响应:

{
  "success": false,
  "data": null,
  "message": "physicalUid参数不能为空"
}

2. 上报设备报警（已有）

接口: POST /device-alarms

用途: ESP32设备上报报警到云端

请求头:

X-Device-Key: 39dc753bd0cb19da5050a2f0edf932f851f5b21b90a6d06ecf9a28d81079a0a6
Content-Type: application/json

请求体:

{
  "physicalUid": "A1B2C3D4E5F6",
  "sourceEventId": "A1B2C3D4E5F6:1737518400000",
  "title": "高温报警",
  "level": "danger",
  "message": "检测到危险高温，平均温度达到85.5°C",
  "temp": 85.5,
  "occurredAtMs": 1737518400000
}

🔧 代码修改

1. AlarmRecordRepository.java

添加了两个查询方法：

// 通过设备物理UID查询报警记录
@Query("SELECT a FROM AlarmRecord a WHERE a.device.physicalUid = :physicalUid ORDER BY a.occurredAt DESC")
List<AlarmRecord> findByDevicePhysicalUidOrderByOccurredAtDesc(
    @Param("physicalUid") String physicalUid, 
    Pageable pageable
);

// 通过设备物理UID和时间戳查询报警记录
@Query("SELECT a FROM AlarmRecord a WHERE a.device.physicalUid = :physicalUid AND a.occurredAt > :since ORDER BY a.occurredAt DESC")
List<AlarmRecord> findByDevicePhysicalUidAndOccurredAtAfterOrderByOccurredAtDesc(
    @Param("physicalUid") String physicalUid, 
    @Param("since") Date since, 
    Pageable pageable
);

2. DeviceAlarmController.java

添加了查询接口：

@GetMapping("/device-alarms")
public ApiResponse<List<AlarmRecordDto>> queryAlarms(
        @RequestParam("physicalUid") String physicalUid,
        @RequestParam(value = "limit", defaultValue = "20") int limit,
        @RequestParam(value = "since", required = false) Long sinceMs) {
    // 查询逻辑
}

📦 打包部署

1. 打包

Windows:

build.bat

Linux/Mac:

mvn clean package -DskipTests

2. 运行

java -jar target/cloud-backend-jdk8-1.0.0.jar

或使用自定义配置：

java -jar target/cloud-backend-jdk8-1.0.0.jar --spring.config.location=application.properties

3. 验证

测试查询接口:

curl "http://115.190.167.176:30088/device-alarms?physicalUid=A1B2C3D4E5F6&limit=10"

预期响应:

{
  "success": true,
  "data": [...],
  "message": "success"
}

🚀 APP集成

Android端

// CloudAlarmListenerService.java
private void pollCloudAlarms() {
    String url = "http://115.190.167.176:30088/device-alarms" + 
                 "?physicalUid=" + deviceMacAddress + 
                 "&limit=10" +
                 "&since=" + lastAlarmTimestamp;
    
    Request request = new Request.Builder()
        .url(url)
        .get()
        .build();
    
    httpClient.newCall(request).enqueue(new Callback() {
        @Override
        public void onResponse(Call call, Response response) throws IOException {
            if (response.isSuccessful() && response.body() != null) {
                String responseBody = response.body().string();
                processCloudAlarms(responseBody);
            }
        }
    });
}

uni-app端

// pages/index/index.vue
async loadCloudAlarmHistory() {
  try {
    const response = await bridgeRequest({
      url: 'http://115.190.167.176:30088/device-alarms',
      method: 'GET',
      data: {
        physicalUid: this.deviceMacAddress,
        limit: 20,
        since: this.lastAlarmTimestamp
      }
    })
    
    if (response.success && response.data) {
      this.processCloudAlarms(response.data)
    }
  } catch (error) {
    console.error('❌ 加载云端报警历史失败:', error)
  }
}

📊 数据流程

ESP32设备
  ↓ (检测到报警)
  ↓ POST /device-alarms
云端服务器（保存报警记录）
  ↑ (轮询查询)
  ↑ GET /device-alarms?physicalUid=xxx
Android APP
  ↓ (转发给uni-app)
uni-app首页（显示报警）

✅ 优势

ESP32省电 - 首页不需要请求ESP32，ESP32只接收信号
实时性好 - APP每15秒轮询云端，延迟可接受
可靠性高 - 云端服务器稳定，离线可查历史
实现简单 - 只需修改后端、Android、uni-app，ESP32不变

📝 注意事项

设备绑定 - 设备必须先绑定用户，否则报警无法保存
physicalUid - 必须与ESP32上报的MAC地址一致
时间戳 - since参数使用毫秒时间戳
查询限制 - 单次查询最多返回100条记录

🔍 测试步骤

部署后端 - 启动云端服务器
ESP32上报 - 触发报警，ESP32自动上报到云端
查询验证 - 使用curl或Postman测试查询接口
APP集成 - Android端实现轮询逻辑
功能测试 - 验证首页能正常显示报警

📞 联系方式

如有问题，请联系开发团队。

6.1 KiB Raw Permalink Blame History Unescape Escape