jesxion/smart-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
152 Commits 2 Branches 0 Tags
main
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

郑州智慧工地管理系统

面向施工现场安全管理的数字化升级方案，提供塔吊/升降机等特种设备实时监测、隐患随手拍、施工日志、AI 智能分析等功能。

目录

  1. 仓库概览
  2. 目录结构
  3. 技术栈
  4. 环境前提
  5. 本地开发
  6. 构建
  7. 生产部署建议
  8. Nginx 反向代理示例
  9. 数据库与环境变量说明
  10. 常见问题 FAQ

1. 仓库概览

本仓库包含三个可独立运行的子项目：

子项目 路径 说明
server server/ 后端 API 服务，Node.js / Express + TypeScript，依赖 MySQL 8.0
h5-app h5-app/ 移动端 H5，React 18 + antd-mobile，面向施工现场用户
admin-web admin-web/ 管理后台，React 19 + Ant Design，面向平台管理员

当前实现状态说明

  • server：核心 API 已实现（认证、隐患管理、施工日志、OSS 文件、设备接入层等），测试套件需要完整的 MySQL 环境才能运行。
  • h5-app：移动端功能实现中，测试可在不连接后端的情况下独立运行。
  • admin-web：管理后台功能实现中，测试可在不连接后端的情况下独立运行。

目标生产架构（含阿里云 OSS、河南三农设备推送、完整多项目租户隔离）请参见 SPEC.md 和 docs/ 目录。

2. 目录结构

smart-project/
├── server/             # 后端 API 服务
│   ├── src/
│   │   ├── config/     # 环境变量解析（Zod 校验）
│   │   ├── lib/        # 数据库连接池
│   │   ├── middleware/  # 认证、项目租户注入
│   │   ├── repositories/ # 数据访问层
│   │   ├── routes/     # API 路由（auth / hazards / logs / files 等）
│   │   ├── services/   # 业务逻辑层
│   │   ├── types/      # TypeScript 类型定义
│   │   └── index.ts    # 服务入口
│   ├── schema.sql      # MySQL 建表脚本
│   ├── .env.example    # 环境变量模板
│   └── package.json
│
├── h5-app/             # 移动端 H5（React 18 + antd-mobile）
│   ├── src/
│   │   ├── features/   # 各功能模块（设备、预警、隐患、日志等）
│   │   ├── pages/      # 页面路由入口
│   │   ├── lib/        # 工具函数、API 客户端
│   │   └── main.tsx    # 入口
│   ├── .env            # 环境变量（含说明注释）
│   └── package.json
│
├── admin-web/          # 管理后台（React 19 + Ant Design）
│   ├── src/
│   │   ├── features/   # 各功能模块
│   │   ├── lib/        # 工具函数、API 客户端
│   │   └── main.tsx    # 入口
│   └── package.json
│
├── docs/               # 产品与架构设计文档
│   ├── architecture.md
│   ├── api.md
│   ├── database.md
│   ├── h5.md
│   └── offline.md
└── SPEC.md             # 产品设计规格书（主文档）

3. 技术栈

当前仓库可运行方案

层级 技术 版本
后端 API Node.js + Express + TypeScript Express ^4.18，TS ^5.3
数据库 MySQL 8.0 mysql2 驱动
认证 JWT jsonwebtoken ^9.0，有效期 7 天
密码哈希 bcryptjs ^3.0
参数校验 Zod ^4.3
移动端 H5 React 18 + antd-mobile React ^18.3，antd-mobile ^5.36
管理后台 React 19 + Ant Design React ^19.2，antd ^6.3
前端构建 Vite h5-app: ^5.4；admin-web: ^8.0
前端路由 React Router DOM h5-app: ^6.26；admin-web: ^7.14
测试框架 Vitest 各子项目独立

目标生产架构（规划中）

层级 技术 说明
文件存储 阿里云 OSS Bucket: jesxion-ai-studio，Region: oss-cn-beijing
设备数据接入 河南三农统一推送 POST /input/post/call
多租户隔离 project_id 贯穿全链路 JWT 解析 → 中间件注入 → 每条查询过滤

4. 环境前提

通用

  • Node.js ≥ 18（推荐 20 LTS）
  • npm ≥ 9

后端（server）

  • MySQL 8.0 — 本地或远程实例均可
  • 已按 server/schema.sql 初始化数据库

前端（h5-app / admin-web）

  • 无额外系统依赖；npm install 后即可启动

5. 本地开发

5.1 安装依赖

# 后端
cd server && npm install

# 移动端 H5
cd h5-app && npm install

# 管理后台
cd admin-web && npm install

5.2 初始化数据库

# 登录 MySQL，执行建表脚本
mysql -u root -p < server/schema.sql

5.3 配置后端环境变量

cp server/.env.example server/.env
# 按实际情况编辑 server/.env

server/.env 最小配置示例：

PORT=3000

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=smart_project

# 至少 32 位随机字符串
JWT_SECRET_KEY=change_me_to_a_long_random_secret_string_32chars

# 目标架构中使用阿里云 OSS；本地开发可先填写占位值
OSS_BUCKET=your_bucket_name
OSS_REGION=oss-cn-beijing

⚠️ 安全提示：JWT_SECRET_KEY 请使用随机生成的强密钥（≥32 字符），切勿提交到版本控制。

5.4 配置前端环境变量

h5-app（已有 .env 文件，按需修改）：

# 开发时 API 代理目标（Vite 代理，不会暴露在浏览器）
DEV_API_TARGET=http://127.0.0.1:3000

# 生产部署时如需子路径，设置此项，例如 /h5/
VITE_BASE=/

# 生产部署时如 API 在不同域，设置绝对 URL；否则留空（同源代理）
VITE_API_BASE=

admin-web（可新建 admin-web/.env）：

DEV_API_TARGET=http://127.0.0.1:3000
VITE_BASE=/
VITE_API_BASE=

5.5 启动开发服务器

在三个独立终端中分别运行：

# 终端 1：后端
cd server
npm run dev          # tsx watch，热重载，默认监听 :3000

# 终端 2：移动端 H5
cd h5-app
npm run dev          # Vite dev server，默认 :5173，/v1 代理到 :3000（或 DEV_API_TARGET）

# 终端 3：管理后台
cd admin-web
npm run dev          # Vite dev server，默认 :5174，/v1 代理到 :3000（或 DEV_API_TARGET）

5.6 运行测试

# 移动端 H5
cd h5-app && npm test

# 管理后台（vitest 默认以 watch 模式运行；非交互环境使用 --run 一次性执行）
cd admin-web && npm test -- --run

# 后端（需要完整 MySQL 环境与正确的 .env 配置）
cd server && npm test

6. 构建

# 后端（输出到 server/dist/）
cd server && npm run build

# 移动端 H5（输出到 h5-app/dist/）
cd h5-app && npm run build

# 管理后台（输出到 admin-web/dist/）
cd admin-web && npm run build

构建产物均为静态文件（前端）或 CommonJS/ESM 模块（后端），可直接部署。

7. 生产部署建议

以下为推荐部署方案，当前仓库不包含 CI/CD 流水线或 Docker 配置，需按实际情况自行搭建。

7.1 后端（server）

# 1. 构建
cd server && npm run build

# 2. 启动（生产模式）
NODE_ENV=production node dist/index.js

# 建议使用 PM2 管理进程
npm install -g pm2
pm2 start dist/index.js --name smart-server
pm2 save && pm2 startup

生产环境 .env 要点：

  • MYSQL_HOST / MYSQL_USER / MYSQL_PASSWORD 指向生产数据库
  • JWT_SECRET_KEY 使用高强度随机密钥，通过密钥管理服务注入，切勿硬编码
  • OSS_BUCKET / OSS_REGION 对应阿里云 OSS 配置（目标架构中用于存储隐患照片、施工日志照片等）

7.2 前端（h5-app / admin-web）

# 构建时注入生产环境变量
VITE_BASE=/h5/ VITE_API_BASE=https://api.example.com npm run build

将 dist/ 目录内容部署到 Nginx 静态文件目录或 CDN 即可。

7.3 数据库

# 生产初始化（仅首次）
mysql -h <host> -u <user> -p <database> < server/schema.sql

推荐定期对 MySQL 数据进行备份，并开启慢查询日志。

7.4 阿里云 OSS（目标架构）

  • Bucket 名称：jesxion-ai-studio，Region：oss-cn-beijing
  • 后端通过 OSS SDK 签发上传凭证与下载链接，客户端直传 OSS，不经过后端转发
  • 相关路由：GET /v1/oss/upload-url、GET /v1/oss/download-url

8. Nginx 反向代理示例

以下示例将三个子项目统一收敛到同一域名下：

server {
    listen 443 ssl;
    server_name your-domain.com;

    # SSL 证书配置（建议使用 Let's Encrypt 或阿里云证书）
    ssl_certificate     /etc/nginx/ssl/your-domain.com.crt;
    ssl_certificate_key /etc/nginx/ssl/your-domain.com.key;

    # ── 管理后台 ──────────────────────────────────────────────
    location /admin/ {
        alias /var/www/admin-web/dist/;
        try_files $uri $uri/ /admin/index.html;
    }

    # ── 移动端 H5 ────────────────────────────────────────────
    location /h5/ {
        alias /var/www/h5-app/dist/;
        try_files $uri $uri/ /h5/index.html;
    }

    # ── 后端 API ─────────────────────────────────────────────
    location /v1/ {
        proxy_pass         http://127.0.0.1:3000;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }

    # ── 设备数据推送接口（河南三农统一推送，目标架构）────────────
    location /input/ {
        proxy_pass         http://127.0.0.1:3000;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

# HTTP → HTTPS 重定向
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

前端部署路径说明：若将前端部署在子路径（如 /h5/），需在构建时设置对应的 VITE_BASE 变量，并在 VITE_API_BASE 中指定后端绝对 URL 或保持为空（同源代理）。

9. 数据库与环境变量说明

9.1 后端必填环境变量

变量名 说明 示例值
PORT HTTP 监听端口 3000
MYSQL_HOST MySQL 主机地址 localhost
MYSQL_PORT MySQL 端口 3306
MYSQL_USER 数据库用户名 smart_user
MYSQL_PASSWORD 数据库密码 strong_password
MYSQL_DATABASE 数据库名称 smart_project
JWT_SECRET_KEY JWT 签名密钥（≥32字符） 随机生成的强密钥
OSS_BUCKET 阿里云 OSS Bucket 名称 jesxion-ai-studio
OSS_REGION 阿里云 OSS Region oss-cn-beijing

所有变量由 Zod Schema 在启动时严格校验；缺少任意变量服务将拒绝启动并打印明确的错误信息。

9.2 前端环境变量

变量名 适用项目 说明
VITE_BASE h5-app / admin-web 应用基础路径，默认 /
VITE_API_BASE h5-app / admin-web API 前缀，空字符串表示同源（Vite 代理或 Nginx 代理）
DEV_API_TARGET h5-app / admin-web 仅用于本地开发时 Vite 代理目标，不会暴露在浏览器端

9.3 数据库租户隔离

所有业务表（hazards、logs、oss_files 等）均携带 project_id 字段。后端 JWT 中间件在每次请求时解析当前用户的 project_id，并将其注入所有数据查询，确保不同项目的数据完全隔离。

9.4 数据库初始化

# 建库建表（首次部署或重置开发环境）
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS smart_project CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p smart_project < server/schema.sql

10. 常见问题 FAQ

Q：启动 server 时报 "Missing or invalid environment variables"？

A：缺少必填环境变量。检查 server/.env 是否存在且包含所有必填字段（参见第 9.1 节）。

Q：server 测试（npm test）失败？

A：服务器测试套件需要真实的 MySQL 连接。请确保 server/.env 中数据库配置正确，且目标数据库已初始化（执行过 schema.sql）。

Q：前端页面 API 请求返回 404 或跨域错误？

A：开发时：确认 server 已在对应端口启动，且前端 vite.config.ts 中 DEV_API_TARGET 指向正确地址。

生产时：检查 Nginx 反向代理配置，确保 /v1/ 路径正确转发到后端服务，并正确设置 VITE_API_BASE。

Q：管理后台或 H5 构建后白屏？

A：检查 VITE_BASE 是否与实际部署路径一致。若部署在 /h5/ 子路径下，构建时需传入 VITE_BASE=/h5/；Nginx try_files 规则也需匹配。

Q：OSS 文件上传功能不可用？

A：OSS_BUCKET 和 OSS_REGION 为后端必填项。本地开发阶段可先填入占位值以正常启动服务，文件上传相关接口在未正确配置时会返回错误。生产环境请配置有效的阿里云 OSS 信息。

Q：如何本地预览生产构建结果？

# h5-app
cd h5-app && npm run build && npm run preview

# 或通过局域网访问
npm run preview:local   # 监听 0.0.0.0:8084

# admin-web
cd admin-web && npm run build && npm run preview

相关文档

文档 说明
SPEC.md 产品设计规格书（主文档）
docs/architecture.md 系统架构设计
docs/api.md API 接口设计
docs/database.md 数据库表结构
docs/h5.md H5 页面结构与交互
docs/offline.md 离线数据方案
Reference in New Issue View Git Blame Copy Permalink
Description
郑州智慧工地管理系统 - 后台API+H5+OSS存储
Readme 998 KiB
Languages
TypeScript 92.8%
HTML 5%
CSS 2.1%
JavaScript 0.1%