Jesxion
cb0ef8c30c
- architecture.md: 全面重写，对齐 Node.js+MySQL 技术栈， 新增三个模块（隐患随手拍/施工日志/AI分析）到模块列表和架构图， 更新数据流、租户隔离模型、部署架构、安全设计 - h5.md: 补充 6 个新页面 wireframe（3.7~3.14）， 更新页面清单（15个页面），API endpoint 前缀 /api → /v1， 更新已知待确认项为已确认状态 - offline.md: 补充 hazards/construction_logs/ai_analyses 三个 IndexedDB store，更新刷新策略表， 补充 6 种离线操作类型（action 类型表） - SPEC.md: 状态升级为"设计完成"，版本升至 v0.2.1， 所有待确认项均已确认（部署地址/推送凭证/OSS路径/JWT/台账）
359 lines
13 KiB
Markdown
359 lines
13 KiB
Markdown
# 郑州智慧工地管理系统 - 产品设计规格书
|
||
|
||
> 版本: v0.2.1
|
||
> 状态: 设计完成（开发前置条件已确认）
|
||
> 仓库: https://git.jesxion.com/jesxion/smart-project
|
||
|
||
---
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [architecture.md](./docs/architecture.md) | 系统架构设计 |
|
||
| [api.md](./docs/api.md) | 后台 API 接口设计（含隐患、施工日志、AI分析） |
|
||
| [database.md](./docs/database.md) | 数据库表结构设计（含新增表） |
|
||
| [h5.md](./docs/h5.md) | H5 页面结构与交互设计 |
|
||
| [offline.md](./docs/offline.md) | 离线数据方案 |
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
### 背景
|
||
|
||
郑州智慧工地项目面向施工现场安全管理的数字化升级需求，提供塔吊、升降机等特种设备的实时监测与预警功能，同时提供隐患随手拍、施工日志、AI 智能分析等现场管理能力。
|
||
|
||
### 核心功能
|
||
|
||
- **设备监控**：塔吊、升降机实时数据接入（来自已有 API）
|
||
- **预警管理**：设备异常实时推送与记录
|
||
- **隐患随手拍**：现场隐患拍照上报，全流程跟踪处理
|
||
- **施工日志**：每日施工记录，含照片附件
|
||
- **AI 智能分析**：设备端 AI 分析结果展示（人员安全/设备异常/环境风险）
|
||
- **H5 移动端**：移动端随时查看设备状态、接收预警、记录隐患
|
||
|
||
### 技术栈
|
||
|
||
| 层级 | 技术选型 |
|
||
|------|----------|
|
||
| 后台 API | Node.js / Express + TypeScript |
|
||
| 数据库 | MySQL 8.0 |
|
||
| H5 前端 | 原生 HTML/CSS/JS，无框架依赖 |
|
||
| 文件存储 | 阿里云 OSS（Bucket: jesxion-ai-studio, Region: oss-cn-beijing） |
|
||
| 设备数据 | 河南三农厂家系统推送（统一推送接口 POST /input/post/call） |
|
||
|
||
### 文档更新记录
|
||
|
||
| 日期 | 版本 | 更新内容 |
|
||
|------|------|----------|
|
||
| 2026-04-14 | v0.1.0 | 初始化草稿，架构设计 |
|
||
| 2026-04-14 | v0.1.1 | 锁定预警轮询、JWT 7天、OSS Bucket 配置 |
|
||
| 2026-04-14 | v0.1.2 | 锁定 SQLite 数据库 |
|
||
| 2026-04-14 | v0.1.3 | 确认设备 API 自带预警判断，移除本地阈值配置 |
|
||
| 2026-04-14 | v0.1.4 | 确认河南三农推送协议（8个接口，appid/secret部署时配置） |
|
||
|| 2026-04-14 | v0.2.1 | API设计补充（隐患随手拍/施工日志/AI分析），数据库表结构完善（MySQL+project_id隔离） |
|
||
|
||
---
|
||
|
||
## 产品需求规格
|
||
|
||
### 1. 用户与权限模型
|
||
|
||
#### 1.1 用户角色
|
||
|
||
系统区分三种身份标识：**项目经理 / 安全负责人 / 安全员**。
|
||
|
||
- 身份仅作为记录字段，不参与权限判断
|
||
- 所有在同一项目下的用户，使用完全相同的功能
|
||
- 数据变更时记录操作人身份和时间戳
|
||
|
||
#### 1.2 账号体系
|
||
|
||
- **一人一项目**：一个用户绑定一个施工项目，不可跨项目操作
|
||
- **一项目多用户**：一个施工项目可包含多个用户（不同身份）
|
||
- **用户身份字段**：`users.role` ∈ {项目经理, 安全负责人, 安全员}
|
||
|
||
#### 1.3 认证机制
|
||
|
||
- JWT Token 认证，有效期 7 天
|
||
- 登录接口：`POST /v1/auth/login`，返回 token + user 信息
|
||
- Token 刷新：MVP 阶段直接重新登录，refresh token 后续扩展
|
||
|
||
---
|
||
|
||
### 2. 租户隔离模型
|
||
|
||
> **项目级逻辑租户** — 所有表通过 `project_id` 字段区分项目归属。用户在注册/创建时绑定 `project_id`，API 中间件在每个请求中自动注入当前用户的 `project_id` 条件，数据查询均以此过滤，实现项目间完全隔离。
|
||
|
||
#### 2.1 涉及 project_id 隔离的表
|
||
|
||
| 表名 | 用途 |
|
||
|------|------|
|
||
| `users` | 用户属于项目 |
|
||
| `devices` | 设备属于项目（塔吊、升降机台账） |
|
||
| `device_realtime` | 设备实时数据，属于项目 |
|
||
| `device_history` | 设备历史数据，属于项目 |
|
||
| `alert_records` | 预警记录，属于项目（通过 device 关联） |
|
||
| `hazards` | 隐患随手拍，属于项目 |
|
||
| `construction_logs` | 施工日志，属于项目 |
|
||
| `ai_analysis_results` | AI 分析结果，属于项目 |
|
||
| `oss_files` | OSS 文件索引，属于项目 |
|
||
|
||
#### 2.2 数据隔离原则
|
||
|
||
- 用户注册时由管理员分配 `project_id`
|
||
- API 中间件从 JWT Token 解析用户 `project_id`，注入到所有查询条件
|
||
- 所有数据表均以 `project_id` 为隔离字段
|
||
- 设备数据通过 `devices.project_id` 间接隔离
|
||
|
||
---
|
||
|
||
### 3. 功能模块详细规格
|
||
|
||
#### 3.1 模块一：隐患随手拍
|
||
|
||
##### 3.1.1 业务流程
|
||
|
||
```
|
||
上报人提交隐患
|
||
↓ [状态: pending]
|
||
↓ 自动记录: 上报人、上报时间、上报人身份、GPS坐标
|
||
↓
|
||
任意项目成员认领 ← 认领操作
|
||
↓ [状态: assigned]
|
||
↓ 自动记录: 认领人、认领时间、认领人身份
|
||
↓
|
||
认领人处理完成 ← 处理说明（选填）
|
||
↓ [状态: resolved]
|
||
↓ 自动记录: 处理人、处理时间、处理人身份
|
||
↓
|
||
结束
|
||
```
|
||
|
||
**说明**：
|
||
- 隐患提交后不可删除，仅可被认领和处理
|
||
- 全流程自动记录操作人和时间戳，无需手动填写
|
||
- 任何人可查看项目内所有隐患记录
|
||
- 隐患照片上传到 OSS，预签名 URL 访问
|
||
|
||
##### 3.1.2 隐患分类标准
|
||
|
||
参照《企业伤亡事故分类》（GB/T 6441-1986）及《房屋市政工程生产安全重大事故隐患判定标准（2022版）》制定：
|
||
|
||
**隐患类别（13类）**：
|
||
|
||
| 序号 | 类别代码 | 类别名称 | 说明 |
|
||
|------|---------|---------|------|
|
||
| 1 | fall | 高处坠落 | 临边、洞口、攀登、悬空、交叉作业时坠落 |
|
||
| 2 | object_strike | 物体打击 | 失控物体的惯性力造成的人身伤害 |
|
||
| 3 | mechanical | 机械伤害 | 机械设备运动部件、工具等伤人 |
|
||
| 4 | electric | 触电 | 电流、静电伤害 |
|
||
| 5 | collapse | 坍塌 | 基坑、沟槽、模板、脚手架、建筑物/构筑物倒塌 |
|
||
| 6 | fire | 火灾 | 违反消防法规、违章动火等 |
|
||
| 7 | lifting | 起重伤害 | 起重机械作业中伤害 |
|
||
| 8 | vehicle | 车辆伤害 | 机动车辆造成的人身伤害 |
|
||
| 9 | blasting | 放炮 | 爆破作业中伤害 |
|
||
| 10 | drowning | 淹溺 | 落水窒息 |
|
||
| 11 | burn | 灼烫 | 高温/化学物质灼伤 |
|
||
| 12 | construction | 现场临建设施 | 办公/宿舍/食堂等临建坍塌 |
|
||
| 13 | other | 其他伤害 | 不属于上述类别的伤害 |
|
||
|
||
**严重程度分级**：
|
||
|
||
| 等级 | 定义 | 依据 |
|
||
|------|------|------|
|
||
| 一般 | 危害程度较小，发现后能立即整改排除 | 《安全生产事故隐患排查治理暂行规定》 |
|
||
| 较大 | 危害程度较重，应局部停产停业，经一定时间治理才能排除 | 同上 |
|
||
| 重大 | 危害程度严重，可能导致群死群伤或重大经济损失 | 《房屋市政工程生产安全重大事故隐患判定标准（2022版）》 |
|
||
|
||
**状态流转**：
|
||
|
||
```
|
||
pending → assigned → resolved
|
||
```
|
||
|
||
- `pending`：待处理（新建）
|
||
- `assigned`：已认领（处理中）
|
||
- `resolved`：已处理（关闭）
|
||
|
||
##### 3.1.3 H5 页面
|
||
|
||
| 页面 | 路由 | 功能 |
|
||
|------|------|------|
|
||
| 隐患随手拍 | `/report.html` | 拍照 + 表单提交 |
|
||
| 隐患列表 | `/reports.html` | 项目内隐患列表，含筛选（状态/类别/严重程度） |
|
||
| 隐患详情 | `/report.html?id=xxx` | 隐患详情 + 认领/处理操作 |
|
||
|
||
##### 3.1.4 API 端点
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/v1/hazards` | 上报隐患 |
|
||
| GET | `/v1/hazards` | 隐患列表（分页+筛选） |
|
||
| GET | `/v1/hazards/:id` | 隐患详情 |
|
||
| POST | `/v1/hazards/:id/assign` | 认领隐患 |
|
||
| POST | `/v1/hazards/:id/resolve` | 处理完成 |
|
||
|
||
详见 `docs/api.md` 隐患随手拍模块。
|
||
|
||
---
|
||
|
||
#### 3.2 模块二：施工日志
|
||
|
||
##### 3.2.1 业务流程
|
||
|
||
```
|
||
项目成员写日志
|
||
↓
|
||
填写：日期、施工部位、作业内容、人员出勤（必填）
|
||
填写：现场照片、安全问题、备注（选填）
|
||
↓
|
||
提交
|
||
↓
|
||
自动记录：撰写人、撰写时间、撰写人身份
|
||
↓
|
||
日志不可编辑，只可追加查看
|
||
```
|
||
|
||
**说明**：
|
||
- 日志提交后不可修改/删除，保证记录真实性
|
||
- 照片上传 OSS
|
||
- 支持按日期范围筛选
|
||
|
||
##### 3.2.2 日志字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| date | date | 是 | 日志日期 |
|
||
| part | string | 是 | 施工部位 |
|
||
| content | text | 是 | 作业内容 |
|
||
| workers | int | 是 | 人员出勤人数 |
|
||
| equipment | string[] | 否 | 设备运行（tower_crane / elevator 多选） |
|
||
| photos | string[] | 否 | 现场照片 OSS URL 列表 |
|
||
| safety_note | text | 否 | 安全问题描述 |
|
||
| note | text | 否 | 备注 |
|
||
| author_id | int | 自动 | 撰写人 ID（从 token 解析） |
|
||
| author_role | string | 自动 | 撰写人身份（从 token 解析） |
|
||
| created_at | datetime | 自动 | 创建时间 |
|
||
|
||
##### 3.2.3 H5 页面
|
||
|
||
| 页面 | 路由 | 功能 |
|
||
|------|------|------|
|
||
| 日志列表 | `/logs.html` | 列表 + 筛选 + 新建入口 |
|
||
| 写日志 | `/log.html` | 新建日志（含照片上传） |
|
||
| 日志详情 | `/log.html?id=xxx` | 查看日志详情 |
|
||
|
||
##### 3.2.4 API 端点
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/v1/logs` | 新建日志 |
|
||
| GET | `/v1/logs` | 日志列表（分页+日期筛选） |
|
||
| GET | `/v1/logs/:id` | 日志详情 |
|
||
|
||
详见 `docs/api.md` 施工日志模块。
|
||
|
||
---
|
||
|
||
#### 3.3 模块三：AI 智能分析
|
||
|
||
##### 3.3.1 数据来源
|
||
|
||
AI 分析由河南三农设备端驱动，设备端 AI 分析完成后，通过统一推送接口 `POST /input/post/call` 将结构化结果推送到后台。后台接收后存入 `ai_analysis_results` 表，H5 提供查看入口。
|
||
|
||
##### 3.3.2 AI 分析类型
|
||
|
||
| 类型代码 | 类型名称 | 说明 |
|
||
|---------|---------|------|
|
||
| personnel_safety | 人员安全 | 人员靠近危险区域、违规操作等 |
|
||
| equipment_anomaly | 设备异常 | 载重超限、风速过大、机械故障前兆等 |
|
||
| environmental_risk | 环境风险 | 地基沉降、倾斜等 |
|
||
|
||
##### 3.3.3 数据字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | UUID |
|
||
| project_id | int | 所属项目 |
|
||
| device_id | string | 关联设备 ID |
|
||
| device_name | string | 设备名称（冗余） |
|
||
| analysis_type | string | 分析类型 |
|
||
| confidence | decimal | 置信度 0.00~1.00 |
|
||
| description | text | AI 分析描述 |
|
||
| suggestion | text | 建议措施（AI 生成） |
|
||
| triggered_at | datetime | 触发时间 |
|
||
| created_at | datetime | 记录创建时间 |
|
||
|
||
##### 3.3.4 H5 页面
|
||
|
||
| 页面 | 路由 | 功能 |
|
||
|------|------|------|
|
||
| AI 分析列表 | `/ai-analyses.html` | AI 分析结果列表 |
|
||
| AI 分析详情 | `/ai-analysis.html?id=xxx` | 分析详情 + 建议措施 |
|
||
|
||
##### 3.3.5 API 端点
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/v1/ai/analyses` | AI 分析列表（分页+类型筛选） |
|
||
| GET | `/v1/ai/analyses/:id` | 分析详情 |
|
||
|
||
详见 `docs/api.md` AI 智能分析模块。
|
||
|
||
---
|
||
|
||
### 4. 部署架构
|
||
|
||
| 组件 | 部署方式 |
|
||
|------|----------|
|
||
| 后台 API | 阿里云函数计算（FC）或轻量服务器 |
|
||
| MySQL | 阿里云 RDS 或轻量服务器自建 |
|
||
| OSS | 阿里云 OSS 标准存储 |
|
||
| H5 静态资源 | Nginx 同一域名反向代理，或 OSS + CDN |
|
||
|
||
**前后端同域**：API 和静态资源共用同一域名，Nginx 反向代理到后端服务。
|
||
|
||
---
|
||
|
||
### 5. 安全设计
|
||
|
||
| 措施 | 说明 |
|
||
|------|------|
|
||
| HTTPS | 全链路 HTTPS，证书由阿里云管理 |
|
||
| Token 认证 | API 请求携带 JWT Token |
|
||
| CORS | 限制允许的 H5 域名 |
|
||
| OSS 鉴权 | H5 通过后台签发临时 URL 访问 OSS 文件 |
|
||
| 输入校验 | Express + Joi/Pydantic（根据技术栈选择）全量参数校验 |
|
||
| SQL 注入防护 | 参数化查询，不拼接 SQL 字符串 |
|
||
| 项目隔离 | 中间件层强制注入 project_id 过滤条件 |
|
||
|
||
---
|
||
|
||
### 6. 验收标准
|
||
|
||
#### MVP 完成条件
|
||
|
||
| 模块 | 验收标准 |
|
||
|------|---------|
|
||
| 用户认证 | 可登录/登出，JWT 有效期内正常访问 |
|
||
| 首页仪表盘 | 展示设备统计（塔吊/升降机数量+在线状态）、今日预警统计 |
|
||
| 设备列表 | 可按类型筛选，设备卡片显示名称+型号+位置+在线状态 |
|
||
| 设备详情 | 实时数据面板，历史数据图表（ECharts） |
|
||
| 预警列表 | 按级别/状态筛选，处理/忽略操作 |
|
||
| 隐患随手拍 | 拍照 + GPS + 类别 + 严重程度提交，认领和处理全流程 |
|
||
| 施工日志 | 填写并提交，含照片附件，展示列表和详情 |
|
||
| AI 智能分析 | 展示 AI 分析结果列表和详情 |
|
||
| 租户隔离 | 不同项目用户数据完全隔离 |
|
||
|
||
---
|
||
|
||
### 7. 待确认
|
||
|
||
- [x] ~~后台 API 公网部署地址~~ → 阿里云服务器（部署时配置）
|
||
- [x] ~~河南三农设备推送的 appid / secret~~ → 部署时配置
|
||
- [x] ~~OSS 存储路径规范~~ → 隐患照片 `reports/`、日志照片 `logs/`、AI 分析附件 `ai/`
|
||
- [x] ~~JWT Secret 管理~~ → 环境变量 `JWT_SECRET_KEY`
|
||
- [x] ~~设备初始台账导入方式~~ → 手动录入河南三农设备 SN
|