# 数据库表结构设计

> 状态: 设计中（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 单租户，后续扩展）