marco/VigilanzaTurni
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a7df004348
VigilanzaTurni/replit.md
Marco Lanzara 6d7d6c82ef Deploy: 2025-10-16 07:58:29
2025-10-16 07:58:31 +00:00

13 KiB
Raw Blame History

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

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