smart-project/docs/architecture.md

系统架构设计

状态: 设计中

---

1. 系统架构图

                        ┌─────────────────────────────────────────┐
                        │           阿里云 OSS                    │
                        │  (jesxion-ai-studio, oss-cn-beijing)     │
                        │  隐患照片 / 施工日志照片 / 证书报告       │
                        └───────────────┬─────────────────────────┘
                                        │ upload / download
                                        ▼
┌──────────┐    ┌──────────────────────────────────────┐    ┌──────────────┐
│ 河南三农  │    │          后台 API 服务                 │    │  H5 客户端   │
│ 设备系统  │───▶│      Node.js / Express + TypeScript   │◀───│  (移动端浏览器)│
│          │    │                                      │    │              │
│ (统一推送  │    │  ┌────────────────────────────────┐  │    └──────────────┘
│  /input/  │    │  │  设备数据接入层  (device_adapter)│  │            ▲
│  post/    │    │  │  预警引擎        (alert_handler) │  │            │
│  call)    │    │  │  OSS 文件管理    (file_mgr)     │  │   polling (30s)
│          │    │  │  项目租户中间件  (project_mw)   │  │   JWT Auth
└──────────┘    │  │  REST API Routes              │  │            │
                │  └────────────────────────────────┘  │            │
                └────────────┬───────────────────────────┘            │
                             │                                       │
                             ▼                                       │
                ┌─────────────────────────┐                          │
                │      MySQL 8.0           │◀─────────────────────────┘
                │  (项目级逻辑租户隔离)     │
                │  devices / users         │
                │  hazards / logs         │
                │  ai_analysis_results    │
                └─────────────────────────┘

---

2. 技术栈

层级	技术选型	说明
后台 API	Node.js / Express + TypeScript	轻量、高并发、易维护
数据库	MySQL 8.0	项目级逻辑租户隔离
H5 前端	原生 HTML/CSS/JS，无框架依赖	低依赖、离线友好
文件存储	阿里云 OSS	隐患照片、施工日志照片
设备数据	河南三农统一推送接口	POST /input/post/call

---

3. 模块划分

3.1 后台 API 服务

职责：数据聚合层，统一对接设备推送数据，屏蔽异构数据源差异，对 H5 提供标准化 REST API。

模块	说明
device_adapter	设备 API 适配器：塔吊协议解析、升降机协议解析
alert_handler	预警接收与存储：接收设备推送的预警数据，存入 DB
file_mgr	OSS 文件管理：上传凭证签发、下载 URL 签发、文件索引
project_middleware	项目租户中间件：从 JWT 解析 project_id，注入所有查询条件
routes/auth	认证接口：登录
routes/devices	设备台账、实时数据、历史数据
routes/alerts	预警列表、详情、处理、忽略
routes/hazards	隐患随手拍：上报、列表、详情、认领、处理
routes/logs	施工日志：新建、列表、详情
routes/ai	AI 智能分析：列表、详情
routes/oss	OSS 文件：上传凭证、下载链接

3.2 H5 客户端

职责：移动端展示与操作界面，基于响应式 H5 开发，适配手机浏览器。

模块	说明
dashboard	首页仪表盘：设备统计、预警统计、快捷入口
device_list	设备列表：塔吊/升降机分类展示
device_detail	设备详情：实时数据面板、历史曲线（ECharts）
alert_list	预警列表：危险/警告/已处理筛选
alert_detail	预警详情：处理/忽略操作
report	隐患随手拍：拍照 + 表单提交
reports	隐患列表：状态/类别/严重程度筛选
report_detail	隐患详情：认领/处理操作
log	施工日志：新建日志（含照片上传）
logs	日志列表：日期筛选
log_detail	日志详情：查看日志
ai_analyses	AI 分析列表：类型筛选
ai_analysis_detail	AI 分析详情：建议措施
profile	个人中心：账号信息、设置

---

4. 数据流向

4.1 设备数据采集（厂家 → 后台）

河南三农厂家系统（推送）
     │ (POST /input/post/call, Bearer Token)
     ▼
device_adapter (协议解析，统一入口)
     │
     ├── 基础信息 pushBasicInfo → 写入/更新 devices 表
     ├── 实时数据 pushRealTimeInfo → 写入 device_realtime（UPSERT）
     ├── 工作循环 pushWorkCycleInfo → 写入 device_history
     ├── 塔吊报警 pushAlarmInfo → 写入 alert_records
     └── 升降机报警 pushAlarmInfo → 写入 alert_records

注：数据为主动推送，无需后台定时轮询。推送频率由厂家控制。 AI 分析结果同样通过厂家系统推送至 POST /input/post/call，写入 ai_analysis_results 表。

4.2 H5 数据请求（H5 → 后台）

H5 浏览器
    │ GET /v1/devices
    │ GET /v1/devices/{id}/realtime
    │ GET /v1/alerts
    │ POST /v1/hazards
    │ GET /v1/logs
    │ GET /v1/ai/analyses
    ▼
JWT Auth Middleware (验证 token，注入 project_id)
    │
    ▼
REST API Routes (Express)
    │
    ├──────────────┐
    ▼              ▼
MySQL             OSS
(结构化数据)      (文件 URL，GET /v1/oss/download-url)

4.3 文件上传流程（H5 → OSS）

H5 客户端
    │ 1. POST /v1/oss/upload-token  → 获取预签名上传 URL
    │ 2. PUT {upload_url} + file   → 直传 OSS
    │
    ▼
后台 API（记录索引）
    └── oss_files 表写入 object_key + metadata

---

5. 租户隔离模型

项目级逻辑租户 — 所有表通过 project_id 字段区分项目归属。

请求进入
    │
    ▼
JWT 解析 → 获取 user.project_id
    │
    ▼
project_middleware 注入 project_id 条件
    │
    ▼
所有 DB 查询自动附加 WHERE project_id = ?

• 用户注册/创建时绑定 project_id
• API 中间件从 JWT Token 解析用户 project_id，注入到所有查询条件
• 所有数据表均以 project_id 为隔离字段
• 设备数据通过 devices.project_id 间接隔离

---

6. 部署架构

MVP 阶段采用轻量部署：

组件	部署方式
后台 API	阿里云函数计算（FC）或轻量服务器
MySQL	阿里云 RDS 或轻量服务器自建
OSS	阿里云 OSS 标准存储（jesxion-ai-studio, oss-cn-beijing）
H5 静态资源	Nginx 反向代理，或 OSS + CDN

前后端同域：API 和静态资源共用同一域名，Nginx 反向代理到后端服务。

---

7. 安全设计

措施	说明
HTTPS	全链路 HTTPS，证书由阿里云管理
JWT Token 认证	有效期 7 天，API 请求携带 Authorization: Bearer ***
项目隔离中间件	中间件层强制注入 project_id 过滤条件
CORS	限制允许的 H5 域名
OSS 鉴权	H5 通过后台签发临时 URL 访问 OSS 文件（有效 1 小时）
输入校验	Express + Joi 参数校验，参数化查询防 SQL 注入

---

8. 文档索引

文档	说明
SPEC.md	产品设计规格书
api.md	后台 API 接口设计
database.md	数据库表结构设计
h5.md	H5 页面结构与交互设计
offline.md	离线数据方案

---

9. 待确认

• 预警阈值配置 → 设备 API 自带预警判断，本系统仅做聚合展示
• 设备 API 协议细节 → 河南三农统一推送接口（8个接口，已确认）
• 多租户隔离方案 → 项目级逻辑租户（project_id 字段）
• 后台 API 公网部署地址（阿里云服务器，部署时配置）
• JWT Secret 管理（环境变量，部署时配置）