Jesxion
7b71edf17a
- alert_engine → alert_handler（仅接收存储） - 移除 alert_records.threshold 字段 - 架构图/DB/API 文档同步更新
194 lines
6.5 KiB
Markdown
194 lines
6.5 KiB
Markdown
# 数据库表结构设计
|
||
|
||
> 状态: 设计中（MVP 版本，SQLite）
|
||
|
||
---
|
||
|
||
## 1. ER 图概述
|
||
|
||
```
|
||
users ─────────┐
|
||
│ 1:N
|
||
▼
|
||
user_device_access (N:M)
|
||
│
|
||
▼
|
||
devices ───────┤
|
||
│
|
||
├──── 1:N ──── device_realtime (最新状态)
|
||
│
|
||
├──── 1:N ──── device_history (历史数据)
|
||
│
|
||
└──── 1:N ──── alert_records (预警记录)
|
||
|
||
alert_records ────── N:1 ──── users (处理人)
|
||
|
||
oss_files ──────────────────────────────────────────────────┐
|
||
│
|
||
(其他模块按需关联) │
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 表结构
|
||
|
||
### 2.1 users（用户表）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | SERIAL | PRIMARY KEY | 自增ID |
|
||
| username | VARCHAR(64) | UNIQUE NOT NULL | 用户名 |
|
||
| password_hash | VARCHAR(256) | NOT NULL | bcrypt 密码哈希 |
|
||
| role | VARCHAR(32) | NOT NULL DEFAULT 'viewer' | 角色: admin / operator / viewer |
|
||
| real_name | VARCHAR(128) | | 真实姓名 |
|
||
| phone | VARCHAR(32) | | 手机号 |
|
||
| is_active | BOOLEAN | DEFAULT true | 是否启用 |
|
||
| created_at | TIMESTAMP | DEFAULT NOW() | 创建时间 |
|
||
| updated_at | TIMESTAMP | DEFAULT NOW() | 更新时间 |
|
||
|
||
**索引**:
|
||
- `idx_users_username` ON (`username`)
|
||
|
||
---
|
||
|
||
### 2.2 devices（设备台账表）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PRIMARY KEY | 设备ID（对接已有API的设备编号） |
|
||
| name | VARCHAR(128) | NOT NULL | 设备名称，如 "1号塔吊" |
|
||
| type | VARCHAR(32) | NOT NULL | 类型: `tower_crane` / `elevator` |
|
||
| model | VARCHAR(128) | | 设备型号，如 "QTZ500" |
|
||
| manufacturer | VARCHAR(128) | | 制造商 |
|
||
| location | VARCHAR(256) | | 安装位置，如 "A区施工现场" |
|
||
| install_date | DATE | | 安装日期 |
|
||
| status | VARCHAR(32) | DEFAULT 'offline' | 在线状态: online / offline |
|
||
| last_seen | TIMESTAMP | | 最后在线时间 |
|
||
| config | JSONB | DEFAULT '{}' | 设备配置（预警阈值等） |
|
||
| created_at | TIMESTAMP | DEFAULT NOW() | 创建时间 |
|
||
| updated_at | TIMESTAMP | DEFAULT NOW() | 更新时间 |
|
||
|
||
**索引**:
|
||
- `idx_devices_type` ON (`type`)
|
||
- `idx_devices_status` ON (`status`)
|
||
|
||
---
|
||
|
||
### 2.3 device_realtime（设备实时状态）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | SERIAL | PRIMARY KEY | 自增ID |
|
||
| device_id | VARCHAR(64) | FOREIGN KEY → devices(id) | 设备ID |
|
||
| timestamp | TIMESTAMP | NOT NULL | 数据时间戳 |
|
||
| raw_data | JSONB | NOT NULL | 原始数据快照 |
|
||
| parsed_data | JSONB | NOT NULL | 解析后的结构化数据 |
|
||
| created_at | TIMESTAMP | DEFAULT NOW() | 写入时间 |
|
||
|
||
**索引**:
|
||
- `idx_realtime_device_id` ON (`device_id`)
|
||
- `idx_realtime_timestamp` ON (`timestamp` DESC)
|
||
|
||
> 每次设备数据更新时，UPSERT 写入此表，仅保留最新一条记录。
|
||
|
||
---
|
||
|
||
### 2.4 device_history（设备历史数据）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | BIGSERIAL | PRIMARY KEY | 自增ID |
|
||
| device_id | VARCHAR(64) | FOREIGN KEY → devices(id) | 设备ID |
|
||
| timestamp | TIMESTAMP | NOT NULL | 数据时间戳 |
|
||
| metric_name | VARCHAR(64) | NOT NULL | 指标名: load / range / height 等 |
|
||
| metric_value | DECIMAL(18,4) | NOT NULL | 指标值 |
|
||
| unit | VARCHAR(32) | | 单位: kN / m / m/s 等 |
|
||
| created_at | TIMESTAMP | DEFAULT NOW() | 写入时间 |
|
||
|
||
**索引**:
|
||
- `idx_history_device_time` ON (`device_id`, `timestamp` DESC)
|
||
- `idx_history_metric` ON (`metric_name`)
|
||
- **分区**: 按月分区（`timestamp`），按设备ID + 时间范围查询
|
||
|
||
> 为节省存储空间，历史数据可定期归档到 OSS（冷存储），DB 仅保留近3个月数据。
|
||
|
||
---
|
||
|
||
### 2.5 alert_records（预警记录表）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PRIMARY KEY | 预警ID（UUID） |
|
||
| device_id | VARCHAR(64) | FOREIGN KEY → devices(id) | 设备ID |
|
||
| device_name | VARCHAR(128) | | 冗余存储，查询方便 |
|
||
| level | VARCHAR(32) | NOT NULL | 级别: warning / danger |
|
||
| metric | VARCHAR(64) | NOT NULL | 触发指标: load / wind_speed 等 |
|
||
| message | VARCHAR(512) | NOT NULL | 预警消息（设备 API 提供） |
|
||
| value | DECIMAL(18,4) | NOT NULL | 触发时的实际值 |
|
||
| status | VARCHAR(32) | DEFAULT 'unread' | 状态: unread / handled / ignored |
|
||
| handled_by | INTEGER | FOREIGN KEY → users(id) | 处理人 |
|
||
| handle_note | TEXT | | 处理备注 |
|
||
| created_at | TIMESTAMP | DEFAULT NOW() | 创建时间 |
|
||
| handled_at | TIMESTAMP | | 处理时间 |
|
||
|
||
**索引**:
|
||
- `idx_alerts_device` ON (`device_id`)
|
||
- `idx_alerts_status` ON (`status`)
|
||
- `idx_alerts_level` ON (`level`)
|
||
- `idx_alerts_created` ON (`created_at` DESC)
|
||
|
||
---
|
||
|
||
### 2.6 oss_files（OSS 文件索引表）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | SERIAL | PRIMARY KEY | 自增ID |
|
||
| object_key | VARCHAR(512) | UNIQUE NOT NULL | OSS 对象路径 |
|
||
| filename | VARCHAR(256) | NOT NULL | 原始文件名 |
|
||
| content_type | VARCHAR(128) | | MIME 类型 |
|
||
| size | BIGINT | | 文件大小（字节） |
|
||
| category | VARCHAR(64) | | 分类: report / certificate / log |
|
||
| uploaded_by | INTEGER | FOREIGN KEY → users(id) | 上传人 |
|
||
| uploaded_at | TIMESTAMP | DEFAULT NOW() | 上传时间 |
|
||
| expires_at | TIMESTAMP | | 过期时间（临时文件） |
|
||
|
||
**索引**:
|
||
- `idx_oss_category` ON (`category`)
|
||
- `idx_oss_uploaded_by` ON (`uploaded_by`)
|
||
|
||
---
|
||
|
||
## 3. 初始数据
|
||
|
||
### 3.1 超级管理员
|
||
|
||
| username | password | role |
|
||
|----------|----------|------|
|
||
| admin | （首次部署时设置） | admin |
|
||
|
||
---
|
||
|
||
## 4. 数据库初始化
|
||
|
||
MVP 阶段使用 SQLite，`schema.sql` 定义建表语句，启动时自动初始化：
|
||
|
||
```bash
|
||
# 手动初始化（可选，生产环境自动执行）
|
||
sqlite3 smart_project.db < schema.sql
|
||
|
||
# 或通过 Python 脚本
|
||
python -m src.db.init_db
|
||
```
|
||
|
||
> SQLite 无需迁移工具，每次表结构变更手动更新 `schema.sql` 并重启服务即可。
|
||
|
||
---
|
||
|
||
## 5. 待确认
|
||
|
||
- [x] OSS Bucket → `jesxion-ai-studio`（开发测试阶段）
|
||
- [x] 数据库 → SQLite（MVP）
|
||
- [ ] 设备 API 协议格式（塔吊/升降机数据字段）— 厂家文档后续提供
|
||
- [ ] 多租户隔离方案（MVP 单租户，后续扩展）
|