michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
89fde6b582
netgescon-day0/docs/000-FILAMENT/00-MANUALE-FILAMENT.md

7.8 KiB
Raw Blame History

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