netgescon-day0/docs/support/MANUALE-SVILUPPO-OPERATIVO.md

Manuale sviluppo operativo NetGescon

Scopo della sezione

Questa documentazione serve a evitare dispersione di informazioni tra chat, script, note locali e memoria personale.

La regola pratica e semplice:

1. quello che diventa operativo o architetturale va scritto qui
2. quello che corregge un problema va riportato anche nel registro bug/fix
3. quello che richiede contesto extra puo essere annotato nel tab Commit + Note
4. il deploy o update applicativo parte poi dalla pagina Supporto > Modifiche

Per il dettaglio del flusso Git-first di staging fare riferimento anche a:

• docs/support/AGGIORNAMENTI-STAGING-GIT.md

Flusso standard di lavoro

1. sviluppo nel workspace Day0
2. test locale mirato sulla funzione toccata
3. aggiornamento del file manuale o bug corrispondente
4. commit Git con messaggio leggibile
5. push su Gitea
6. aggiornamento del nodo dalla pagina admin-filament/supporto/modifiche con sync Git da Gitea
7. verifica finale su staging

Effetto pratico

• [P] il progetto inizia ad avere una memoria strutturale interna, non solo conversazionale
• [P] l agent puo leggere direttamente dal repository cosa e stato fatto, perche e stato fatto e quali file sono coinvolti
• [U] chi opera dalla UI trova nello stesso punto manuale, aggiornamenti, bug e note commit
• [P] dopo ogni Git staging puo essere riallineato da Gitea direttamente dalla UI, senza terminale
• [P] il changelog Git automatico puo essere rigenerato sul nodo senza sporcare il repository locale

Implementazioni recenti da tenere come riferimento

0-ter. Stabile come hub documentale e operativo per posta e acqua

• condomini/stabile ora raccoglie in un unico punto documentazione, caselle ufficiali, protocollo comunicazioni e link a Google/Drive.
• strumenti/comunicazioni e diventata una regia amministratore effettiva invece di una vista placeholder.
• Per 0023 - GERMANICO 79 sono stati riallineati sia la parte anagrafica sia l archivio acqua 2024, cosi il prossimo slice puo partire dalla raccolta letture unita per unita invece che da import grezzi sparsi.

Effetto pratico:

• [U] lo stabile ha un punto unico per posta ufficiale, protocollo e archivio documentale
• [U] l amministratore vede le comunicazioni sia per stabile sia a livello studio con la stessa logica dei ticket
• [P] la futura raccolta letture acqua puo appoggiarsi a dati gia importati e ai nominativi riallineati

0. Direzione di prodotto: NetGescon come spazio unico a ruoli e moduli

• La direzione attuale non e piu quella di un gestionale chiuso solo per l amministratore condominiale.
• NetGescon va trattato come uno spazio operativo unico dove la differenza non la fa la macchina o il menu fisso, ma l abilitazione concessa a ruolo, persona o tenant.
• Lo stesso utente puo lavorare su piu assi: assistenza informatica, sviluppo software, revisione contabile, collaboratore amministrativo, gestione PBX, supporto fornitori.
• La base dominio resta stabile: unita immobiliari, anagrafica unica, spese, banca, piano dei conti, ripartizioni, partita doppia.
• Sopra questa base si attivano moduli o funzioni: CTI/PBX, ticketing, revisione, import legacy, storage tenant-aware, distribuzione server, fornitori, allegati, analytics.

Effetto pratico:

• [P] l evoluzione corretta e modulo-first e permission-first, non pagina-first
• [P] lo stesso record dominio deve poter essere usato in procedure diverse senza duplicare dati o UI separate per mestiere
• [U] una persona puo lavorare nello stesso ambiente con ruoli multipli senza cambiare prodotto

0-bis. Slice appena chiuso su CRM telefonico e instradamento umano

• In strumenti/post-it-gestione le chiamate recenti hanno ora anche box raggruppati per chiamante/numero/linea consecutivi.
• Le chiamate interne sono escluse dal raggruppamento operativo, cosi la vista serve davvero per il CRM e non per il rumore tecnico.
• Ogni box puo aprire direttamente il Post-it corrispondente.
• In strumenti/post-it il Post-it puo essere assegnato esplicitamente a operatore, collaboratore o fornitore.
• In impostazioni/scheda-amministratore il tab PBX/TAPI accumula i token osservati e permette di associare piu linee, gruppi ed extension allo stesso collaboratore.

Effetto pratico:

• [U] meno duplicazione nei richiami ripetuti
• [U] piu facile decidere chi prende in carico una chiamata o un ticket derivato
• [P] il PBX viene trattato come sorgente di segnali osservati, non come struttura rigida hard-coded sul fornitore attuale

1. CTI / CSTA / click-to-call piu aperti lato PBX

• Separato il tab tecnico SMDR dal tab CTI / CSTA e Click-to-Call in strumenti/post-it-gestione.
• Esposta in UI una vista piu orientata al provider PBX, non solo a Panasonic.
• Aggiunta la creazione di richieste click-to-call direttamente dai messaggi tecnici CSTA.
• Mantenuta la base attuale Panasonic, ma con direzione compatibile con future integrazioni FreePBX.

Effetto pratico:

• [U] test piu precisi tra tracciato passivo SMDR e canale CTI/CSTA
• [U] possibilita di verificare il flusso di chiamata originata dal gestionale verso il telefono/interno associato
• [P] base piu riusabile per l adapter PBX successivo

2. Allineamento stabile/anno nelle pagine gestionali

• gescon/ordinarie ora eredita l anno attivo dal contesto topbar.
• La risoluzione dei codici legacy stabile e stata centralizzata in StabileContext.
• condomini/servizi-utenze e l archivio letture applicano l anno attivo e il contesto stabile in modo piu coerente.

Effetto pratico:

• [U] riduzione dei casi in cui l header mostra uno stabile/anno ma i dati arrivano da un altro contesto
• [U] base piu affidabile per estrazioni acqua e verifiche contabili per gestione
• [P] meno logica sparsa con chiavi session legacy non coerenti tra le pagine

3. Supporto > Modifiche come pannello unico

• La pagina ha gia tab per aggiornamenti, bug, commit e migliorie.
• Ora diventa anche punto di lettura del manuale strutturale dal repository.
• La sezione manuale espone anche la sync Git/Gitea per staging con stato del repository e avanzamento job.
• La tab Aggiornamenti + Bug espone in chiaro sia il comando predisposto usato dalla UI sia gli aggiornamenti inclusi nel riallineamento Git.

Effetto pratico:

• [P] una sola sezione per spiegare, tracciare, aggiornare e riprendere il lavoro
• [U] piu semplice per chi usa il gestionale capire cosa e stato aggiunto o corretto

File guida da considerare autorevoli

• docs/README.md
• docs/NETGESCON-MODIFICHE.md
• docs/support/MANUALE-SVILUPPO-OPERATIVO.md
• docs/support/AGGIORNAMENTI-STAGING-GIT.md
• docs/support/PBX-PANASONIC-STATO-OPERATIVO.md
• docs/support/ARCHITETTURA-STORAGE-TENANCY.md
• docs/support/BUG-RISOLTI-E-VALIDAZIONI.md
• docs/support/CONTINUITA-SVILUPPO-AGENT.md

Regola editoriale minima

Quando completiamo una modifica, aggiorniamo almeno uno di questi livelli:

• manuale operativo se cambia il modo di lavorare o una funzione importante
• bug risolti se correggiamo un errore o un comportamento incoerente
• note commit se il commit ha dettagli utili ma troppo specifici per stare nel manuale

Prossimi passi consigliati

1. usare questa sezione come fonte primaria per le prossime implementazioni CTI e contabilita
2. automatizzare anche la scrittura di snapshot di sviluppo basati sui commit e sulle note operative
3. aggiungere progressivamente how-to piu mirati, senza spargere file duplicati
4. spostare le prossime decisioni su ruoli/moduli nel documento architetturale dedicato docs/support/ARCHITETTURA-RUOLI-MODULI-COWORKING.md
5. preparare il primo nodo esterno di debug/deploy seguendo docs/support/DISTRIBUZIONE-SERVER-DEBUG.md