smart-project/docs/database.md

数据库表结构设计

状态: 设计中（MVP 版本，PostgreSQL）

---

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	预警消息
value	DECIMAL(18,4)	NOT NULL	触发值
threshold	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. 迁移工具

使用 Alembic 管理数据库迁移：

# 初始化
alembic init alembic

# 生成迁移脚本
alembic revision --autogenerate -m "init schema"

# 执行迁移
alembic upgrade head

---

5. 待确认

• 设备历史数据保留策略（多久归档到 OSS）
• 多租户隔离方案（MVP 单租户，后续扩展）
• 预警阈值配置（存 DB 还是配置文件）