Documento di Progettazione del Database MyEMS

Questo documento è rivolto ai programmatori e fornisce una spiegazione dettagliata dell'architettura del database, della struttura delle tabelle e della filosofia di progettazione del sistema di gestione energetica MyEMS.

Indice

• Progettazione dell'architettura del database
• Descrizione dettagliata del database
• Relazioni di flusso dati
• Specifiche di progettazione della struttura delle tabelle

---

Progettazione dell'architettura del database

Filosofia di progettazione

1. Separazione dei dati: I dati sono suddivisi in database diversi in base al tipo e all'uso, per evitare che un singolo database diventi troppo grande
2. Separazione tra lettura e scrittura: I dati storici sono memorizzati in formato serie temporale, consentendo interrogazioni efficienti
3. Scalabilità orizzontale: I database di grandi dimensioni (historical_db, energy_db) possono essere scalati indipendentemente
4. Standard unificati: Tutti i database utilizzano lo stesso set di caratteri e regole di ordinamento

Configurazione del database

Tutti i database utilizzano uniformemente la seguente configurazione:

• Set di caratteri: utf8mb4 (supporta il set di caratteri UTF-8 completo, incluse le emoji)
• Regola di ordinamento: utf8mb4_unicode_ci (regola di ordinamento Unicode)
• Motore di archiviazione: InnoDB (predefinito, supporta transazioni e chiavi esterne)

Convenzioni di denominazione

• Denominazione dei database: myems_{funzione}_db (minuscolo, separato da underscore)
• Denominazione delle tabelle: tbl_{nome_entità} (minuscolo, separato da underscore)
• Denominazione dei campi: Minuscolo, separato da underscore, come start_datetime_utc
• Denominazione degli indici: tbl_{nome_tabella}_index_{numero_sequenziale}

---

Descrizione dettagliata del database

1. myems_system_db (database di configurazione di sistema)

Scopo: Memorizzare la configurazione base e i metadati del sistema, fungendo da libreria di configurazione centrale dell'intero sistema.

Caratteristiche:

• Contiene il maggior numero di tabelle (oltre 150)
• Il volume di dati è relativamente ridotto, ma la struttura è complessa
• Contiene numerose tabelle di associazione

Classificazione principale delle tabelle:

1.1 Tabelle di configurazione base

nome tabella	Descrizione	campo chiave
tbl_energy_categories	Categorie energetiche (elettricità, acqua, gas, freddo, calore, ecc.)	id, name, unit_of_measure, kgce, kgco2e
tbl_energy_items	Sottovoci di consumo energetico (illuminazione, climatizzazione, forza motrice, ecc.)	id, name, energy_category_id
tbl_cost_centers	Centro di costo	id, name, external_id
tbl_data_sources	Configurazione delle fonti dati	id, name, gateway_id, protocol, connection
tbl_protocols	Configurazione dei protocolli	id, name, protocol_type

1.2 Tabelle di gestione delle apparecchiature

nome tabella	Descrizione	campo chiave
tbl_equipments	Informazioni sui dispositivi	id, name, uuid, equipment_type_id, cost_center_id
tbl_combined_equipments	Dispositivo combinato (combinazione di più dispositivi)	id, name, is_input_counted, is_output_counted
tbl_meters	Informazioni sui contatori	id, name, uuid, energy_category_id, is_counted
tbl_offline_meters	Contatore offline (inserimento manuale)	id, name, energy_category_id
tbl_virtual_meters	Contatore virtuale (calcolato)	id, name, expression (formato JSON)
tbl_points	Informazioni sui punti dati	id, name, data_source_id, object_type, object_id

1.3 Tabelle di organizzazione spaziale

nome tabella	Descrizione	campo chiave
tbl_spaces	Informazioni spaziali (stanze, piani, ecc.)	id, name, uuid, parent_space_id, area
tbl_stores	Informazioni sui punti vendita	id, name, uuid, space_id
tbl_tenants	Informazioni sugli inquilini	id, name, uuid, space_id
tbl_shopfloors	Informazioni sui reparti produttivi	id, name, uuid, space_id

1.4 Tabelle di relazione di associazione

Il sistema utilizza numerose tabelle di associazione per stabilire relazioni molti-a-molti:

• tbl_equipments_meters: Associazione tra apparecchiature e contatori
• tbl_equipments_offline_meters: Associazione tra apparecchiature e contatori offline
• tbl_equipments_virtual_meters: Associazione tra apparecchiature e contatori virtuali
• tbl_spaces_equipments: Associazione tra spazi e apparecchiature
• tbl_spaces_meters: Associazione tra spazi e contatori
• tbl_combined_equipments_equipments: Associazione tra dispositivi combinati e apparecchiature
• ecc...

1.5 Elenco delle apparecchiature energetiche rinnovabili

nome tabella	Descrizione	campo chiave
tbl_photovoltaic_power_stations	Centrale fotovoltaica	id, name, capacity, contact_id
tbl_energy_storage_containers	Contenitore di accumulo energetico	id, name, rated_capacity, rated_power
tbl_energy_storage_power_stations	Centrale di accumulo energetico	id, name, rated_capacity
tbl_microgrids	Microrete	id, name, address
tbl_charging_stations	Stazione di ricarica	id, name, rated_capacity, rated_power

1.6 Tabelle di controllo e schedulazione

nome tabella	Descrizione	campo chiave
tbl_commands	Comando di controllo	id, name, topic, payload (formato JSON)
tbl_control_modes	Modalità di controllo	id, name, is_active
tbl_control_modes_times	Periodo temporale della modalità di controllo	id, control_mode_id, start_time_of_day, end_time_of_day

1.7 Altre tabelle di configurazione

• tbl_contacts: Informazioni di contatto
• tbl_distribution_systems: Sistemi di distribuzione
• tbl_distribution_circuits: Circuiti di distribuzione
• tbl_energy_flow_diagrams: Diagrammi di flusso energetico
• tbl_tariffs: Configurazione delle tariffe elettriche
• tbl_working_calendars: Calendari lavorativi
• tbl_web_messages: Messaggi web

Precauzioni per lo sviluppo:

• Tutte le tabelle hanno id (BIGINT AUTO-INCREMENT) come chiave primaria
• La maggior parte delle tabelle dispone di un campo uuid (CHAR(36)) per l'integrazione con sistemi esterni
• Le tabelle di associazione di solito hanno solo id e due campi di chiave esterna
• I campi JSON utilizzano il tipo LONGTEXT per memorizzare stringhe JSON formattate

---

2. myems_historical_db (database di dati storici)

Scopo: Memorizzare i dati di monitoraggio in tempo reale e i dati storici, essendo uno dei database con il maggior volume di dati del sistema.

Caratteristiche:

• Il volume di dati è enorme, si utilizza l'archiviazione in serie temporale
• Contiene dati grezzi e tabelle di cache dell'ultimo valore
• Supporta l'etichettatura della qualità dei dati (is_bad, is_published)

Struttura principale delle tabelle:

nome tabella	Descrizione	campo chiave	Strategia di indicizzazione
tbl_analog_value	Dati storici analogici	point_id, utc_date_time, actual_value, is_bad, is_published	(point_id, utc_date_time), (utc_date_time)
tbl_analog_value_latest	Ultimo valore analogico (cache)	point_id, utc_date_time, actual_value	(point_id, utc_date_time)
tbl_digital_value	Dati storici digitali	point_id, utc_date_time, actual_value (INT)	(point_id, utc_date_time), (utc_date_time)
tbl_digital_value_latest	Ultimo valore numerico (cache)	point_id, utc_date_time, actual_value	(point_id, utc_date_time)
tbl_energy_value	Dati storici di consumo energetico	point_id, utc_date_time, actual_value, is_bad, is_published	(point_id, utc_date_time), (utc_date_time)
tbl_energy_value_latest	Ultimo valore di consumo energetico (cache)	point_id, utc_date_time, actual_value	(point_id, utc_date_time)
tbl_text_value	Dati storici di valori testuali	point_id, utc_date_time, actual_value (LONGTEXT)	(point_id, utc_date_time), (utc_date_time)
tbl_text_value_latest	Ultimo valore di valori testuali (cache)	point_id, utc_date_time, actual_value	(point_id, utc_date_time)

Tabelle di archiviazione file:

nome tabella	Descrizione	campo chiave
tbl_cost_files	File di costo (Excel/CSV)	file_name, uuid, upload_datetime_utc, status, file_object (LONGBLOB)
tbl_offline_meter_files	File di dati di contatori offline	file_name, uuid, upload_datetime_utc, status, file_object
tbl_data_repair_files	File di riparazione dati	file_name, uuid, upload_datetime_utc, status, file_object
tbl_energy_plan_files	File di piano di consumo energetico	file_name, uuid, upload_datetime_utc, status, file_object

Descrizione dei tipi di dati:

• actual_value: DECIMAL(21,6) - Supporta valori numerici ad alta precisione con 6 cifre decimali
• utc_date_time: DATETIME - Ora UTC, tutte le ore utilizzano uniformemente l'UTC
• is_bad: BOOL - Etichetta di qualità dati, True indica dati non validi
• is_published: BOOL - Flag di pubblicazione, True indica pubblicato

Precauzioni per lo sviluppo:

• Tutti i campi temporali utilizzano l'ora UTC, la visualizzazione frontend viene convertita nell'ora locale
• Le tabelle _latest sono utilizzate per interrogare velocemente gli ultimi valori ed evitare la scansione delle tabelle storiche
• Le tabelle di file utilizzano LONGBLOB per memorizzare file binari, prestare attenzione alle limitazioni di dimensione
• Pulire regolarmente i dati storici per evitare che le tabelle diventino troppo grandi e influenzino le prestazioni

---

3. myems_energy_db (database di consumo energetico)

Scopo: Memorizzare le statistiche di consumo energetico di varie apparecchiature, aggregate per ora, giorno, mese e anno.

Caratteristiche:

• I dati sono calcolati e generati dal servizio myems-aggregation
• Suddivisi in tabelle orarie, giornaliere, mensili e annuali per granularità temporale
• Supporta le statistiche per categoria energetica e sottovoce di consumo

Regole di denominazione delle tabelle:

• tbl_{tipo_oggetto}_{direzione}_{classificazione}_{granularità_temporale}
• Tipo oggetto: meter, equipment, combined_equipment, space, store, tenant, shopfloor
• Direzione: input (ingresso), output (uscita)
• Classificazione: category (categoria energetica), item (sottovoce di consumo)
• Granularità temporale: hourly, daily, monthly, yearly

Struttura principale delle tabelle:

3.1 Tabelle di consumo energetico dei contatori

nome tabella	Descrizione	campo chiave
tbl_meter_hourly	Consumo energetico orario del contatore	meter_id, start_datetime_utc, actual_value
tbl_meter_daily	Consumo energetico giornaliero del contatore	meter_id, start_datetime_utc, actual_value
tbl_meter_monthly	Consumo energetico mensile del contatore	meter_id, start_datetime_utc, actual_value
tbl_meter_yearly	Consumo energetico annuale del contatore	meter_id, start_datetime_utc, actual_value
tbl_offline_meter_hourly	Consumo energetico orario del contatore offline	offline_meter_id, start_datetime_utc, actual_value
tbl_virtual_meter_hourly	Consumo energetico orario del contatore virtuale	virtual_meter_id, start_datetime_utc, actual_value

3.2 Tabelle di consumo energetico delle apparecchiature

nome tabella	Descrizione	campo chiave
tbl_equipment_input_category_hourly	Consumo energetico in ingresso dell'apparecchiatura (per categoria)	equipment_id, energy_category_id, start_datetime_utc, actual_value
tbl_equipment_input_item_hourly	Consumo energetico in ingresso dell'apparecchiatura (per voce)	equipment_id, energy_item_id, start_datetime_utc, actual_value
tbl_equipment_output_category_hourly	Consumo energetico in uscita dell'apparecchiatura (per categoria)	equipment_id, energy_category_id, start_datetime_utc, actual_value
tbl_combined_equipment_input_category_hourly	Consumo energetico in ingresso del dispositivo combinato (per categoria)	combined_equipment_id, energy_category_id, start_datetime_utc, actual_value
tbl_combined_equipment_output_category_hourly	Consumo energetico in uscita del dispositivo combinato (per classificazione)	combined_equipment_id, energy_category_id, start_datetime_utc, actual_value

3.3 Tabelle di consumo energetico degli spazi

nome tabella	Descrizione	campo chiave
tbl_space_input_category_hourly	Consumo energetico in ingresso dello spazio (per categoria)	space_id, energy_category_id, start_datetime_utc, actual_value
tbl_space_input_item_hourly	Consumo energetico in ingresso dello spazio (per voce)	space_id, energy_item_id, start_datetime_utc, actual_value
tbl_space_output_category_hourly	Consumo energetico in uscita dello spazio (per classificazione)	space_id, energy_category_id, start_datetime_utc, actual_value
tbl_store_input_category_hourly	Consumo energetico in ingresso del punto vendita	store_id, energy_category_id, start_datetime_utc, actual_value
tbl_tenant_input_category_hourly	Consumo energetico in ingresso dell'inquilino	tenant_id, energy_category_id, start_datetime_utc, actual_value
tbl_shopfloor_input_category_hourly	Consumo energetico in ingresso del reparto produttivo	shopfloor_id, energy_category_id, start_datetime_utc, actual_value

3.4 Tabelle di consumo energetico delle apparecchiature energetiche rinnovabili

nome tabella	Descrizione	campo chiave
tbl_photovoltaic_power_station_hourly	Produzione energetica oraria della centrale fotovoltaica	photovoltaic_power_station_id, start_datetime_utc, actual_value
tbl_energy_storage_container_charge_hourly	Capacità di ricarica del contenitore di accumulo	energy_storage_container_id, start_datetime_utc, actual_value
tbl_energy_storage_container_discharge_hourly	Capacità di scarica del contenitore di accumulo	energy_storage_container_id, start_datetime_utc, actual_value
tbl_energy_storage_container_grid_buy_hourly	Acquisto di elettricità da parte del contenitore di accumulo	energy_storage_container_id, start_datetime_utc, actual_value
tbl_energy_storage_container_grid_sell_hourly	Vendita di elettricità da parte del contenitore di accumulo	energy_storage_container_id, start_datetime_utc, actual_value
tbl_microgrid_charge_hourly	Capacità di ricarica della microrete	microgrid_id, start_datetime_utc, actual_value
tbl_microgrid_discharge_hourly	Capacità di scarica della microrete	microgrid_id, start_datetime_utc, actual_value

Progettazione degli indici:

• Tutte le tabelle dispongono di un indice composto: (id_oggetto, id_classificazione, start_datetime_utc) o (id_oggetto, start_datetime_utc)
• Supportano interrogazioni rapide per oggetto e intervallo temporale

Precauzioni per lo sviluppo:

• start_datetime_utc rappresenta l'ora di inizio del periodo temporale (es. 01/01/2024 00:00:00 indica il periodo dalle 00:00 alle 01:00 del 1° gennaio)
• actual_value è il valore aggregato, non il valore originale
• I dati sono calcolati periodicamente dal servizio di aggregazione, non scritti in tempo reale
• Prestare attenzione alla conversione del fuso orario durante le interrogazioni

---

4. myems_billing_db (database di fatturazione)

Scopo: Memorizzare i dati di consumo energetico relativi alla fatturazione. La sua struttura è identica a myems_energy_db, ma i dati sono calcolati in base alle tariffe elettriche.

Caratteristiche:

• La struttura delle tabelle è identica a myems_energy_db
• I dati sono calcolati dal servizio myems-aggregation utilizzando le configurazioni tariffarie
• Supporta regole di fatturazione complesse come tariffe orarie e prezzi a scalare

Tabelle principali:

• Struttura delle tabelle identica a myems_energy_db
• I valori dei dati sono moltiplicati per la tariffa corrispondente, solitamente in unità monetarie (es. EUR, USD)

Note per lo sviluppo:

• I dati di fatturazione dipendono dalla configurazione delle tariffe in myems_system_db.tbl_tariffs
• Devono essere associati ai centri di costo (cost_center)
• Supporta molteplici strategie tariffarie (orarie, a scalare, basate sulla capacità, ecc.)

---

5. myems_carbon_db (database di emissioni di carbonio)

Scopo: Memorizzare i dati energetici relativi alle emissioni di carbonio per il calcolo dell'impronta carbonica.

Caratteristiche:

• La struttura delle tabelle è identica a myems_energy_db
• I dati sono calcolati dal servizio myems-aggregation basandosi sui fattori di emissione di carbonio
• I fattori di emissione di carbonio sono memorizzati in myems_system_db.tbl_energy_categories.kgco2e

Tabelle principali:

• Struttura delle tabelle identica a myems_energy_db
• I valori dei dati sono moltiplicati per il fattore di emissione di carbonio, solitamente in kgCO2e (chili di CO₂ equivalente)

Note per lo sviluppo:

• I fattori di emissione di carbonio possono cambiare nel tempo, quindi è necessario supportare i fattori storici
• Diversi tipi di energia (elettricità, gas, petrolio, ecc.) hanno fattori di emissione differenti
• Supporta il calcolo delle emissioni di carbonio di Scope 1, Scope 2 e Scope 3

---

6. myems_energy_baseline_db (database di baseline energetica)

Scopo: Memorizzare i dati di baseline energetica per l'analisi del risparmio energetico e la valutazione dell'efficienza energetica.

Caratteristiche:

• La struttura delle tabelle è simile a myems_energy_db
• I dati di baseline sono solitamente calcolati basandosi su dati storici o valori standard
• Utilizzati per confrontare il consumo energetico effettivo con il consumo di baseline e calcolare il risparmio energetico

Tabelle principali:

• Struttura delle tabelle identica a myems_energy_db
• Memorizzano valori di baseline anziché valori effettivi

Note per lo sviluppo:

• I dati di baseline devono essere aggiornati regolarmente
• Supporta molteplici metodi di calcolo della baseline (media storica, analisi di regressione, valori standard, ecc.)

---

7. myems_energy_model_db (database di modelli di consumo energetico)

Scopo: Memorizzare i dati del modello di consumo energetico annuale di 8760 ore (8760 ore all'anno).

Caratteristiche:

• Ogni oggetto memorizza 8760 record (dati orari per un anno)
• Utilizzato per la previsione e la pianificazione del consumo energetico
• Il nome della tabella contiene il suffisso _8760

Tabella principale:

nome tabella	Descrizione	campo chiave
tbl_meter_8760	Modello 8760 ore del contatore	meter_id, start_datetime_utc, actual_value
tbl_equipment_input_category_8760	Modello di consumo energetico in ingresso dell'apparecchiatura	equipment_id, energy_category_id, start_datetime_utc, actual_value
tbl_combined_equipment_input_category_8760	Modello di consumo energetico in ingresso del dispositivo combinato	combined_equipment_id, energy_category_id, start_datetime_utc, actual_value
tbl_space_input_category_8760	Modello di consumo energetico in ingresso dello spazio	space_id, energy_category_id, start_datetime_utc, actual_value
tbl_shopfloor_input_category_8760	Modello di consumo energetico in ingresso del reparto produttivo	shopfloor_id, energy_category_id, start_datetime_utc, actual_value
tbl_store_input_category_8760	Modello di consumo energetico in ingresso del punto vendita	store_id, energy_category_id, start_datetime_utc, actual_value
tbl_tenant_input_category_8760	Modello di consumo energetico in ingresso dell'inquilino	tenant_id, energy_category_id, start_datetime_utc, actual_value

Precauzioni per lo sviluppo:

• Il modello 8760 ore è solitamente generato basandosi su dati storici o modelli standard
• Utilizzato per la previsione e la preparazione del budget del consumo energetico annuale
• Supporta la visualizzazione per dimensioni come settimana, mese, trimestre, ecc.

---

8. myems_energy_plan_db (database di piani energetici)

Scopo: Memorizzare i dati di piano e obiettivo energetico.

Caratteristiche:

• La struttura delle tabelle è simile a myems_energy_db
• Memorizzano valori pianificati anziché valori effettivi
• Utilizzati per il budgeting e la gestione degli obiettivi di consumo energetico

Tabelle principali:

• Struttura delle tabelle identica a myems_energy_db
• I dati provengono da file di piano o inserimenti manuali

Note per lo sviluppo:

• I dati di piano devono essere confrontati con i dati effettivi per l'analisi
• Supporta piani multilivello (annuali, mensili, settimanali, ecc.)

---

9. myems_energy_prediction_db (database di previsione energetica)

Scopo: Memorizzare i dati di previsione del consumo energetico.

Caratteristiche:

• La struttura delle tabelle è simile a myems_energy_db
• Memorizzano valori previsti anziché valori effettivi
• Utilizzati per la previsione e gli avvisi di consumo energetico

Tabelle principali:

• Struttura delle tabelle identica a myems_energy_db
• I dati sono generati da algoritmi di previsione

Note per lo sviluppo:

• I dati di previsione devono essere aggiornati regolarmente
• Supporta molteplici algoritmi di previsione (serie temporali, machine learning, ecc.)
• L'accuratezza della previsione richiede un'ottimizzazione continua

---

10. myems_fdd_db (database di diagnosi guasti)

Scopo: Memorizzare i dati relativi al rilevamento e alla diagnosi dei guasti.

Caratteristiche:

• Supporta molteplici canali di allarme (web, email, SMS, WeChat, telefono)
• Il motore di regole supporta logiche complesse di rilevamento guasti
• Supporta la conferma e la gestione dei messaggi di guasto

Struttura principale delle tabelle:

nome tabella	Descrizione	campo chiave
tbl_rules	Regole di diagnostica	id, name, category, fdd_code, priority, channel, expression (JSON), message_template, is_enabled
tbl_web_messages	Messaggio web	id, rule_id, user_id, subject, category, priority, message, status, belong_to_object_type, belong_to_object_id
tbl_email_messages	Messaggio email	id, rule_id, recipient_name, recipient_email, subject, message, attachment_file_name, status
tbl_text_messages_outbox	Posta in uscita SMS	id, rule_id, recipient_mobile, message, status, acknowledge_code
tbl_text_messages_inbox	Posta in entrata SMS	id, sender_mobile, message, status
tbl_wechat_messages_outbox	Posta in uscita messaggi WeChat	id, rule_id, recipient_openid, message_template_id, message_data (JSON)
tbl_wechat_messages_inbox	Posta in entrata messaggi WeChat	id, sender_openid, message, status
tbl_email_servers	Configurazione server email	id, host, port, requires_authentication, user_name, password, from_addr
tbl_wechat_configs	Configurazione WeChat	id, api_server, app_id, app_secret, access_token, expires_datetime_utc

Categorie di regole (category):

• REALTIME: Allarmi in tempo reale
• SYSTEM: Allarmi di sistema
• SPACE: Allarmi di spazio
• METER: Allarmi di contatore
• TENANT: Allarmi di inquilino
• STORE: Allarmi di punto vendita
• SHOPFLOOR: Allarmi di reparto produttivo
• EQUIPMENT: Allarmi di apparecchiatura
• COMBINEDEQUIPMENT: Allarmi di dispositivo combinato

Priorità (priority):

• CRITICAL: Critica
• HIGH: Alta
• MEDIUM: Media
• LOW: Bassa

Note per lo sviluppo:

• Il campo expression memorizza l'espressione di regola in formato JSON
• message_template supporta la sostituzione di variabili (es. $name, $value)
• Le regole supportano sia l'esecuzione pianificata che l'esecuzione immediata
• Stato dei messaggi: new → sent → acknowledged / timeout

---

11. myems_user_db (database utenti)

Scopo: Memorizzare l'autenticazione utente, le chiavi API, i messaggi email, ecc.

Caratteristiche:

• Volume di dati ridotto, ma requisiti di sicurezza elevati
• Supporta la gestione dei permessi utente
• Supporta l'autenticazione tramite chiave API

Struttura principale delle tabelle:

nome tabella	Descrizione	campo chiave
tbl_users	Informazioni utente	id, name, uuid, display_name, email, salt, password, is_admin, is_read_only, privilege_id, account_expiration_datetime_utc, password_expiration_datetime_utc, failed_login_count
tbl_privileges	Configurazione permessi	id, name, data (formato JSON)
tbl_sessions	Sessione utente	id, user_uuid, token, utc_expires
tbl_api_keys	Chiave API	id, name, token, created_datetime_utc, expires_datetime_utc
tbl_email_messages	Messaggio email	id, recipient_name, recipient_email, subject, message, attachment_file_name, status, scheduled_datetime_utc
tbl_email_message_sessions	Conversazione email	id, recipient_email, token, expires_datetime_utc
tbl_logs	Registro operazioni	id, user_uuid, request_datetime_utc, request_method, resource_type, resource_id, request_body (JSON)
tbl_notifications	Messaggio di notifica	id, user_id, created_datetime_utc, status, subject, message, url
tbl_new_users	Nuovo utente (da attivare)	id, name, uuid, display_name, email, salt, password
tbl_verification_codes	Codice di verifica	id, recipient_email, verification_code, created_datetime_utc, expires_datetime_utc

Progettazione della sicurezza:

• Le password sono memorizzate con salt + hash, nessun archiviazione in testo semplice
• Supporta la scadenza di account e password
• Supporta il limite di tentativi di accesso falliti
• Le chiavi API supportano la data di scadenza

Note per lo sviluppo:

• I campi password devono essere memorizzati in forma criptata, non interrogati direttamente
• I token di sessione devono essere puliti periodicamente per rimuovere i record scaduti
• I registri operazioni devono registrare tutte le azioni critiche per l'auditing
• Stato delle notifiche: unread → read → archived

---

12. myems_reporting_db (database di reportistica)

Scopo: Memorizzare messaggi email e allegati relativi ai report.

Caratteristiche:

• Volume di dati ridotto
• Supporta l'archiviazione di modelli di report e file generati

Struttura principale delle tabelle:

nome tabella	Descrizione	campo chiave
tbl_reports	Configurazione report	id, name, uuid, expression (JSON), is_enabled, last_run_datetime_utc, next_run_datetime_utc, is_run_immediately
tbl_reports_files	File di report	id, uuid, create_datetime_utc, file_name, file_type (xlsx/pdf/docx), file_object (LONGBLOB)
tbl_template_files	File modello di report	id, uuid, report_id, file_name, file_type, file_object
tbl_email_messages	Messaggio email	id, recipient_name, recipient_email, subject, message, attachment_file_name, attachment_file_object, status

Note per lo sviluppo:

• I file di report supportano i formati Excel, PDF e Word
• I file modello sono utilizzati per la generazione dei report
• I report supportano sia la generazione pianificata che la generazione immediata
• I file sono memorizzati utilizzando LONGBLOB; prestare attenzione alle limitazioni di dimensione

---

13. myems_production_db (database di produzione)

Scopo: Memorizzare i dati di prodotto relativi alla produzione.

Caratteristiche:

• Volume di dati ridotto
• Utilizzato per l'analisi correlata del consumo energetico di produzione

Struttura principale delle tabelle:

nome tabella	Descrizione	campo chiave
tbl_products	Informazioni prodotto	id, name, uuid, unit_of_measure, tag, standard_product_coefficient
tbl_teams	Informazioni squadra	id, name, uuid, description
tbl_shifts	Informazioni turno	id, shopfloor_id, team_id, product_id, product_count, start_datetime_utc, end_datetime_utc, reference_timestamp
tbl_shopfloor_hourly	Produzione oraria del reparto produttivo	id, shopfloor_id, start_datetime_utc, product_id, product_count
tbl_space_hourly	Produzione oraria dello spazio	id, space_id, start_datetime_utc, product_id, product_count
tbl_shopfloors_products	Associazione reparto produttivo e prodotto	id, shopfloor_id, product_id
tbl_shopfloors_teams	Associazione reparto produttivo e squadra	id, shopfloor_id, team_id

Precauzioni per lo sviluppo:

• I dati di produzione sono utilizzati per calcolare il consumo energetico per unità di prodotto
• Supporta le statistiche per dimensioni come prodotto, squadra, reparto produttivo, ecc.
• Associati ai dati di consumo energetico per calcolare gli indicatori di efficienza energetica

---

Relazioni di flusso dati

Processo di acquisizione dati

Flusso di acquisizione dati

Dispositivo / Sensore
↓ (Modbus TCP / MQTT / HTTP)
myems-modbus-tcp (Servizio di acquisizione dati)
↓ (Scrittura)
myems_historical_db.tbl_analog_value / tbl_digital_value / tbl_energy_value
↓ (Normalizzazione dati)
myems-normalization (Servizio di normalizzazione)
↓ (Pulizia dati)
myems-cleaning (Servizio di pulizia)
↓ (Aggregazione dati)
myems-aggregation (Servizio di aggregazione)
↓ (Scrittura)
myems_energy_db (Dati energetici)
myems_billing_db (Dati di fatturazione)
myems_carbon_db (Dati di emissioni di carbonio)

---

Flusso di interrogazione dati

Richiesta utente
↓
myems-api (Servizio API)
↓ (Interrogazione)
myems_system_db (Dati di configurazione)
myems_historical_db (Dati storici)
myems_energy_db (Dati energetici)
↓ (Risposta)
myems-web / myems-admin (Visualizzazione frontend)

---

Diagramma delle relazioni dati

myems_system_db.tbl_points
↓ (point_id)
myems_historical_db.tbl_analog_value
↓ (Calcolo di aggregazione)
myems_energy_db.tbl_meter_hourly
↓ (Collegamento)
myems_system_db.tbl_meters
↓ (Collegamento)
myems_system_db.tbl_equipments
↓ (Collegamento)
myems_system_db.tbl_spaces

---

Specifiche di progettazione della struttura delle tabelle

Campi generali

Tutte le tabelle contengono i seguenti campi comuni:

nome campo	tipo	Descrizione
id	BIGINT NOT NULL AUTO_INCREMENT	Chiave primaria, auto-incrementale
name	VARCHAR(255)	Nome
uuid	CHAR(36)	UUID, utilizzato per l'integrazione con sistemi esterni
description	VARCHAR(255)	Descrizione (opzionale)

Campi temporali

nome campo	tipo	Descrizione
utc_date_time	DATETIME	Ora UTC (tabelle di dati storici)
start_datetime_utc	DATETIME	Ora di inizio del periodo temporale (tabelle di dati aggregati)
created_datetime_utc	DATETIME	Ora di creazione
updated_datetime_utc	DATETIME	Ora di aggiornamento
last_run_datetime_utc	DATETIME	Ora dell'ultima esecuzione
next_run_datetime_utc	DATETIME	Ora della prossima esecuzione

Attenzione: Tutti i campi temporali devono utilizzare uniformemente l'ora UTC, la visualizzazione frontend viene convertita nell'ora locale.

Campi numerici

nome campo	tipo	Descrizione
actual_value	DECIMAL(21, 6)	Valore effettivo, supporta alta precisione (6 cifre decimali)
set_value	DECIMAL(21, 6)	Valore impostato
rated_capacity	DECIMAL(21, 6)	Capacità nominale
rated_power	DECIMAL(21, 6)	Potenza nominale

Campi JSON

nome campo	tipo	Descrizione
connection	LONGTEXT	Configurazione di connessione (formato JSON)
expression	LONGTEXT	Espressione (formato JSON)
payload	LONGTEXT	Payload (formato JSON)
data	LONGTEXT	Dati (formato JSON)

Nota: I campi JSON memorizzano stringhe JSON formattate e devono essere analizzati prima dell'uso.

Campi di stato

nome campo	tipo	Descrizione
is_enabled	BOOL	Abilitato o meno
is_active	BOOL	Stato di attivazione
is_bad	BOOL	Presenza di dati non validi
is_published	BOOL	Pubblicato o meno
is_counted	BOOL	Incluso nelle statistiche o meno
status	VARCHAR(32)	Stato (es. nuovo, inviato, completato, errore)

Progettazione degli indici

Indice primario:

• Tutte le tabelle hanno PRIMARY KEY (id)

Indice unico:

• I campi chiave (come name, uuid) di solito dispongono di indici univoci

Indice composto:

• Creare un indice composto per le combinazioni di campi interrogati frequentemente
• Esempio: (point_id, utc_date_time), (meter_id, start_datetime_utc)

Indice temporale:

• Il campo temporale è solitamente indicizzato separatamente, supporta interrogazioni per intervallo temporale