主页仪表板¶

本文引用的文件 - data/index.html - rest_api.c - webui_server.c - style.css - config_manager.h - network_manager.h - ble_gateway.h - webui_server.h - mqtt_client_wrapper.c - mqtt_client_wrapper.h

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考虑
故障排除指南
结论

简介¶

本文件为 ESP32S3 BLE 网关“主页仪表板”的前端开发文档，聚焦于主页的整体布局设计、系统状态展示区域、WiFi 连接状态、MQTT 连接状态与 BLE 扫描器状态的界面实现。文档解释状态指示器的设计原理、实时数据更新机制与用户交互流程，并提供卡片式布局的 CSS 样式实现、响应式设计适配与视觉反馈机制的技术细节。同时给出状态数据绑定、定时刷新与错误处理的 JavaScript 实现要点，以及系统版本信息、运行时间与内存使用情况的展示逻辑。

项目结构¶

该仓库包含两套前端实现与对应的后端 REST API： - 新版前端：data/index.html（极简卡片布局，仅包含系统状态、网络状态与 BLE 状态） - 老版前端：old_version/data/index.html 与 old_version/data/style.css（完整仪表板，含 WiFi、MQTT、BLE 扫描器等）

后端通过 REST API 提供状态数据与设备列表，WebUI 服务器负责静态资源与路由注册。

graph TB
subgraph "浏览器"
UI["主页仪表板<br/>data/index.html"]
Style["样式表<br/>data/style.css"]
end
subgraph "嵌入式Web服务器"
WebUI["WebUI服务器<br/>webui_server.c"]
REST["REST API处理器<br/>rest_api.c"]
end
subgraph "系统服务"
Config["配置管理<br/>config_manager.h"]
NetMgr["网络管理<br/>network_manager.h"]
BleGW["BLE网关接口<br/>ble_gateway.h"]
Mqtt["MQTT客户端封装<br/>mqtt_client_wrapper.c/.h"]
end
UI --> WebUI
UI --> REST
REST --> Config
REST --> NetMgr
REST --> BleGW
REST --> Mqtt
WebUI --> REST

图表来源 - data/index.html - webui_server.c - rest_api.c - config_manager.h - network_manager.h - ble_gateway.h - mqtt_client_wrapper.c

章节来源 - data/index.html - webui_server.c

核心组件¶

主页仪表板 HTML 结构与样式：采用卡片式网格布局，包含系统状态、网络状态与 BLE 状态三大区域，使用 CSS Grid 实现自适应排列。
实时数据更新：通过 JavaScript 定时调用 /api/status 接口，解析返回的 JSON 并更新 DOM 元素。
后端 REST API：提供 /api/status 返回系统版本、运行时间、可用内存、网络连接状态与 IP、接口名及 BLE 设备数量。
WebUI 服务器：注册 /、/api/status 等路由，承载前端页面与 API 服务。

章节来源 - data/index.html - rest_api.c - webui_server.c

架构总览¶

下图展示了从浏览器到后端服务的数据流与职责划分：

sequenceDiagram
participant Browser as "浏览器"
participant WebUI as "WebUI服务器"
participant REST as "REST API"
participant Sys as "系统服务"
Browser->>WebUI : 请求 /
WebUI-->>Browser : 返回 data/index.html
Browser->>REST : GET /api/status
REST->>Sys : 读取配置/网络/BLE状态
Sys-->>REST : 系统状态数据
REST-->>Browser : JSON 响应
Browser->>Browser : 更新DOM系统状态/网络状态/设备计数
Browser->>REST : 每5秒重复请求 /api/status

图表来源 - data/index.html - rest_api.c - webui_server.c

详细组件分析¶

卡片式布局与响应式设计¶

布局结构：容器采用最大宽度限制与居中对齐；卡片使用阴影与圆角提升可读性；状态网格使用 CSS Grid，自动适配列数。
响应式：在小屏设备上，网格会自动调整为单列，保证内容可读性。
视觉反馈：状态项中的值根据连接状态动态添加在线/离线类名，实现颜色区分。

章节来源 - data/index.html - data/index.html

系统状态展示区域¶

字段包括：网关ID、固件版本、运行时间（分钟）、可用堆内存（KB）。
数据绑定：通过 fetch 获取 /api/status，解析字段并填充对应 DOM 节点。
时间格式化：运行时间以秒为单位，前端转换为“分钟”显示。
内存格式化：字节数转为 KB 显示。

章节来源 - data/index.html - data/index.html - rest_api.c

网络状态展示区域¶

字段包括：连接状态（在线/离线）、IP 地址、接口名。
连接状态样式：根据是否连接动态切换在线/离线样式类，实现颜色变化与视觉反馈。
数据来源：/api/status 中的 network 对象，包含连接标志、IP 与接口名。

章节来源 - data/index.html - data/index.html - rest_api.c

BLE 扫描器状态展示区域¶

字段包括：发现设备数量。
数据来源：/api/status 中的 ble.devices。
交互：老版前端包含“开始扫描/停止扫描”按钮，新版前端未包含该功能入口。

章节来源 - data/index.html - data/index.html - rest_api.c

实时数据更新机制与定时刷新¶

初次加载即调用一次状态更新函数。
使用定时器每 5 秒轮询一次 /api/status，确保状态面板实时反映系统状态。
错误处理：当请求失败或解析异常时，不更新状态，避免覆盖当前有效数据。

章节来源 - data/index.html - data/index.html

状态指示器设计原理与视觉反馈¶

在老版前端中，存在顶部状态指示灯 dot，根据 API 请求结果切换在线/离线样式类，实现全局状态可视化。
新版前端未保留该指示灯，但通过状态项的颜色变化（在线/离线）实现局部反馈。

章节来源 - old_version/data/index.html - old_version/data/style.css

用户交互流程（老版前端）¶

页面加载后，自动拉取系统状态、配置、过滤条件与设备列表。
支持自动刷新开关，开启后定时刷新设备列表。
支持设备详情弹窗、连接/断开设备、应用/清除过滤条件、保存配置与重启设备等操作。

章节来源 - old_version/data/index.html

API 定义与数据模型¶

GET /api/status：返回系统状态、网络状态与 BLE 状态。
GET /api/devices：返回 BLE 设备列表。
POST /api/devices/scan：启用/禁用 BLE 扫描。
GET /api/config：获取配置。
PUT /api/config：更新配置。

章节来源 - rest_api.c - webui_server.c

数据模型映射¶

系统状态字段：gateway_id、firmware、uptime、heap_free、network（connected、ip、interface）、ble（devices）。
设备列表字段：mac、name、rssi、connected。

章节来源 - rest_api.c - rest_api.c

依赖关系分析¶

graph LR
Index["data/index.html"] --> REST["components/rest_api/rest_api.c"]
REST --> ConfigMgr["include/config_manager.h"]
REST --> NetMgr["include/network_manager.h"]
REST --> BleGW["include/ble_gateway.h"]
WebUI["old_version/components/webui_server/webui_server.c"] --> REST
WebUI --> Style["old_version/data/style.css"]

图表来源 - data/index.html - rest_api.c - config_manager.h - network_manager.h - ble_gateway.h - webui_server.c - style.css

章节来源 - webui_server.c - rest_api.c

性能考虑¶

定时刷新频率：主页每 5 秒刷新一次，平衡了实时性与网络负载。
数据量控制：/api/devices 返回固定上限的设备列表，避免一次性传输过多数据。
前端渲染：DOM 更新集中在状态面板，避免频繁重排与重绘。
样式优化：使用 CSS Grid 与 Flex 布局，减少复杂选择器层级，提升渲染效率。

故障排除指南¶

页面空白或状态不更新
检查 /api/status 是否可达，确认 WebUI 服务器已启动且路由注册成功。
查看浏览器开发者工具 Network 面板，确认请求返回 200 且 JSON 格式正确。
网络状态始终显示离线
确认网络管理模块已初始化并连接成功；检查 /api/status 中 network.connected 字段。
设备数量不变化
确认 BLE 扫描已启用；检查 /api/devices 是否返回设备列表。
样式异常
确认 data/style.css 或老版 style.css 已正确加载；检查媒体查询在目标设备上的表现。

章节来源 - webui_server.h - webui_server.c

结论¶

本主页仪表板通过简洁的卡片式布局与实时数据刷新，实现了对系统状态、网络状态与 BLE 设备数量的直观展示。前端通过定时轮询与条件样式实现良好的视觉反馈，后端 REST API 提供稳定的数据源。建议在保持现有性能的基础上，逐步引入更丰富的交互与状态指示器，以进一步提升用户体验。