# Data Model And API Map

## Page Guide

- **Use Cases**: For quickly finding relationships between business tables, APIs, and pages during secondary development, troubleshooting, SQL upgrades, and API integration.
- **Source Location**: SQL is located at `springboot/sql`; the current major-version initialization script is `fastbee-v2.9.0.sql`.
- **Database Scope**: Includes the MySQL main database, multi-database adaptation scripts, TDengine/IoTDB time-series data, and AI initialization scripts.
- **How To Use**: Find the table name prefix by business module, then trace back to the API, frontend page, and secondary-development notes.

## 1. Table Name Prefixes

| Prefix | Business Scope | Examples |
| --- | --- | --- |
| `iot_` | IoT core business | Products, devices, thing models, rules, alerts, work orders, firmware |
| `scene_` | Scene models | Scenes, variables, devices, tags |
| `sip_` | GB28181 video | SIP configuration, devices, channels |
| `common_` | Common media channels | URL stream pulling, channel binding |
| `media_` | Streaming media service | Media server configuration |
| `notify_` | Notification service | Channels, templates, logs |
| `ai_` | AI capabilities | Models, knowledge base, conversations, protocol adaptation |
| `report_` | Report center | Reports, rules, records |
| `sys_` | System administration | Users, roles, menus, dictionaries, configuration |
| `oauth_` | OAuth/SSO | Clients, tokens, authorization codes |
| `oss_` | File storage | OSS configuration, file details |
| `qrtz_` | Scheduled tasks | Quartz task tables |

## 2. Core IoT Tables

| Professional | Main Tables | API Prefix | Frontend Entry |
| --- | --- | --- | --- |
| Product | `iot_product`, `iot_category`, `iot_product_authorize`, `iot_product_ext_param` | `/iot/product` | `vue3/src/views/iot/product` |
| Thing Model | `iot_things_model`, `iot_things_model_tag`, `iot_things_model_template` | `/iot/model`, `/iot/template` | Product detail, thing model pages |
| Device | `iot_device`, `iot_device_user`, `iot_device_share`, `iot_device_group` | `/iot/device`, `/iot/deviceUser` | `vue3/src/views/iot/device` |
| Logs | `iot_device_log`, `iot_event_log`, `iot_function_log` | `/iot/record`, `/iot/message` | Device detail log tab |
| OTA | `iot_firmware`, `iot_firmware_task`, `iot_firmware_task_detail` | `/iot/firmware` | `vue3/src/views/iot/firmware` |
| Rule | `iot_rule_el`, `iot_rule_trigger`, `iot_rule_log` | `/iot/ruletrigger`, `/rule/chain` | `vue3/src/views/ruleengine` |
| Bridging | `iot_bridge`, `iot_script_bridge` | `/iot/bridge` | Rule and bridging pages |
| Alert | `iot_alert`, `iot_alert_log`, `iot_alert_scene`, `iot_alert_notify_template` | `/iot/alert` | `vue3/src/views/iot/alert` |
| Work Orders And Maintenance | `iot_work_order`, `iot_device_maintenance` | `/iot/workOrder`, `/iot/maintenance` | Work order and maintenance pages |
| IoT Card | `iot_card`, `iot_card_platform` | Card management APIs | `vue3/src/views/iot/card` |

## 3. Device Access And Protocol Tables

| Professional | Main Tables | Notes |
| --- | --- | --- |
| Protocol management | `iot_protocol` | Platform protocol configuration and protocol scripts |
| Modbus configuration | `iot_modbus_config`, `iot_modbus_params`, `iot_modbus_job` | Device-level registers, parameters, and polling jobs |
| Product Modbus | `iot_product_modbus_job`, `iot_product_sub_gateway` | Product-level gateways, sub-products, and polling configuration |
| Gateway sub-devices | `iot_sub_gateway` | Gateway and sub-device relationships |
| Variable templates | `iot_var_temp`, `iot_var_temp_salve` | Variable templates and slave configuration |
| Simulation logs | `iot_simulate_log` | Simulated device or debugging records |

## 4. Video And Visualization Tables

| Professional | Main Tables | API Prefix |
| --- | --- | --- |
| SIP configuration | `sip_config` | `/sip/sipconfig` |
| SIP devices | `sip_device` | `/sip/device` |
| SIP channels | `sip_device_channel`, `iot_sip_relation` | `/iot/channel` |
| URL channels | `common_channel` | `/iot/channel` |
| Media servers | `media_server` | `/mediaserver` |
| Visualization projects | `iot_goview_project`, `iot_goview_project_data` | `/goview/project`, `/goview/projectData` |

## 5. Scene, Report, And Notification Tables

| Professional | Main Tables | API Prefix |
| --- | --- | --- |
| Scene models | `scene_model`, `scene_model_data`, `scene_model_device`, `scene_model_tag` | `/scene/model`, `/scene/modelData` |
| Scene tag points | `scene_tag_points` | Scene tags and points |
| Reports | `report`, `report_records`, `report_rule`, `report_rule_data` | Report-related APIs |
| Notifications | `notify_channel`, `notify_template`, `notify_log` | `/notify/channel`, `/notify/template`, `/notify/log` |

## 6. AI Tables

| Professional | Main Tables | API Prefix |
| --- | --- | --- |
| Model providers | `ai_provider` | `/ai/provider` |
| Model configuration | `ai_model` | `/ai/model` |
| Conversations | `ai_chat_session`, `ai_chat_message` | `/ai/chat`, `/ai/chatRecord` |
| Knowledge base | `ai_knowledge_base`, `ai_knowledge_document`, `ai_knowledge_version` | `/ai/knowledge` |
| Invocation logs | `ai_invoke_log`, `ai_tool_call_log` | AI invocation auditing |
| File assets | `ai_file_asset` | Knowledge base file assets |
| Protocol adaptation | `ai_protocol_adaptation_task`, `ai_protocol_adaptation_artifact`, `ai_protocol_generation_record` | `/ai/protocol/adaptation` |

## 7. System And Plug-in Tables

| Professional | Main Tables | API Prefix |
| --- | --- | --- |
| Users and roles | `sys_user`, `sys_role`, `sys_menu`, `sys_dept` | `/system/user`, `/system/role`, `/system/menu` |
| Dictionary configuration | `sys_dict_type`, `sys_dict_data`, translation tables | `/system/dict/*` |
| Login and operation logs | `sys_logininfor`, `sys_oper_log` | `/monitor/*` |
| Scheduled tasks | `sys_job`, `sys_job_log`, `qrtz_*` | `/monitor/job` |
| OAuth/SSO | `oauth_client_details`, `oauth_access_token`, `oauth_refresh_token` | `/oauth2/*`, `/iot/clientDetails` |
| OSS | `oss_config`, `oss_detail` | `/oss/config`, `/oss/detail` |
| Code generator | `gen_table`, `gen_table_column` | `/tool/gen` |

## 8. Upgrade Script Strategy

| Scenario | Recommendation |
| --- | --- |
| New deployment | Use the current major-version initialization SQL |
| Version upgrade | Execute the `upgrade` scripts in version order |
| Multiple databases | Use the Dameng, KingbaseES, Oracle, Postgres, or SQL Server scripts in the corresponding directory |
| AI initialization | Confirm whether the AI tables and initialization data have been merged into the main script; run the AI initialization script if necessary |
| Time-series database | TDengine/IoTDB use independent initialization scripts and runtime configuration |
| Before go-live | Back up the database, record the current version, and rehearse the upgrade in a test environment first |

## 9. Secondary-Development Notes

* When adding a business field, update the Domain, Mapper, VO/DTO, Controller, frontend form, and SQL together.
* When multi-database support is involved, do not change only the MySQL script.
* Do not write all high-frequency device data directly into MySQL; prefer the time-series data link.
* When tenant isolation is involved, confirm the `create_by`, organization, and role data scope and query conditions.
* When modifying core tables such as thing model, device, and rule, consider cache refresh.
* Before deleting data, confirm whether there are related devices, rules, scenes, schematics, alerts, work orders, and historical data.

## 10. Related Docs

* [Backend Module Map](https://www.fastbee.cn/doc/en/business/v2/dev/backend-module-map.html)
* [Database Persistence Layer Architecture](https://www.fastbee.cn/doc/en/business/v2/dev/database.html)
* [Data And Database Architecture](https://www.fastbee.cn/doc/en/business/v2/architecture/data.html)
* [Vue3 Frontend Development And Integration](https://www.fastbee.cn/doc/en/business/v2/dev/vue3-development.html)
