# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**HTT QRCode** is a Laravel 12 web application for managing industrial articles with QR code generation and scanning. Key capabilities: article catalog CRUD, unique QR code generation per article, PDF label printing, public QR scanner (no auth required), and Excel import.

**Stack**: Laravel 12 / PHP 8.2+ · Blade + TailwindCSS 3 + Alpine.js · SQLite (default) or MySQL · Vite · SimpleSoftwareIO/simple-qrcode · Barryvdh/laravel-dompdf · PHPOffice/PhpSpreadsheet

## Development Commands

```bash
# Start everything (PHP server + queue + logs + Vite HMR)
composer run dev

# Or separately:
php artisan serve        # http://localhost:8000
npm run dev              # Vite with hot reload

# Build for production
npm run build

# Run tests
composer run test
# or
php artisan test
php artisan test --filter NomeTest   # single test

# Database
php artisan migrate
php artisan migrate:fresh --seed     # reset + re-seed
php artisan db:seed --class=AdminUserSeeder   # admin@example.com / password

# Code style (Laravel Pint)
./vendor/bin/pint

# Clear caches
php artisan cache:clear && php artisan config:clear && php artisan view:clear

# View all routes
php artisan route:list

# Real-time logs
php artisan pail
```

## Architecture

### Route → Controller → View mapping

| Route | Controller | View |
|---|---|---|
| `GET /` | closure | `welcome.blade.php` |
| `GET /scanner` | `PublicArticoloController@scanner` | `public/scanner.blade.php` |
| `GET /articolo/{qr_code}` | `PublicArticoloController@show` | `public/articolo.blade.php` |
| `admin/articoli` (resource) | `Admin/ArticoloController` | `admin/articoli/*.blade.php` |

Admin routes are grouped under `middleware(['auth'])` with prefix `admin/` and name prefix `admin.`. The `/dashboard` route simply redirects to `admin.articoli.index`.

### Articolo Model

`qr_code` is auto-generated on `created` event using the format `{id}-{timestamp}`. The `codice_articolo` field is unique. The public scanner URL resolves articles via `qr_code`, not `id`.

### QR Code features in `ArticoloController`

- `qrCode()` — renders QR inline as SVG/PNG
- `downloadQrCode()` — streams PNG (300×300px, error correction H)
- `printQrCodes()` — generates multi-article PDF via dompdf using `pdf-qrcodes.blade.php`
- `import()` — Excel import via PhpSpreadsheet; supports "merge" (default) and "clean import" modes

### Layouts

- `layouts/app.blade.php` — authenticated area (uses `<x-app-layout>`)
- `layouts/guest.blade.php` — public/auth pages (uses `<x-guest-layout>`)
- Blade components live in `resources/views/components/` and `app/View/Components/`

## Database

Default is **SQLite** (`database/database.sqlite`). The `articoli` table has two unique constraints: `codice_articolo` and `qr_code`.

Excel import expects these column groups: `UBICAZIONE` (Codice Articolo, Ciclo, Diametro, Descrizione, Posizione, Quantita) and `PARAMETRI TECNOLOGICI` (Tipo Lavorazione, Materiale da lavorare, Maximum Thickness, Speed RPM, Feed, Max Thrust A, Min Torque A, Quantita Fori).