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](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

```bash
cd backoffice
composer install
```

### Database

Creare il database (una volta sola):

```sql
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:

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

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

```ini
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

```bash
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

```bash
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)

```bash
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](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`

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

```bash
./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](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`.

```bash
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](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` |