Skip to content

Commit b15d9ce

Browse files
lucasalva87lucasalva87
committed
fix: agents.md, 7 colonne dichiarate, 8 valori - NULL finiva su nome
1 parent 10a2abf commit b15d9ce

12 files changed

Lines changed: 1469 additions & 2 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -278,8 +278,7 @@ VALUES (1, LAST_INSERT_ID(), 'Mio Plugin');
278278
### Registering Settings (`zz_settings`)
279279

280280
```sql
281-
INSERT INTO `zz_settings` (`nome`, `valore`, `tipo`, `editable`, `sezione`, `order`, `is_user_setting`)
282-
VALUES
281+
INSERT INTO `zz_settings` (`id`, `nome`, `valore`, `tipo`, `editable`, `sezione`, `order`, `is_user_setting`) VALUES
283282
(NULL, 'Abilita funzionalità X', '0', 'boolean', 1, 'Generali', 10, 0);
284283

285284
INSERT INTO `zz_settings_lang` (`id_lang`, `id_record`, `title`, `help`)

‎analysis/architecture-analysis.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# OpenSTAManager – Architecture Analysis
2+
> Generato automaticamente – Fase 1 (Discovery & Architecture)
3+
4+
## Pattern architetturale generale
5+
6+
OpenSTAManager adotta un'architettura **ibrida** che combina:
7+
8+
1. **Legacy MVC PHP** – Il nucleo storico: `core.php` inizializza la sessione, il database e il translator; `controller.php` / `editor.php` fungono da dispatcher front-controller che includono dinamicamente i file PHP dei moduli.
9+
2. **Laravel moderno** – Laravel 12 è usato come layer di infrastruttura (Eloquent ORM, Routing, Queue, Mail, API Platform). Il file `bootstrap/app.php` crea l'Application Laravel con routing in `routes/`.
10+
3. **Moduli plug-in** – La logica di business è organizzata in **moduli** (`modules/`) e **plugin** (`plugins/`), ognuno con la propria struttura `src/`, `custom/src/`, viste PHP e risorse.
11+
12+
---
13+
14+
## Mappa dei componenti principali
15+
16+
```
17+
┌─────────────────────────────────────────────────────────────┐
18+
│ Browser / Client │
19+
└──────────────────────┬──────────────────────────────────────┘
20+
│ HTTP
21+
┌────────────▼────────────────┐
22+
│ Entry Points │
23+
│ index.php / controller.php │
24+
│ editor.php / ajax*.php │
25+
│ api/index.php │
26+
└────────────┬────────────────┘
27+
│
28+
┌────────────▼────────────────┐
29+
│ core.php │ Bootstrap globale
30+
│ - Sessione PHP │
31+
│ - App::getConfig() │
32+
│ - Database (singleton) │
33+
│ - Translator │
34+
│ - AuthOSM │
35+
└────────────┬────────────────┘
36+
│
37+
┌───────────────┼───────────────────┐
38+
│ │ │
39+
┌──────▼──────┐ ┌──────▼──────┐ ┌─────────▼────────┐
40+
│ src/App.php │ │src/Modules │ │ src/Database.php │
41+
│ Config │ │ .php │ │ (Eloquent │
42+
│ Assets │ │ Module list │ │ Capsule) │
43+
│ File paths │ │ Hierarchy │ │ │
44+
└──────┬───────┘ └──────┬──────┘ └─────────┬─────────┘
45+
│ │ │
46+
│ ┌──────▼──────┐ ┌──────▼──────┐
47+
│ │ modules/ │ │ src/Models/ │
48+
│ │ ~70 moduli │ │ Eloquent │
49+
│ │ plugins/ │ │ Models │
50+
│ │ ~30 plugin │ └─────────────┘
51+
│ └─────────────┘
52+
│
53+
┌──────▼───────────────────────────────┐
54+
│ assets/ (frontend) │
55+
│ Bootstrap, AdminLTE, jQuery, │
56+
│ FullCalendar, Chart.js – build Gulp │
57+
└──────────────────────────────────────┘
58+
```
59+
60+
---
61+
62+
## Struttura directory – ruolo di ogni cartella
63+
64+
| Directory | Contenuto |
65+
|---|---|
66+
| `src/` | Core PHP: App, Auth, Database, Modules, Models, Controllers Laravel, API, Util |
67+
| `modules/` | ~70 moduli applicativi (ogni modulo = directory autonoma con PHP + src/) |
68+
| `plugins/` | ~30 plugin (logica add-on attaccata ai moduli) |
69+
| `templates/` | Template di stampa PDF (mPDF/html2pdf) |
70+
| `include/` | Partials HTML: header/footer, form comuni, init scripts |
71+
| `config/` | Configurazioni Laravel (database, mail, cache, osm, sanctum…) |
72+
| `routes/` | Routing Laravel (web.php, api.php, console.php) |
73+
| `bootstrap/` | Bootstrap Laravel (app.php, providers.php) |
74+
| `assets/src` | Sorgenti frontend (SCSS, JS) da compilare con Gulp |
75+
| `assets/dist` | Asset compilati serviti al browser |
76+
| `locale/` | File .po/.mo per internazionalizzazione (it_IT, en_GB, de_DE) |
77+
| `update/` | Script di migrazione SQL/PHP per ogni versione |
78+
| `lib/` | Funzioni helper globali (functions.php, common.php, util.php) |
79+
| `files/` | Allegati e file upload organizzati per modulo |
80+
| `vendor/` | Dipendenze Composer |
81+
| `node_modules/` | Dipendenze npm/yarn |
82+
| `docker/` | Configurazione Docker per sviluppo |
83+
| `logs/` | Log applicativi (error.log, cron-*.log, setup.log) |
84+
| `storage/` | Storage Laravel (framework cache, logs) |
85+
86+
---
87+
88+
## Sistema dei Moduli
89+
90+
Ogni modulo in `modules/<nome>/` ha questa struttura tipica:
91+
92+
```
93+
modules/fatture/
94+
├── src/ # Classi PHP del modulo (namespace Modules\Fatture\)
95+
├── custom/src/ # Override personalizzati (non sovrascritti dagli aggiornamenti)
96+
├── init.php # Inizializzazione modulo
97+
├── modutil.php # Utility specifiche
98+
├── edit.php # Vista di dettaglio/modifica
99+
├── actions.php # Azioni POST del modulo
100+
└── bulk.php # Operazioni bulk
101+
```
102+
103+
Il sistema `custom/` è il meccanismo ufficiale di personalizzazione: i file in `custom/src/` e `custom/` sovrascrivono quelli standard senza toccare il codice base, sopravvivendo agli aggiornamenti.
104+
105+
---
106+
107+
## Flusso di una richiesta tipica
108+
109+
```
110+
1. Browser → controller.php?id_module=X&id_record=Y
111+
2. core.php → inizializza sessione, DB, auth, translator
112+
3. AuthOSM::check() → verifica login
113+
4. Permissions::check() → verifica permessi modulo
114+
5. Modules::getCurrent() → carica metadati modulo da DB
115+
6. include modules/<nome>/init.php → inizializza modulo
116+
7. App::load('edit.php', ...) → cerca custom/ poi standard
117+
8. Output HTML con include top.php / bottom.php
118+
```
119+
120+
---
121+
122+
## Sistema di autenticazione
123+
124+
- **Classe**: `AuthOSM` (src/AuthOSM.php)
125+
- **Sessione PHP** nativa per la sessione utente
126+
- **OAuth2** via `zz_oauth2` table: supporto Microsoft, Google, Keycloak
127+
- **Token OTP**: accesso temporaneo per link condivisi (`zz_tokens`)
128+
- **Brute-force**: lockout automatico dopo N tentativi falliti
129+
- **Intended URL**: redirect post-login all'URL originale richiesto
130+
131+
---
132+
133+
## API REST
134+
135+
- **Path**: `api/index.php` + `routes/api.php`
136+
- **Framework**: Laravel + API Platform ^4.1
137+
- **Auth**: Laravel Sanctum (Bearer token)
138+
- **Risorse**: auto-generate da `src/Models/ApiResource.php`
139+
140+
---
141+
142+
## Internazionalizzazione
143+
144+
- File `.po`/`.mo` in `locale/`
145+
- Lingue: `it_IT` (primaria), `en_GB`, `de_DE`
146+
- Classe: `src/Translator.php` + `symfony/translation`
147+
- Helper globale: `tr()` (alias di traduzione)
148+
149+
---
150+
151+
## Pattern "Custom Override"
152+
153+
Il sistema riconosce percorsi con `|custom|` e cerca prima `custom/` poi il file standard:
154+
155+
```php
156+
// App::filepath('include|custom|/common/', 'form.php')
157+
// cerca: include/common/custom/form.php → se esiste usa questo
158+
// altrimenti: include/common/form.php
159+
```
160+
161+
Stesso meccanismo per i moduli: `modules/<nome>/custom/src/` sovrascrive `modules/<nome>/src/`.

‎analysis/code-patterns-identified.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Pattern del Codice – Analisi Trasversale
2+
> Fase 2 – Component Analysis
3+
4+
## Pattern rilevati nel codebase
5+
6+
---
7+
8+
### 1. Pattern "Dual Write" per campi tradotti
9+
Ogni operazione su un'entità con campi traducibili richiede
10+
una scrittura doppia: tabella principale + tabella `_lang`.
11+
12+
```php
13+
// INSERT nuovo modulo → SEMPRE doppia scrittura
14+
$dbo->insert('zz_modules', ['name' => 'MioModulo', 'enabled' => 1]);
15+
$dbo->insert('zz_modules_lang', [
16+
'id_record' => $id,
17+
'id_lang' => $id_lang,
18+
'title' => 'Mio Modulo'
19+
]);
20+
```
21+
22+
Tabelle principali con corrispondente `_lang`:
23+
`zz_modules`, `co_statidocumento`, `co_tipidocumento`, `co_pagamenti`,
24+
`dt_causalet`, `zz_segments`, `zz_views`, e molte altre.
25+
26+
---
27+
28+
### 2. Pattern "Custom Override" (personalizzazioni sicure)
29+
Il meccanismo `|custom|` in `App::filepath()` cerca prima `custom/` poi il file standard.
30+
Permette override senza modificare il codice base (aggiornamenti sicuri).
31+
32+
```
33+
modules/fatture/edit.php → file standard
34+
modules/fatture/custom/edit.php → override personalizzato (ha precedenza)
35+
36+
modules/fatture/src/Fattura.php → classe standard
37+
modules/fatture/custom/src/Fattura.php → override personalizzato
38+
```
39+
40+
---
41+
42+
### 3. Pattern "Superselect" per filtri contestuali
43+
Array `$superselect` passato alle select per filtrare dinamicamente le opzioni:
44+
45+
```php
46+
$superselect['dir'] = 'entrata'; // filtra tipi documento per direzione
47+
$superselect['idtipodocumento'] = $record['idtipodocumento'];
48+
// HTMLBuilder SelectHandler usa questi valori come WHERE aggiuntivi
49+
```
50+
51+
---
52+
53+
### 4. Pattern "Init + Edit + Actions" per ogni modulo
54+
Ogni modulo segue questa struttura di file obbligatori:
55+
56+
```
57+
init.php → carica il record dal DB, inizializza variabili
58+
edit.php → HTML del form (usa tag HTMLBuilder)
59+
actions.php → gestisce le operazioni POST (op=save, op=delete, ecc.)
60+
modutil.php → funzioni utility specifiche del modulo
61+
```
62+
63+
---
64+
65+
### 5. Pattern "op" per le azioni
66+
Tutte le azioni POST usano il parametro `op`:
67+
68+
```php
69+
$op = post('op'); // o filter('op')
70+
71+
switch ($op) {
72+
case 'save': // salva record
73+
case 'delete': // elimina record
74+
case 'upload': // carica file
75+
// ...
76+
}
77+
```
78+
79+
---
80+
81+
### 6. Helper globali come alias
82+
Il codebase usa molti helper PHP globali per accesso rapido a oggetti singleton:
83+
84+
```php
85+
database() // → Database::getInstance()
86+
auth_osm() // → AuthOSM::getInstance()
87+
setting($key) // → Settings::get($key)
88+
tr($string) // → traduzione
89+
filter($key) // → input GET sanitizzato
90+
post($key) // → input POST sanitizzato
91+
prepare($val) // → PDO::quote() per query
92+
flash() // → App::flash() per messaggi utente
93+
```
94+
95+
---
96+
97+
### 7. Pattern Documenti – Direzione entrata/uscita
98+
I moduli `Fatture di vendita` e `Fatture di acquisto` condividono la stessa
99+
tabella `co_documenti` e la stessa logica, differenziati da `co_tipidocumento.dir`:
100+
101+
```php
102+
if ($module->name == 'Fatture di vendita') {
103+
$dir = 'entrata';
104+
} else {
105+
$dir = 'uscita';
106+
}
107+
```
108+
Stesso pattern per DDT, Ordini, Preventivi.
109+
110+
---
111+
112+
### 8. Pattern Riferimenti Incrociati
113+
I documenti sono collegati tra loro tramite campi `ref_documento`:
114+
- Fattura → Note di credito (`reversed=1`, `ref_documento`)
115+
- Fattura → Autofattura (`id_autofattura`)
116+
- DDT → Fattura
117+
- Ordine → DDT → Fattura
118+
119+
---
120+
121+
## Problemi tecnici identificati
122+
123+
### 1. Mixed query styles (debito tecnico)
124+
Convivono tre stili di query: raw PDO, API imperativa `$dbo->fetchArray()`,
125+
e Eloquent Model. Non c'è una linea guida unica.
126+
127+
### 2. Query SQL inline nei template (init.php)
128+
Query SQL complesse con molte JOIN nei file `init.php` dei moduli.
129+
Difficile testare e riutilizzare questa logica.
130+
131+
### 3. SelectHandler con query SQL nel template
132+
```php
133+
{[ "type": "select", "values": "query=SELECT id, nome FROM an_anagrafiche WHERE ..." ]}
134+
```
135+
Il parametro `values` può contenere SQL arbitrario proveniente dal file di template.
136+
Non accetta input utente quindi sicuro, ma difficile da manutenere.
137+
138+
### 4. Global scope `enabled` su Module
139+
Il global scope filtra sempre i moduli disabilitati.
140+
Per accedere a moduli disabilitati serve `withoutGlobalScope('enabled')`.
141+
142+
### 5. ob_start() per template rendering
143+
Il rendering usa output buffering PHP nativo invece di un template engine.
144+
Rende il debug dei template più complesso.

‎analysis/codebase-analysis-progress.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# OpenSTAManager – Codebase Analysis Progress
2+
> File di stato per continuità tra sessioni di analisi
3+
4+
## Progetto
5+
- **Path**: `C:\wamp64\www\openstamanager`
6+
- **Analisi completata**: 2026-03-16
7+
8+
---
9+
10+
## ✅ ANALISI COMPLETA – Tutte e 3 le fasi completate
11+
12+
---
13+
14+
## Fasi completate
15+
16+
### ✅ Fase 1 – Discovery & Architecture
17+
**Scoperte chiave**: architettura ibrida Laravel 12 + legacy PHP, ~70 moduli + ~30 plugin,
18+
sistema custom/ per personalizzazioni, auth multi-provider, API Platform + Sanctum.
19+
20+
### ✅ Fase 2 – Component Analysis
21+
**Scoperte chiave**: tre livelli di query DB coesistenti, pattern Dual Write per traduzioni,
22+
HTMLBuilder DSL `{[]}` / `{()}`, AuthOSM con 5 metodi di autenticazione,
23+
pattern "op" per azioni POST, pattern "dir" per documenti bidirezionali.
24+
25+
### ✅ Fase 3 – Documentation & Recommendations
26+
**Prodotti**: guida onboarding, raccomandazioni prioritizzate (10 items),
27+
guida completa al codebase con schema DB, pattern reference, helper sheet.
28+
29+
---
30+
31+
## File di analisi generati
32+
33+
```
34+
analysis/
35+
├── project-overview.md ✅ Fase 1
36+
├── architecture-analysis.md ✅ Fase 1
37+
├── code-patterns-identified.md ✅ Fase 2
38+
├── comprehensive-codebase-guide.md ✅ Fase 3
39+
├── developer-onboarding-guide.md ✅ Fase 3
40+
├── technical-recommendations.md ✅ Fase 3
41+
├── component-deep-dives/
42+
│ ├── database-layer.md ✅ Fase 2
43+
│ ├── models-and-traits.md ✅ Fase 2
44+
│ ├── htmlbuilder.md ✅ Fase 2
45+
│ └── auth-system.md ✅ Fase 2
46+
└── codebase-analysis-progress.md ✅ (questo file)
47+
```
48+
49+
---
50+
51+
## Raccomandazioni tecniche – top 3
52+
53+
1. **Alta** – Standardizzare le query verso Eloquent/Fluent Builder (abbandonare
54+
il pattern `fetchArray('... WHERE id='.prepare($id))` nei nuovi file)
55+
2. **Alta** – Estrarre la logica SQL da `init.php` nei Model Eloquent
56+
(per testabilità e riuso)
57+
3. **Alta** – Aggiungere test unitari per i componenti core
58+
(Database::sync, AuthOSM::validateOTP, HTMLBuilder::decode, Update)
59+
60+
---
61+
62+
## Continuare l'analisi in una nuova chat
63+
64+
> "Continua l'analisi del codebase – leggi
65+
> `C:\wamp64\www\openstamanager\analysis\codebase-analysis-progress.md`
66+
> per sapere dove ci siamo fermati, poi prosegui con [argomento specifico]."
67+
68+
Argomenti utili per approfondimenti futuri:
69+
- Analisi sicurezza (SQL injection, CSRF, XSS)
70+
- Analisi performance (query N+1, cache)
71+
- Analisi modulo fatturazione elettronica (XML FE, codice SDI)
72+
- Documentazione API REST (endpoint disponibili)
73+
- Analisi sistema di stampa PDF (templates/)

0 commit comments

Comments
 (0)