设备运行时长管理

设备运行时长管理用于统计每一台设备的开机运行时间。由设备按日汇总上报今日设备开关机情况，每天开关机多次则有多条数据（一组包含开机时间-关机时间的列表），即隔天上报前一日的数据，如遇到第二日设备未开机或无网络等异常情况，则会在下一次网络等恢复后上报所有积累的数据。

快速访问

在设备运行时长管理模块中，您可以快速访问系统。

功能入口：数据分析 -> 设备运行时长管理
直接访问：点击跳转到设备运行时长管理

功能说明

设备运行时长管理的功能说明：

1. 运行时长概览（一级页面）

在设备运行时长管理的一级页面中，该页面按设备或日期维度展示运行概况（仅展示总运行时长，无详细开关机日志）。由设备按日汇总上报今日设备开关机情况，每天开关机多次则有多条数据（一组包含开机时间-关机时间的列表），即隔天上报前一日的数据，如遇到第二日设备未开机或无网络等异常情况，则会在下一次网络等恢复后上报所有积累的数据。

一级页面列表查询

操作说明：

支持通过 MAC、CPU 进行搜索。
可选择 统计维度（日、月、年） 和 记录时间范围（跟随统计维度）来筛选数据。

字段说明：

MAC：设备MAC地址。
CPU：设备CPU ID。
运行时长：对应统计维度（年、月、日）该设备的运行时长。点击数值可切换显示格式（详细格式/小时格式）。
记录时间：对应统计维度（年、月、日）的具体时间点。

数据导出：

同步导出：点击导出后，系统立即处理并返回导出结果。

2. 运行时长明细（二级页面）

设备运行时长的二级页面：

在设备运行时长管理的二级页面中，选中一级页面某条数据后进入，可查看该设备对应的详细开关机日志。由设备按日汇总上报今日设备开关机情况，每天开关机多次则有多条数据（一组包含开机时间-关机时间的列表），即隔天上报前一日的数据，如遇到第二日设备未开机或无网络等异常情况，则会在下一次网络等恢复后上报所有积累的数据。

二级页面列表查询

操作说明：

可选择 统计维度（日、月、年） 和 记录时间范围（跟随统计维度）来筛选数据。

字段说明：

MAC：设备MAC地址。
CPU：设备CPU ID。
运行时长：单次开关机的持续时长。
开机时间：设备开机时间。
关机时间：设备关机时间。
记录时间：对应统计维度（年、月、日）的具体时间点。

数据导出：

同步导出：点击导出后，系统立即处理并返回导出结果。

业务逻辑与数据流

1. 业务流程图

Mermaid Diagram Code:

flowchart TD
    subgraph 设备端
        A[设备开关机] --> B[记录开关机时间]
        B --> C[按日汇总]
        C --> D[上报运行记录]
    end
    
    subgraph 平台端
        D --> E[接收事件上报]
        E --> F[发送到消息队列]
        F --> G[异步消费处理]
        G --> H[计算运行时长]
        H --> I[写入明细表]
        H --> J[聚合写入统计表]
    end

2. 数据上报流程

触发条件：设备每日汇总上报前一天的开关机记录

业务规则：

数据汇总：设备按日汇总当天的开关机情况
延迟上报：如遇网络异常，数据会累积并在网络恢复后统一上报
事件类型：通过 DEVICE_RUN_RECORD 事件类型标识运行记录

3. 数据处理流程

处理步骤：

接收上报：平台接收设备上报的事件数据
消息分发：将数据发送到消息队列进行异步处理
时长计算：计算每次开关机的持续时长（关机时间 - 开机时间）
明细存储：记录每次开关机的详细信息
统计聚合：按日汇总设备的总运行时长

4. 统计维度说明

统计维度	说明	数据保留
日统计	每日设备运行总时长	90天
月统计	每月设备运行总时长	365天
年统计	每年设备运行总时长	6年

数据写入说明：

所有统计数据由 Consumer 消费消息后实时写入 TDengine 时序数据库
数据按日、月、年三个维度分别存储在不同的数据库中

5. 数据归档重整

由于设备可能存在网络延迟、离线累积上报等情况，会导致数据乱序写入 TDengine。时序数据库的乱序写入会造成存储空间持续膨胀，因此系统会定期执行数据归档重整任务。

归档重整流程：

创建影子数据库（与原库结构相同）
切换数据源到影子库（新数据写入影子库）
导出原库数据
使用 -W 参数重映射导入到影子库（解决乱序问题）
重置原库（释放磁盘空间）

执行周期：按需执行，通常在磁盘空间告警时触发

6. 数据关系说明

Mermaid Diagram Code:

erDiagram
    运行明细 {
        string MAC
        string CPU
        datetime 开机时间
        datetime 关机时间
        long 持续时长
    }
    
    运行统计 {
        string MAC
        string CPU
        date 记录日期
        long 总运行时长
    }
    
    运行明细 ||--o{ 运行统计 : "聚合汇总"

核心业务逻辑(技术角度)

1. 数据上报与接收

接口入口：

设备端通过 /task/recoedDeviceEvent 接口上报事件。
后端 DeviceEventService 识别事件类型为 DEVICE_RUN_RECORD，并将数据封装为 DeviceRuntimeEvent 发送到 Kafka Topic（配置项 ${kafka.topic.device-run-record}）。

2. 数据处理 (DeviceRuntimeConsumer)

数据通过 Kafka 消费者 DeviceRuntimeConsumer 进行异步处理，主要包含两个步骤：

明细处理 (handleDetails)：
- 遍历上报的 DeviceRuntimeReq 列表。
- 计算单次运行时长：duration = lastTime - startTime。
- 过滤无效数据（时长 <= 0）。
- 将有效记录写入 TDengine 的明细表 device_runtime。
日统计聚合 (handleDayCounts)：
- 将上报的记录按日期（truncateToDateStart）进行分组。
- 对每一天的数据，累加所有记录的运行时长，计算当天的总 deviceDuration。
- 将聚合后的日统计数据写入 TDengine 的日统计表 device_runtime_count_day。

3. 数据存储

存储引擎：使用 TDengine 时序数据库。
存储策略：
- 明细表 (device_runtime)：存储每一次开关机的详细记录。
- 统计表：
  - 日统计 (device_runtime_count_day)：由 Consumer 计算并写入。
  - 月/年统计：系统设计了 device_runtime_count_month 和 device_runtime_count_year 表，支持更长周期的维度查询（通过 DeviceRuntimeCountServiceImpl 支持不同维度的查询路由）。

关联模块

查看设备详情请前往设备管理
查看设备日活统计请前往设备日活统计管理

快速访问​

功能说明​

1. 运行时长概览（一级页面）​

2. 运行时长明细（二级页面）​

业务逻辑与数据流​

1. 业务流程图​

2. 数据上报流程​

3. 数据处理流程​

4. 统计维度说明​

5. 数据归档重整​

6. 数据关系说明​

核心业务逻辑(技术角度)​

1. 数据上报与接收​

2. 数据处理 (DeviceRuntimeConsumer)​

3. 数据存储​