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.
• 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)	*
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.

Checklist di deploy in produzione

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

• 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 e ambiente di sviluppo.