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

Refactor documentation: Update README.md with Laravel branding and restructure content; add new DOCUMENTAZIONE.md for comprehensive project details.

Browse Source
This commit is contained in:
Carmine Savino
2026-01-19 08:24:22 +01:00
parent 9b3d4b61fc
commit ec8955f9b7
5 changed files with 819 additions and 683 deletions
Download Patch File Download Diff File Expand all files Collapse all files

720
readme.md
View File

@@ -1,701 +1,59 @@
# Documentazione Progetto HTT QRCode
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
## 📋 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)
<p align="center">
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
</p>
---
## About Laravel
## 📖 Panoramica del Progetto
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
**HTT QRCode** è un'applicazione web Laravel per la gestione di articoli industriali con generazione e scansione di codici QR. L'applicazione permette di:
- [Simple, fast routing engine](https://laravel.com/docs/routing).
- [Powerful dependency injection container](https://laravel.com/docs/container).
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
- [Robust background job processing](https://laravel.com/docs/queues).
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
- ✅ 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
Laravel is accessible, powerful, and provides tools required for large, robust applications.
### Stack Tecnologico
## Learning Laravel
- **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
Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application.
---
If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
## 🏗️ Struttura del Progetto
## Laravel Sponsors
```
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
```
We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com).
---
### Premium Partners
## 🚀 Bootstrap e Installazione
- **[Vehikl](https://vehikl.com)**
- **[Tighten Co.](https://tighten.co)**
- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)**
- **[64 Robots](https://64robots.com)**
- **[Curotec](https://www.curotec.com/services/technologies/laravel)**
- **[DevSquad](https://devsquad.com/hire-laravel-developers)**
- **[Redberry](https://redberry.international/laravel-development)**
- **[Active Logic](https://activelogic.com)**
### Prerequisiti
## Contributing
Assicurati di avere installato:
Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
- **PHP 8.2+** con estensioni: `pdo`, `mbstring`, `xml`, `gd`, `zip`
- **Composer** (https://getcomposer.org/)
- **Node.js 18+** e **npm** (https://nodejs.org/)
- **Git**
## Code of Conduct
### Installazione Passo-Passo
In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
#### 1. Clona il Repository
## Security Vulnerabilities
```bash
cd /path/to/your/projects
git clone <repository-url> htt-qrcode
cd htt-qrcode
```
If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
#### 2. Installa le Dipendenze PHP
## License
```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! 🚀**
The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).