carmine.savino/htt-locator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Carmine Savino
2026-01-18 12:23:37 +01:00
commit ae792f4996
124 changed files with 19497 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

701
readme.md Normal file
View File

@@ -0,0 +1,701 @@
# 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! 🚀**