# Manuale Filament NetGescon (Laravel)

## 1) Scopo
Questa guida riassume lo stato **attuale** del progetto Filament e la pipeline di import GESCON, basata sul codice presente. È pensata per ripartire rapidamente dopo aggiornamenti o ripristini.

## 2) Stack e versioni
- Laravel 12
- Filament v4
- Livewire 3
- DB principale: MySQL
- DB staging import: `gescon_import`

Riferimenti:
- Composer: `filament/filament:^4.0`, `laravel/framework:^12.0`.

## 3) Panel Filament
**Panel provider**:
- File: `app/Providers/Filament/AdminFilamentPanelProvider.php`
- ID panel: `admin-filament`
- Path: `/admin-filament`
- Theme: `resources/css/filament/admin/theme.css`
- Hook custom: `legacy-admin-assets`, `topbar-context`, `topbar-icons`, `footer`

**Login Filament**:
- File: `app/Filament/Auth/Login.php`
- Redirect forzato post-login: `/admin-filament`
- Motivazione: evitare redirect verso UI classica (`/admin`).

## 4) Navigazione ibrida
Nel panel Filament convivono:
- **Pagine Filament nuove** (Pages)
- **Link alla UI classica** (routes `admin.*`)

La navigazione è configurata nel panel provider con `NavigationItem::make()`.

## 5) Struttura Filament
Le pagine sono sotto `app/Filament/Pages` con gruppi principali:
- `Gescon/*` → import, archivi legacy, viste GESCON
- `Contabilita/*` → cruscotti contabili, rate, incassi, prima nota
- `Condomini/*` → schede stabile, unità, tabelle millesimali
- `Supporto/*`, `Strumenti/*`, `RevisioneContabile/*`

### Scheda Stabile (Condomini → Stabile)
- Tab Gestione: elenco gestioni aperte con archivio separato.
- Azioni rapide: nuova gestione e duplicazione gestione.
- Click su gestione → Tab “Periodi emissione rate” con dati gestione.
- Checklist fine anno condivisa (tabella `checklist_fine_anno_items`).
- Straordinarie: dettaglio con sotto-tab Operazioni/Preventivo/Rate/Incassi/Consuntivo (legacy).

Pagine chiave GESCON:
- `app/Filament/Pages/Gescon/ImportazioneArchivi.php`
- `app/Filament/Pages/Gescon/GesconHome.php`

## 6) Archivi legacy (solo lettura)
Gli archivi GESCON legacy sono **in sola lettura**:
- Path base: `/mnt/gescon-archives/gescon/`
- Struttura tipica:
  - `dbc/Stabili.mdb`
  - `<cod_stabile>/<anno>/singolo_anno.mdb`
  - `generale_stabile.mdb`

Nota: il path base non include il codice amministratore. Il codice univoco serve solo per import/archiviazione interna, non per il mount legacy.

## 7) Staging DB (anti-duplicazione)
I dati legacy vengono importati in **staging** per evitare duplicati.
Connessione:
- `config/database.php` → `gescon_import`

Uso principale:
- Le tabelle staging contengono `legacy_year`, `legacy_period`, `legacy_file`.
- I comandi e servizi import leggono staging per sincronizzare il dominio.

## 8) Pipeline Import (panoramica)
### 8.1 Flusso consigliato
1. **Carica MDB in staging**
2. **Sincronizza nel dominio** con la pipeline completa o step singoli
3. **Arricchisci** (catasto/banche) se richiesto

### 8.2 Componenti principali
**UI Filament**:
- `ImportazioneArchivi` gestisce:
  - modalità Linux (path su disco)
  - modalità Windows (upload file/zip e estrazione)

**Servizi**:
- `LegacyArchiveService`: preview/letture legacy (MDB o staging)
- `EssentialImportService`: orchestratore “light”
- `StabileEnrichmentService`: arricchisce dati stabile con Stabili.mdb

**Pipeline completa**:
- Command: `gescon:import-full` (ImportGesconFullPipeline)
- Steps: `stabili`, `unita`, `soggetti`, `diritti`, `millesimi`, `voci`, `banche`, `operazioni`, `rate`, `incassi`, `giroconti`, `straord`, `addebiti`, `detrazioni`

## 9) Comandi importanti
### Staging MDB
- `gescon:load-mdb` → Importa una tabella MDB in staging

### Pipeline dominio
- `gescon:import-full` → Pipeline completa a step
- `gescon:import-gestioni` → Import gestioni (usato da EssentialImportService)

### Import mirati (staging)
- `import:gescon-mdb` → import diretto MDB → staging multi-anno
- `import:gescon-fornitori` → Fornitori.mdb → staging
- `import:gescon-fatture-legacy` → generale_stabile.mdb (Fatture) → staging

## 10) Regole di dedup/sicurezza
- Lo staging è la sorgente primaria per evitare doppie importazioni.
- La pipeline completa evita di sovrascrivere campi già valorizzati a meno di `--force-mapping`.
- `EssentialImportService` calcola hash staging per capire se lo stabile è cambiato.

## 11) Punti chiave per ripartenza rapida
1. Verificare `gescon_import` (DB staging) attivo e tabelle presenti.
2. Verificare `mdb-tools` installato (`mdb-export`, `mdb-tables`).
3. Configurare path archivi GESCON (`/mnt/gescon-archives/gescon`).
4. Usare Filament `ImportazioneArchivi` per orchestrare import UI.
5. Se serve una pipeline completa: `gescon:import-full`.

## 12) Note operative
- Il sistema è ibrido: Filament + UI classica coesistono.
- Le parti legacy sono in sola lettura (archivi MDB).
- La documentazione storica è obsoleta: questa guida è la base “attuale”.

## 13) Checklist fine anno (condivisa)
- Tabella: `checklist_fine_anno_items`
- Campi: `label`, `action_url`, `sort_order`, `is_active`
- Uso: guida operativa per chiusura esercizio e convocazione assemblea.

## 13.1) Straordinarie (documento dedicato)
- Vedi: `docs/000-FILAMENT/13-ARCHITETTURA-STRAORDINARIE.md`
- Contiene mapping legacy, tab operative e stato integrazione.

## 13) Linee guida UI Filament (nuove viste)
- Preferire tabelle compatte con font piccoli (text-xs) come in GESCON/Ordinarie.
- Usare modali Filament per dettagli (mastrino, riparti, FE/RA).
- Intestazioni con sezioni e subtotali per leggibilità.
- Pulsanti “Apri” piccoli per azioni secondarie.

## 14) Importazione Archivi (tabs Linux/Windows)
- Tab Linux: path su disco (/mnt/gescon-archives/gescon)
- Tab Windows: upload file MDB/ZIP verso server

## 15) Import banche
Documento dedicato: `11-BANCHE-IMPORT.md`

## 16) Revisione contabile (Filament) — CED HOUSE e Bilanci
Questa sezione documenta **la revisione contabile** implementata in Filament, con estrazione dati da PDF CED HOUSE e PDF Bilanci.

### XX-01 · Estratti conto (CED HOUSE)
- Pagina: Revisione Contabile → Dettaglio revisione (tab **Estratti conto**)
- PDF sorgente: cartella locale estratti (Intesa)
- Estrazione TXT: `pdftotext -layout` → `storage/app/reports/*.txt`
- Funzioni chiave: estrazione, preview testo, import righe in `revisione_precedente_movimento_banca`
- **Segno importi**: negativo solo quando il segno è **attaccato al simbolo** (`-€`); il “-” separatore non inverte
- **Link PDF → Unità**: associazione manuale per nominativo e confronto

### XX-02 · Parsing estratti (sezioni supportate)
- Riepilogo versamenti (importa anche “altre gestioni”)
- Gestione Ordinaria 2023 (versamenti + rate + conguagli)
- Gestione Ordinaria 2024 (versamenti + rate + conguagli)
- Gestione Straordinaria LevelOn (rate + versamenti)
- Rate emesse (filtrate da Ordinaria)
- Conguagli: confronto automatico con `dett_tab` (tab Situazione Iniziale)

### XX-03 · Correzioni post-import
- Pulsante “Correggi negativi importati”:
  - normalizza segni errati (solo per casi `-€`)
  - non altera righe con separatore `-   -€`

### XX-04 · Bilancio 2023 (Bilancio Ordinaria)
- Tab principale **Bilancio 2023** (fuori da Estratti conto)
- PDF sorgente: `Miki-Bug-workspace/Importazione/Andrea doria/Bilancio Ordinaria`
- Sotto-sezioni:
  - **Preventivo/Consuntivo** (Mastro/Conto, Preventivo, Spese, Sbilancio)
  - **Conto Economico** (Costi/Ricavi) con confronto “Versamenti estratti”
  - **Stato Patrimoniale**
  - **Crediti/Debiti verso fornitori**
- Verifica di coerenza:
  - Totali mastri ↔ Conto Economico (Δ Mastro)
  - Versamenti estratti ↔ “VERSAMENTI ESEGUITI DA CONDOMINI”

### XX-05 · Tracciamento stato PDF
- Stato “Fatto/Da fare” e collegamento unità salvati in JSON:
  `storage/app/reports/revisione-<id>-estratti.json`

---
Aggiornare questo file quando cambiano:
- path del panel Filament
- flusso import (staging o pipeline)
- set di comandi
- directory archivi legacy