105 lines
4.4 KiB
Markdown
105 lines
4.4 KiB
Markdown
# 🔄 **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`.
|