🌟 模块设计文档：12. 实时环境信息展示（★★★★★）

一、模块目的

本模块用于在客户端大屏实时展示智慧工地各区域的环境信息，包括温度、湿度、粉尘浓度、施工进度、监控轮播等。同时支持动态内容扩展（小地图、考勤简况）。

二、主要功能

功能名称	描述
环境信息展示	按工地区域展示温度、湿度、粉尘等
施工进度展示	展示施工各阶段的计划与完成量
监控轮播	轮流显示各摄像头视频
小地图预览	小区域标注各传感设备与状态
考勤情况快览	当前人员在场数、签到率等

三、数据来源说明

数据项	来源	方式
温度/湿度/粉尘	传感器上传 → 服务端转发	真实时（服务端主动推送）
施工进度	数据库记录	客户端定时请求（轮询）
摄像头画面	摄像头/服务端视频转码接口	RTSP/HTTP 播放
考勤情况	服务端接口	轮询/更新推送

四、客户端设计

Qt结构建议（基于大屏显示）

EnvDisplayModule/
├── EnvMainWindow.ui             # 大屏界面布局
├── EnvRealtimeWidget.h/.cpp     # 环境数据展示区
├── VideoCarouselWidget.h/.cpp   # 视频轮播区
├── MapMiniWidget.h/.cpp         # 小地图显示区域
├── ProgressWidget.h/.cpp        # 施工进度区
├── AttendanceSummaryWidget.h/.cpp # 考勤快览
├── EnvSocketHandler.h/.cpp      # 接收推送数据

五、服务端接口设计

WebSocket 推送接口（推荐）

地址：ws://server:port/ws/env
推送格式（JSON）：

{
  "area": "北区1号塔吊",
  "device_id": "D-1002",
  "temperature": 31.2,
  "humidity": 48.3,
  "dust": 0.76,
  "timestamp": "2025-06-17T14:00:00"
}

施工进度查询接口

URL：GET /api/progress/list
返回值：

[
  {
    "type": "基坑开挖",
    "plan": 100,
    "done": 60,
    "unit": "m³",
    "timestamp": "2025-06-17"
  }
]

六、数据库结构设计

环境信息表 `env_data`

字段名	类型	描述
id	int	主键
device_id	varchar	设备编号
area	varchar	区域名称
temperature	float	温度
humidity	float	湿度
dust	float	粉尘浓度
timestamp	datetime	数据时间

施工进度表 `progress_info`

字段名	类型	描述
id	int	主键
type	varchar	施工类型
plan	float	预计工作量
done	float	当前完成
unit	varchar	单位
timestamp	datetime	更新时间

🚨 模块设计文档：13. 警报管理（★★★★）

一、模块目的

对工地中的环境指标进行实时监测和报警判断，当数值超过设定阈值时触发报警，通过声光预警、客户端提示、派单等方式进行闭环管理。

二、功能概述

功能	描述
阈值管理	每项指标可设置最小值/最大值，动态调整
报警触发	服务端判断超过阈值时触发警报事件
客户端显示	所有客户端实时弹出或标记警报信息
报警记录	所有历史报警入库，供查询统计
报警处理	可记录处理方式（自动/派单/手动）

三、报警触发逻辑

服务端处理流程：

数据接收 → 判断是否超出阈值 → 是 → 
1. 写入警报表
2. 转发报警给所有客户端（WebSocket）

四、数据库表结构设计

警报信息表 `alarm_info`

字段名	类型	描述
id	int	主键
device_id	varchar	来源设备编号
metric	varchar	指标名称（温度等）
value	float	触发值
threshold_min	float	最小阈值
threshold_max	float	最大阈值
status	varchar	状态（预警/处理中/已解决）
handler	varchar	处理人
timestamp	datetime	触发时间

阈值设置表 `alarm_threshold`

字段名	类型	描述
id	int	主键
metric	varchar	指标（温度、湿度等）
min_value	float	最小值
max_value	float	最大值
update_time	datetime	更新时间

五、客户端界面设计

阈值管理界面

支持查询、修改（权限校验）
用表格方式展示各指标当前阈值

警报展示界面

可作为顶部红色横幅实时滚动
支持弹窗通知、报警列表展示

六、数据推送格式（WebSocket）

{
  "type": "alarm",
  "device_id": "D-1002",
  "metric": "粉尘浓度",
  "value": 1.35,
  "min": 0.0,
  "max": 1.2,
  "status": "预警",
  "timestamp": "2025-06-17T14:01:00"
}

七、客户端模块设计建议

AlarmModule/
├── AlarmManager.h/.cpp           # 逻辑处理、阈值判断封装
├── AlarmThresholdWidget.ui       # 阈值设置界面
├── AlarmDisplayWidget.ui         # 实时警报显示区
├── AlarmWebSocketHandler.cpp     # 推送处理器

✅ 推荐架构：数据统一管理，Widget 只负责显示

👉 核心思想：数据获取统一处理，UI 显示分别更新

🔧 架构分层建议

1. ✅ 数据中心（统一管理）

负责接收、解析、缓存所有数据（包括推送和轮询）
推荐单例类：DataCenter 或 DataDispatcher

它负责：

统一 WebSocket/TCP 接收传感器数据（推送）
定时轮询接口拉取数据库数据
维护本地缓存（如当前温度、进度、考勤）
发射 Qt 信号：dataUpdated()，通知所有需要刷新显示的控件

class DataCenter : public QObject {
    Q_OBJECT
public:
    static DataCenter* instance(); // 单例

    void init();                   // 初始化数据源连接、定时器等
    QVariantMap getEnvData();      // 获取当前缓存
    QVariantMap getProgressData();

signals:
    void envDataUpdated();
    void progressDataUpdated();
    void attendDataUpdated();
};

2. ✅ 每个分区 widget —— 只监听、显示

各个 widget 专注做**一件事：显示 UI + 接收数据更新信号**

EnvWidget 监听 envDataUpdated()，自动更新温度/湿度标签
ProgressWidget 监听 progressDataUpdated()，刷新图表
AttendWidget 监听 attendDataUpdated()，展示出勤人数
AlarmWidget 监听统一告警信号 alarmTriggered(...)，弹出提示

connect(DataCenter::instance(), &DataCenter::envDataUpdated, this, &EnvWidget::updateDisplay);

3. ✅ 视频播放部分（例外）

RTSP 视频推荐由每个 CameraWidget 自行维护流地址与播放器（如 VLC/FFmpeg 封装）
因为每个监控画面播放负载高、并且 UI 控制较强（轮播、切换）
可统一配置视频源，但播放逻辑分布在控件中

✳️ 总结对比

方案	特点	建议
统一管理（推荐）	所有数据统一接入、缓存、转发给各 widget	更清晰、更易维护、更好解耦
分别在各 widget 获取数据	控件自己去轮询、维护定时器、解析接口	初期简单，后期容易混乱、重复代码、不好统一更新

✅ 统一管理的优点

🌟 解耦：UI 和数据处理分开，清晰职责
📦 缓存集中：多个 widget 共享数据，不重复访问接口
🔁 统一轮询/推送处理：方便扩展协议、接口、调试
🚨 统一告警处理：告警判断逻辑不需要写在每个 widget 中

🧱 推荐你实现的模块类划分

模块	类名	作用
数据中心	`DataCenter`	管理所有数据通信、缓存、信号
网络通信	`WebSocketClient` / `HttpClient`	实现推送/轮询
UI - 环境信息区	`EnvDisplayWidget`	监听 `envDataUpdated()`
UI - 视频轮播	`CameraCarouselWidget`	维护播放器
UI - 地图	`MapWidget`	根据 `deviceDataUpdated()` 添加设备状态图标
UI - 进度图	`ProgressChartWidget`	展示数据库进度数据
UI - 考勤	`AttendWidget`	展示服务端考勤结果
UI - 告警	`AlarmBannerWidget`	统一接收预警显示

🌟 模块设计文档：12. 实时环境信息展示（★★★★★）

一、模块目的

二、主要功能

三、数据来源说明

四、客户端设计

Qt结构建议（基于大屏显示）

五、服务端接口设计

WebSocket 推送接口（推荐）

施工进度查询接口

六、数据库结构设计

环境信息表 env_data

施工进度表 progress_info

🚨 模块设计文档：13. 警报管理（★★★★）

一、模块目的

二、功能概述

三、报警触发逻辑

服务端处理流程：

四、数据库表结构设计

警报信息表 alarm_info

阈值设置表 alarm_threshold

五、客户端界面设计

阈值管理界面

警报展示界面

六、数据推送格式（WebSocket）

七、客户端模块设计建议

✅ 推荐架构：**数据统一管理，Widget 只负责显示**

🔧 架构分层建议

1. ✅ 数据中心（统一管理）

2. ✅ 每个分区 widget —— 只监听、显示

3. ✅ 视频播放部分（例外）

✳️ 总结对比

✅ 统一管理的优点

🧱 推荐你实现的模块类划分

环境信息表 `env_data`

施工进度表 `progress_info`

警报信息表 `alarm_info`

阈值设置表 `alarm_threshold`

✅ 推荐架构：数据统一管理，Widget 只负责显示