设备运行时长管理

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

快速访问

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

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

功能说明

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

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

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

一级页面列表查询

操作说明：

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

字段说明：

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

数据导出：

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

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

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

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

二级页面列表查询

操作说明：

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

字段说明：

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

数据导出：

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

技术架构与数据流

本模块涉及从设备端上报、Kafka消息消费、TDengine时序数据库存储的完整流程。

1. 数据流向图

以下是设备运行时长从采集到存储、统计的完整数据流向。数据通过设备按日汇总上报（DEVICE_RUN_RECORD 事件），汇入 Kafka Topic 进行统一处理：

Mermaid Diagram Code:

flowchart TD
    subgraph DeviceSide [设备端]
        Device[设备] -->|按日汇总上报| Gateway[网关/API]
        Device -->|"事件上报(DEVICE_RUN_RECORD)"| Gateway
    end

    subgraph Middleware [中间件]
        Gateway -->|Push| Kafka{Kafka Topic: device-run-record}
    end

    subgraph Service [后端服务]
        Consumer[DeviceRuntimeConsumer]
        
        Kafka -->|Consume| Consumer
    end

    subgraph Storage [存储层]
        TDengineDetail[(TDengine明细表)]
        TDengineDay[(TDengine日统计表)]
        
        Consumer -->|1. 计算时长 & 写入明细| TDengineDetail
        Consumer -->|2. 按日分组 & 写入日统计| TDengineDay
    end

2. 数据模型关系图

主要涉及的数据实体及其关系如下：

Mermaid Diagram Code:

erDiagram
    DeviceRuntimeDetailDO {
        string mac "设备MAC"
        string cpu "设备CPU"
        timestamp startTime "开机时间"
        timestamp endTime "关机时间"
        long deviceDuration "持续时长(秒)"
        string tbname "子表名"
    }
    
    DeviceRuntimeCountDO {
        string mac "设备MAC"
        string cpu "设备CPU"
        timestamp ts "记录日期"
        long deviceDuration "总运行时长(秒)"
        string dataKey "主键(mac+cpu)"
    }
    
    DeviceRuntimeDetailDO ||--o{ DeviceRuntimeCountDO : "聚合统计"

核心业务逻辑

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. 数据模型关系图​

核心业务逻辑​

1. 数据上报与接收​

2. 数据处理 (DeviceRuntimeConsumer)​

3. 数据存储​