Files

- 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/台账）

2026-04-14 16:53:33 +08:00

13 KiB

Raw Permalink Blame History

郑州智慧工地管理系统 - 产品设计规格书

版本: v0.2.1 状态: 设计完成（开发前置条件已确认）仓库: https://git.jesxion.com/jesxion/smart-project

文档索引

文档	说明
architecture.md	系统架构设计
api.md	后台 API 接口设计（含隐患、施工日志、AI分析）
database.md	数据库表结构设计（含新增表）
h5.md	H5 页面结构与交互设计
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

产品需求规格

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. 待确认

~~后台 API 公网部署地址~~ → 阿里云服务器（部署时配置）
~~河南三农设备推送的 appid / secret~~ → 部署时配置
~~OSS 存储路径规范~~ → 隐患照片 reports/、日志照片 logs/、AI 分析附件 ai/
~~JWT Secret 管理~~ → 环境变量 JWT_SECRET_KEY
~~设备初始台账导入方式~~ → 手动录入河南三农设备 SN

13 KiB Raw Permalink Blame History Unescape Escape