docs: 全面审阅修复

- 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
parent ba5d65d438
commit cb0ef8c30c
4 changed files with 484 additions and 81 deletions
--- 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 管理（环境变量，部署时配置）