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

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