# 郑州智慧工地 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` | 设备列表 | - |

**实时数据字段**:
```json
{
  "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` | 设备列表 | - |

**实时数据字段**:
```json
{
  "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` |

**响应**:
```json
{
  "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 }
```

#### 错误响应格式

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

#### 分页响应格式

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

### 数据库设计（参考）

#### 隐患表 (hazards)
```sql
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)
```sql
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)
```sql
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
```