378 lines
13 KiB
Markdown
378 lines
13 KiB
Markdown
# 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
|