From cb0ef8c30cb2672dfa6879fe2f3a1ead99faa97d Mon Sep 17 00:00:00 2001 From: Jesxion Date: Tue, 14 Apr 2026 16:53:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=9D=A2=E5=AE=A1=E9=98=85?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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/台账） --- SPEC.md | 14 +-- docs/architecture.md | 213 ++++++++++++++++++++++---------- docs/h5.md | 281 ++++++++++++++++++++++++++++++++++++++++++- docs/offline.md | 57 +++++++-- 4 files changed, 484 insertions(+), 81 deletions(-) diff --git a/SPEC.md b/SPEC.md index 98b7620..8ce637d 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,7 +1,7 @@ # 郑州智慧工地管理系统 - 产品设计规格书 -> 版本: v0.2.0 -> 状态: 设计中 +> 版本: v0.2.1 +> 状态: 设计完成（开发前置条件已确认） > 仓库: https://git.jesxion.com/jesxion/smart-project --- @@ -351,8 +351,8 @@ AI 分析由河南三农设备端驱动，设备端 AI 分析完成后，通过 ### 7. 待确认 -- [ ] 后台 API 公网部署地址（阿里云服务器，部署时配置） -- [ ] 河南三农设备推送的 appid / secret（部署时配置） -- [ ] OSS 存储路径规范（目录前缀规则） -- [ ] JWT Secret 管理（环境变量） -- [ ] 设备初始台账导入方式（手动录入还是自动发现） +- [x] ~~后台 API 公网部署地址~~ → 阿里云服务器（部署时配置） +- [x] ~~河南三农设备推送的 appid / secret~~ → 部署时配置 +- [x] ~~OSS 存储路径规范~~ → 隐患照片 `reports/`、日志照片 `logs/`、AI 分析附件 `ai/` +- [x] ~~JWT Secret 管理~~ → 环境变量 `JWT_SECRET_KEY` +- [x] ~~设备初始台账导入方式~~ → 手动录入河南三农设备 SN diff --git a/docs/architecture.md b/docs/architecture.md index 816b652..74a9864 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -7,132 +7,217 @@ ## 1. 系统架构图 ``` - ┌─────────────────────────────────────────┐ - │ 阿里云 OSS │ - │ (文件存储: 证书/报告/日志) │ - └───────────────┬─────────────────────────┘ - │ upload - ▼ -┌──────────┐ ┌─────────────────────────┐ ┌──────────────┐ -│ 已有API │───▶│ 后台 API 服务 │◀───│ H5 客户端 │ -│ (塔吊/ │ │ Python / FastAPI │ │ (移动端浏览器)│ -│ 升降机) │ │ │ │ │ -└──────────┘ │ ┌───────────────────┐ │ └──────────────┘ - │ │ 设备数据接入层 │ │ ▲ - │ │ 预警引擎 │ │ │ polling / websocket - │ │ OSS 文件管理 │ │ - │ │ REST API │ │ - │ └───────────────────┘ │ │ - └────────────┬────────────┘ │ - │ │ - ▼ │ - ┌─────────────────────────┐ - │ SQLite │ - │ (设备台账/预警记录/ │◀────────────┘ - │ 用户/OSS文件索引) │ + ┌─────────────────────────────────────────┐ + │ 阿里云 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. 模块划分 +## 2. 技术栈 -### 2.1 后台 API 服务 +| 层级 | 技术选型 | 说明 | +|------|----------|------| +| 后台 API | Node.js / Express + TypeScript | 轻量、高并发、易维护 | +| 数据库 | MySQL 8.0 | 项目级逻辑租户隔离 | +| H5 前端 | 原生 HTML/CSS/JS，无框架依赖 | 低依赖、离线友好 | +| 文件存储 | 阿里云 OSS | 隐患照片、施工日志照片 | +| 设备数据 | 河南三农统一推送接口 | POST /input/post/call | -**职责**：数据聚合层，统一对接已有设备 API，屏蔽异构数据源差异，对 H5 提供标准化 REST API。 +--- + +## 3. 模块划分 + +### 3.1 后台 API 服务 + +**职责**：数据聚合层，统一对接设备推送数据，屏蔽异构数据源差异，对 H5 提供标准化 REST API。 | 模块 | 说明 | |------|------| | `device_adapter` | 设备 API 适配器：塔吊协议解析、升降机协议解析 | -| `monitor` | 设备状态监控：定时轮询已有 API，写入本地 DB | -| `alert_handler` | 预警接收与存储：接收设备 API 的预警数据，存入 DB | -| `file_mgr` | OSS 文件管理：上传、下载、索引 | -| `api_routes` | REST API 路由：设备台账、实时数据、历史查询、预警、OSS | +| `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 文件：上传凭证、下载链接 | -### 2.2 H5 客户端 +### 3.2 H5 客户端 **职责**：移动端展示与操作界面，基于响应式 H5 开发，适配手机浏览器。 | 模块 | 说明 | |------|------| -| `dashboard` | 首页仪表盘：设备总数、在线/离线、告警统计 | +| `dashboard` | 首页仪表盘：设备统计、预警统计、快捷入口 | | `device_list` | 设备列表：塔吊/升降机分类展示 | -| `device_detail` | 设备详情：实时数据面板、历史曲线 | -| `alert_list` | 预警列表：未读/已处理筛选 | +| `device_detail` | 设备详情：实时数据面板、历史曲线（ECharts） | +| `alert_list` | 预警列表：危险/警告/已处理筛选 | | `alert_detail` | 预警详情：处理/忽略操作 | -| `profile` | 个人中心：账号信息、通知设置 | +| `report` | 隐患随手拍：拍照 + 表单提交 | +| `reports` | 隐患列表：状态/类别/严重程度筛选 | +| `report_detail` | 隐患详情：认领/处理操作 | +| `log` | 施工日志：新建日志（含照片上传） | +| `logs` | 日志列表：日期筛选 | +| `log_detail` | 日志详情：查看日志 | +| `ai_analyses` | AI 分析列表：类型筛选 | +| `ai_analysis_detail` | AI 分析详情：建议措施 | +| `profile` | 个人中心：账号信息、设置 | --- -## 3. 数据流向 +## 4. 数据流向 -### 3.1 设备数据采集 +### 4.1 设备数据采集（厂家 → 后台） ``` 河南三农厂家系统（推送） - │ (统一推送接口 POST /input/post/call) + │ (POST /input/post/call, Bearer Token) ▼ device_adapter (协议解析，统一入口) │ - ▼ -monitor (写入 DB) - │ - ├──────────────────┐ - ▼ ▼ -SQLite alert_handler -(设备状态表) (接收设备预警，写入 DB) - │ - ▼ - alert_records (预警记录表) + ├── 基础信息 pushBasicInfo → 写入/更新 devices 表 + ├── 实时数据 pushRealTimeInfo → 写入 device_realtime（UPSERT） + ├── 工作循环 pushWorkCycleInfo → 写入 device_history + ├── 塔吊报警 pushAlarmInfo → 写入 alert_records + └── 升降机报警 pushAlarmInfo → 写入 alert_records ``` > 注：数据为主动推送，无需后台定时轮询。推送频率由厂家控制。 +> AI 分析结果同样通过厂家系统推送至 `POST /input/post/call`，写入 `ai_analysis_results` 表。 -### 3.2 H5 数据请求 +### 4.2 H5 数据请求（H5 → 后台） ``` H5 浏览器 - │ GET /api/devices - │ GET /api/devices/{id}/realtime - │ GET /api/alerts + │ GET /v1/devices + │ GET /v1/devices/{id}/realtime + │ GET /v1/alerts + │ POST /v1/hazards + │ GET /v1/logs + │ GET /v1/ai/analyses ▼ -api_routes (FastAPI) +JWT Auth Middleware (验证 token，注入 project_id) + │ + ▼ +REST API Routes (Express) │ ├──────────────┐ ▼ ▼ -PostgreSQL OSS -(结构化数据) (文件URL) +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 ``` --- -## 4. 部署架构 +## 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）或轻量服务器 | -| PostgreSQL | 阿里云 RDS 或轻量服务器自建 | -| OSS | 阿里云 OSS 标准存储 | +| MySQL | 阿里云 RDS 或轻量服务器自建 | +| OSS | 阿里云 OSS 标准存储（jesxion-ai-studio, oss-cn-beijing） | +| H5 静态资源 | Nginx 反向代理，或 OSS + CDN | + +**前后端同域**：API 和静态资源共用同一域名，Nginx 反向代理到后端服务。 --- -## 5. 安全设计 +## 7. 安全设计 | 措施 | 说明 | |------|------| | HTTPS | 全链路 HTTPS，证书由阿里云管理 | -| Token 认证 | H5 API 请求携带 JWT Token | +| JWT Token 认证 | 有效期 7 天，API 请求携带 `Authorization: Bearer ***` | +| 项目隔离中间件 | 中间件层强制注入 project_id 过滤条件 | | CORS | 限制允许的 H5 域名 | -| OSS 鉴权 | H5 通过后台签发临时 URL 访问 OSS 文件 | -| 输入校验 | FastAPI Pydantic 模型全量参数校验 | +| OSS 鉴权 | H5 通过后台签发临时 URL 访问 OSS 文件（有效 1 小时） | +| 输入校验 | Express + Joi 参数校验，参数化查询防 SQL 注入 | --- -## 6. 待细化 +## 8. 文档索引 + +| 文档 | 说明 | +|------|------| +| [SPEC.md](./SPEC.md) | 产品设计规格书 | +| [api.md](./api.md) | 后台 API 接口设计 | +| [database.md](./database.md) | 数据库表结构设计 | +| [h5.md](./h5.md) | H5 页面结构与交互设计 | +| [offline.md](./offline.md) | 离线数据方案 | + +--- + +## 9. 待确认 - [x] ~~预警阈值配置~~ → 设备 API 自带预警判断，本系统仅做聚合展示 - [x] ~~设备 API 协议细节~~ → 河南三农统一推送接口（8个接口，已确认） +- [x] ~~多租户隔离方案~~ → 项目级逻辑租户（project_id 字段） - [ ] 后台 API 公网部署地址（阿里云服务器，部署时配置） -- [ ] 多租户隔离方案（目前 MVP 单租户设计） +- [ ] JWT Secret 管理（环境变量，部署时配置） diff --git a/docs/h5.md b/docs/h5.md index cc288dd..0ff5ee8 100644 --- a/docs/h5.md +++ b/docs/h5.md @@ -31,6 +31,14 @@ | 设备详情 | `/device.html?id=xxx` | 实时数据 + 历史曲线 | | 预警列表 | `/alerts.html` | 预警推送列表 | | 预警详情 | `/alert.html?id=xxx` | 预警详情 + 处理操作 | +| 隐患随手拍 | `/report.html` | 拍照 + 表单提交 | +| 隐患列表 | `/reports.html` | 项目内隐患列表，状态/类别/严重程度筛选 | +| 隐患详情 | `/report.html?id=xxx` | 隐患详情 + 认领/处理操作 | +| 日志列表 | `/logs.html` | 列表 + 日期筛选 | +| 写日志 | `/log.html` | 新建日志（含照片上传） | +| 日志详情 | `/log.html?id=xxx` | 查看日志详情 | +| AI 分析列表 | `/ai-analyses.html` | AI 分析结果列表，类型筛选 | +| AI 分析详情 | `/ai-analysis.html?id=xxx` | 分析详情 + 建议措施 | | 个人中心 | `/profile.html` | 个人信息、设置 | --- @@ -188,7 +196,7 @@ │ ┌──────────┐ │ │ │ 👤 │ │ │ └──────────┘ │ -│ 张三（管理员） │ +│ 张三（安全员） │ │ 138****1234 │ │ │ │ ┌──────────────────────────────┐ │ @@ -211,6 +219,273 @@ └──────────────────────────────────────┘ ``` +### 3.7 隐患随手拍 `/report.html` + +``` +┌──────────────────────────────────────┐ +│ ← 返回 上报隐患 │ +├──────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ │ │ +│ │ 📷 点击拍照 │ │ ← 拍照区 +│ │ （最多 4 张） │ │ +│ └──────────────────────────────┘ │ +│ │ +│ 隐患类别 * │ +│ ┌──────────────────────────────┐ │ +│ │ 请选择类别 ▼ │ │ ← 下拉选择 +│ └──────────────────────────────┘ │ +│ 高处坠落 / 物体打击 / 机械伤害 ... │ +│ │ +│ 严重程度 * │ +│ ○ 一般 ○ 较大 ○ 重大 │ ← 单选 +│ │ +│ 隐患描述 * │ +│ ┌──────────────────────────────┐ │ +│ │ │ │ +│ │ │ │ +│ └──────────────────────────────┘ │ +│ │ +│ GPS 坐标: 34.7652, 113.6241 │ │ ← 自动获取（可关闭） +│ │ +│ [提交隐患] │ +│ │ +└──────────────────────────────────────┘ +``` + +**表单字段**：category / severity / description（必填）；photos / gps_lat / gps_lng（选填） + +### 3.8 隐患列表 `/reports.html` + +``` +┌──────────────────────────────────────┐ +│ ☰ 隐患随手拍 [筛选 ▼] │ +├──────────────────────────────────────┤ +│ [全部] [待处理] [处理中] [已处理] │ ← Tab 状态筛选 +├──────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ 🔴 一般 高处坠落 │ │ ← 红色=待处理 +│ │ A区2楼临边防护缺失 │ │ +│ │ 安全员 · 2小时前 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ 🟡 较大 机械伤害 │ │ ← 黄色=处理中 +│ │ B区钢筋加工区缺防护罩 │ │ +│ │ 安全负责人 · 昨天 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ 🟢 一般 物体打击 │ │ ← 绿色=已处理 +│ │ C区材料堆放过高 │ │ +│ │ 安全员 · 04-13 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ [+ 上报隐患] │ ← 悬浮按钮 +└──────────────────────────────────────┘ +``` + +### 3.9 隐患详情 `/report.html?id=xxx` + +``` +┌──────────────────────────────────────┐ +│ ← 返回 隐患详情 │ +├──────────────────────────────────────┤ +│ │ +│ 🔴 一般 │ +│ 高处坠落 │ +│ │ +│ A区2楼临边防护缺失 │ +│ │ +│ ┌────┐ ┌────┐ │ +│ │ 📷 │ │ 📷 │ │ ← 照片 +│ └────┘ └────┘ │ +│ │ +│ 位置: 34.7652, 113.6241 │ +│ │ +│ ── 流程 ────────────────────────── │ +│ │ +│ 上报 安全员 张三 04-14 14:30 │ +│ ↓ │ +│ 认领 安全负责人 李四 04-14 15:00 │ +│ ↓ │ +│ 处理 （待处理） │ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ 处理说明（选填） │ │ +│ │ __________________________ │ │ +│ │ │ │ +│ │ [认领] [处理完成] │ │ ← 根据状态显示 +│ └──────────────────────────────┘ │ +│ │ +└──────────────────────────────────────┘ +``` + +**状态说明**： +- `pending`（待处理）：显示「认领」「处理完成」按钮 +- `assigned`（处理中）：显示「处理完成」按钮，附处理说明输入框 +- `resolved`（已处理）：显示处理结果，无操作按钮 + +### 3.10 施工日志 `/log.html`（新建） + +``` +┌──────────────────────────────────────┐ +│ ← 返回 写日志 │ +├──────────────────────────────────────┤ +│ │ +│ 日期 * │ +│ ┌──────────────────────────────┐ │ +│ │ 2026-04-14 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ 施工部位 * │ +│ ┌──────────────────────────────┐ │ +│ │ A区主体结构 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ 作业内容 * │ +│ ┌──────────────────────────────┐ │ +│ │ │ │ +│ │ │ │ +│ └──────────────────────────────┘ │ +│ │ +│ 人员出勤 * 28 人 │ +│ │ +│ 设备运行 │ +│ ☑ 塔吊 ☑ 升降机 │ +│ │ +│ 现场照片 │ +│ ┌────┐ ┌────┐ │ +│ │ 📷 │ │ ➕ │ │ +│ └────┘ └────┘ │ +│ │ +│ 安全问题（选填） │ +│ ┌──────────────────────────────┐ │ +│ │ │ │ +│ └──────────────────────────────┘ │ +│ │ +│ 备注（选填） │ +│ ┌──────────────────────────────┐ │ +│ │ │ │ +│ └──────────────────────────────┘ │ +│ │ +│ [提交日志] │ +│ │ +└──────────────────────────────────────┘ +``` + +**表单字段**：date / part / content / workers（必填）；equipment / photos / safety_note / note（选填） + +### 3.11 日志列表 `/logs.html` + +``` +┌──────────────────────────────────────┐ +│ ☰ 施工日志 [+ 写日志] │ +├──────────────────────────────────────┤ +│ 日期筛选 │ +│ [04-01 ─── ○ ─── 04-14] │ ← 日期范围选择 +├──────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ 04-14 A区主体结构 │ │ +│ │ 3层混凝土浇筑，钢筋绑扎... │ │ +│ │ 👷 28人 🏗️ 塔吊+升降机 │ │ +│ │ 安全员 张三 · 17:00 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ 04-13 B区地下室 │ │ +│ │ 土方开挖，护坡施工... │ │ +│ │ 👷 15人 │ │ +│ │ 安全负责人 李四 · 16:30 │ │ +│ └──────────────────────────────┘ │ +│ │ +└──────────────────────────────────────┘ +``` + +### 3.12 日志详情 `/log.html?id=xxx` + +``` +┌──────────────────────────────────────┐ +│ ← 返回 日志详情 │ +├──────────────────────────────────────┤ +│ │ +│ 04-14 A区主体结构 │ +│ │ +│ 👷 28人 🏗️ 塔吊+升降机 │ +│ │ +│ 作业内容 │ +│ 3层混凝土浇筑，钢筋绑扎，模板安装 │ +│ │ +│ 现场照片 │ +│ ┌────┐ ┌────┐ ┌────┐ │ +│ │ 📷 │ │ 📷 │ │ 📷 │ │ +│ └────┘ └────┘ └────┘ │ +│ │ +│ 安全问题 │ +│ 临边作业已挂安全网 │ +│ │ +│ 备注 │ +│ 下午2点停电1小时 │ +│ │ +│ ────────────────────────────────── │ +│ 安全员 张三 04-14 17:00 │ +│ │ +└──────────────────────────────────────┘ +``` + +### 3.13 AI 分析列表 `/ai-analyses.html` + +``` +┌──────────────────────────────────────┐ +│ ☰ AI 智能分析 [筛选 ▼] │ +├──────────────────────────────────────┤ +│ [全部] [人员安全] [设备异常] [环境风险] │ ← Tab 类型筛选 +├──────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ 🤖 人员安全 置信度 92% │ │ +│ │ 1号塔吊 │ │ +│ │ 检测到人员靠近吊装区域... │ │ +│ │ 04-14 10:25 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ ⚙️ 设备异常 置信度 87% │ │ +│ │ 2号升降机 │ │ +│ │ 载重超限预警... │ │ +│ │ 04-14 09:10 │ │ +│ └──────────────────────────────┘ │ +│ │ +└──────────────────────────────────────┘ +``` + +### 3.14 AI 分析详情 `/ai-analysis.html?id=xxx` + +``` +┌──────────────────────────────────────┐ +│ ← 返回 AI 分析详情 │ +├──────────────────────────────────────┤ +│ │ +│ 🤖 人员安全 置信度 92% │ +│ │ +│ 设备: 1号塔吊（QTZ500） │ +│ 位置: A区施工现场 │ +│ 时间: 04-14 10:25:00 │ +│ │ +│ ── AI 分析描述 ──────────────────── │ +│ 检测到人员靠近吊装区域， │ +│ 触发区域入侵告警 │ +│ │ +│ ── 建议措施 ────────────────────── │ +│ 建议立即疏散人员，后续加强 │ +│ 吊装区域围挡和警示标志 │ +│ │ +└──────────────────────────────────────┘ +``` + --- ## 4. 页面交互 @@ -293,7 +568,7 @@ async function api(endpoint, options = {}) { ## 6. 待确认 -- [ ] 预警推送机制（轮询 vs WebSocket） -- [ ] 登录 Session 管理方案（JWT 有效期） +- [x] ~~预警推送机制~~ → 轮询（前端每 30s，SPEC.md 已确认） +- [x] ~~登录 Session 管理方案~~ → JWT 有效期 7 天（SPEC.md 已确认） - [ ] 是否有扫码登录需求 - [ ] 报表导出（H5 直接拉 OSS 预签名 URL） diff --git a/docs/offline.md b/docs/offline.md index a797898..2060190 100644 --- a/docs/offline.md +++ b/docs/offline.md @@ -36,7 +36,7 @@ // 数据库: SmartProjectDB // 版本: 1 -// 对象存储 1: devices +// 对象存储 1: devices（设备台账） { store: 'devices', keyPath: 'id', @@ -44,15 +44,42 @@ data: { id, name, type, model, location, status, last_seen } } -// 对象存储 2: alerts +// 对象存储 2: alerts（预警记录） { store: 'alerts', keyPath: 'id', indexes: ['status', 'level', 'created_at'], - data: { id, device_id, device_name, level, message, status, created_at } + data: { id, device_id, device_name, level, message, metric, value, status, created_at } } -// 对象存储 3: sync_queue（离线操作队列） +// 对象存储 3: hazards（隐患随手拍） +{ + store: 'hazards', + keyPath: 'id', + indexes: ['status', 'category', 'severity', 'reported_at'], + data: { id, category, severity, description, photo_count, status, + reporter_id, reporter_role, reported_at, assignee_id, resolved_at } +} + +// 对象存储 4: construction_logs（施工日志） +{ + store: 'construction_logs', + keyPath: 'id', + indexes: ['date', 'author_id'], + data: { id, date, part, content, workers, equipment, photo_count, + author_id, author_role, created_at } +} + +// 对象存储 5: ai_analyses（AI 智能分析） +{ + store: 'ai_analyses', + keyPath: 'id', + indexes: ['device_id', 'analysis_type', 'triggered_at'], + data: { id, device_id, device_name, analysis_type, confidence, + description, triggered_at } +} + +// 对象存储 6: sync_queue（离线操作队列） { store: 'sync_queue', keyPath: 'id', @@ -68,7 +95,12 @@ | 设备列表 | 每 5 分钟 | 后台静默更新 | | 设备详情 | 每 30 秒 | 页面打开时拉取 + 定时刷新 | | 预警列表 | 每 1 分钟 | 后台静默更新 + 新预警推送 | -| 预警详情 | 实时 | 打开时拉取 | +| 隐患列表 | 每 2 分钟 | 后台静默更新 | +| 施工日志列表 | 每 5 分钟 | 后台静默更新 | +| AI 分析列表 | 每 5 分钟 | 后台静默更新 | +| 隐患详情 | 实时 | 打开时拉取 | +| 日志详情 | 实时 | 打开时拉取 | +| AI 分析详情 | 实时 | 打开时拉取 | **更新流程**: ``` @@ -85,9 +117,20 @@ ### 4.1 场景 -用户在离线状态下执行操作（如处理预警、提交备注），操作记录存入 `sync_queue`，网络恢复后自动同步。 +用户在离线状态下执行操作（如处理预警、提交隐患、处理日志），操作记录存入 `sync_queue`，网络恢复后自动同步。 -### 4.2 同步流程 +### 4.2 支持的离线操作类型 + +| action | 说明 | 对应 API | +|--------|------|----------| +| `handle_alert` | 处理预警 | POST /v1/alerts/:id/handle | +| `ignore_alert` | 忽略预警 | POST /v1/alerts/:id/ignore | +| `create_hazard` | 上报隐患 | POST /v1/hazards | +| `assign_hazard` | 认领隐患 | POST /v1/hazards/:id/assign | +| `resolve_hazard` | 处理完成 | POST /v1/hazards/:id/resolve | +| `create_log` | 新建日志 | POST /v1/logs | + +### 4.3 同步流程 ``` 检测到网络恢复（navigator.onLine 事件）