kreios/docs/AVVIO_LOCALE.md

Avvio locale — Krèios

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

Panoramica

Componente	Cartella	Stack	Porta	URL dev
Configuratore 3D	. (root del repo)	Vite 6 + Three.js + jQuery	5173	http://localhost:5173
Backoffice (API + admin)	backoffice/	Laravel 13 + Filament 3 + MySQL	8000	http://localhost:8000/api, admin su http://localhost:8000/admin
App cliente preventivi	backoffice/cliente/	Vue 3 + Vite	5199	http://localhost:5199

Le tre porte sono fisse (strictPort: true nei vari vite.config.js / serve --port): se una porta è già occupata l'avvio fallisce con un errore esplicito invece di spostarsi silenziosamente su un'altra.

Come si collegano:

• Il configuratore chiama l'API Laravel per il carrello (POST /api/carrello/aggiungi, ecc.).
• L'URL dell'app cliente non è hardcoded nel configuratore: all'avvio chiama GET /api/config e usa il frontend_cliente_url restituito da Laravel (letto da APP_FRONTEND_CLIENTE_URL nel .env del backoffice).
• Il flusso completo è descritto in PREVENTIVI_BACKOFFICE.md.

Requisiti

Strumento	Versione minima	Note
Node.js	20+	per i tre front (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
APP_FRONTEND_CLIENTE_URL=http://localhost:5199
ADMIN_NOTIFY_EMAIL=tua-email@example.com
MAIL_MAILER=log

Variabile	Descrizione
APP_URL	Base URL del backoffice
APP_FRONTEND_CLIENTE_URL	URL dell'app cliente — restituito al configuratore da GET /api/config
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) App cliente (Vue) — porta 5199

cd backoffice/cliente
pnpm install
pnpm dev

.env già presente in repo con il default corretto per lo sviluppo: VITE_API_BASE=http://localhost:8000/api.

3) Configuratore 3D — porta 5173

pnpm install
pnpm dev

• Il server parte su 0.0.0.0:5173 (vedi vite.config.js).

• L'entry point richiede due parametri obbligatori nella query string:

  http://localhost:5173/?sistema=pvc&type=finestra_2_ante
  

  • sistema: pvc | alluminio | legno | acciaio
  • type: id modello valido per quel sistema (elenco completo in URL_PARAMS.md)

  Senza i due parametri l'app lancia un errore in fase di avvio.

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

Sequenza completa (tre terminali)

# Terminale 1 — backoffice Laravel (API + admin)
cd backoffice && php artisan serve --port=8000

# Terminale 2 — app cliente
cd backoffice/cliente && pnpm dev

# Terminale 3 — configuratore (dalla root del repo)
pnpm dev

Verifica end-to-end

1. Apri http://localhost:5173/?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:5199/?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 (configuratore)

# 1. Creare .env.production (non tracciato in git) con l'URL API reale
cp .env.production.example .env.production
#    -> VITE_PREVENTIVI_API_BASE=https://preventivi.kreiosinfissi.it/api

# 2. Build + zip (build.sh fallisce se .env.production manca)
./build.sh            # pnpm build -> dist/ -> rinominata in kreios/ + kreios.zip

pnpm preview serve localmente la build di produzione per un'anteprima.

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
Port 5173/5199 is already in use o errore di porta su 8000	Le porte sono fisse: individuare e fermare l'altro processo (lsof -i :5173)
"Aggiungi al preventivo" dà errore / richieste CORS rifiutate	Laravel non è in ascolto su 8000, oppure VITE_PREVENTIVI_API_BASE nel .env della root non punta a http://localhost:8000/api
"Vai al preventivo" apre la URL sbagliata	Controllare APP_FRONTEND_CLIENTE_URL nel .env del backoffice: il configuratore legge l'URL dell'app cliente 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