# 系统架构设计

> 状态: 设计中

---

## 1. 系统架构图

```
                    ┌─────────────────────────────────────────┐
                    │           阿里云 OSS                    │
                    │    (文件存储: 证书/报告/日志)            │
                    └───────────────┬─────────────────────────┘
                                    │ upload
                                    ▼
┌──────────┐    ┌─────────────────────────┐    ┌──────────────┐
│ 已有API  │───▶│      后台 API 服务        │◀───│   H5 客户端   │
│ (塔吊/   │    │   Python / FastAPI      │    │  (移动端浏览器)│
│  升降机) │    │                         │    │               │
└──────────┘    │  ┌───────────────────┐  │    └──────────────┘
                │  │  设备数据接入层    │  │            ▲
                │  │  预警引擎          │  │            │ polling / websocket
                │  │  OSS 文件管理      │  │
                │  │  REST API          │  │
                │  └───────────────────┘  │            │
                └────────────┬────────────┘            │
                             │                          │
                             ▼                          │
                ┌─────────────────────────┐
                │      SQLite              │
                │  (设备台账/预警记录/     │◀────────────┘
                │   用户/OSS文件索引)     │
                └─────────────────────────┘
```

---

## 2. 模块划分

### 2.1 后台 API 服务

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

| 模块 | 说明 |
|------|------|
| `device_adapter` | 设备 API 适配器：塔吊协议解析、升降机协议解析 |
| `monitor` | 设备状态监控：定时轮询已有 API，写入本地 DB |
| `alert_handler` | 预警接收与存储：接收设备 API 的预警数据，存入 DB |
| `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)
     │
     ├──────────────────┐
     ▼                  ▼
SQLite              alert_handler
(设备状态表)       (接收设备预警，写入 DB)
                         │
                         ▼
                  alert_records (预警记录表)
```

### 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. 待细化

- [x] ~~预警阈值配置~~ → 设备 API 自带预警判断，本系统仅做聚合展示
- [ ] 设备 API 协议细节（塔吊/升降机数据字段）— 厂家文档后续提供
- [ ] 多租户隔离方案（目前 MVP 单租户设计）