kreios/docs/PREVENTIVI_BACKOFFICE.md

Backoffice Preventivi — Architettura, ambienti e deploy

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. Per il contratto dei parametri URL del configuratore vedi URL_PARAMS.md.

Architettura: un solo server

                         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                                              │
└──────────────────────────────────────────────────────────────────────────────────┘

Componente	Sorgenti	Build in	URL
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

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".

Come vengono serviti

• 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 (Cache-Control: no-cache, così una nuova build è visibile subito; gli asset hanno nomi con hash). Se la build manca rispondono 404.
• La home / reindirizza a /configuratore/, conservando eventuali parametri (/?sistema=pvc → /configuratore/?sistema=pvc). Senza parametri il configuratore apre il primo sistema e modello attivi.
• 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).

URL dell'API e dell'app cliente

• Configuratore → API: di default ${location.origin}/api (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), 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), che di default vale APP_URL/preventivo. Fallback se l'API non risponde: ${location.origin}/preventivo.

Sviluppo

./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.

Variabili d'ambiente

Backend Laravel (backoffice/.env)

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)	*
NODE_BINARY	Node usato per comprimere con Draco i modelli 3D caricati (es. /opt/plesk/node/22/bin/node): PHP-FPM di solito non ha Node nel PATH	node
MODELLI_3D_MAX_MB	Dimensione massima del .glb caricabile dal backoffice (anche il limite di PHP upload_max_filesize/post_max_size deve permetterla)	200
DB_*, MAIL_*	Database e posta	—

Frontend

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.

Deploy in produzione (Plesk + Git)

Il deploy avviene con l'estensione Git di Plesk, che scarica l'intero repository. Le build dei frontend non sono in git: le genera ./build.sh sul server dopo ogni pull.

Configurazione una tantum in Plesk

1. Git: repository collegato al dominio, cartella di deploy es. kreios/.

2. Hosting: Document root = kreios/backoffice/public, PHP 8.3+.

3. Node.js: estensione Node.js di Plesk (versione 22) e accesso SSH dell'utente della subscription con shell /bin/bash (non chroot, altrimenti /opt/plesk/node non è visibile). pnpm non va installato: build.sh usa npx pnpm@10.34.7, la versione dei lockfile (lockfileVersion: '9.0'), qualunque pnpm sia presente sulla macchina.

4. .env creato a mano in kreios/backoffice/.env (APP_ENV=production, APP_DEBUG=false, APP_URL, DB_*, MAIL_*, ADMIN_NOTIFY_EMAIL), poi una volta sola: php artisan key:generate, php artisan storage:link, php artisan db:seed --force (admin, catalogo e immagini del configuratore).

5. Azioni di deploy aggiuntive (Git → impostazioni del repository). Esempio, da adattare ai percorsi di PHP/Node del server:

   export PATH=/opt/plesk/node/22/bin:$PATH
   PHP=/opt/plesk/php/8.3/bin/php
   (cd backoffice && composer install --no-dev --optimize-autoloader --no-interaction)
   # svuota tutte le cache di Laravel (config, route, view, eventi, cache applicativa, compilati)
   (cd backoffice && $PHP artisan optimize:clear)
   # esegue solo le migrazioni non ancora applicate (--force: richiesto in produzione)
   (cd backoffice && $PHP artisan migrate --force)
   (cd backoffice && $PHP artisan optimize && $PHP artisan queue:restart)
   ./build.sh
   

build.sh installa le dipendenze con pnpm install --frozen-lockfile: se package.json cambia, va committato anche il pnpm-lock.yaml aggiornato (generato con pnpm 10), altrimenti il deploy fallisce. Durante la build le cartelle public/configuratore e public/preventivo vengono svuotate e riscritte: per qualche secondo le due pagine non sono disponibili.

Modelli 3D

I .glb si caricano dal backoffice (Modelli → scheda del modello → Configurazione 3D). Al salvataggio il file viene compresso con Draco: l'originale resta archiviato in storage/app/private/modelli-3d/originali (non pubblico), il configuratore scarica solo la copia compressa. Un modello senza 3D non è attivabile e non compare nel configuratore.

Una tantum, dopo il deploy che introduce questa gestione, importare i modelli che prima stavano nel frontend:

(cd backoffice && $PHP artisan modelli3d:importa)

Il comando salta i modelli che hanno già un 3D (si può rilanciare). modelli3d:ricomprimi rigenera le copie compresse dagli originali (es. dopo una modifica di scripts/comprimi-glb.mjs).

Dopo ogni deploy

• Nel sito kreiosinfissi.it l'iframe punta a https://<backend>/configuratore/?sistema=…&type=….
• Restringere CORS_ALLOWED_ORIGINS (o lasciarlo vuoto) se nessun dominio esterno usa l'API.
• 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.

Riferimenti file

• backoffice/routes/web.php — route /configuratore/ e /preventivo/.
• vite.config.js, backoffice/cliente/vite.config.js — base e outDir dentro backoffice/public.
• src/js/api_base.js, backoffice/cliente/src/api.js — base URL dell'API.
• src/js/starter.js — integrazione configuratore↔backend, link all'app cliente.
• backoffice/config/preventivi.php — frontend_cliente_url, configuratore_url.
• build.sh, dev.sh — build dei frontend (anche su Plesk) e ambiente di sviluppo.