1. 项目概述与需求分析
1.1 数字工地管理背景
传统建筑工地管理长期面临“信息黑箱”困境：设备分布散乱、人员考勤滞后、环境数据采集靠人工巡检、异常事件无法实时预警。随着物联网（IoT）与可视化技术的成熟，数字工地管理已成为行业转型的必然方向。
本实战项目以设备跟踪为核心场景，通过传感器采集、MQTT 实时传输、Flask 后端处理、ECharts 前端渲染，构建一套可落地、可扩展的数字工地管理现场看板。学员将完整经历从需求分析到系统交付的全流程。
核心痛点： 工地设备“在哪、谁在用、状态如何、是否异常”——传统管理方式无法实时回答这四个问题。
1.2 现场看板核心功能
看板系统围绕“设备全生命周期跟踪”设计，包含以下五大功能模块：
| 功能模块 | 核心能力 | 用户价值 |
|---|---|---|
| 设备实时定位 | 基于 GPS/蓝牙信标，每 5 秒上报位置 | 快速查找设备，减少丢失与闲置 |
| 状态监控 | 运行/待机/故障/离线四种状态自动切换 | 提前发现故障，降低停机损失 |
| 使用记录 | 操作人员、开始/结束时间、工作时长 | 责任到人，优化设备调度 |
| 告警推送 | 超时未归、越界、电量低、异常震动 | 及时响应，保障安全 |
| 数据看板 | 设备总数、在线率、告警统计、热力图 | 管理层一目了然，辅助决策 |
1.3 数据可视化目标
可视化不是“把数据画出来”，而是让数据可读、可交互、可决策。本项目设定以下四个量化目标：
- 实时性： 看板数据刷新延迟 ≤ 2 秒（MQTT + WebSocket 保障）。
- 直观性： 设备位置通过地图散点图呈现，状态通过颜色编码（绿=正常，黄=待机，红=故障，灰=离线）。
- 可交互： 点击设备节点弹出详情卡片，支持按类型/状态/区域筛选。
- 可追溯： 保留 7 天历史轨迹与告警记录，支持时间轴回放。
设计原则： 看板默认展示“全局概览”，用户通过下钻操作获取细节，避免信息过载。
1.4 项目技术栈选型
技术选型遵循“轻量、高效、易学、可扩展”原则，前后端分离，数据流清晰：
| 层级 | 技术 | 选型理由 |
|---|---|---|
| 后端框架 | Python + Flask | 轻量灵活，生态丰富，适合快速原型与教学 |
| 前端可视化 | ECharts 5.x | 国产开源，图表类型全，交互能力强，社区活跃 |
| 实时通信 | MQTT (Mosquitto) + Paho MQTT Client | 物联网标准协议，低带宽低延迟，支持海量设备 |
| 数据存储 | SQLite (开发) / MySQL (生产) | 零配置起步，后期可平滑迁移 |
| 前端框架 | 原生 HTML + CSS + JavaScript | 降低学习曲线，聚焦可视化逻辑本身 |
整体数据流架构如下：
1.5 项目目录结构
为保障代码可维护性，项目采用分层目录结构，各模块职责清晰：
digital_worksite_dashboard/
├── app.py # Flask 应用入口
├── config.py # 配置文件（MQTT 地址、数据库路径等）
├── models/
│ └── device.py # 设备数据模型（SQLAlchemy ORM）
├── mqtt_client/
│ └── subscriber.py # MQTT 订阅与消息处理
├── routes/
│ ├── api.py # RESTful API 路由
│ └── pages.py # 页面路由
├── static/
│ ├── css/
│ │ └── dashboard.css # 看板样式
│ ├── js/
│ │ ├── echarts.min.js # ECharts 库
│ │ ├── mqtt.js # MQTT WebSocket 客户端
│ │ └── dashboard.js # 看板主逻辑
│ └── data/ # 模拟数据（开发阶段使用）
├── templates/
│ └── dashboard.html # 看板页面模板
└── requirements.txt # Python 依赖清单
避坑提示： 不要将 MQTT 客户端逻辑直接写在 app.py 中。分离到独立模块后，便于后期扩展多协议接入（如 CoAP、HTTP 轮询）。