feat: 初始化设计文档草稿
- SPEC.md: 项目概览与文档索引 - docs/architecture.md: 系统架构设计 - docs/api.md: 后台 API 接口设计 - docs/database.md: 数据库表结构设计 - docs/h5.md: H5 页面结构与交互设计 - docs/offline.md: 离线数据方案 状态: 设计中，待设备API协议确认后细化
This commit is contained in:
139
docs/architecture.md
Normal file
139
docs/architecture.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# 系统架构设计
|
||||
|
||||
> 状态: 设计中
|
||||
|
||||
---
|
||||
|
||||
## 1. 系统架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 阿里云 OSS │
|
||||
│ (文件存储: 证书/报告/日志) │
|
||||
└───────────────┬─────────────────────────┘
|
||||
│ upload
|
||||
▼
|
||||
┌──────────┐ ┌─────────────────────────┐ ┌──────────────┐
|
||||
│ 已有API │───▶│ 后台 API 服务 │◀───│ H5 客户端 │
|
||||
│ (塔吊/ │ │ Python / FastAPI │ │ (移动端浏览器)│
|
||||
│ 升降机) │ │ │ │ │
|
||||
└──────────┘ │ ┌───────────────────┐ │ └──────────────┘
|
||||
│ │ 设备数据接入层 │ │ ▲
|
||||
│ │ 预警引擎 │ │ │ polling / websocket
|
||||
│ │ OSS 文件管理 │ │
|
||||
│ │ REST API │ │
|
||||
│ └───────────────────┘ │ │
|
||||
└────────────┬────────────┘ │
|
||||
│ │
|
||||
▼ │
|
||||
┌─────────────────────────┐ │
|
||||
│ PostgreSQL │ │
|
||||
│ (设备台账/预警记录/ │◀────────────┘
|
||||
│ 用户/OSS文件索引) │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 模块划分
|
||||
|
||||
### 2.1 后台 API 服务
|
||||
|
||||
**职责**：数据聚合层，统一对接已有设备 API，屏蔽异构数据源差异，对 H5 提供标准化 REST API。
|
||||
|
||||
| 模块 | 说明 |
|
||||
|------|------|
|
||||
| `device_adapter` | 设备 API 适配器：塔吊协议解析、升降机协议解析 |
|
||||
| `monitor` | 设备状态监控：定时轮询已有 API，写入本地 DB |
|
||||
| `alert_engine` | 预警引擎：阈值判断、预警生成、通知分发 |
|
||||
| `file_mgr` | OSS 文件管理：上传、下载、索引 |
|
||||
| `api_routes` | REST API 路由：设备台账、实时数据、历史查询、预警、OSS |
|
||||
|
||||
### 2.2 H5 客户端
|
||||
|
||||
**职责**：移动端展示与操作界面，基于响应式 H5 开发，适配手机浏览器。
|
||||
|
||||
| 模块 | 说明 |
|
||||
|------|------|
|
||||
| `dashboard` | 首页仪表盘：设备总数、在线/离线、告警统计 |
|
||||
| `device_list` | 设备列表：塔吊/升降机分类展示 |
|
||||
| `device_detail` | 设备详情：实时数据面板、历史曲线 |
|
||||
| `alert_list` | 预警列表：未读/已处理筛选 |
|
||||
| `alert_detail` | 预警详情：处理/忽略操作 |
|
||||
| `profile` | 个人中心：账号信息、通知设置 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据流向
|
||||
|
||||
### 3.1 设备数据采集
|
||||
|
||||
```
|
||||
已有设备 API
|
||||
│ (定时轮询: 每 30s 或设备主动推送)
|
||||
▼
|
||||
device_adapter (协议解析)
|
||||
│
|
||||
▼
|
||||
monitor (写入 DB + 触发预警判断)
|
||||
│
|
||||
├──────────────────┐
|
||||
▼ ▼
|
||||
PostgreSQL alert_engine
|
||||
(设备状态表) (阈值判断)
|
||||
│
|
||||
▼
|
||||
alert_records (预警记录表)
|
||||
│
|
||||
▼
|
||||
通知分发 (站内/OSS记录)
|
||||
```
|
||||
|
||||
### 3.2 H5 数据请求
|
||||
|
||||
```
|
||||
H5 浏览器
|
||||
│ GET /api/devices
|
||||
│ GET /api/devices/{id}/realtime
|
||||
│ GET /api/alerts
|
||||
▼
|
||||
api_routes (FastAPI)
|
||||
│
|
||||
├──────────────┐
|
||||
▼ ▼
|
||||
PostgreSQL OSS
|
||||
(结构化数据) (文件URL)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 部署架构
|
||||
|
||||
MVP 阶段采用轻量部署：
|
||||
|
||||
| 组件 | 部署方式 |
|
||||
|------|----------|
|
||||
| 后台 API | 阿里云函数计算（FC）或轻量服务器 |
|
||||
| PostgreSQL | 阿里云 RDS 或轻量服务器自建 |
|
||||
| OSS | 阿里云 OSS 标准存储 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 安全设计
|
||||
|
||||
| 措施 | 说明 |
|
||||
|------|------|
|
||||
| HTTPS | 全链路 HTTPS，证书由阿里云管理 |
|
||||
| Token 认证 | H5 API 请求携带 JWT Token |
|
||||
| CORS | 限制允许的 H5 域名 |
|
||||
| OSS 鉴权 | H5 通过后台签发临时 URL 访问 OSS 文件 |
|
||||
| 输入校验 | FastAPI Pydantic 模型全量参数校验 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 待细化
|
||||
|
||||
- [ ] 设备 API 协议细节（目前尚未获取，需跟进沟通）
|
||||
- [ ] 预警阈值配置方案（管理员界面 or 配置文件）
|
||||
- [ ] 实时通知方案（WebSocket / SSE / 轮询）
|
||||
- [ ] 多租户隔离方案（目前 MVP 单租户设计）
|
||||
Reference in New Issue
Block a user