carmine.savino/kreios
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor PVC models and update tests

Browse Source 
- Updated the PVC models in the database and adjusted the tests accordingly to reflect the new model counts and codes.
- Removed deprecated models from the JSON data for PVC systems.
- Added new GLB models for "scorrevole_sf_3_ante" and "scorrevole_sf_4_ante".
- Enhanced the development scripts to streamline the build process for both frontends.
- Updated documentation to reflect changes in the development environment and deployment process.
- Improved the styling of texture radio options for better visibility.
- Fixed URL handling in the configurator to ensure proper routing and API calls.
This commit is contained in:
carmine.savino
2026-10-20 18:40:59 +02:00
parent b6a32edfe6
commit 0dfda3a338
33 changed files with 339 additions and 366 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PREVENTIVI_BACKOFFICE.md
+71 -132
View File
@@ -1,162 +1,101 @@
# Backoffice Preventivi — Architettura, ambienti e deploy
Questo documento descrive il sistema di preventivi collegato al configuratore: come sono collegati i tre
componenti, come gestiscono le porte/URL in sviluppo, e cosa serve per portarlo in produzione.
Questo documento descrive il sistema di preventivi collegato al configuratore: come sono collegati i
componenti, come vengono serviti e cosa serve per portarlo in produzione.
Per il modello dati, l'API e il flusso applicativo dettagliato vedi [`backoffice/README.md`](../backoffice/README.md).
Per il contratto dei parametri URL del configuratore vedi [`URL_PARAMS.md`](./URL_PARAMS.md).
## Architettura: tre componenti separati
## Architettura: un solo server
```
┌─────────────────────┐ POST /api/carrello/aggiungi ┌──────────────────────┐
│ Configuratore 3D │ ───────────────────────────────────────▶ │ Backend Laravel │
│ (root del repo, │ │ (backoffice/) │
│ Three.js + Vite) │ ◀─────────────────────────────────────── │ API + Filament │
└──────────┬───────────┘ GET /api/config (frontend url) └──────────┬────────────┘
│ │
│ link "Vai al preventivo" │ GET/DELETE/POST
│ https://<app-cliente>/?token=XXX │ /api/carrello/...
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ App cliente Vue │ ───────────────────────────────────────▶ │ (stesso backend) │
│ (backoffice/cliente)│ carrello + checkout │ │
└──────────────────────┘ └──────────────────────┘
Backend Laravel (backoffice/) — unica origine
┌──────────────────────────────────────────────────────────────────────────────────┐
│ /configuratore/ build statica del configuratore 3D (root repo, Vite+Three.js) │
│ /preventivo/ build statica dell'app cliente (backoffice/cliente, Vue 3) │
│ /api/... API catalogo, prezzi, carrello, auth │
│ /admin pannello Filament │
└──────────────────────────────────────────────────────────────────────────────────┘
```
Sono **tre processi indipendenti**, ognuno con il proprio server di sviluppo/deploy:
| Componente | Cartella | Tecnologia | Ruolo |
| Componente | Sorgenti | Build in | URL |
|---|---|---|---|
| Configuratore 3D | `/` (root repo) | Vite + Three.js | UI di configurazione prodotto, genera lo screenshot e invia il primo prodotto al carrello |
| Backend | `backoffice/` | Laravel 13 + Filament 3 | API carrello/preventivi, PDF, email, pannello admin |
| App cliente | `backoffice/cliente/` | Vue 3 + Vite | Riepilogo carrello, form contatti, conferma preventivo |
| Configuratore 3D | `/` (root repo, `src/`) | `backoffice/public/configuratore/` | `/configuratore/?sistema=…&type=…` |
| App cliente (preventivo) | `backoffice/cliente/` | `backoffice/public/preventivo/` | `/preventivo/?token=…` |
| Backend (API + admin) | `backoffice/` | — | `/api`, `/admin` |
Il configuratore e l'app cliente **non si parlano mai direttamente**: comunicano solo passando dal backend
Laravel (il configuratore scrive nel carrello via API, l'app cliente lo legge via API). Il collegamento tra
i due frontend è un singolo `token` passato in query string nel link "Vai al preventivo".
I due frontend restano progetti Vite separati, ma vengono compilati dentro `backoffice/public` e serviti da
Laravel: un solo dominio, un solo processo, nessun CORS tra frontend e API. Il configuratore e l'app cliente
non si parlano direttamente: il configuratore scrive nel carrello via API, l'app cliente lo legge via API;
il collegamento tra i due è il `token` passato in query string nel link "Vai al preventivo".
## Il problema che questo documento previene
### Come vengono serviti
I tre servizi girano su porte/domini diversi. Storicamente questo ha causato due classi di bug:
- I file statici (`/configuratore/assets/…`, `/preventivo/assets/…`) li serve direttamente il web server
(o `php artisan serve`), come qualsiasi file in `public/`.
- L'`index.html` di ciascun frontend è servito dalle route `configuratore` e `preventivo` in
[`backoffice/routes/web.php`](../backoffice/routes/web.php) (`Cache-Control: no-cache`, così una nuova
build è visibile subito; gli asset hanno nomi con hash). Se la build manca rispondono 404.
- Il configuratore usa path runtime relativi (`./assets/…`), quindi l'URL deve finire con `/`: Apache/nginx
reindirizzano `/configuratore` → `/configuratore/`, e uno script inline in `src/index.html` aggiunge lo
slash anche quando il server non lo fa (es. `php artisan serve`).
1. **Porte di sviluppo che collidono silenziosamente** — Vite, se una porta è occupata, ne sceglie
un'altra automaticamente. Se due progetti hanno lo stesso default (era il caso: sia il configuratore
che l'app cliente avevano `port: 5174`), il secondo processo avviato scivola su un'altra porta senza
errori — e i link generati puntano alla porta sbagliata.
2. **URL di produzione indovinati o hardcoded** — se l'indirizzo di un servizio è scritto a mano nel
codice dell'altro, ogni cambio di dominio/porta richiede una modifica e un rebuild manuale, facile da
dimenticare.
### URL dell'API e dell'app cliente
Soluzione adottata: **porte fisse in sviluppo** (`strictPort: true`, fallisce rumorosamente invece di
scivolare) + **scoperta dinamica degli URL** dove possibile, invece di hardcoding.
- **Configuratore → API**: di default `${location.origin}/api` ([`src/js/api_base.js`](../src/js/api_base.js)).
Override possibili: `VITE_PREVENTIVI_API_BASE` a build time (`.env*` nella root del repo) o
`window.PREVENTIVI_API_BASE` a runtime — servono solo se l'API sta su un altro dominio.
- **App cliente → API**: di default `${location.origin}/api` ([`backoffice/cliente/src/api.js`](../backoffice/cliente/src/api.js)),
override con `VITE_API_BASE`.
- **Configuratore → app cliente**: il link "Vai al preventivo" usa `frontend_cliente_url` restituito da
`GET /api/config` ([`backoffice/config/preventivi.php`](../backoffice/config/preventivi.php)), che di default
vale `APP_URL/preventivo`. Fallback se l'API non risponde: `${location.origin}/preventivo`.
## Porte di sviluppo (fisse)
## Sviluppo
| Servizio | Porta | Comando | Config |
|---|---|---|---|
| Configuratore | `5173` | `pnpm dev` (root) | [`vite.config.js`](../vite.config.js) — `server.port` + `strictPort: true` |
| App cliente | `5199` | `pnpm dev` (in `backoffice/cliente/`) | [`backoffice/cliente/vite.config.js`](../backoffice/cliente/vite.config.js) |
| Backend Laravel | `8000` | `php artisan serve --port=8000` (in `backoffice/`) | nessuna config fissa, va specificata al comando |
`./dev.sh` dalla root avvia `php artisan serve --port=8000` e i due `vite build --watch`: ogni modifica ai
sorgenti ricompila il frontend in `backoffice/public/…`; basta ricaricare la pagina (non c'è HMR).
Dettagli in [AVVIO_LOCALE.md](AVVIO_LOCALE.md).
Con `strictPort: true`, se una porta è già occupata **l'avvio fallisce con un errore esplicito** invece di
spostarsi su un'altra porta a caso. Se capita, il fix è liberare la porta (o capire quale altro processo
la sta usando) — non serve più inseguire link rotti.
## Come i due frontend si trovano l'un l'altro
### App cliente → Backend
L'app cliente conosce l'indirizzo dell'API tramite `VITE_API_BASE` in
[`backoffice/cliente/.env`](../backoffice/cliente/.env) (default `http://localhost:8000/api`). È un valore
di build-time (Vite), va impostato per ambiente.
### Configuratore → Backend
Il configuratore conosce l'indirizzo dell'API tramite `VITE_PREVENTIVI_API_BASE`, letto a build-time da
`.env` / `.env.production` nella **root del repo** (vedi sezione successiva). È l'unico URL che deve essere
"noto a priori": da lì in poi il configuratore può fare domande al backend.
### Configuratore → App cliente (il pezzo dinamico)
Il configuratore **non conosce a priori** dove gira l'app cliente. All'avvio chiama:
```
GET {VITE_PREVENTIVI_API_BASE}/api/config
→ { "frontend_cliente_url": "http://localhost:5199" }
```
Il valore restituito viene letto da Laravel dalla variabile `APP_FRONTEND_CLIENTE_URL` nel suo `.env`
([`backoffice/config/preventivi.php`](../backoffice/config/preventivi.php)). Il link "Vai al preventivo"
viene costruito con questo valore, non con un default fisso nel bundle del configuratore.
**Implicazione pratica**: se l'app cliente cambia dominio/porta, basta aggiornare **una sola variabile**
lato Laravel (`APP_FRONTEND_CLIENTE_URL`) — il configuratore già in produzione la recepisce alla prossima
richiesta, senza rebuild.
Logica in [`src/js/starter.js`](../src/js/starter.js) (`configReady`, `mostraLinkPreventivo`,
`ripristinaLinkPreventivo`). Se il backend non è raggiungibile, resta un fallback locale
(`window.APP_CLIENTE_URL` se impostato, altrimenti `http://localhost:5199`) — solo per non rompere lo
sviluppo offline, non pensato per la produzione.
## Variabili d'ambiente per componente
### Configuratore (root del repo)
Attenzione: `vite.config.js` ha `root: 'src'` ma `envDir` è impostato esplicitamente sulla root del repo
(dove stanno anche `build.sh`/`deploy.sh`) — i file `.env*` vanno quindi creati **nella root del repo**, non
dentro `src/`.
| File | Tracciato in git? | Contenuto |
|---|---|---|
| `.env` | Sì | `VITE_PREVENTIVI_API_BASE=http://localhost:8000/api` — default di sviluppo |
| `.env.production` | **No** (in `.gitignore`) | `VITE_PREVENTIVI_API_BASE=<url reale dell'API in produzione>` — va creato a mano prima del deploy |
| `.env.production.example` | Sì | Traccia/promemoria del formato atteso, da copiare in `.env.production` |
`pnpm build` (production mode di Vite) usa `.env.production` se presente. **`build.sh` blocca la build se
`.env.production` manca**, per evitare di deployare per sbaglio con `localhost` incorporato nel bundle.
Override runtime senza rebuild (usato raramente, es. hotfix): impostare `window.PREVENTIVI_API_BASE` /
`window.APP_CLIENTE_URL` in uno script inline prima del bundle in `index.html` — ha priorità sul valore di
build.
## Variabili d'ambiente
### Backend Laravel (`backoffice/.env`)
| Variabile | Descrizione | Dev | Produzione |
|---|---|---|---|
| `APP_URL` | URL pubblico del backend stesso (usato per link nelle email e asset Filament) | `http://localhost:8000` | URL reale del backend |
| `APP_FRONTEND_CLIENTE_URL` | URL dell'app cliente — letto da `/api/config` | `http://localhost:5199` | URL reale dell'app cliente |
| `ADMIN_NOTIFY_EMAIL` | Email che riceve la notifica di nuovo preventivo | — | email reale dell'admin |
| `CORS_ALLOWED_ORIGINS` | Origini autorizzate a chiamare l'API | `*` (di default, comodo in dev) | **da restringere** alle origini reali di configuratore + app cliente, separate da virgola |
| `DB_*` | MySQL: `127.0.0.1` / `root` / nessuna password / `kreios_preventivi` in locale | — | credenziali del DB di produzione |
| `MAIL_*` | `MAIL_MAILER=log` in dev (le email finiscono in `storage/logs/laravel.log`) | — | SMTP reale |
| Variabile | Descrizione | Default |
|---|---|---|
| `APP_URL` | URL pubblico del backend: base per link nelle email, `/preventivo` e `/configuratore/` | — |
| `APP_FRONTEND_CLIENTE_URL` | Solo se l'app cliente **non** è servita dal backend | `APP_URL/preventivo` |
| `APP_CONFIGURATORE_URL` | Link "Configuratore" nel menu admin, solo se servito altrove | `APP_URL/configuratore/` |
| `ADMIN_NOTIFY_EMAIL` | Email che riceve la notifica di nuovo preventivo | — |
| `CORS_ALLOWED_ORIGINS` | Origini autorizzate all'API da domini **esterni** (i frontend serviti dal backend non ne hanno bisogno) | `*` |
| `DB_*`, `MAIL_*` | Database e posta | — |
### App cliente (`backoffice/cliente/.env`)
### Frontend
| Variabile | Descrizione | Dev | Produzione |
|---|---|---|---|
| `VITE_API_BASE` | URL base dell'API Laravel | `http://localhost:8000/api` | URL reale dell'API |
Nessuna variabile necessaria. `VITE_PREVENTIVI_API_BASE` (root) e `VITE_API_BASE` (`backoffice/cliente`)
restano disponibili solo per puntare a un'API su un dominio diverso.
## Checklist di deploy in produzione
1. **Backend Laravel** (`backoffice/`)
- `.env` di produzione: `APP_URL`, `APP_FRONTEND_CLIENTE_URL`, `DB_*`, `MAIL_*`, `ADMIN_NOTIFY_EMAIL`.
- Restringere `CORS_ALLOWED_ORIGINS` alle origini reali (non lasciare `*`).
- `php artisan migrate --force`, `php artisan storage:link`, `php artisan config:cache`.
2. **App cliente** (`backoffice/cliente/`)
- `cliente/.env` (o `.env.production`) con `VITE_API_BASE` reale.
- `pnpm build`, deploy dei file statici generati.
3. **Configuratore** (root del repo)
- `cp .env.production.example .env.production` e impostare `VITE_PREVENTIVI_API_BASE` reale.
- `./build.sh` (fallisce se `.env.production` manca) → `./deploy.sh`.
- **Non serve** impostare l'URL dell'app cliente qui: viene letto da `/api/config` a runtime.
4. Verifica end-to-end: configurare un prodotto → "Aggiungi al preventivo" → il link "Vai al preventivo"
deve puntare al dominio reale dell'app cliente → completare il checkout → verificare che il preventivo
compaia nel backoffice Filament e che le email (cliente + admin) siano state inviate.
1. `./build.sh` dalla root: compila configuratore e app cliente in `backoffice/public/configuratore` e
`backoffice/public/preventivo` (cartelle ignorate da git: vanno generate in fase di deploy o caricate
insieme al backend).
2. Backend: `.env` di produzione (`APP_URL`, `DB_*`, `MAIL_*`, `ADMIN_NOTIFY_EMAIL`), poi
`php artisan migrate --force`, `php artisan storage:link`, `php artisan config:cache`.
3. Nel sito `kreiosinfissi.it` l'iframe punta a `https://<backend>/configuratore/?sistema=…&type=…`.
4. Restringere `CORS_ALLOWED_ORIGINS` (o lasciarlo vuoto) se nessun dominio esterno usa l'API.
5. Verifica end-to-end: configurare un prodotto → "Aggiungi al preventivo" → "Vai al preventivo" apre
`/preventivo/` sullo stesso dominio → completare il checkout → il preventivo compare in Filament e le
email (cliente + admin) sono inviate.
`deploy.sh` (upload di `kreios.zip` su un host statico separato) appartiene al vecchio schema a server
separati e non serve più.
## Riferimenti file
- [`src/js/starter.js`](../src/js/starter.js) — integrazione configuratore↔backend, scoperta dinamica dell'URL app cliente.
- [`vite.config.js`](../vite.config.js) — porta fissa, `envDir`.
- [`backoffice/routes/api.php`](../backoffice/routes/api.php) — endpoint `/api/config` e `/api/carrello/*`.
- [`backoffice/config/preventivi.php`](../backoffice/config/preventivi.php) — sorgente di `frontend_cliente_url`.
- [`backoffice/config/cors.php`](../backoffice/config/cors.php) — origini autorizzate.
- [`build.sh`](../build.sh) — guardia su `.env.production`.
- [`backoffice/README.md`](../backoffice/README.md) — setup locale, modello dati, API, branding.
- [`backoffice/routes/web.php`](../backoffice/routes/web.php) — route `/configuratore/` e `/preventivo/`.
- [`vite.config.js`](../vite.config.js), [`backoffice/cliente/vite.config.js`](../backoffice/cliente/vite.config.js) — `base` e `outDir` dentro `backoffice/public`.
- [`src/js/api_base.js`](../src/js/api_base.js), [`backoffice/cliente/src/api.js`](../backoffice/cliente/src/api.js) — base URL dell'API.
- [`src/js/starter.js`](../src/js/starter.js) — integrazione configuratore↔backend, link all'app cliente.
- [`backoffice/config/preventivi.php`](../backoffice/config/preventivi.php) — `frontend_cliente_url`, `configuratore_url`.
- [`build.sh`](../build.sh), [`dev.sh`](../dev.sh) — build e ambiente di sviluppo.