vent_ai_platform/docs/database-design.md

数据库设计

数据库选择

• 本地开发和测试：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	工作流执行记录、输入、输出和模型信息

关键关系

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 可增加矿井维度的组合索引

迁移

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

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