netgescon-master/docs/02-architettura-laravel/specifiche/NETGESCON_IMPORTER.md

🐍 NETGESCON IMPORTER - Bridge Python per GESCON

🔄 Sistema di importazione e sincronizzazione
Per convivenza temporale GESCON → NetGescon
Aggiornato: 14 Luglio 2025

🎯 OBIETTIVO

Creare un bridge Python che permetta:

• ✅ Import graduale dati da GESCON esistente
• 🔄 Sincronizzazione bidirezionale temporanea
• 📊 Validazione integrità dati importati
• 🚀 Transizione sicura senza perdita dati

🏗️ ARCHITETTURA SISTEMA

Struttura Directory

netgescon-importer/
├── requirements.txt              # Dipendenze Python
├── config/
│   ├── gescon_config.yml        # Config connessione GESCON
│   ├── netgescon_config.yml     # Config API NetGescon  
│   └── mapping_schema.yml       # Mapping campi GESCON → NetGescon
├── src/
│   ├── gescon_reader.py         # Lettura dati GESCON
│   ├── data_mapper.py           # Mapping e trasformazione
│   ├── netgescon_client.py      # Client API NetGescon
│   ├── validator.py             # Validazione dati
│   ├── sync_service.py          # Servizio sincronizzazione
│   └── scheduler.py             # Scheduling automatico
├── logs/                        # Log operazioni
├── temp/                        # File temporanei
└── main.py                      # Entry point principale

🔧 COMPONENTI PRINCIPALI

1. GESCON Reader

# gescon_reader.py
class GesconReader:
    def __init__(self, config):
        self.config = config
        self.connection = None
    
    def connect_database(self):
        """Connessione al DB GESCON (Access/SQL Server/MySQL)"""
        pass
    
    def read_stabili(self):
        """Lettura tabella stabili"""
        pass
    
    def read_unita_immobiliari(self):
        """Lettura unità immobiliari"""
        pass
    
    def read_soggetti(self):
        """Lettura anagrafica soggetti"""
        pass
    
    def read_movimenti_contabili(self, from_date=None):
        """Lettura movimenti contabilità"""
        pass

2. Data Mapper

# data_mapper.py
class DataMapper:
    def __init__(self, mapping_config):
        self.mapping = mapping_config
    
    def map_stabile(self, gescon_stabile):
        """Mappa dati stabile GESCON → NetGescon"""
        return {
            'denominazione': gescon_stabile['denominazione'],
            'codice_fiscale': gescon_stabile['cod_fisc'],
            'indirizzo': gescon_stabile['indirizzo'],
            # ... altri campi
        }
    
    def map_unita_immobiliare(self, gescon_unita):
        """Mappa unità immobiliare"""
        pass
    
    def validate_mapping(self, source_data, mapped_data):
        """Valida la correttezza del mapping"""
        pass

3. NetGescon API Client

# netgescon_client.py
class NetGesconClient:
    def __init__(self, base_url, api_token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {api_token}',
            'Content-Type': 'application/json'
        }
    
    def import_stabili(self, stabili_data):
        """Import stabili via API"""
        response = requests.post(
            f'{self.base_url}/api/import/stabili',
            json=stabili_data,
            headers=self.headers
        )
        return response.json()
    
    def check_import_status(self, job_id):
        """Check status import job"""
        pass

4. Sync Service

# sync_service.py
class SyncService:
    def __init__(self, gescon_reader, netgescon_client, mapper):
        self.gescon = gescon_reader
        self.netgescon = netgescon_client
        self.mapper = mapper
    
    def full_import(self):
        """Import completo iniziale"""
        try:
            # 1. Import stabili
            stabili = self.gescon.read_stabili()
            mapped_stabili = [self.mapper.map_stabile(s) for s in stabili]
            result = self.netgescon.import_stabili(mapped_stabili)
            
            # 2. Import unità immobiliari
            # 3. Import soggetti
            # 4. Import contabilità
            
        except Exception as e:
            logger.error(f"Errore import: {e}")
    
    def incremental_sync(self):
        """Sincronizzazione incrementale"""
        pass

📋 FASI IMPLEMENTAZIONE

FASE 1: Setup Ambiente (1-2 giorni)

# Setup progetto Python
cd /home/michele/netgescon/
mkdir netgescon-importer
cd netgescon-importer

# Virtual environment
python3 -m venv venv
source venv/bin/activate

# Dipendenze base
pip install pandas sqlalchemy requests pyyaml schedule logging

FASE 2: Analisi Schema GESCON (2-3 giorni)

• Connessione database GESCON esistente
• Mappatura tabelle e relazioni
• Identificazione primary/foreign keys
• Analisi integrità dati esistenti
• Documentazione schema trovato

FASE 3: Mapping Dati (3-4 giorni)

• Creazione mapping_schema.yml
• Implementazione DataMapper class
• Test trasformazioni dati
• Validazione mapping correttezza

FASE 4: API Integration (2-3 giorni)

• API endpoint NetGescon per import
• Autenticazione API token
• Gestione job asincroni import
• Monitoring status e errori

FASE 5: Sincronizzazione (4-5 giorni)

• Import iniziale completo
• Sync incrementale automatica
• Conflict resolution strategy
• Rollback procedure

⚙️ CONFIGURAZIONE

gescon_config.yml

database:
  type: "access"  # access, sqlserver, mysql
  path: "/path/to/gescon.mdb"  # Per Access
  # connection_string: "..." # Per SQL Server/MySQL
  
tables:
  stabili: "Stabili"
  unita: "UnitaImmobiliari"  
  soggetti: "Soggetti"
  movimenti: "MovimentiContabili"

netgescon_config.yml

api:
  base_url: "http://localhost:8000"  # URL NetGescon
  token: "your-api-token"
  timeout: 30
  
import:
  batch_size: 100
  max_retries: 3
  validate_before_import: true

mapping_schema.yml

stabili:
  denominazione: "Denominazione"
  codice_fiscale: "CodiceFiscale"
  indirizzo: "Indirizzo"
  citta: "Citta"
  cap: "CAP"
  # ... mapping completo campi

unita_immobiliari:
  # ... mapping unità

🎯 UTILIZZO

Import Iniziale

# Import completo da GESCON
python main.py --action=full-import --validate=true

# Import solo stabili
python main.py --action=import --entity=stabili

# Preview import (senza salvare)
python main.py --action=preview --entity=all

Sincronizzazione Automatica

# Avvia scheduler sincronizzazione ogni ora
python main.py --action=schedule --interval=1h

# Sync manuale incrementale
python main.py --action=sync-incremental

Monitoring

# Status ultimo import
python main.py --action=status

# Log errori
tail -f logs/netgescon_importer.log

📊 REPORT E VALIDAZIONE

Report Import

• 📈 Statistiche: Record importati, errori, warning
• 📋 Mapping: Campi mappati vs non mappati
• ⚠️ Anomalie: Dati mancanti, duplicati, inconsistenze
• ✅ Validazione: Controlli integrità superati

Dashboard Web (Opzionale)

Creare semplice dashboard web per:

• 📊 Status import in tempo reale
• 📈 Grafici progresso migrazione
• 📋 Log operazioni con filtri
• 🔧 Controlli manuali correzione errori

🚀 DEPLOYMENT

Server Dedicato Import

# Setup su server Linux
git clone netgescon-importer
cd netgescon-importer
./setup.sh

# Service systemd per scheduling
sudo systemctl enable netgescon-importer
sudo systemctl start netgescon-importer

Docker Container (Opzionale)

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "main.py", "--action=schedule"]

🔒 SICUREZZA

• 🔐 Credenziali in variabili ambiente
• 🛡️ Backup automatico prima import
• 📝 Audit trail tutte le operazioni
• 🔄 Rollback procedure emergency
• ⚡ Rate limiting API calls

---

📋 CHECKLIST IMPLEMENTAZIONE

Setup ✅

• Ambiente Python configurato
• Dipendenze installate
• Config files creati
• Connessione GESCON testata

Development 🔄

• GesconReader implementato
• DataMapper completato
• NetGesconClient funzionante
• SyncService operativo
• Test suite creata

Testing ⏳

• Import test dati campione
• Validazione mapping
• Performance test
• Error handling test
• Rollback test

Production ⏳

• Deploy server produzione
• Monitoring configurato
• Backup procedures
• Documentation utenti
• Training team

Questo sistema garantisce una transizione sicura e graduale da GESCON a NetGescon! 🚀