fastbee/docs/knowledge-base/03-data-model.md

数据库与表关系

数据库来源

主初始化脚本：sql/yack-init.sql。

补充脚本：

• sql/iot_device_deferred_command.sql
• sql/iot_things_model_push.sql

yack-init.sql 中包含约 100+ 张核心表，并带有大量初始化数据。业务表普遍不使用数据库外键；关系主要由字段命名、联合主键、索引和业务代码保证。Quartz 表保留真实外键。

通用字段约定

字段	含义
tenant_id, tenant_name	多租户归属，IoT/通知/可视化等表常见。
user_id, user_name	用户归属或操作者。
create_by, create_time, update_by, update_time	若依通用审计字段。
del_flag	软删除标记，常见取值 0 正常、2 删除。
status	业务状态，不同表含义不同，需结合枚举/字典。
serial_number	设备唯一编号，是设备日志、Topic、指令和网关关系中的高频关联键。

核心业务 ER 概览

erDiagram
  SYS_USER ||--o{ IOT_DEVICE_USER : owns
  SYS_USER ||--o{ IOT_GROUP : creates
  SYS_USER ||--o{ IOT_DEVICE_SHARE : shared_to
  IOT_CATEGORY ||--o{ IOT_PRODUCT : classifies
  IOT_PRODUCT ||--o{ IOT_DEVICE : has
  IOT_PRODUCT ||--o{ IOT_THINGS_MODEL : defines
  IOT_DEVICE ||--o{ IOT_THINGS_MODEL : overrides
  IOT_DEVICE ||--o{ IOT_DEVICE_LOG : reports
  IOT_DEVICE ||--o{ IOT_EVENT_LOG : emits
  IOT_DEVICE ||--o{ IOT_FUNCTION_LOG : receives
  IOT_PRODUCT ||--o{ IOT_FIRMWARE : owns
  IOT_FIRMWARE ||--o{ IOT_FIRMWARE_TASK : upgrades
  IOT_FIRMWARE_TASK ||--o{ IOT_FIRMWARE_TASK_DETAIL : tracks
  IOT_SCENE ||--o{ IOT_SCENE_DEVICE : triggers
  IOT_SCENE ||--o{ IOT_SCENE_SCRIPT : actions
  IOT_SCRIPT ||--o{ IOT_SCRIPT_BRIDGE : uses
  BRIDGE ||--o{ IOT_SCRIPT_BRIDGE : bound

上图是业务约定关系，不代表 SQL 外键。

产品、设备、物模型

表	主键	说明	关键关系
iot_category	category_id	产品分类，支持 parent_id 层级。	iot_product.category_id 关联分类。
iot_product	product_id	产品定义，包含分类、租户、协议、设备类型等。	一对多关联设备、物模型、固件、Modbus 配置。
iot_protocol	id	协议定义，protocol_code 唯一。	产品通过协议编码/配置选择编解码实现。
iot_device	device_id	设备注册表，serial_number 唯一。	关联产品、租户、用户、日志、网关、物模型覆盖。
iot_things_model	model_id	产品级/设备级物模型。	product_id 关联产品；device_id=0 通常表示产品级，device_id>0 表示设备级覆盖或计算物模型。
iot_things_model_template	template_id	物模型模板。	可用于产品物模型复用。
iot_device_template	id	产品和采集点模板关系。	product_id + template_id。
iot_things_model_translate	id	物模型翻译。	通过 product_id、标识符等业务字段关联。
iot_things_model_template_translate	id	物模型模板翻译。	通过模板标识业务关联。

关键约束/索引：

• iot_device.serial_number 是唯一索引。
• iot_product.category_id、iot_product.tenant_id 有普通索引。
• iot_things_model.product_id、tenant_id、model_order 有普通索引。
• iot_things_model 还有 idx_calculated_serial(is_calculated, serial_number)，用于计算物模型按设备检索。

设备归属、共享和分组

表	主键	说明	关键关系
iot_device_user	device_id, user_id	设备与用户归属关系。	关联 iot_device 和 sys_user。
iot_device_share	device_id, user_id	设备共享关系和权限。	关联设备与被共享用户。
iot_device_group	device_id, group_id	设备加入分组。	关联 iot_device 和 iot_group。
iot_group	group_id	用户创建的设备分组。	user_id 关联 sys_user。
iot_device_alert_user	device_id, user_id	设备告警接收用户。	关联设备与告警接收用户。
order_control	id	指令权限控制。	user_id + device_id 限制控制权限。
command_preferences	id	指令偏好模板。	product_id 和 serial_number 关联设备/产品。

网关、子设备和 Modbus

表	主键	说明	关键关系
iot_sub_gateway	id	网关设备与子设备关系。	gw_device_id、sub_device_id 均约定关联 iot_device.device_id。
iot_product_sub_gateway	id	网关产品与子产品关系。	gw_product_id、sub_product_id 约定关联 iot_product.product_id。
iot_modbus_config	id	产品物模型的 Modbus 点位配置。	product_id 关联产品。
iot_modbus_params	id	产品级 Modbus 默认参数。	product_id 关联产品，slave_id 表示默认从机。
iot_modbus_job	task_id	设备轮询任务。	sub_device_id、job_id 是业务关联字段。
iot_product_modbus_job	task_id	产品轮询任务模板。	product_id 关联产品。
iot_var_temp	template_id	采集变量模板。	user_id 关联模板所属用户。
iot_var_temp_salve	id	模板下从机/点位配置。	device_temp_id 关联 iot_var_temp.template_id。

数据日志

表	主键	说明	关键关系
iot_device_log	log_id	设备属性/监测日志。	device_id、serial_number、tenant_id、user_id。
iot_event_log	log_id	设备事件日志。	关联设备、租户和用户。
iot_function_log	id	服务/指令下发日志。	serial_number、message_id、user_id。
iot_alert_log	alert_log_id	告警历史。	serial_number、product_id、user_id。
iot_simulate_log	log_id	模拟设备日志。	device_id、serial_number。
iot_device_air_log	id	Air780 上报记录。	product_id、device_id。

高频查询索引：

• iot_device_log(serial_number, create_time)
• iot_device_log(serial_number, is_monitor, create_time)
• iot_alert_log(serial_number)
• iot_alert_log(product_id)
• iot_device_log(device_id)

规则、场景、桥接和告警

表	主键	说明	关键关系
iot_scene	scene_id	场景联动/LiteFlow 规则链。	user_id，recover_id 可指向恢复场景。
iot_scene_device	scene_device_id	场景触发设备/产品。	scene_id、product_id、serial_number、script_id。
iot_scene_script	script_id	场景动作/条件脚本。	scene_id、product_id、job_id、parent_id。
iot_script	script_id	规则引擎脚本组件。	scene_id、product_id、user_id。
bridge	id	数据桥接端点配置。	HTTP/MQTT/数据库桥接配置主体。
iot_script_bridge	script_id, bridge_id	脚本与桥接端点关系。	多对多关联 iot_script 和 bridge。
iot_alert	alert_id	告警定义。	租户维度定义告警。
iot_alert_scene	alert_id, scene_id	告警与场景关系。	多对多关联告警和场景。
iot_alert_notify_template	alert_id, notify_template_id	告警与通知模板关系。	多对多关联告警和通知模板。
iot_device_job	job_id, job_name, job_group	设备定时任务。	可关联设备、产品、场景、告警。

LiteFlow SQL 源直接读取：

• iot_scene.chain_name
• iot_scene.el_data
• iot_scene.enable
• iot_script.script_id
• iot_script.script_data
• iot_script.script_language
• iot_script.enable

场景模型、SCADA 和可视化

表	主键	说明	关键关系
scene_model	scene_model_id	业务场景管理。	租户维度。
scene_model_device	id	场景关联设备/虚拟数据源。	scene_model_id、cus_device_id。
scene_model_data	id	场景数据源绑定。	scene_model_id、scene_model_device_id、datasource_id。
scene_model_tag	id	场景录入型变量/计算变量。	scene_model_id。
scene_tag_points	id	运算型变量点。	tag_id 关联变量，scene_model_data_id 关联数据源。
iot_goview_project	id	GoView 项目。	租户维度。
iot_goview_project_data	id	GoView 项目数据。	project_id 关联项目。
scada	id	组态页面。	租户维度。
scada_component	id	组态组件。	tenant_id、user_id。
scada_device_bind	id	组态组件设备绑定。	serial_number 关联设备。
scada_echart	id	图表管理。	租户维度。
scada_gallery	id	组态图库。	租户维度。
scada_model	id	三维模型配置。	租户维度。

固件和 OTA

表	主键	说明	关键关系
iot_firmware	firmware_id	产品固件版本。	product_id 关联产品，tenant_id 关联租户。
iot_firmware_task	id	固件升级任务。	firmware_id 关联固件。
iot_firmware_task_detail	id	任务下设备升级状态。	task_id 关联任务，serial_number 关联设备。

视频监控和媒体

表	主键	说明	关键关系
sip_config	id	SIP 系统配置。	可关联 product_id。
sip_device	device_id	GB28181 监控设备/NVR。	product_id，device_sip_id。
sip_device_channel	id, device_sip_id	摄像头通道。	device_sip_id 关联 SIP 设备编号，channel_sip_id 是通道编号。
media_server	id	ZLMediaKit 流媒体服务器配置。	server_id 是媒体服务标识。
iot_sip_relation	id	IoT 设备/场景与 SIP 通道关系。	channel_id、re_device_id、re_scene_model_id。

通知和推送

表	主键	说明	关键关系
notify_channel	id	通知渠道账号。	租户维度。
notify_template	id	通知模板。	channel_id 关联通知渠道。
notify_log	id	通知发送日志。	channel_id、notify_template_id。
iot_things_model_push_config	id	物模型数据推送配置。	device_id、template_id、user_id。
iot_push_model_item	id	推送配置下的物模型项和阈值。	config_id 关联推送配置，model_id 关联物模型。
iot_push_user	id	推送接收用户。	config_id 关联推送配置，user_id 关联系统用户。

系统 RBAC 和基础表

erDiagram
  SYS_DEPT ||--o{ SYS_USER : contains
  SYS_USER ||--o{ SYS_USER_ROLE : has
  SYS_ROLE ||--o{ SYS_USER_ROLE : assigned
  SYS_ROLE ||--o{ SYS_ROLE_MENU : grants
  SYS_MENU ||--o{ SYS_ROLE_MENU : included
  SYS_ROLE ||--o{ SYS_ROLE_DEPT : scopes
  SYS_DEPT ||--o{ SYS_ROLE_DEPT : scoped
  SYS_USER ||--o{ SYS_USER_POST : holds
  SYS_POST ||--o{ SYS_USER_POST : assigned

表	主键	说明
sys_user	user_id	用户。
sys_dept	dept_id	部门/机构，parent_id 形成树。
sys_role	role_id	角色。
sys_menu	menu_id	菜单和权限，parent_id 形成树。
sys_post	post_id	岗位。
sys_user_role	user_id, role_id	用户角色关系。
sys_role_menu	role_id, menu_id	角色菜单权限。
sys_role_dept	role_id, dept_id	角色数据权限。
sys_user_post	user_id, post_id	用户岗位关系。
sys_config	config_id	系统参数。
sys_dict_type	dict_id	字典类型，dict_type 唯一。
sys_dict_data	dict_code	字典数据，通过 dict_type 关联字典类型。
sys_notice	notice_id	通知公告。
sys_oper_log	oper_id	操作日志。
sys_logininfor	info_id	登录日志。
sys_client	id	系统授权客户端。
sys_auth_user	auth_id	第三方授权用户。
sys_user_relation	root_id	用户关系和层级深度缓存。

翻译表：

• sys_menu_translate
• sys_dict_type_translate
• sys_dict_data_translate

OAuth、第三方登录和内容

表	说明
oauth_client_details	OAuth 客户端配置。
oauth_access_token, oauth_refresh_token, oauth_client_token, oauth_code, oauth_approvals	Spring OAuth Token/授权数据。
iot_social_platform	第三方登录平台配置。
iot_social_user	第三方用户和系统用户绑定。
app_language	App 语言配置。
app_preferences	用户 App 偏好，user_id + language 唯一。
news, news_category	新闻资讯和分类。

OSS、代码生成和任务

表	说明
oss_config	对象存储配置。
oss_detail	上传文件记录。
gen_table, gen_table_column	代码生成器元数据。
sys_job, sys_job_log	若依定时任务配置和日志。

Quartz 强约束关系

这些是 SQL 中真实存在的外键：

qrtz_triggers(sched_name, job_name, job_group)
  -> qrtz_job_details(sched_name, job_name, job_group)

qrtz_blob_triggers(sched_name, trigger_name, trigger_group)
  -> qrtz_triggers(sched_name, trigger_name, trigger_group)

qrtz_cron_triggers(sched_name, trigger_name, trigger_group)
  -> qrtz_triggers(sched_name, trigger_name, trigger_group)

qrtz_simple_triggers(sched_name, trigger_name, trigger_group)
  -> qrtz_triggers(sched_name, trigger_name, trigger_group)

qrtz_simprop_triggers(sched_name, trigger_name, trigger_group)
  -> qrtz_triggers(sched_name, trigger_name, trigger_group)

其他 Quartz 表如 qrtz_calendars、qrtz_fired_triggers、qrtz_locks、qrtz_scheduler_state 由 Quartz 框架维护。

关系梳理原则

• 优先看 SQL 主键、联合主键、唯一索引和普通索引。
• 再看 Java Domain、Mapper XML、Service 查询条件。
• 对无外键的业务表，文档只标记为“业务约定关联”。
• serial_number 是很多运行时链路的核心关联键，但真正的设备主键仍是 iot_device.device_id。
• product_id、device_id、user_id、tenant_id 等字段在不同表中含义一致，但删除/更新一致性由业务代码维护。