VigilanzaTurni/replit.md

# VigilanzaTurni - Sistema Gestione Turni per Istituti di Vigilanza

## Overview
Sistema professionale di gestione turni 24/7 per istituti di vigilanza con:
- Autenticazione multi-ruolo (Admin, Coordinatore, Guardia, Cliente)
- Gestione anagrafica guardie con skill matrix e certificazioni
- Pianificazione turni con calendario 24/7
- Gestione siti/commesse con tipologie servizio
- Dashboard operativa con KPI live
- Reportistica ore lavorate
- Sistema notifiche

## Project Architecture

### Stack Tecnologico
- **Frontend**: React + TypeScript + Tailwind CSS + Shadcn UI
- **Backend**: Express.js + TypeScript
- **Database**: PostgreSQL (Neon) con Drizzle ORM
- **Autenticazione**: Replit Auth (OIDC)
- **State Management**: TanStack Query v5
- **Routing**: Wouter

### Design System
- **Font Principale**: Inter (sans-serif)
- **Font Monospace**: JetBrains Mono (per matricole, ID)
- **Colori**:
  - Primary: Blue (210, 100%, 45-50%) - operativo, affidabile
  - Status Active: Green (140, 60%, 45%)
  - Status Late/Warning: Orange (25, 90%, 55%)
  - Status Emergency: Red (0, 70%, 55%)
  - Status Inactive: Gray (220, 15%, 50%)
- **Tema**: Dark mode di default con supporto light mode
- **Componenti**: Shadcn UI con design operativo

## Database Schema

### Core Tables

**users** (Replit Auth):
- id, email, firstName, lastName, profileImageUrl
- role: admin | coordinator | guard | client
- createdAt, updatedAt

**guards**:
- id, userId (FK), badgeNumber (unique), phoneNumber
- Skills: isArmed, hasFireSafety, hasFirstAid, hasDriverLicense
- languages: array

**certifications**:
- id, guardId (FK), type, name
- issueDate, expiryDate
- status: valid | expiring_soon | expired

**sites**:
- id, name, address, clientId (FK)
- shiftType: fixed_post | patrol | night_inspection | quick_response
- minGuards, requiresArmed, requiresDriverLicense
- isActive

**shifts**:
- id, siteId (FK)
- startTime, endTime
- status: planned | active | completed | cancelled

**shift_assignments**:
- id, shiftId (FK), guardId (FK)
- checkInTime, checkOutTime

**notifications**:
- id, userId (FK), title, message, type
- isRead, relatedEntityId

## API Endpoints

### Authentication
- `GET /api/login` - Inizia flow OIDC
- `GET /api/callback` - Callback OIDC
- `GET /api/logout` - Logout
- `GET /api/auth/user` - Current user (protected)

### Users
- `GET /api/users` - Lista utenti (admin only)
- `PATCH /api/users/:id` - Modifica ruolo utente (admin only, non self)

### Guards
- `GET /api/guards` - Lista guardie con certificazioni
- `POST /api/guards` - Crea guardia
- `PATCH /api/guards/:id` - Aggiorna guardia
- `DELETE /api/guards/:id` - Elimina guardia

### Sites
- `GET /api/sites` - Lista siti
- `POST /api/sites` - Crea sito
- `PATCH /api/sites/:id` - Aggiorna sito
- `DELETE /api/sites/:id` - Elimina sito

### Shifts
- `GET /api/shifts` - Lista tutti i turni
- `GET /api/shifts/active` - Solo turni attivi
- `POST /api/shifts` - Crea turno
- `PATCH /api/shifts/:id` - Aggiorna turno
- `DELETE /api/shifts/:id` - Elimina turno

### Notifications
- `GET /api/notifications` - Lista notifiche utente
- `PATCH /api/notifications/:id/read` - Segna come letto

## Frontend Routes

| Route | Accesso | Descrizione |
|-------|---------|-------------|
| `/` | Public/Protected | Landing page o Dashboard |
| `/guards` | Admin, Coordinator | Gestione guardie |
| `/sites` | Admin, Coordinator, Client | Gestione siti |
| `/shifts` | Admin, Coordinator, Guard | Pianificazione turni |
| `/reports` | Admin, Coordinator, Client | Reportistica |
| `/notifications` | Admin, Coordinator, Guard | Notifiche |
| `/users` | Admin | Gestione utenti e ruoli |

## User Roles

### Admin
- Accesso completo a tutte le funzionalità
- Gestione guardie, siti, turni
- Visualizzazione reportistica completa

### Coordinator
- Pianificazione turni
- Assegnazione guardie
- Gestione siti operativi
- Reportistica

### Guard
- Visualizzazione turni assegnati
- Timbratura (future)
- Notifiche
- Profilo personale

### Client
- Visualizzazione siti di competenza
- Reportistica servizi
- KPI e SLA

## Key Features

### Dashboard Operativa
- KPI Cards: Turni attivi, Guardie totali, Siti attivi, Certificazioni in scadenza
- Live status turni in corso
- Alert certificazioni in scadenza (< 30 giorni)

### Gestione Guardie
- Anagrafica completa con foto profilo
- Skill matrix (armato, antincendio, primo soccorso, patente)
- Gestione certificazioni con scadenze automatiche
- Badge number univoco

### Gestione Siti/Commesse
- Tipologie servizio: Presidio fisso, Pattugliamento, Ispettorato notturno, Pronto intervento
- Requisiti minimi (n° guardie, armato, patente)
- Geolocalizzazione (future)

### Pianificazione Turni
- Calendario 24/7
- Assegnazione manuale guardie
- Vincoli base (future: riposi, orari massimi)
- Stati turno: pianificato, attivo, completato, annullato

### Reportistica
- Ore totali lavorate
- Ore mensili per guardia
- Statistiche turni completati
- Export dati (future)

## Development

### Setup
```bash
npm install
npm run db:push  # Setup database
npm run dev      # Start application
```

### Environment Variables
- `DATABASE_URL` - PostgreSQL connection string
- `SESSION_SECRET` - Session encryption key
- `REPLIT_DOMAINS` - Authorized domains for OIDC
- `ISSUER_URL` - OIDC provider URL (default: https://replit.com/oidc)
- `REPL_ID` - Replit application ID

### Testing
All interactive elements have `data-testid` attributes for automated testing.

## Recent Changes

### 2025-10-11
- Implementato schema database completo
- Creato frontend con tutte le pagine operative
- Configurato Replit Auth per autenticazione multi-ruolo
- Implementati endpoint API per CRUD completo
- Aggiunto sistema notifiche
- **Fix definitivo conversione date nei turni**:
  - Implementato `insertShiftFormSchema` con zodResolver
  - Validazione robusta: string → refine (check valid date) → transform to Date
  - Frontend: form validation client-side con messaggi errore chiari
  - Backend: validazione ISO strings prima di conversione a Date
  - Test e2e passati con successo ✅
- **Sistema assegnazione guardie ai turni** ✅:
  - Dialog assegnazione con validazione skills vs requisiti sito
  - Mostra competenze guardie (Armato, Patente, Primo Soccorso, Antincendio)
  - Solo guardie idonee possono essere assegnate
  - Add/Remove assignments con sync real-time (refetchQueries)
  - DELETE /api/shift-assignments/:id implementato
- **CRUD completo (Backend)** ✅:
  - PATCH/DELETE /api/guards/:id
  - PATCH/DELETE /api/sites/:id
  - PATCH/DELETE /api/shifts/:id
  - 404 handling quando risorse non esistono
  - Storage methods restituiscono entità aggiornate/eliminate
- **Gestione Utenti e Ruoli** ✅:
  - Pagina /users solo per admin (route protetta)
  - Modifica ruoli utenti via dropdown (admin, coordinator, guard, client)
  - Protezione: impossibile modificare il proprio ruolo
  - GET /api/users e PATCH /api/users/:id con controlli autorizzazione
  - UI con avatar, email, ruolo corrente
- **Funzionalità Modifica Record** ✅:
  - Pulsanti edit (icona matita) su Guards, Sites, Shifts
  - Dialog di modifica con form precompilati
  - Validazione zodResolver per tutti i form
  - PATCH mutations con cache invalidation automatica
  - Toast notifiche successo/errore
  - Auto-close dialog dopo aggiornamento
  - Test e2e passati per tutte le pagine ✅
- Aggiunto SEO completo (title, meta description, Open Graph)
- Tutti i componenti testabili con data-testid attributes

## Future Enhancements

### Priorità Alta
- App mobile guardie con geofencing e timbratura GPS
- Motore ottimizzazione turni con vincoli avanzati
- Sistema ronde con checkpoint NFC/QR
- Panic button e incident reporting

### Priorità Media
- Portale clienti dedicato
- Gestione dotazioni (armi, bodycam, radio)
- Integrazione payroll (Zucchetti/Teamsystem)
- Export reportistica avanzata

### Priorità Bassa
- Dashboard analytics avanzata
- Audit trail completo
- API pubblica per integrazioni terze

## User Preferences
- Interfaccia in italiano
- Dark mode di default
- Design operativo e funzionale (non decorativo)
- Focus su efficienza e densità informativa