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** 
```python
# 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**
```python
# 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**
```python
# 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**
```python
# 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)
```bash
# 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**
```yaml
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**
```yaml
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**
```yaml
stabili:
  denominazione: "Denominazione"
  codice_fiscale: "CodiceFiscale"
  indirizzo: "Indirizzo"
  citta: "Citta"
  cap: "CAP"
  # ... mapping completo campi

unita_immobiliari:
  # ... mapping unità
```

## 🎯 **UTILIZZO**

### **Import Iniziale**
```bash
# 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**
```bash
# Avvia scheduler sincronizzazione ogni ora
python main.py --action=schedule --interval=1h

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

### **Monitoring**
```bash
# 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**
```bash
# 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)
```dockerfile
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!** 🚀