Jesxion
86777f585e
- SPEC.md: 项目概览与文档索引 - docs/architecture.md: 系统架构设计 - docs/api.md: 后台 API 接口设计 - docs/database.md: 数据库表结构设计 - docs/h5.md: H5 页面结构与交互设计 - docs/offline.md: 离线数据方案 状态: 设计中，待设备API协议确认后细化
300 lines
14 KiB
Markdown
300 lines
14 KiB
Markdown
# H5 页面结构与交互设计
|
||
|
||
> 状态: 设计中
|
||
|
||
---
|
||
|
||
## 1. 技术选型
|
||
|
||
| 项目 | 选型 |
|
||
|------|------|
|
||
| 页面渲染 | 原生 HTML5 + CSS3 + Vanilla JS |
|
||
| UI 框架 | 无，响应式布局手工实现 |
|
||
| 图表 | ECharts（CDN 引入） |
|
||
| 字体图标 | 阿里巴巴矢量图标库（iconfont） |
|
||
| 构建 | 无构建步骤，单 HTML 文件按模块拆分 |
|
||
|
||
**设计原则**：
|
||
- 移动端优先（适配 375px ~ 414px 宽度）
|
||
- 低依赖，不依赖任何 JS 框架
|
||
- 离线可缓存核心资产（Service Worker）
|
||
|
||
---
|
||
|
||
## 2. 页面清单
|
||
|
||
| 页面 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| 登录 | `/login.html` | 账号密码登录 |
|
||
| 首页仪表盘 | `/index.html` | 设备统计、预警统计、快捷入口 |
|
||
| 设备列表 | `/devices.html` | 塔吊/升降机分类列表 |
|
||
| 设备详情 | `/device.html?id=xxx` | 实时数据 + 历史曲线 |
|
||
| 预警列表 | `/alerts.html` | 预警推送列表 |
|
||
| 预警详情 | `/alert.html?id=xxx` | 预警详情 + 处理操作 |
|
||
| 个人中心 | `/profile.html` | 个人信息、设置 |
|
||
|
||
---
|
||
|
||
## 3. 页面结构
|
||
|
||
### 3.1 首页仪表盘 `/index.html`
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ ☰ 郑州智慧工地 [👤 个人中心] │ ← 顶栏
|
||
├──────────────────────────────────────┤
|
||
│ │
|
||
│ ┌────────────┐ ┌────────────┐ │
|
||
│ │ 塔吊 │ │ 升降机 │ │ ← 设备数量卡片
|
||
│ │ 12 台 │ │ 8 台 │ │
|
||
│ │ 12 在线 │ │ 8 在线 │ │
|
||
│ └────────────┘ └────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 今日预警 │ │ ← 预警统计卡片
|
||
│ │ 危险 2 警告 5 │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ 最新预警 │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 🔴 1号塔吊 载重超限 │ │ ← 预警列表（最新5条）
|
||
│ │ 10:25 │ │
|
||
│ ├──────────────────────────────┤ │
|
||
│ │ 🟡 3号升降机 风速过大 │ │
|
||
│ │ 10:20 │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ [查看全部预警] │
|
||
│ │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 设备列表 `/devices.html`
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ ☰ 设备列表 [筛选 ▼] │
|
||
├──────────────────────────────────────┤
|
||
│ [全部] [塔吊] [升降机] │ ← Tab 切换
|
||
├──────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 🏗️ 1号塔吊 🟢 在线 │ │ ← 设备卡片
|
||
│ │ QTZ500 | A区施工现场 │ │
|
||
│ │ 最后在线: 10:30 │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 🏗️ 2号塔吊 ⚫ 离线 │ │
|
||
│ │ QTZ500 | B区施工现场 │ │
|
||
│ │ 最后离线: 04-13 18:00 │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.3 设备详情 `/device.html`
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ ← 返回 1号塔吊 │
|
||
├──────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 实时数据面板 │ │ ← 关键指标卡片
|
||
│ │ 载重 幅度 起升高度 │ │
|
||
│ │ 45.2kN 30.5m 85.0m │ │
|
||
│ │ │ │
|
||
│ │ 风速 力矩 回转角度 │ │
|
||
│ │ 5.2m/s 320.5 120.5° │ │
|
||
│ │ │ │
|
||
│ │ ⚠️ 载重超限 │ │ ← 告警状态
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ 历史趋势（最近24小时） │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 📈 ECharts 折线图 │ │ ← ECharts 图表
|
||
│ │ 载重 / 幅度 / 风速 曲线 │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ [ 刷新 ] │
|
||
│ │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.4 预警列表 `/alerts.html`
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ 预警中心 [筛选 ▼] │
|
||
├──────────────────────────────────────┤
|
||
│ [全部] [危险] [警告] [已处理] │ ← Tab 筛选
|
||
├──────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 🔴 载重超限 │ │ ← 危险预警（红色）
|
||
│ │ 1号塔吊 | 2026-04-14 10:25 │ │
|
||
│ │ 当前45.2kN，超过额定40kN │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 🟡 风速过大 │ │ ← 警告预警（黄色）
|
||
│ │ 3号升降机 | 2026-04-14 10:20 │ │
|
||
│ │ 当前8.5m/s，超过阈值6m/s │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.5 预警详情 `/alert.html`
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ ← 返回 预警详情 │
|
||
├──────────────────────────────────────┤
|
||
│ │
|
||
│ 🔴 危险 │
|
||
│ │
|
||
│ 载重超限 │
|
||
│ │
|
||
│ 设备: 1号塔吊（QTZ500） │
|
||
│ 位置: A区施工现场 │
|
||
│ 时间: 2026-04-14 10:25:00 │
|
||
│ │
|
||
│ 当前载重: 45.2 kN │
|
||
│ 额定载重: 40.0 kN（阈值） │
|
||
│ 超限幅度: 13% │
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 处理方式: │ │
|
||
│ │ │ │
|
||
│ │ [确认处理] [忽略] │ │ ← 操作按钮
|
||
│ │ │ │
|
||
│ │ 备注: ____________________ │ │
|
||
│ │ │ │
|
||
│ │ [提交] │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.6 个人中心 `/profile.html`
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ ← 返回 个人中心 │
|
||
├──────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────┐ │
|
||
│ │ 👤 │ │
|
||
│ └──────────┘ │
|
||
│ 张三（管理员） │
|
||
│ 138****1234 │
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 📊 预警接收设置 │ │
|
||
│ │ [ ] 危险预警推送 │ │
|
||
│ │ [ ] 警告预警推送 │ │
|
||
│ │ [x] 短信通知 │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 🔔 消息推送设置 │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────┐ │
|
||
│ │ 🔐 修改密码 │ │
|
||
│ └──────────────────────────────┘ │
|
||
│ │
|
||
│ [退出登录] │
|
||
│ │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 页面交互
|
||
|
||
### 4.1 API 请求
|
||
|
||
所有页面通过 `fetch` 调用后台 API，基础封装：
|
||
|
||
```javascript
|
||
// api.js
|
||
const API_BASE = '/v1';
|
||
|
||
async function api(endpoint, options = {}) {
|
||
const token = localStorage.getItem('token');
|
||
const resp = await fetch(API_BASE + endpoint, {
|
||
...options,
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'Authorization': token ? `Bearer ${token}` : '',
|
||
...options.headers,
|
||
}
|
||
});
|
||
if (resp.status === 401) {
|
||
location.href = '/login.html';
|
||
return;
|
||
}
|
||
const json = await resp.json();
|
||
if (json.code !== 0) {
|
||
alert(json.message);
|
||
return;
|
||
}
|
||
return json.data;
|
||
}
|
||
```
|
||
|
||
### 4.2 数据加载流程
|
||
|
||
```
|
||
页面加载
|
||
│
|
||
▼
|
||
检查登录状态（localStorage.token）
|
||
│
|
||
├─ 无 token → 跳转 login.html
|
||
│
|
||
└─ 有 token → API 请求
|
||
│
|
||
├─ 成功 → 渲染页面
|
||
│
|
||
└─ 失败 → 显示错误提示
|
||
```
|
||
|
||
### 4.3 实时数据刷新
|
||
|
||
- **策略**: 首次加载后，每 **30 秒**自动刷新实时数据
|
||
- **实现**: `setInterval` 定时调用 `GET /devices/{id}/realtime`
|
||
- **优化**: 仅在设备详情页刷新，其他页面用户主动下拉刷新
|
||
|
||
### 4.4 离线缓存
|
||
|
||
使用 **Service Worker** 缓存静态资源：
|
||
|
||
```javascript
|
||
// 缓存策略：Network First, Fallback to Cache
|
||
// 缓存内容：HTML / CSS / JS / iconfont 字体
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 响应式断点
|
||
|
||
| 断点 | 宽度 | 适配 |
|
||
|------|------|------|
|
||
| mobile-s | 320px ~ 374px | 小屏手机 |
|
||
| mobile-l | 375px ~ 413px | 主流手机 |
|
||
| tablet | 768px ~ 1023px | 平板 |
|
||
| desktop | 1024px+ | 桌面端 |
|
||
|
||
---
|
||
|
||
## 6. 待确认
|
||
|
||
- [ ] 预警推送机制（轮询 vs WebSocket）
|
||
- [ ] 登录 Session 管理方案（JWT 有效期）
|
||
- [ ] 是否有扫码登录需求
|
||
- [ ] 报表导出（H5 直接拉 OSS 预签名 URL）
|