carmine.savino/htt-locator

Fork 0

Files

Carmine Savino ae792f4996 first commit

2026-01-18 12:23:37 +01:00

18 KiB

Raw Blame History

Documentazione Progetto HTT QRCode

📋 Indice

Panoramica del Progetto
Struttura del Progetto
Bootstrap e Installazione
Architettura dell'Applicazione
Modifica di Elementi della Pagina
Funzionalità Principali
Database e Modelli
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

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

2. Installa le Dipendenze PHP

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

# 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):

DB_CONNECTION=sqlite

Crea il file database:

touch database/database.sqlite

Per MySQL:

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

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)

# 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

npm install

Questo installerà:

Vite
TailwindCSS
Alpine.js
Axios

8. Compila gli Asset

# Per sviluppo (con hot reload)
npm run dev

# Per produzione
npm run build

9. Avvia il Server di Sviluppo

In terminali separati:

# 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:

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/)

// 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/)

// 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/)

<!-- 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

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

Rotte Principali

// 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):

<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):

class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
+ Nuovo Articolo

Dopo (verde con icona):

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

Salva il file
Se hai npm run dev attivo, Vite rileva automaticamente il cambiamento
Ricarica la pagina nel browser
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)

<!-- 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)

<!-- 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)

<!-- 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>:

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

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

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

// 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

# 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):

composer require barryvdh/laravel-debugbar --dev

Mostra query SQL, variabili, performance, ecc.

Logs

# Monitora i log in tempo reale
php artisan pail

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

Testing

# 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:

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

Buon sviluppo! 🚀

18 KiB Raw Blame History Unescape Escape