# Documentazione Progetto HTT QRCode

## 📋 Indice
1. [Panoramica del Progetto](#panoramica-del-progetto)
2. [Struttura del Progetto](#struttura-del-progetto)
3. [Bootstrap e Installazione](#bootstrap-e-installazione)
4. [Architettura dell'Applicazione](#architettura-dellapplicazione)
5. [Modifica di Elementi della Pagina](#modifica-di-elementi-della-pagina)
6. [Funzionalità Principali](#funzionalità-principali)
7. [Database e Modelli](#database-e-modelli)
8. [Sviluppo e Debug](#sviluppo-e-debug)

---

## 📖 Panoramica del Progetto

**HTT QRCode** è un'applicazione web Laravel per la gestione di articoli industriali con generazione e scansione di codici QR. L'applicazione permette di:

- ✅ Gestire un catalogo di articoli con parametri tecnici
- ✅ Generare QR Code univoci per ogni articolo
- ✅ Stampare etichette con QR Code in formato PDF
- ✅ Scansionare QR Code per visualizzare informazioni pubbliche
- ✅ Importare articoli da file Excel
- ✅ Autenticazione utenti con Laravel Breeze

### Stack Tecnologico

- **Backend**: Laravel 12 (PHP 8.2+)
- **Frontend**: Blade Templates + TailwindCSS 3 + Alpine.js
- **Database**: SQLite (default) / MySQL
- **QR Code**: SimpleSoftwareIO/simple-qrcode
- **PDF**: Barryvdh/laravel-dompdf
- **Excel**: PHPOffice/PhpSpreadsheet
- **Build Tool**: Vite

---

## 🏗️ Struttura del Progetto

```
htt-qrcode/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Admin/
│   │   │   │   └── ArticoloController.php    # CRUD articoli + QR Code
│   │   │   ├── ProfileController.php         # Gestione profilo utente
│   │   │   └── PublicArticoloController.php  # Scanner pubblico
│   │   └── Requests/                         # Form Request validation
│   ├── Models/
│   │   ├── Articolo.php                      # Model principale
│   │   └── User.php                          # Model utente
│   └── Providers/
│       └── AppServiceProvider.php
│
├── database/
│   ├── migrations/
│   │   ├── 0001_01_01_000000_create_users_table.php
│   │   └── 2026_01_17_134622_create_articolos_table.php
│   └── seeders/
│       ├── AdminUserSeeder.php               # Crea utente admin
│       ├── ArticoloSeeder.php                # Import Excel + dati fake
│       └── DatabaseSeeder.php
│
├── resources/
│   ├── views/
│   │   ├── admin/
│   │   │   └── articoli/
│   │   │       ├── index.blade.php           # Lista articoli
│   │   │       ├── create.blade.php          # Form creazione
│   │   │       ├── edit.blade.php            # Form modifica
│   │   │       ├── show.blade.php            # Dettaglio articolo
│   │   │       └── pdf-qrcodes.blade.php     # Template PDF QR
│   │   ├── public/
│   │   │   ├── scanner.blade.php             # Pagina scanner
│   │   │   └── articolo.blade.php            # Vista pubblica articolo
│   │   ├── layouts/
│   │   │   ├── app.blade.php                 # Layout principale
│   │   │   └── guest.blade.php               # Layout pubblico
│   │   └── components/                       # Componenti Blade riutilizzabili
│   ├── css/
│   │   └── app.css                           # TailwindCSS
│   └── js/
│       ├── app.js                            # Entry point JavaScript
│       └── bootstrap.js                      # Axios config
│
├── routes/
│   ├── web.php                               # Rotte principali
│   ├── auth.php                              # Rotte autenticazione (Breeze)
│   └── console.php
│
├── public/
│   ├── index.php                             # Entry point Laravel
│   └── build/                                # Assets compilati da Vite
│
├── config/                                   # File di configurazione
├── storage/                                  # File storage e cache
├── tests/                                    # Test automatici
├── vendor/                                   # Dipendenze Composer
│
├── .env.example                              # Template variabili ambiente
├── composer.json                             # Dipendenze PHP
├── package.json                              # Dipendenze JavaScript
├── artisan                                   # CLI Laravel
├── vite.config.js                            # Configurazione Vite
└── tailwind.config.js                        # Configurazione TailwindCSS
```

---

## 🚀 Bootstrap e Installazione

### Prerequisiti

Assicurati di avere installato:

- **PHP 8.2+** con estensioni: `pdo`, `mbstring`, `xml`, `gd`, `zip`
- **Composer** (https://getcomposer.org/)
- **Node.js 18+** e **npm** (https://nodejs.org/)
- **Git**

### Installazione Passo-Passo

#### 1. Clona il Repository

```bash
cd /path/to/your/projects
git clone <repository-url> htt-qrcode
cd htt-qrcode
```

#### 2. Installa le Dipendenze PHP

```bash
composer install
```

Questo installerà tutte le dipendenze definite in `composer.json`:
- Laravel Framework
- Laravel Breeze (autenticazione)
- SimpleSoftwareIO QR Code
- Barryvdh DomPDF
- PHPOffice PhpSpreadsheet

#### 3. Configura l'Ambiente

```bash
# Copia il file .env.example in .env
cp .env.example .env

# Genera la chiave dell'applicazione
php artisan key:generate
```

#### 4. Configura il Database

Apri il file `.env` e configura il database. Per SQLite (default):

```env
DB_CONNECTION=sqlite
```

Crea il file database:

```bash
touch database/database.sqlite
```

Per MySQL:

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=htt_qrcode
DB_USERNAME=root
DB_PASSWORD=your_password
```

#### 5. Esegui le Migrazioni

```bash
php artisan migrate
```

Questo creerà le tabelle:
- `users` - Utenti del sistema
- `articoli` - Articoli con QR Code
- `cache`, `jobs`, `sessions` - Tabelle di sistema

#### 6. Popola il Database (Opzionale)

```bash
# Crea un utente admin e articoli di esempio
php artisan db:seed

# Solo utente admin (email: admin@example.com, password: password)
php artisan db:seed --class=AdminUserSeeder

# Solo articoli di esempio
php artisan db:seed --class=ArticoloSeeder
```

#### 7. Installa le Dipendenze Frontend

```bash
npm install
```

Questo installerà:
- Vite
- TailwindCSS
- Alpine.js
- Axios

#### 8. Compila gli Asset

```bash
# Per sviluppo (con hot reload)
npm run dev

# Per produzione
npm run build
```

#### 9. Avvia il Server di Sviluppo

In terminali separati:

```bash
# Terminal 1: Server PHP
php artisan serve

# Terminal 2: Vite (hot reload)
npm run dev
```

**OPPURE** usa il comando composer personalizzato che avvia tutto insieme:

```bash
composer run dev
```

Questo comando avvia automaticamente:
- Server PHP (porta 8000)
- Queue listener
- Log tail (pail)
- Vite dev server

#### 10. Accedi all'Applicazione

Apri il browser e vai a:

- **Homepage**: http://localhost:8000
- **Login**: http://localhost:8000/login
- **Dashboard**: http://localhost:8000/dashboard (richiede autenticazione)

**Credenziali default** (se hai eseguito il seeder):
- Email: `admin@example.com`
- Password: `password`

---

## 🏛️ Architettura dell'Applicazione

### Pattern MVC (Model-View-Controller)

Laravel segue il pattern MVC:

#### **Model** (app/Models/)
```php
// Articolo.php - Rappresenta un articolo nel database
class Articolo extends Model
{
    protected $fillable = ['codice_articolo', 'ciclo', 'descrizione', ...];
    
    // Generazione automatica QR Code alla creazione
    protected static function boot() { ... }
}
```

#### **Controller** (app/Http/Controllers/)
```php
// ArticoloController.php - Gestisce le richieste CRUD
class ArticoloController extends Controller
{
    public function index()    // GET /admin/articoli
    public function create()   // GET /admin/articoli/create
    public function store()    // POST /admin/articoli
    public function show()     // GET /admin/articoli/{id}
    public function edit()     // GET /admin/articoli/{id}/edit
    public function update()   // PUT /admin/articoli/{id}
    public function destroy()  // DELETE /admin/articoli/{id}
}
```

#### **View** (resources/views/)
```blade
<!-- index.blade.php - Template Blade per visualizzare la lista -->
<x-app-layout>
    @foreach ($articoli as $articolo)
        <tr>
            <td>{{ $articolo->codice_articolo }}</td>
            ...
        </tr>
    @endforeach
</x-app-layout>
```

### Flusso delle Richieste

1. **Richiesta HTTP** → `routes/web.php`
2. **Middleware** (autenticazione, CSRF) → filtra la richiesta
3. **Controller** → elabora la logica
4. **Model** → interagisce con il database
5. **View** → renderizza l'HTML
6. **Risposta HTTP** → ritorna al browser

### Rotte Principali

```php
// routes/web.php

// Rotte pubbliche
Route::get('/', ...);                              // Homepage
Route::get('/scanner', ...);                       // Scanner QR pubblico
Route::get('/articolo/{qr_code}', ...);           // Vista articolo pubblico

// Rotte autenticate
Route::middleware('auth')->group(function () {
    Route::resource('admin/articoli', ArticoloController::class);
    Route::get('admin/articoli/{id}/qrcode', ...);           // Genera QR
    Route::get('admin/articoli/{id}/qrcode/download', ...);  // Download QR
    Route::get('admin/articoli-print-qrcodes', ...);         // Stampa PDF
    Route::post('admin/articoli-import', ...);               // Import Excel
});
```

---

## 🎨 Modifica di Elementi della Pagina

### Esempio Pratico: Modificare il Pulsante "Nuovo Articolo"

Seguiamo un esempio concreto per capire come modificare la UI dell'applicazione.

#### Obiettivo
Cambiare il colore e il testo del pulsante "Nuovo Articolo" nella pagina index degli articoli.

#### Passo 1: Individua il File

Il file è: `resources/views/admin/articoli/index.blade.php`

Puoi trovarlo:
- Guardando la route: `Route::resource('admin/articoli', ...)` → metodo `index()`
- Il controller ritorna: `view('admin.articoli.index')` → `resources/views/admin/articoli/index.blade.php`

#### Passo 2: Trova l'Elemento

Apri `resources/views/admin/articoli/index.blade.php` e cerca il pulsante (linea ~16):

```blade
<a href="{{ route('admin.articoli.create') }}" 
   class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
    + Nuovo Articolo
</a>
```

#### Passo 3: Modifica l'Elemento

**Prima** (blu):
```blade
class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
+ Nuovo Articolo
```

**Dopo** (verde con icona):
```blade
class="bg-green-600 hover:bg-green-800 text-white font-bold py-2 px-4 rounded shadow-lg"
➕ Aggiungi Articolo
```

#### Passo 4: Salva e Verifica

1. Salva il file
2. Se hai `npm run dev` attivo, Vite rileva automaticamente il cambiamento
3. Ricarica la pagina nel browser
4. Il pulsante sarà ora verde con il nuovo testo!

### Anatomia delle Classi TailwindCSS

```
bg-green-600        → Background verde
hover:bg-green-800  → Background verde scuro al passaggio del mouse
text-white          → Testo bianco
font-bold           → Testo in grassetto
py-2                → Padding verticale (sopra/sotto)
px-4                → Padding orizzontale (sinistra/destra)
rounded             → Bordi arrotondati
shadow-lg           → Ombra grande
```

### Altri Esempi Comuni

#### 1. Modificare il Titolo della Pagina

**File**: `resources/views/admin/articoli/index.blade.php` (linea ~4)

```blade
<!-- Prima -->
<h2 class="font-semibold text-xl text-gray-800 leading-tight">
    {{ __('Gestione Articoli') }}
</h2>

<!-- Dopo -->
<h2 class="font-bold text-2xl text-indigo-900 leading-tight">
    📦 Catalogo Articoli
</h2>
```

#### 2. Cambiare i Colori delle Righe della Tabella

**File**: `resources/views/admin/articoli/index.blade.php` (linea ~73)

```blade
<!-- Prima -->
<tr class="{{ $loop->even ? 'bg-gray-100' : 'bg-white' }} hover:bg-blue-50">

<!-- Dopo (alternanza bianco/azzurrino) -->
<tr class="{{ $loop->even ? 'bg-blue-50' : 'bg-white' }} hover:bg-blue-100">
```

#### 3. Modificare il Placeholder della Ricerca

**File**: `resources/views/admin/articoli/index.blade.php` (linea ~35)

```blade
<!-- Prima -->
placeholder="Cerca per codice, descrizione o ciclo..."

<!-- Dopo -->
placeholder="🔍 Inserisci il codice articolo o una parola chiave..."
```

#### 4. Aggiungere un Messaggio di Benvenuto

**File**: `resources/views/admin/articoli/index.blade.php`

Aggiungi dopo il tag `<x-slot name="header">...</x-slot>`:

```blade
<div class="max-w-7xl mx-auto sm:px-6 lg:px-8 pt-6">
    <div class="bg-indigo-100 border-l-4 border-indigo-500 text-indigo-700 p-4 rounded">
        <p class="font-bold">👋 Benvenuto nel gestionale!</p>
        <p>Gestisci i tuoi articoli e genera QR Code in pochi click.</p>
    </div>
</div>
```

### Workflow di Modifica Completo

```
1. Identifica la rotta → routes/web.php
2. Trova il controller → app/Http/Controllers/
3. Individua la view → resources/views/
4. Modifica il template Blade
5. (Opzionale) Modifica il CSS → resources/css/app.css
6. (Opzionale) Aggiungi JS → resources/js/app.js
7. Salva e verifica nel browser
```

---

## ⚙️ Funzionalità Principali

### 1. Gestione Articoli (CRUD)

- **Crea**: Form con validazione per tutti i campi
- **Leggi**: Lista paginata con ricerca
- **Aggiorna**: Modifica dati esistenti
- **Elimina**: Cancellazione con conferma

### 2. QR Code

**Generazione Automatica**:
```php
// Model Articolo.php - boot() method
$articolo->qr_code = $articolo->id . '-' . time();
// Esempio: "42-1737235200"
```

**Download Singolo**:
- PNG 300x300px, error correction H
- Formato nome: `qr-{codice_articolo}.png`

**Stampa Multipla**:
- Selezione multipla con checkbox
- PDF A4 con griglia di QR Code
- Template: `resources/views/admin/articoli/pdf-qrcodes.blade.php`

### 3. Import Excel

**Formato Supportato**: XLSX, XLS

**Colonne Richieste**:
```
UBICAZIONE
├── Codice Articolo (obbligatorio)
├── Ciclo
├── Diametro
├── Descrizione
├── Posizione
└── Quantita

PARAMETRI TECNOLOGICI
├── Tipo Lavorazione
├── Materiale da lavorare
├── Maximum Thickness
├── Speed RPM
├── Feed
├── Max Thrust A
├── Min Torque A
└── Quantita Fori
```

**Modalità**:
- **Merge** (default): aggiorna esistenti, crea nuovi
- **Clean Import**: elimina tutto e re-importa

### 4. Scanner Pubblico

- Accessibile senza autenticazione
- Route: `/scanner`
- Utilizza API HTML5 per fotocamera
- Reindirizza a `/articolo/{qr_code}` dopo scansione

---

## 💾 Database e Modelli

### Tabella `articoli`

```sql
CREATE TABLE articoli (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    codice_articolo VARCHAR(255) UNIQUE NOT NULL,
    ciclo VARCHAR(255),
    diametro VARCHAR(255),
    descrizione TEXT,
    posizione VARCHAR(255),
    quantita INTEGER DEFAULT 0,
    tipo_lavorazione VARCHAR(255),
    materiale_lavorare VARCHAR(255),
    maximum_thickness VARCHAR(255),
    speed_rpm INTEGER,
    feed DECIMAL(8,2),
    max_thrust_a VARCHAR(255),
    min_torque_a VARCHAR(255),
    quantita_fori INTEGER,
    qr_code VARCHAR(255) UNIQUE,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

### Model Eloquent

```php
// Query Builder Examples

// Tutti gli articoli
Articolo::all();

// Paginati
Articolo::paginate(15);

// Con ricerca
Articolo::where('codice_articolo', 'like', "%{$search}%")
    ->orWhere('descrizione', 'like', "%{$search}%")
    ->get();

// Trova per QR Code
Articolo::where('qr_code', $qrCode)->firstOrFail();

// Crea nuovo
Articolo::create([
    'codice_articolo' => 'ART001',
    'descrizione' => 'Descrizione...',
    ...
]);

// Aggiorna
$articolo->update(['quantita' => 100]);

// Elimina
$articolo->delete();
```

---

## 🛠️ Sviluppo e Debug

### Comandi Artisan Utili

```bash
# Crea controller
php artisan make:controller NomeController

# Crea model con migration
php artisan make:model NomeModel -m

# Crea migration
php artisan make:migration create_nome_table

# Esegui migrazioni
php artisan migrate

# Rollback ultima migrazione
php artisan migrate:rollback

# Reset database
php artisan migrate:fresh --seed

# Crea seeder
php artisan make:seeder NomeSeeder

# Pulisci cache
php artisan cache:clear
php artisan config:clear
php artisan view:clear

# Lista rotte
php artisan route:list

# Avvia Tinker (REPL)
php artisan tinker
```

### Debug con Laravel Debugbar

Installa (opzionale):

```bash
composer require barryvdh/laravel-debugbar --dev
```

Mostra query SQL, variabili, performance, ecc.

### Logs

```bash
# Monitora i log in tempo reale
php artisan pail

# Oppure
tail -f storage/logs/laravel.log
```

### Testing

```bash
# Esegui tutti i test
php artisan test

# Test specifico
php artisan test --filter NomeTest
```

### Vite + HMR (Hot Module Replacement)

Durante lo sviluppo, Vite rileva automaticamente le modifiche a:
- `resources/css/app.css`
- `resources/js/app.js`
- `resources/views/**/*.blade.php`

E ricarica il browser automaticamente!

---

## 📚 Risorse Aggiuntive

- **Laravel Docs**: https://laravel.com/docs/12.x
- **Tailwind CSS**: https://tailwindcss.com/docs
- **Alpine.js**: https://alpinejs.dev/
- **Simple QR Code**: https://www.simplesoftwareio.com/docs/simple-qrcode
- **DomPDF**: https://github.com/barryvdh/laravel-dompdf

---

## 🤝 Supporto

Per problemi o domande:

1. Controlla i log: `storage/logs/laravel.log`
2. Verifica le variabili in `.env`
3. Consulta la documentazione Laravel
4. Usa `php artisan tinker` per testare query

---

**Buon sviluppo! 🚀**