smart-home/CloudAlarmReporter_README.md

# ESP32云端报警上报功能实现

## 功能概述

本功能实现了ESP32设备向云端服务器自动上报报警事件的能力。当ESP32检测到火灾、高温、异常升温等报警时，会自动将报警信息通过HTTP POST请求发送到云端服务器。

## 核心特性

- ✅ **异步上报**: 不阻塞主程序，使用队列+后台任务处理
- ✅ **自动重试**: 失败时自动重试，最多3次
- ✅ **幂等去重**: 使用sourceEventId防止重复上报
- ✅ **设备鉴权**: 使用X-Device-Key头进行设备身份验证
- ✅ **完整集成**: 已集成到现有AlarmManager模块

## 实现架构

### 1. 核心模块

```
CloudAlarmReporter (云端报警上报模块)
├── 异步队列处理
├── HTTP客户端封装
├── JSON数据构建
├── 重试机制
└── 设备UID管理
```

### 2. 集成点

```
AlarmManager::addAlarmToHistory()
├── 保存本地历史记录
├── 调用CloudAlarmReporter::reportAlarmAsync()
└── 异步上报到云端
```

## 关键文件

### 新增文件

1. **`main/Module/CloudAlarmReporter.h`** - 头文件
2. **`main/Module/CloudAlarmReporter.cpp`** - 实现文件
3. **`test_cloud_alarm_reporter.py`** - 测试工具

### 修改文件

1. **`main/Module/AlarmManager.cpp`** - 添加云端上报调用
2. **`main/app_main.cpp`** - 添加模块初始化

## 配置参数

### 云端服务器配置

```cpp
// 云端服务器URL
static constexpr const char* CLOUD_SERVER_URL = "http://115.190.167.176:36988/device-alarms";

// 设备认证密钥
static constexpr const char* DEVICE_KEY = "39dc753bd0cb19da5050a2f0edf932f851f5b21b90a6d06ecf9a28d81079a0a6";
```

### 性能参数

```cpp
static constexpr int REPORT_QUEUE_SIZE = 20;        // 报警队列大小
static constexpr int HTTP_TIMEOUT_MS = 10000;       // HTTP超时时间
static constexpr int MAX_RETRY_COUNT = 3;           // 最大重试次数
static constexpr int RETRY_DELAY_MS = 2000;         // 重试延迟
```

## API规范

### HTTP请求格式

```http
POST /device-alarms HTTP/1.1
Host: 115.190.167.176:36988
Content-Type: application/json
X-Device-Key: 39dc753bd0cb19da5050a2f0edf932f851f5b21b90a6d06ecf9a28d81079a0a6

{
  "physicalUid": "206EF1B3AD74",
  "sourceEventId": "206EF1B3AD74:1700000000000",
  "title": "燃烧报警",
  "level": "danger",
  "message": "检测到燃烧，峰值温度92.3°C，位置(12,21)",
  "temp": 92.3,
  "occurredAtMs": 1700000000000
}
```

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| physicalUid | string | 设备物理UID（MAC地址，不带冒号大写） |
| sourceEventId | string | 事件唯一ID（physicalUid:timestampMs） |
| title | string | 报警标题 |
| level | string | 报警级别（danger/warning/info） |
| message | string | 报警详细信息 |
| temp | number | 温度值 |
| occurredAtMs | number | 发生时间戳（毫秒） |

## 报警类型映射

| AlarmType | title | level |
|-----------|-------|-------|
| DANGER_TEMP_ALARM | 高温报警 | danger |
| HEATER_BURST_ALARM | 异常升温报警 | warning |
| HEATER_MOVING_ALARM | 高温移动报警 | warning |
| BURNING_ALARM | 燃烧报警 | danger |
| EXPANDING_ALARM | 高温扩散报警 | warning |
| UNATTENDED_ALARM | 无人照看报警 | warning |

## 使用示例

### 1. 初始化（已自动集成）

```cpp
// 在app_main.cpp中已自动初始化
CloudAlarmReporter::init();
```

### 2. 上报报警（已自动集成）

```cpp
// 在AlarmManager::addAlarmToHistory中已自动调用
bool success = CloudAlarmReporter::reportAlarmAsync(
    AlarmManager::BURNING_ALARM,
    "检测到燃烧，峰值温度92.3°C，位置(12,21)",
    92.3f,
    "厨房区域"
);
```

### 3. 获取状态信息

```cpp
// 获取队列大小
int queue_size = CloudAlarmReporter::getQueueSize();

// 检查上报器是否运行
bool is_running = CloudAlarmReporter::isReporterRunning();
```

## 测试验证

### 1. 运行测试工具

```bash
python test_cloud_alarm_reporter.py
```

### 2. 观察ESP32日志

```
I (12345) CloudAlarmReporter: 🌐 初始化云端报警上报模块
I (12346) CloudAlarmReporter: ✅ 云端报警上报模块初始化成功
I (12347) AlarmManager: 📝 添加报警历史: [14:30:25] 燃烧 - 检测到燃烧... (温度: 92.3°C)
I (12348) AlarmManager: ☁️ 报警已加入云端上报队列
I (12349) CloudAlarmReporter: 📨 开始上报报警: [燃烧报警] 206EF1B3AD74:1700000000000
I (12350) CloudAlarmReporter: 📡 HTTP响应状态码: 200
I (12351) CloudAlarmReporter: ✅ 报警上报成功: 206EF1B3AD74:1700000000000
```

### 3. 验证步骤

1. ✅ 确认App已登录并完成设备绑定
2. ✅ 触发一次真实报警
3. ✅ ESP32串口日志显示POST上报成功
4. ✅ 云端数据库alarm_records出现新记录
5. ✅ App报警历史页显示云端记录

## 故障排除

### 常见问题

1. **HTTP请求失败**
   - 检查网络连接
   - 确认云端服务器地址和端口
   - 验证设备密钥是否正确

2. **队列满**
   - 检查网络状况
   - 增加队列大小
   - 检查云端服务器响应速度

3. **重复上报**
   - 确认sourceEventId生成逻辑
   - 检查云端去重机制

### 调试日志

启用详细日志：

```cpp
// 在menuconfig中设置日志级别为DEBUG
esp_log_level_set("CloudAlarmReporter", ESP_LOG_DEBUG);
```

## 性能影响

- **内存占用**: 约8KB（任务栈 + 队列缓冲）
- **CPU占用**: 极低（仅在报警时激活）
- **网络流量**: 每次报警约200-500字节
- **延迟影响**: 无（异步处理）

## 扩展功能

### 未来可扩展的功能

1. **批量上报**: 将多个报警打包上报
2. **离线缓存**: 网络断开时缓存报警，恢复后上报
3. **压缩传输**: 使用gzip压缩减少流量
4. **加密传输**: 使用HTTPS加密通信
5. **配置动态更新**: 支持远程更新服务器地址和密钥

## 总结

ESP32云端报警上报功能已完全集成到现有系统中，无需额外配置即可使用。该功能具有高可靠性、低延迟、易扩展的特点，为智能家居系统提供了完整的云端数据同步能力。