# 离线存储功能测试指南

## 功能概述

离线存储功能会在网络断开时自动将数据存储到 Flash 中，并在网络恢复后自动补传数据。

## 测试步骤

### 1. 编译并烧录固件

```bash
cd "/home/beihong/esp_projects/Distributed Collector Gateway"
idf.py build
idf.py flash monitor
```

### 2. 观察启动日志

系统启动时会显示以下关键日志：

```
I (xxxx) main: Initializing SPIFFS file system...
I (xxxx) FLASH_SPIFS: SPIFFS mounted successfully at /flash
I (xxxx) FLASH_SPIFS: Total size: 8388608 bytes, Used: 0 bytes
I (xxxx) main: Initializing offline storage module...
I (xxxx) OFFLINE_STORAGE: Offline storage initialized
I (xxxx) main: Offline data upload task started
```

### 3. 测试场景A：网络断开时的数据存储

**操作步骤：**

1. 在系统正常运行时，断开网络连接（拔掉网线或断开路由器）
2. 观察日志输出，应该看到网络断开的提示
3. 等待 MODBUS 数据采集任务产生数据
4. 观察日志，应该看到类似以下信息：

```
W (xxxx) MQTT_ESP: Network offline, storing data locally (topic: xxx, len: xxx)
I (xxxx) MQTT_ESP: Storing offline data (type=1, size=xxx)
I (xxxx) OFFLINE_STORAGE: Stored offline data: /flash/offline/xxxxxx.json
I (xxxx) MQTT_ESP: Storage usage: 4096 / 8388608 bytes (0.0%)
```

**预期结果：**
- 数据被成功存储到 Flash 中
- 显示存储使用情况
- 设备继续正常运行，不会因为网络断开而崩溃

### 4. 测试场景B：网络恢复时的自动补传

**操作步骤：**

1. 在测试场景A中存储了一些离线数据后
2. 重新连接网络（插上网线或恢复路由器）
3. 观察日志输出

**预期日志：**

```
I (xxxx) MQTT_ESP: Network online, resuming normal operation
I (xxxx) MQTT_ESP: Found 5 offline data files, uploading...
I (xxxx) MQTT_ESP: Publishing offline data (type=1, size=xxx)
I (xxxx) MQTT_ESP: Offline data published successfully, msg_id=xxx
I (xxxx) OFFLINE_STORAGE: Deleted offline data: /flash/offline/xxxxxx.json
I (xxxx) MQTT_ESP: Storage usage: 32768 / 8388608 bytes (0.4%)
```

**预期结果：**
- 系统自动检测到网络恢复
- 自动开始上传离线存储的数据
- 每次上传成功后删除对应文件
- 逐条上传，直到所有离线数据都上传完成

### 5. 测试场景C：设备状态数据的离线存储

**操作步骤：**

1. 断开网络连接
2. 等待设备状态上报周期（默认10秒）
3. 观察日志输出

**预期日志：**

```
W (xxxx) MQTT_ESP: Network offline, storing device status locally
I (xxxx) MQTT_ESP: Storing offline data (type=2, size=xxx)
I (xxxx) OFFLINE_STORAGE: Stored offline data: /flash/offline/xxxxxx.json
```

**预期结果：**
- 设备状态数据被正确识别为 OFFLINE_DATA_TYPE_DEVICE_STATUS 类型
- 数据成功存储到 Flash

### 6. 测试场景D：存储空间耗尽

**操作步骤：**

1. 持续在网络断开状态下运行设备
2. 让 MODBUS 数据持续产生（通过发送 MODBUS 查询命令）
3. 观察存储使用率的变化

**预期日志：**

```
I (xxxx) MQTT_ESP: Storage usage: 8355840 / 8388608 bytes (99.6%)
W (xxxx) OFFLINE_STORAGE: Storage nearly full (99.6%), consider clearing old data
```

**预期结果：**
- 当存储空间快满时，系统会发出警告
- 新数据仍然可以存储，直到空间完全耗尽
- 系统继续正常运行

### 7. 测试场景E：手动清空离线数据

如果需要手动清空所有离线数据，可以：

1. 通过串口终端发送清空命令（需要自行实现）
2. 或者重新格式化 SPIFFS 文件系统（会删除所有数据）

**格式化方法：**
- 在代码中调用 `flash_spiffs_format()` 函数
- 这会清空整个文件系统，包括离线数据和配置

## MQTT 服务器端验证

在 MQTT 服务器端（如使用 MQTTX 或 Mosquitto Client）：

1. 订阅设备发布的主题：`CONFIG_MQTT_PUB_TOPIC`（在 sdkconfig 中配置）
2. 在网络断开时，应该收不到新数据
3. 在网络恢复后，应该收到之前存储的离线数据
4. 验证接收到的数据完整性和顺序

## 常见问题排查

### 问题1：日志显示 "Failed to store offline data"

**可能原因：**
- SPIFFS 文件系统挂载失败
- Flash 存储空间已满
- 文件系统错误

**解决方法：**
1. 检查 SPIFFS 初始化日志
2. 查看存储使用情况
3. 必要时格式化文件系统

### 问题2：网络恢复后没有自动上传离线数据

**可能原因：**
- 离线上传任务未启动
- MQTT 客户端未连接
- 网络状态判断错误

**解决方法：**
1. 检查日志中是否有 "Offline data upload task started"
2. 确认 MQTT 客户端已连接
3. 检查 `g_is_online` 状态

### 问题3：离线数据上传不完整或丢失

**可能原因：**
- MQTT 发布失败
- 文件读取错误
- 文件删除时机问题

**解决方法：**
1. 查看日志中的错误信息
2. 确认 MQTT 服务器可用
3. 检查 Flash 文件完整性

## 性能测试

### 存储性能

- 每条数据存储时间：通常 < 100ms
- 支持的数据大小：最大 4096 bytes（单条）
- 存储容量：约 8MB（基于分区表配置）

### 上传性能

- 每条数据上传时间：取决于网络延迟
- 上传间隔：1 秒（在离线上传任务中）
- 支持的最大数据条数：约 2000 条（基于平均每条 4KB）

## 存储容量分析

基于当前配置：

- **分区大小**: 8MB
- **SPIFFS 开销**: 约 10-20%
- **可用空间**: 约 6.4-7.2MB
- **最小文件大小**: 4KB（SPIFFS 特性）
- **MODBUS 数据大小**: 约 200 bytes/秒
- **可存储时长**: 约 2-3 小时

**注意：** 由于 SPIFFS 最小文件大小为 4KB，即使只有 200 bytes 的数据也会占用 4KB 空间。如果需要更长时间的离线存储，建议：
1. 增大存储分区
2. 使用 LittleFS 文件系统（支持更小的文件块）
3. 实现数据打包存储（多条数据打包到一个文件）

## 测试总结

完成以上测试后，你应该能够验证：

1. ✅ 网络断开时数据能正确存储到 Flash
2. ✅ 网络恢复时数据能自动补传
3. ✅ 设备状态和 MODBUS 数据都能正确处理
4. ✅ 存储空间管理正常
5. ✅ 系统在各种网络状态切换下稳定运行

如有问题，请查看 ESP 日志输出，或参考 `docs/OFFLINE_STORAGE.md` 获取详细的技术文档。