kreios/docs/AVVIO_LOCALE.md

Avvio locale — Krèios

Guida per avviare l'ambiente completo di sviluppo: backoffice Laravel (API + pannello admin) che serve anche il configuratore 3D e l'app cliente per i preventivi.

Panoramica

Un solo server: Laravel su http://localhost:8000 serve API, pannello admin e i due frontend, che sono progetti Vite compilati dentro backoffice/public.

Componente	Sorgenti	Stack	URL dev
Configuratore 3D	. (root del repo)	Vite 6 + Three.js + jQuery	http://localhost:8000/configuratore/?sistema=pvc&type=finestra_2_ante
App cliente (preventivo)	backoffice/cliente/	Vue 3 + Vite	http://localhost:8000/preventivo/
Backoffice (API + admin)	backoffice/	Laravel 13 + Filament 3 + MySQL	http://localhost:8000/api, admin su http://localhost:8000/admin

Come si collegano: tutto è sulla stessa origine, quindi configuratore e app cliente chiamano /api/... senza configurazione né CORS. Architettura e variabili in PREVENTIVI_BACKOFFICE.md.

Requisiti

Strumento	Versione minima	Note
Node.js	20+	per compilare i frontend (Vite)
pnpm	8+	package manager della root e dell'app cliente (pnpm-lock.yaml è il lockfile di riferimento) — npm i -g pnpm o corepack enable
PHP	8.3+	richiesta da composer.json ("php": "^8.3")
Composer	2+	dipendenze Laravel
MySQL	8	host 127.0.0.1, user root, nessuna password
Python 3	3.10+	opzionale: solo per rigenerare i listini PVC

1) Backoffice Laravel (API + admin) — porta 8000

cd backoffice
composer install

Database

Creare il database (una volta sola):

CREATE DATABASE kreios_preventivi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

.env

Il backoffice ignora il suo .env in git: in un clone fresco va creato:

cp .env.example .env
php artisan key:generate

Poi impostare le variabili di sviluppo (in questo repo il .env è già configurato così):

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=kreios_preventivi
DB_USERNAME=root
DB_PASSWORD=

APP_URL=http://localhost:8000
ADMIN_NOTIFY_EMAIL=tua-email@example.com
MAIL_MAILER=log

Variabile	Descrizione
APP_URL	Base URL del backoffice (e quindi di /configuratore/ e /preventivo/)
ADMIN_NOTIFY_EMAIL	Email che riceve la notifica di nuovo preventivo
CONFIGURATOR_SESSION_DAYS	Durata (giorni) della sessione di login del configuratore
MAIL_MAILER	log in dev: le email finiscono in storage/logs/laravel.log (incluso il PDF allegato)

Migrations, seed e asset

php artisan migrate --seed   # crea le tabelle + l'utente admin
php artisan storage:link
npm install                  # asset Vite del pannello (nessun lockfile; .npmrc ha ignore-scripts=true)

Avvio

php artisan serve --port=8000

• API: http://localhost:8000/api
• Pannello admin: http://localhost:8000/admin
  • Email: admin@kreiosinfissi.it — Password: password (seed di default)
• Le email di conferma preventivo sono inviate in modo sincrono (Mail::send): in dev non serve avviare queue:listen.

Alternativa: composer dev avvia in parallelo server, queue, log (pail) e Vite.

2) Frontend (configuratore + app cliente)

pnpm install                              # root: configuratore
(cd backoffice/cliente && pnpm install)   # app cliente
./build.sh                                # compila entrambi in backoffice/public/{configuratore,preventivo}

Dopo la build, con il solo php artisan serve attivo:

• configuratore: http://localhost:8000/configuratore/?sistema=pvc&type=finestra_2_ante
  • sistema: pvc | alluminio | legno | acciaio
  • type: id modello valido per quel sistema (elenco in URL_PARAMS.md)
• app cliente: http://localhost:8000/preventivo/

In produzione il configuratore gira dentro un <iframe> su kreiosinfissi.it; in dev si apre direttamente in una tab.

Sviluppo quotidiano: ./dev.sh

./dev.sh

Avvia Laravel sulla porta 8000 e i due frontend in vite build --watch: a ogni modifica dei sorgenti la build in backoffice/public viene rigenerata, basta ricaricare la pagina (non c'è hot reload). Ctrl+C ferma tutto.

Verifica end-to-end

1. Apri http://localhost:8000/configuratore/?sistema=pvc&type=finestra_2_ante — il modello 3D si carica e il menu è attivo.
2. Configura dimensioni/finiture e clicca "Aggiungi al preventivo" → POST /api/carrello/aggiungi; il token del carrello viene salvato in localStorage.
3. Clicca "Vai al preventivo" → si apre http://localhost:8000/preventivo/?token=XXX con il riepilogo del carrello.
4. Compila i dati del cliente e conferma.
5. Controlla il risultato:
   • il preventivo compare in http://localhost:8000/admin con stato inviato;
   • le email (cliente con PDF allegato + notifica admin) sono in backoffice/storage/logs/laravel.log.

Build di produzione

./build.sh   # configuratore -> backoffice/public/configuratore, app cliente -> backoffice/public/preventivo

Le due cartelle sono ignorate da git e vanno distribuite insieme al backend. Nessun .env dei frontend è necessario: l'API è sulla stessa origine. Checklist completa in PREVENTIVI_BACKOFFICE.md.

Rigenerare i listini PVC (opzionale)

scripts/extract_listini_pvc.py parsa PVC_LISTINO.xls e rigenera i file src/assets/data/modelli/pvc/<modello>/listino.json.

python3 -m venv .venv && source .venv/bin/activate
pip install -r scripts/requirements.txt   # xlrd
python3 scripts/extract_listini_pvc.py    # eseguire dalla root del repo

Nota: ogni nuovo titolo presente nel foglio ma non ancora mappato va aggiunto alla costante KNOWN_FOLDERS dello script, altrimenti il modello non viene riconosciuto (vedi ORIGINE_LISTINI_PVC.md).

Troubleshooting

Sintomo	Causa probabile / soluzione
/configuratore/ o /preventivo/ rispondono 404 "Build … assente"	Eseguire ./build.sh (o avviare ./dev.sh e attendere la prima build)
Modifiche ai frontend non visibili	Con ./dev.sh attendere la fine della ricompilazione e ricaricare; senza, rieseguire ./build.sh
"Vai al preventivo" apre la URL sbagliata	Controllare APP_URL (ed eventuale APP_FRONTEND_CLIENTE_URL) nel .env del backoffice: il link viene da GET /api/config
SQLSTATE[HY000] [2002] Connection refused	MySQL non è in esecuzione, oppure credenziali/host errati nel .env del backoffice
SQLSTATE[HY000] [1049] Unknown database 'kreios_preventivi'	Creare il database (vedi sezione 1)
Login admin rifiutato	Eseguire php artisan migrate --seed e usare admin@kreiosinfissi.it / password
Il configuratore parte con errore a schermo	Manca o è errato uno dei parametri sistema/type nell'URL
Prezzi assenti o a zero	Listini non presenti: rigenerarli con lo script Python o verificare i JSON in src/assets/data/modelli/<sistema>/<modello>/listino.json
php artisan serve dice che la porta è occupata	Fermare l'altro server: lsof -i :8000