# 🔄 **PROCESSO IMPORT AUTOMATICO NETGESCON**

## 📋 **PANORAMICA**

Sistema automatizzato per importare dati dal vecchio programma Gescon a NetGescon tramite API.

Per import reali nel progetto Laravel usa la pipeline CLI: php artisan gescon:import-full [opzioni] – supporta dry-run, filtraggio per stabile/anno, esecuzione per step e aggiornamento viste QA.

---

## 📁 **STRUTTURA CARTELLE**

```
000-IMPORT/
├── README-IMPORT-PROCESS.md     # Questo file - guida processo
├── 01-GESCON/                   # Dati estratti da Gescon
│   ├── amministratori.json      # Dati amministratori
│   ├── stabili.json             # Dati stabili
│   ├── unita.json              # Unità immobiliari
│   └── condomini.json          # Anagrafica condomini
├── 02-MAPPING/                  # Mapping campi
│   ├── campo-mapping.json       # Corrispondenze campi
│   └── validation-rules.json    # Regole validazione
└── 03-SCRIPTS/                  # Script automatici
    ├── import-runner.js          # Script principale import
    ├── validation-checker.js     # Controllo pre-import
    └── progress-monitor.js       # Monitoraggio progresso
```

---

## 🎯 **FASI IMPORT**

### **Fase 1: Preparazione Dati** ✅
1. Estrazione dati dal vecchio CSV/XML
2. Conversione in formato JSON standardizzato
3. Validazione struttura dati

### **Fase 2: Mapping Automatico** 🔄
1. Mapping campi vecchio → nuovo sistema
2. Trasformazione valori (date, formati, etc.)
3. Validazione integrità referenziale

### **Fase 3: Import Automatico** ⏳
1. Login API NetGescon
2. Import sequenziale (Admin → Stabili → Unità → Condomini)
3. Gestione errori e rollback
4. Report finale

---

## 🚀 **ORDINE IMPORT**

1. Amministratori → Base del sistema
2. Stabili → CF/CF-amministratore, catasto, dati bancari
3. Unità immobiliari → collegate agli stabili (palazzine/scale)
4. Soggetti/Diritti → proprietari, inquilini, quote
5. Tabelle millesimali → per-unità, bilanciamento
6. Voci/Operazioni → prima nota, partita doppia
7. Rate/Incassi → flusso incassi
8. Straord./Addebiti/Detrazioni → componenti extra

---

## 📊 **MONITORAGGIO**

- Progress tracking in tempo reale
- Log dettagliati di ogni operazione
- Statistiche import (successi/errori)
- Possibilità di rollback completo
 - Aggiornamento viste QA automatico (disattivabile con --no-views)

### Resume e Log di esecuzione

- Ogni esecuzione scrive log persistenti in `/home/michele/netgescon/docs/logs/gescon_<task>_*`.
- File: `state.json` (stato corrente), `progress.jsonl` (eventi con timestamp), `stdout.log` (output raw).
- Per riprendere, leggere `state.json` e rilanciare il comando artisan corrispondente (vedi sezione Pipeline). Vedi anche `docs/logs/README-IMPORT-LOGS.md`.

## 🔧 Pipeline artisan (riepilogo)

- php artisan gescon:import-full --stabile=NNNN [--dry-run] [--anno=YYYY] [--solo=step]
- Step disponibili: stabili, unita, soggetti, diritti, millesimi, voci, operazioni, rate, incassi, giroconti, straord, addebiti, detrazioni

---

## 🔧 **CONFIGURAZIONE**

Vedere file specifici in ogni cartella per dettagli implementazione.

## 🧱 Lettura legacy: strategia e servizi

- Strategia: MDB-first con fallback su staging/dataset. Per ogni stabile/anno si tenta la lettura da `singolo_anno.mdb` e, se non disponibile, si ricade su staging.
- Servizio dedicato: `App/Services/GesconImport/LegacyArchiveService` centralizza discovery e lettura (anni, gestioni, unità, casse), evitando duplicazioni nel controller.
- Risoluzione cartella→anno: il servizio usa la tabella `anni` in `generale_stabile.mdb` per mappare `nome_dir` (es. "0001") all'anno civile e ai periodi (ordinarie/riscaldamento). Questo consente di passare in input sia l'anno che la cartella.

## 🔎 Smoke test Unità (diagnostica rapida)

Per validare rapidamente la lettura delle unità per uno stabile e una cartella/anno è disponibile lo script CLI `scripts/smoke_unita.php` nel progetto Laravel. Lo script:

- risolve automaticamente cartella/anno usando `LegacyArchiveService`
- stampa periodi e gestioni risolte
- legge intestazioni e prime righe della tabella `condomin` (MDB-first, fallback su staging)

Nota: in presenza di discrepanze tra anno cartella e periodo riscaldamento (es. riscaldamento che sconfina sull'anno successivo), fare riferimento alla risoluzione basata su tabella `anni`.