weekly-plan/zzhz-smart-construction/README.md

郑州智慧工地 H5 应用

项目概述

郑州智慧工地信息化系统 H5 前端应用。

技术方案

前端技术栈

• 框架: 纯 HTML5 + CSS3 + Vanilla JavaScript（无框架依赖）
• 布局: CSS Grid + Flexbox
• 图表: Chart.js（轻量级）
• HTTP: Axios
• 构建: 暂无（纯静态页面）

后台 API 设计

基础信息

• 协议: RESTful HTTP API
• 认证: JWT Token
• 数据格式: JSON
• Base URL: https://api.zzhz-smart-construction.com（待配置）

API 端点设计

1. 隐患随手拍模块

方法	路径	说明	请求体/参数
POST	/api/v1/hazards	上报隐患	{location, type, level, description, images[]}
GET	/api/v1/hazards	隐患列表	?page&size&status&startDate&endDate
GET	/api/v1/hazards/{id}	隐患详情	-
PUT	/api/v1/hazards/{id}/status	更新状态	{status, handler, result}
POST	/api/v1/hazards/{id}/images	上传图片	multipart/form-data

隐患状态流转: pending → assigned → processing → resolved → closed

2. 塔吊监测模块

方法	路径	说明	请求体/参数
GET	/api/v1/tower-crane/realtime	实时数据	?deviceId
GET	/api/v1/tower-crane/history	历史数据	?deviceId&startTime&endTime
GET	/api/v1/tower-crane/alarms	报警记录	?deviceId&startDate&endDate
GET	/api/v1/tower-crane/devices	设备列表	-

实时数据字段:

{
  "deviceId": "TC-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "load": 2.5,        // 载重(吨)
  "amplitude": 45.0,  // 幅度(米)
  "height": 50.0,    // 高度(米)
  "rotation": 180,   // 回转角度(度)
  "windSpeed": 5.2,  // 风速(m/s)
  "status": "normal" // normal/warning/danger
}

3. 升降机监测模块

方法	路径	说明	请求体/参数
GET	/api/v1/elevator/realtime	实时数据	?deviceId
GET	/api/v1/elevator/history	历史数据	?deviceId&startTime&endTime
GET	/api/v1/elevator/alarms	报警记录	?deviceId&startDate&endDate
GET	/api/v1/elevator/devices	设备列表	-

实时数据字段:

{
  "deviceId": "EL-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "load": 800,        // 载重(kg)
  "height": 30.5,     // 高度(m)
  "speed": 1.2,      // 速度(m/s)
  "doorStatus": "closed",
  "status": "normal"
}

4. AI 分析模块

方法	路径	说明	请求体/参数
GET	/api/v1/ai/alarms	AI报警列表	?type&startDate&endDate&acknowledged
GET	/api/v1/ai/alarms/{id}	报警详情	-
PUT	/api/v1/ai/alarms/{id}/ack	确认报警	{operator, note}
GET	/api/v1/ai/analysis/results	分析结果	?startDate&endDate

5. 施工日志模块

方法	路径	说明	请求体/参数
POST	/api/v1/logs	创建日志	{title, content, type, weather, workers}
GET	/api/v1/logs	日志列表	?page&size&startDate&endDate&type
GET	/api/v1/logs/{id}	日志详情	-
PUT	/api/v1/logs/{id}	更新日志	{title, content, ...}
GET	/api/v1/logs/stats	统计分析	?startDate&endDate

6. 文件上传（OSS）

方法	路径	说明	请求体/参数
POST	/api/v1/upload/presign	获取预签名URL	{filename, contentType}
PUT	{presignedUrl}	直接上传到OSS	binary

响应:

{
  "uploadUrl": "https://oss.zzhz-smart-construction.com/hazards/xxx.jpg?签名参数",
  "fileUrl": "https://cdn.zzhz-smart-construction.com/hazards/xxx.jpg"
}

认证机制

Authorization: Bearer <JWT_TOKEN>

登录接口:

POST /api/v1/auth/login
Body: { username, password }
Response: { token, refreshToken, user }

错误响应格式

{
  "code": 40001,
  "message": "参数错误",
  "detail": "deviceId 不能为空"
}

分页响应格式

{
  "data": [],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 100,
    "totalPages": 5
  }
}

数据库设计（参考）

隐患表 (hazards)

CREATE TABLE hazards (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  location VARCHAR(255) NOT NULL,
  type ENUM('safety', 'general', 'serious') NOT NULL,
  level ENUM('low', 'medium', 'high') NOT NULL,
  description TEXT,
  images JSON,
  status ENUM('pending', 'assigned', 'processing', 'resolved', 'closed') DEFAULT 'pending',
  reporter_id BIGINT,
  handler_id BIGINT,
  resolved_at DATETIME,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

塔吊数据表 (tower_crane_data)

CREATE TABLE tower_crane_data (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  device_id VARCHAR(50) NOT NULL,
  load DECIMAL(5,2),
  amplitude DECIMAL(5,2),
  height DECIMAL(5,2),
  rotation DECIMAL(5,2),
  wind_speed DECIMAL(4,2),
  status ENUM('normal', 'warning', 'danger'),
  recorded_at DATETIME,
  INDEX idx_device_time (device_id, recorded_at)
);

施工日志表 (construction_logs)

CREATE TABLE construction_logs (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  title VARCHAR(255) NOT NULL,
  content TEXT,
  type ENUM('daily', 'weekly', 'incident') NOT NULL,
  weather VARCHAR(50),
  worker_count INT,
  author_id BIGINT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

技术架构图

┌─────────────────────────────────────────────────────────────┐
│                      H5 前端 (手机端)                        │
│    隐患随手拍 / 塔吊监测 / 升降机监测 / AI分析 / 施工日志      │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTPS
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                      API 网关 (Nginx)                       │
│                   JWT 认证 / 限流 / 路由                      │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ↓               ↓               ↓
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ 后台API  │    │ 实时数据  │    │ 文件服务  │
    │ Node.js  │    │ WebSocket│    │  OSS     │
    └────┬─────┘    └──────────┘    └──────────┘
         │
    ┌────┴─────┐
    ↓          ↓
┌────────┐  ┌────────┐
│MySQL/  │  │塔吊/升降│
│Postgres│  │机 API   │
└────────┘  └────────┘

部署方案

• 前端: CDN 静态部署（或 Nginx）
• 后台: Node.js + Express
• 数据库: PostgreSQL
• 文件存储: 阿里云 OSS / 腾讯云 COS
• 实时数据: WebSocket 长连接

项目结构

zzhz-smart-construction/
├── README.md              # 本文件
├── api-design.md          # API 设计文档（本文档）
├── SPEC.md                # 产品需求规格
├── 前端/
│   ├── index.html         # 首页
│   ├── hazard-report.html # 隐患随手拍
│   ├── tower-crane.html   # 塔吊监测
│   ├── elevator.html      # 升降机监测
│   ├── ai-analysis.html   # AI分析
│   ├── construction-log.html # 施工日志
│   ├── css/
│   │   └── style.css      # 样式文件
│   └── js/
│       ├── api.js         # API 调用
│       ├── app.js         # 主逻辑
│       └── charts.js      # 图表
└── 后台/
    ├── src/
    │   ├── routes/        # 路由
    │   ├── controllers/   # 控制器
    │   ├── models/        # 数据模型
    │   ├── services/      # 业务逻辑
    │   └── middleware/     # 中间件
    ├── package.json
    └── .env.example