# 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. 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`