Roadmap OSM Future

[Dasc3er]

Questa issue descrive le scelte effettuate per la versione futura del gestionale OpenSTAManager, finalizzata a migliorare la struttura del gestionale secondo standard più recenti.

Cioò prevede 3 sezioni principali:

• Aggiornare il gestionale all'utilizzo di un framework PHP standard (Laravel, o Symfony) per garantire maggiore semplicità di aggiornamento e modifica nel tempo
• Agevolare la separazione tra UI e backend, preferibilmente gestendo il frontend separatamente dal backend (to be defined: grado di separazione, ed eventuale riscrittura in Typescript del frontend)
• Spostare la comunicazione tra UI e backend ad utilizzare un singolo layer di API

Maggiori informazioni sulla separazione dei moduli.

Backend

Il gestionale utilizza al momento un framework personalizzato basato su file specifici per la gestione delle azioni.
Dalla versione 2.3/2.4 sono stati integrati alcuni componenti di Laravel, soprattutto per una migliore gestione dei modelli di accesso al database.

Data la complessità del progetto, si sconsiglia il passaggio a Laravel per la gestione completa del progetto. Questo perchè Laravel è principlamente composto di elementi che richiedono un forte ristrutturazione del gestionale nel suo completo, il che potrebbe a uno stop dello sviluppo per un tempo non breve.

Si consiglia invece di iniziare a introdurre alcuni componenti Symfony per la gestione delle route: questi possono essere configurati a costo quasi nullo per l'intero gestionale.
Un esempio di tale funzionalità è indicato nella seguente domanda StackOverflow: https://stackoverflow.com/questions/59637483/can-i-use-symfonys-route-annotation-in-non-symfony-project (deve essere aggiornato per lavorare con Attributi PHP). Questa logica si può aggiungere al file core.php, per identificare in automatico tutti i route e controller definiti all'intero dei moduli e la cartella src.

A lungo termine, il gestionale dovrebbe evitare in modo completo l'utilizzo di include per chiamare file diretti tra di loro.

1. Primi controller

Per la prima introduzione di controller PHP, si consiglia di iniziare con componenti che non sono interconnesse con altri elementi: stampe, ajax-select options, altre chiamate AJAX che non richiamano componenti standard, integrazione OAuth, sezione gestione utenti, e simili. Queste componenti possono essere aggiornate senza richiedere cambiamenti estensivi e rompere altre sezioni del gestionale.

Esempio: /logs carica logs.php, /print carica print.php.

Una volta fatta una prima connessione di questo tipo, si può spostare la logica interna nel controller. Esempio per stampe: https://github.com/devcode-it/openstamanager/tree/laravel/app/OSM/Prints

I controller Symfony possono ritornare HTML diretto, basato sulla documentazione. Questo può essere utilizzato in un primo momento, per poi passare a un gestore di template come Twig o Blade. Esempio per template: https://github.com/devcode-it/openstamanager/tree/laravel

2. Aggiornare un modulo

Un modulo di partenza per l'aggiornamento totale al nuovo standard sarebbe Impostazioni, in quanto piuttosto semplice e comunque dinamico (chiamate AJAX per aggiornamento parametri).

Per prima cosa, si consiglia di un semplice passaggio di retrocompatibilità: chiamate a edit.php, actions.php, ... devono fare un redirect al route impostato per il controller (o chiamare il controller direttamente). Questo permetterebbe di mantenere un sistema funzionante, e isolare il cambiamento al modulo.

Il modulo deve essere consistente a livello interno - si possono considerare successivamente miglioramenti di logica e pulizia.

3. Sfruttare un sistema di template

Una volta completati i passaggi precedenti, si può considerare l'utilizzo di un sistema di template al posto di PHP diretto con HTML per la generazione delle pagine.

Il framework Twig è maggiormente integrato con Symfony, ma altri possono essere usati come desiderato.
Esempio per template Blade (richiede qualche aggiornamento): https://github.com/devcode-it/openstamanager/tree/laravel

4. Introduzione formale API

Dai punti precedenti, esistono controller che contengono le azioni previste da actions.php.

Questi sono controller che verranno chiamati per aggiornare, creare od operare su record del modulo. Con uno sforzo minimo, possono essere trasformati in API formali.

Idealmente, il formato delle API (e.g. struttura in input e output con descrizione di tipo per ogni elmento) dovrebbero essere descritte formlamente per garantire che i cambiamenti non causino problemi di compatibilità nel tempo.

Si consideri OpenAPI come standard (https://swagger.io/specification/) oppure un formato persinalizzato che sia riconducibile a OpenAPI con un semplice processore.
Questo permetterebbe la generazione di un client preimpostato per chiamare l'API e lavorare con i risultati, utilizzabile nell'UI allo step successivo (invece che generando il codice a mando per le chiamate AJAX).

5. Miglioramento integrazione con UI

Una volta definite le API del punto precedente, si può usare lo standard OpenAPI per generare il client JS per l'UI.

6. Integrazione con struttura base

Una volta definito lo standard di cui sopra, si può lavorare con i file editor.php e controller.php per supportare il nuovo standard ed evitare l'utilizzo di file edit.php e simili nel modulo.

7. Aggiornare tutto il gestionale

Piano piano, di release in release, si può lentamente aggiornare il gestionale con la struttura indicata.

8. Modifiche di accesso

Il punto di accesso del gestionale a lungo termite dovrebbe essere la sola cartella public/.
Questo permette maggiore controllo sull'accesso ai file del gestionale da utenti e sistema.

Frontend

Proposta esistente per riscrittura via Typescript

Scritto in Typescript (Javascript tipizzato) che utilizza il framework JS Mithril e il framework grafico Material Web/MWC (Material Design).

• Mithril gestisce tutte le views/pagine (aiutato da Inertia, approfondito sotto questo paragrafo).
• Material Web e MWC sono entrambi framework CSS/JS open source, sviluppati da Google, con cui costruire la nuova UI (sostituendo Bootstrap). Material Web è la versione di MWC con lo stile e i componenti del Material Design 3, non ancora completa di tutti i componenti, ma le mancanze di MDC verranno compensate da MWC (la versione 2), finchè non saranno disponibili i componenti aggiornati. Datatables è stato sostituito con il componente DataTable del Material Design, implementando anche filtri e paginazione.

Ponte fra backend e frontend: InertiaJS. Permette di condividere dati tra Laravel e Mithril, e gestire meglio il routing tra i due framework.

Esempio: https://github.com/devcode-it/openstamanager/tree/3.x

Operazioni da definire e completare

• Rimozione dei plugin in favore di una gestione unificata come moduli
• Revisione dei vari componenti come pacchetti Laravel (Revisione dei Componenti #793 per logica personalizzata)
• Revisione del sistema di permessi tramite Middleware (Revisione del sistema di permessi #792) [moduli, plugin, widget, stampe, email, cronjob, ...]
• Implementazione del templating nelle email
• Interfaccia di base per il sistema di importazione/esportazione dei contenuti in vari formati
• Sistema di upload personalizzabile ed estendibile a servizi esterni (Revisione del sistema degli allegati #791)
• Generalizzazione sistema evasioni documenti (Generalizzazione sistema evasioni documenti #786)con revisione degli stati
  • Stato del documento
  • Stato di riferimento (non importato, parzialmente importato, importato)
  • Come gestire la traslazione automatica tra stati sulla base del documento di riferimento?
• Separazione dei sezionali (strettamente legati ai documenti) dai segmenti (filtri selezionabili manualmente dall'utente) (Spostare la gestione dei “Segmenti” in nuovo panel all’interno del modulo “Viste”. #206)
• Introduzione di un gestore dei menu principali del gestionale scollegato dalla logica dei moduli
• Rimozione delle query a database per i moduli di default, in modo tale da avere fisicamente raggiungibile la query e mantenendo la personalizzabilità esclusivamente a database (da considerare per le Viste)
• Rimuovere il supporto a versioni MySQL troppo vecchie (Compatibilità MySQL #355)
• Miglioramento della gestione interna dei totali (prezzo, iva, ...) per le righe in generale e i documenti (Miglioramento struttura righe/articoli/sconti/descrizioni #546)
• Revisione del sistema di aggiornamento
  • Controlli di integrità e correttezza di file e database
  • Backup automatico
  • Anteprima dell'aggiornamento
  • Ripristino da backup indipendente in caso di errori
• Revisione dei campi idtipo* e idstato* in id_tipo_* (da cambiare in id_tipo) e id_stato
• Sistema di chat e controllo utenti connessi

---

La roadmap qui indicata non è definitiva e può essere soggetta a cambiamenti anche considerevoli.

[Dasc3er]

Ulteriori punti di interesse per la nuova versione:

• Gestione modulare attraverso Composer #45 propone l'utilizzo di Composer come sistema di gestione dei moduli, semplificato dall'introduzione di Laravel Modules
• Nuova tabella zz_user_setting #74 introduce una sezione di Impostazioni specifiche per l'utente, utili per ampliamenti futuri (notifiche browser, temi, lingua, ...)
• Maggiore precisione nei calcoli #99 propone l'utilizzo di una libreria per l'esecuzione dei conti numerici del gestionale, al fine di migliorare la stabilità e l'affidabilità dei risultati (attualmente gli importi sono gestiti tramite semplici float nativi, che causano problemi in casi estremi). In particolare, con le classi Eloquent si potrebbe implementare internamente brick/math per la gestione dei calcoli relativi.
• Strutturazione actions.php esterni per sviluppare più moduli esterni #212 discute la gestione della struttura al fine delle personalizzazioni di moduli e funzionalità di base (senza particolari risultati pratici)
• Salvataggio informazioni per documenti evasi #248 propone il salvataggio delle informazioni collegate ai documenti all'emissione (in particolare, indirizzi e sedi delle Anagrafiche) per evitare la falsificazione dei dati per modifiche successive. Similmente, Miglioramento movimentazione documenti in Bozza #787 discute della gestione dei movimenti degli Articoli, che dovrebbero essere effettuati solo all'emissione del documento. Ancora, Mantenimento prima nota e scadenze durante riapertura fatture #818 studia le problematiche attuali alla riapertura delle Fatture.
• Standardizzazione dei campi #311, Standardizzare la sede legale #310, Standardizzare la Ritenuta D'Acconto #309 prevedono alcune correzioni sulla struttura interna di Stati documenti, Sedi anagrafiche e la gestione della Ritenuta d'Acconto (quest'ultima da considerare in vista degli aggiornamenti più recenti di Fattura Elettronica)
• Nome allegati via mail #297 richiede di migliorare l'interfaccia di invio email per permettere la personalizzazione dei nomi degli allegati in modo dinamico
• Aggiornamento del database in sviluppo #346 propone di migliorare la gestione delle modifiche al database tramite l'utilizzo delle migrazioni, ovvero file fisici ristretti a un piccolo numero di query (solitamente 1 per modifica al database). Tramite Laravel, la procedura di integrazione con questo sistema è automatica (anche per i moduli) e la generazione si effettua dinamicamente tramite Artisan. In riferimento agli aggiornamenti, è di interesse Revisione sistema di aggiornamento #795 per il miglioramento della procedura pratica di aggiornamento tramite archivio ZIP.
• MIGLIORIA: Serial number deve essere univoco sullo stesso articolo #658, Miglioramento del sistema dei seriali  #851 discutono le problematiche relative al sistema attuale di gestione dei seriali (in particolare, il riutilizzo dei serial number non è permesso al momento). Movimentazione non tiene conto del Serial Number #933 richiede lo spostamento di seriali tra sedi.
• Miglioramento evasione contratti e preventivi #788 propone un nuovo sistema per l'evasione di Contratti e Preventivi
• Introduzione sistema di gestione per gli utenti connessi #797 propone un sistema di gestione degli utenti connessi, sia per maggiore sicurezza che per una eventuale chat interna
• Revisione del sistema di traduzione #800 considera le problematiche nella gestione delle traduzioni dei contenuti fissi a database (moduli e diciture automatiche in particolare)
• Codice metodo pagamento associato alla rate #830 propone la possibilità di associare pagamenti distinti alle diverse rate delle Fatture
• SCADENZARIO - Individuazione della rata  #356, Aggiunta numero rata in Scadenzario e Prima Nota #833 e MIGLIORIA: Problema con lo scadenzario #877 descrivono la necessità di gestire le rate dello Scadenzario in modo distinto (evitando il comportamento attuale che completa le rate in ordine)

[Dasc3er]

PR #1710 aggiunge le funzionalità base per l'API con standard OpenAPI attraverso API Platform.