# 数据库设计

## 数据库选择

- 本地开发和测试：SQLite
- 生产环境：MySQL 8.0，字符集 `utf8mb4`
- 高频时序数据：当前提供 `sensor_readings` 基础表，生产建议迁移到专用时序数据库
- 原始文件：数据库只保存元数据和路径，文件建议使用 MinIO 或对象存储

所有业务表使用 32 位字符串 UUID，通过 SQLAlchemy `Base.metadata` 统一生成。

## 业务域

### 矿井与空间对象

| 表 | 用途 |
|---|---|
| `mines` | 矿井主数据 |
| `mine_areas` | 采区 |
| `work_faces` | 采掘工作面 |
| `roadways` | 巷道和通风网络对象 |

对象层级：矿井 → 采区 → 工作面/巷道。

### 数据感知与监测

| 表 | 用途 |
|---|---|
| `data_sources` | 安全监控、视频、物联平台等数据源 |
| `sensors` | 传感器主数据和最近值 |
| `sensor_readings` | 时序监测读数 |
| `ventilation_facilities` | 风门、风窗、密闭、风桥等设施 |

生产环境可将 `sensor_readings` 拆到 TDengine 等时序库，`sensors` 仍保留在关系库。

### 工业视频平台

| 表 | 用途 |
|---|---|
| `video_channels` | 视频通道、设备树、分屏预览、实时流地址和演示视频磁盘路径 |
| `video_snapshots` | AI 识别抓拍图像（车辆/人员通行、风门未关严、人员检测等）的元数据与磁盘路径 |
| `video_analysis_events` | 视频分析事件与实时告警及处理状态 |
| `video_records` | 通行与操作记录统一宽表（车辆/人员通行、风门未关严、人员轨迹、区域统计、设备操作、预警） |

视频与图像文件本身不落库，表字段保存磁盘绝对路径（演示数据来自风门/局扇/主扇识别演示目录，
根目录由 `VIDEO_MEDIA_ROOT` 配置），接口按路径流式读取。
`video_records.record_type` 区分记录类型：
`vehicle_passage`、`person_passage`、`door_unclosed`、`person_track`、`area_stay`、
`person_warn`、`person_detect`、`device_operation`、`device_warn`。
模块维度由 `module` 字段区分：`door`、`local_fan`、`main_fan`。

### 业务资料

| 表 | 用途 |
|---|---|
| `business_documents` | 资料元数据、分类、解析状态和文件路径 |
| `document_extractions` | OCR/版面解析后的结构化字段 |

资料分类固定为：

`全部资料`、`通风专业`、`火灾防治`、`监测监控`、`粉尘防治`、`瓦斯防治`、`制度管理`。

### 知识中心

| 表 | 用途 |
|---|---|
| `knowledge_items` | 规程、案例、专家经验和制度知识 |
| `knowledge_chunks` | 知识切片和向量索引引用 |

当前检索使用数据库关键词匹配，后续可接向量库和知识图谱。

### 缺陷诊断

| 表 | 用途 |
|---|---|
| `diagnosis_rules` | 规则库和阈值 |
| `diagnosis_tasks` | 一次诊断任务 |
| `diagnosis_results` | 缺陷、风险等级、置信度和建议 |
| `diagnosis_evidence` | 监测、视频、知识、设施等证据链 |

场景建议值：

`局部通风`、`通风设施`、`通风系统管理`、`风量分配`、`灾害防治`。

### 综合评价

| 表 | 用途 |
|---|---|
| `evaluation_indicators` | 指标树、维度、权重和计算口径 |
| `evaluation_runs` | 一次评价批次、总分、等级和建议 |
| `evaluation_scores` | 每个指标的原始值、得分和权重 |

默认维度：

`安全性`、`可靠性`、`经济性`、`管理合规`、`数据质量`。

### 告警与闭环

| 表 | 用途 |
|---|---|
| `alarms` | 原始告警 |
| `work_orders` | 整改任务 |
| `work_order_events` | 创建、指派、整改、复核、关闭轨迹 |

建议状态：`pending`、`processing`、`review`、`completed`、`closed`。

### Agent 运行

| 表 | 用途 |
|---|---|
| `agent_sessions` | DeepAgent 会话 |
| `agent_runs` | 工作流执行记录、输入、输出和模型信息 |

## 关键关系

```text
mines 1 ── n mine_areas
mines 1 ── n work_faces
mines 1 ── n roadways
mines 1 ── n data_sources
mines 1 ── n sensors
sensors 1 ── n sensor_readings
mines 1 ── n ventilation_facilities
mines 1 ── n video_channels
video_channels 1 ── n video_snapshots
video_channels 1 ── n video_records
video_channels 1 ── n video_analysis_events
video_snapshots 1 ── n video_records
mines 1 ── n business_documents
business_documents 1 ── n document_extractions
business_documents 1 ── n knowledge_items
diagnosis_tasks 1 ── n diagnosis_results
diagnosis_results 1 ── n diagnosis_evidence
evaluation_runs 1 ── n evaluation_scores
evaluation_indicators 1 ── n evaluation_scores
alarms 1 ── n work_orders
work_orders 1 ── n work_order_events
agent_sessions 1 ── n agent_runs
```

## 索引策略

- 所有关联外键建立索引
- 矿井编码、资料分类、解析状态、任务状态、缺陷等级和工单状态建立索引
- `sensor_readings(sensor_id, measured_at)` 是主要时序查询组合
- 生产 MySQL 可增加矿井维度的组合索引

## 迁移

```powershell
alembic upgrade head
alembic revision --autogenerate -m "add table"
```

新表必须同时进入 `app/db/models/` 和 `app/db/models/__init__.py`，否则 Alembic 无法识别。