# Documentazione Progetto DataHub ## Architettura di alto livello ``` DataHub | ├── CoreDB (Database centrale) | └── Tabelle strutturali (prodotti, emesso, diritti, ecc.) | ├── DataIngestion (Importazione e pulizia dati) | └── Funzionalità di controllo qualità e normalizzazione | ├── DataOptimization (Ottimizzazione strutturale) | └── Normalizzazione e miglioramento schema | ├── AutoLink (Integrazione dati temporanea) | └── Join temporanei con dati esterni | └── QueryFlex (Interrogazione analitica) └── Query parametriche su CoreDB e tabelle temporanee ``` ## Struttura delle directory del progetto ``` datahub/ ├── main.py # Punto di ingresso principale ├── config/ # Configurazione │ └── settings.py # Impostazioni generali │ ├── core/ # Funzionalità core │ ├── __init__.py │ ├── db.py # Gestione del database centrale (CoreDB) │ └── models.py # Definizioni dei modelli di dati │ ├── modules/ │ ├── __init__.py │ │ │ ├── ingestion/ # DataIngestion - già parzialmente implementato │ │ ├── __init__.py │ │ ├── data_ingestion.py │ │ ├── data_quality_gate.py │ │ └── processors/ # Processori specifici per tipo di dati │ │ ├── __init__.py │ │ ├── prodotti_processor.py │ │ ├── emesso_processor.py │ │ └── diritti_processor.py │ │ │ ├── optimization/ # DataOptimization - nuova funzionalità │ │ ├── __init__.py │ │ ├── schema_optimizer.py │ │ └── optimizers/ │ │ ├── __init__.py │ │ ├── diritti_optimizer.py │ │ ├── prodotti_optimizer.py │ │ └── emesso_optimizer.py │ │ │ ├── autolink/ # AutoLink - modulo pianificato │ │ ├── __init__.py │ │ ├── data_linker.py │ │ └── temporary_tables.py │ │ │ └── queryflex/ # QueryFlex - modulo pianificato │ ├── __init__.py │ ├── query_builder.py │ ├── predefined_queries.py │ └── result_formatter.py │ └── utils/ # Utilità generiche ├── __init__.py ├── cli.py # Utility per interfaccia a linea di comando ├── progress.py # Tracciamento progresso operazioni └── logger.py # Logging centralizzato ``` ## Dettaglio dei moduli principali ### 1. CoreDB - **Non è un modulo di codice** ma il database centrale stesso - Contiene le tabelle strutturali importate (prodotti, emesso, diritti) - È il repository permanente dei dati - Implementato come database SQLite ### 2. DataIngestion - **Stato: Parzialmente implementato** - Responsabilità: - Validazione dei file CSV in ingresso - Standardizzazione dei dati (formati, tipi, valori) - Importazione nelle tabelle di CoreDB - Generazione di report di qualità - Componenti principali: - `data_ingestion.py`: Orchestrazione del processo - `data_quality_gate.py`: Validazione e pulizia - Processori specifici per tipo di dati ### 3. DataOptimization - **Stato: Da implementare** - Responsabilità: - Ottimizzazione della struttura delle tabelle - Normalizzazione selettiva per migliorare efficienza - Aggiunta di ID numerici come chiavi primarie - Estrazione di dati in tabelle di lookup - Componenti principali: - `schema_optimizer.py`: Gestione generale - Ottimizzatori specifici per tabella (diritti, prodotti, ecc.) ### 4. AutoLink - **Stato: Pianificato** - Responsabilità: - Integrazione temporanea di dati esterni con CoreDB - Creazione di tabelle temporanee per analisi - Join con tabelle strutturali senza modifiche permanenti - Componenti principali: - `data_linker.py`: Logica di integrazione - `temporary_tables.py`: Gestione delle tabelle temporanee ### 5. QueryFlex - **Stato: Pianificato** - Responsabilità: - Esecuzione di query analitiche parametrizzate - Interfaccia per interrogare sia CoreDB che tabelle temporanee - Formattazione dei risultati per report - Componenti principali: - `query_builder.py`: Costruzione dinamica delle query - `predefined_queries.py`: Query predefinite comuni - `result_formatter.py`: Formattazione output ## Interfaccia a linea di comando ``` datahub [opzioni globali] [opzioni comando] [opzioni sottocomando] ``` Comandi principali: - `datahub init` - Inizializza il database CoreDB - `datahub import [--all|--prodotti|--emesso|--diritti]` - Importa dati in CoreDB - `datahub optimize [--all|--diritti|--prodotti|--emesso]` - Ottimizza la struttura del database - `datahub autolink --file --join ` - Integra temporaneamente dati esterni - `datahub query --type [parametri]` - Esegue query analitiche ## Priorità di sviluppo 1. **Fase 1 - Importazione robusta** (attuale) - Completare DataIngestion - Assicurare importazione corretta di tutte le tabelle 2. **Fase 2 - Ottimizzazione strutturale** (prossima) - Implementare DataOptimization - Priorità: ottimizzazione tabella diritti 3. **Fase 3 - Integrazione dati temporanei** - Sviluppare AutoLink - Permettere analisi con dati esterni 4. **Fase 4 - Query analitiche** - Implementare QueryFlex - Creare set di query predefinite utili ## Considerazioni tecniche importanti 1. **Compatibilità con MS Access e Power BI**: - Preferire ID numerici come chiavi primarie - Evitare normalizzazione eccessiva - Mantenere nomi di colonne comprensibili 2. **Performance**: - Creare indici appropriati - Bilanciare normalizzazione e semplicità - Ottimizzare le query più frequenti 3. **Resilienza**: - Backup automatici prima di modifiche strutturali - Validazione rigorosa dei dati in ingresso - Gestione completa degli errori ## Implementazione del modulo DataOptimization ### Approccio per ottimizzare la tabella diritti Lo script di ottimizzazione per la tabella diritti dovrà: 1. Creare un backup del database 2. Creare una nuova tabella `diritti` con ID univoco come chiave primaria 3. Estrarre le colonne relative alle finestre temporali (win_X) in una tabella separata `windows` 4. Migrare i dati dalla vecchia struttura alla nuova 5. Sostituire la vecchia tabella con quella nuova 6. Ricreare gli indici necessari Esempio di codice per l'ottimizzatore della tabella `diritti`: ```python def optimize_diritti(db_path): """Ottimizza la tabella diritti con un approccio di normalizzazione selettiva""" # Crea un backup del database backup_path = create_backup(db_path) # Crea la tabella windows per le finestre temporali create_windows_table(db_path) # Migra i dati delle windows dalla tabella diritti migrate_windows_data(db_path) # Crea una nuova tabella diritti con ID univoco create_optimized_diritti_table(db_path) # Migra i dati dalla vecchia tabella alla nuova migrate_diritti_data(db_path) # Sostituisci la vecchia tabella con quella nuova replace_table(db_path, "diritti") # Ricrea gli indici necessari recreate_indices(db_path) ``` ### Vantaggi dell'ottimizzazione 1. **Riduzione del numero di colonne**: Da 109 a circa 55 2. **Struttura più pulita**: Separazione logica dei dati delle finestre temporali 3. **Chiave primaria semplificata**: ID numerico anziché chiave composta da 5 campi 4. **Compatibilità con strumenti esterni**: Miglior funzionamento con MS Access e Power BI 5. **Performance migliorate**: Join più efficienti grazie all'ID numerico ## Note per l'implementazione L'implementazione di DataOptimization dovrebbe seguire questi principi: 1. **Modularità**: Ogni ottimizzatore deve essere indipendente 2. **Reversibilità**: Backup automatici per permettere di tornare indietro 3. **Validazione**: Verifica dei dati migrati per assicurare l'integrità 4. **Prestazioni**: Operazioni in batch per tabelle grandi 5. **Logging**: Log dettagliati di tutte le operazioni Questa architettura fornisce una solida base per sviluppare DataHub come piattaforma completa di gestione dati, mantenendo la flessibilità per evolvere nel tempo.