# 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

### Scheduling & Constraints Tables

**guard_constraints** (Vincoli Operatori):
- id, guardId (FK unique)
- preferredShiftType: morning | afternoon | night | any
- maxHoursPerDay, maxHoursPerWeek
- preferredDaysOff: array
- availableOnHolidays: boolean

**site_preferences** (Preferenze Siti):
- id, siteId (FK), guardId (FK)
- preference: preferred | blacklisted
- priority, reason
- Unique constraint: (siteId, guardId)

**contract_parameters** (Parametri CCNL):
- contractType (unique, default: CCNL_VIGILANZA_2023)
- maxHoursPerDay (8), maxOvertimePerDay (2)
- maxHoursPerWeek (40), maxOvertimePerWeek (8)
- minDailyRestHours (11), minWeeklyRestHours (24)
- maxNightHoursPerWeek (48)
- Maggiorazioni: holidayPayIncrease (30%), nightPayIncrease (20%), overtimePayIncrease (15%)

**training_courses** (Formazione):
- id, guardId (FK)
- courseName, courseType (mandatory/optional)
- scheduledDate, completionDate, expiryDate
- status: scheduled | completed | expired | cancelled
- provider, hours, certificateUrl

**holidays** (Festività):
- id, name, date, year
- isNational: boolean
- Unique constraint: (date, year)

**holiday_assignments** (Rotazioni Festività):
- id, holidayId (FK), guardId (FK), shiftId (FK nullable)
- Unique constraint: (holidayId, guardId)

**absences** (Assenze/Malattie):
- id, guardId (FK), type: sick_leave | vacation | personal_leave | injury
- startDate, endDate
- isApproved, needsSubstitute, substituteGuardId (FK nullable)
- certificateUrl, notes

**absence_affected_shifts** (Turni Impattati da Assenza):
- id, absenceId (FK), shiftId (FK)
- isSubstituted: boolean
- Unique constraint: (absenceId, shiftId)

## 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 ✅
- **Estensione Schema Database per Pianificazione Avanzata** ✅:
  - **guard_constraints**: vincoli operatori (preferenze turno, max ore, riposi, disponibilità festività)
  - **site_preferences**: continuità servizio (operatori preferiti/blacklisted per sito)
  - **contract_parameters**: parametri CCNL (limiti orari, riposi, maggiorazioni)
  - **training_courses**: formazione obbligatoria con scadenze e tracking
  - **holidays + holiday_assignments**: festività nazionali con rotazioni operatori
  - **absences + absence_affected_shifts**: assenze/malattie con sistema sostituzione automatica
  - Tutti unique indexes e FK integrity implementati per garantire coerenza dati
  - Schema pronto per algoritmo pianificazione automatica turni
- **Pagina Pianificazione Avanzata** ✅:
  - Rotta /planning accessibile a admin e coordinator
  - UI con 3 tabs: Formazione, Assenze, Festività
  - CRUD completo per training courses (mandatory/optional, scheduled/completed)
  - CRUD completo per absences (sick_leave, vacation, personal_leave, injury)
  - CRUD completo per holidays con filtraggio per anno
  - Dialogs di creazione con validazione form
  - Fix cache invalidation bug: TanStack Query ora invalida correttamente con parametri year
  - Data formatting italiano con date-fns locale
  - Toast notifications per feedback operazioni
- **API Routes Pianificazione** ✅:
  - GET/POST /api/guard-constraints/:guardId - vincoli operatore (upsert)
  - GET/POST/DELETE /api/site-preferences - preferenze sito-guardia
  - GET/POST/PATCH/DELETE /api/training-courses - formazione (con filtro guardId)
  - GET/POST/DELETE /api/holidays - festività (con filtro year)
  - GET/POST/PATCH/DELETE /api/absences - assenze (con filtro guardId)
- **Storage Layer Completo** ✅:
  - DatabaseStorage esteso con metodi CRUD per tutte le nuove entità
  - Guard constraints: upsert semantics (create o update se esiste)
  - Gestione relazioni FK con cascading deletes dove appropriato
  - Query con ordering e filtering per date/status
- Aggiunto SEO completo (title, meta description, Open Graph)
- Tutti i componenti testabili con data-testid attributes
- **Sistema Deployment Automatico** ✅:
  - Pipeline CI/CD GitLab (.gitlab-ci.yml) con stages build/test/deploy
  - Script setup server AlmaLinux 9 (deploy/setup-server.sh)
  - Script deployment automatico (deploy/deploy.sh)
  - Configurazione Nginx reverse proxy con SSL
  - Password PostgreSQL autogenerata (sicurezza)
  - Workflow: Replit → GitLab → CI/CD → Server produzione
  - Documentazione completa (DEPLOYMENT.md, QUICKSTART-DEPLOYMENT.md)
  - Helper script push-to-gitlab.sh per deployment rapido

## Deployment

### Setup Produzione
Il sistema supporta deployment automatico su server AlmaLinux 9 tramite GitLab CI/CD:

**Workflow Deployment:**
```
Replit (modifiche) → Git Push → GitLab CI/CD → Deploy Server
```

**File Deployment:**
- `.gitlab-ci.yml` - Pipeline CI/CD (build, test, deploy, rollback)
- `deploy/setup-server.sh` - Setup iniziale server (Node, PostgreSQL, Nginx, PM2)
- `deploy/deploy.sh` - Script deployment automatico
- `deploy/nginx.conf` - Configurazione reverse proxy
- `.env.production.example` - Template variabili ambiente produzione

**Documentazione:**
- `DEPLOYMENT.md` - Guida completa step-by-step
- `QUICKSTART-DEPLOYMENT.md` - Setup rapido 15 minuti

**Security:**
- Password PostgreSQL autogenerata (non hard-coded)
- SSL/TLS con Let's Encrypt
- Firewall configurato automaticamente

## 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


Test
1