VigilanzaTurni/replit.md

VigilanzaTurni - Sistema Gestione Turni per Istituti di Vigilanza

Overview

VigilanzaTurni is a professional 24/7 shift management system designed for security companies. It offers multi-role authentication (Admin, Coordinator, Guard, Client), comprehensive guard and site management, 24/7 shift planning, a live operational dashboard with KPIs, reporting for worked hours, and a notification system. The system supports multi-location operations (Roccapiemonte, Milano, Roma) managing 250+ security personnel across different branches. The project aims to streamline operations and enhance efficiency for security institutes.

User Preferences

• Interfaccia in italiano
• Dark mode di default
• Design operativo e funzionale (non decorativo)
• Focus su efficienza e densità informativa
• Testing: Tutti i test vengono eseguiti ESCLUSIVAMENTE sul server esterno (vt.alfacom.it) con autenticazione locale (non Replit Auth)

System Architecture

Stack Tecnologico

• Frontend: React + TypeScript + Tailwind CSS + Shadcn UI
• Backend: Express.js + TypeScript
• Database: PostgreSQL (Neon) with Drizzle ORM
• Autenticazione: Replit Auth (OIDC)
• State Management: TanStack Query v5
• Routing: Wouter

Design System

• Font Principale: Inter (sans-serif)
• Font Monospace: JetBrains Mono
• Colori: Primary Blue, Status Green, Orange, Red, Gray for various operational states.
• Tema: Dark mode by default, with light mode support.
• Componenti: Shadcn UI with an operational design.

Database Schema

The database includes core tables for users, guards, certifications, sites, shifts, shift_assignments, and notifications. Advanced scheduling and constraints are managed via guard_constraints, site_preferences, contract_parameters, training_courses, holidays, holiday_assignments, absences, and absence_affected_shifts. All tables include appropriate foreign keys and unique constraints to maintain data integrity.

Recent Schema Updates (October 2025):

• Service types now include specialized parameters: fixedPostHours (ore presidio fisso), patrolPassages (numero passaggi pattuglia), inspectionFrequency (frequenza ispezioni), responseTimeMinutes (tempo risposta pronto intervento)
• Sites include service schedule fields: serviceStartTime and serviceEndTime (formato HH:MM)
• Contract Management: Sites now include contract fields: contractReference (codice contratto), contractStartDate, contractEndDate (date validità contratto in formato YYYY-MM-DD)
• Sites now reference service types via serviceTypeId foreign key; shiftType is optional and can be derived from service type

Recent Bug Fixes (October 17, 2025):

• Operational Planning Date Handling: Fixed date sanitization in /api/operational-planning/uncovered-sites and /api/operational-planning/availability endpoints to handle malformed date inputs (e.g., "2025-10-17/2025-10-17"). Both endpoints now validate dates using parseISO/isValid and return 400 for invalid formats.
• Checkbox Event Propagation: Fixed double-toggle bug in operational planning resource selection by wrapping vehicle and guard checkboxes in <div onClick={e => e.stopPropagation()}> to prevent Card onClick from firing when clicking checkboxes.
• Resource Query Key: Added selectedSite?.id to TanStack Query queryKey for availability endpoint to ensure resources re-fetch when operator selects a different site.

API Endpoints

Comprehensive RESTful API endpoints are provided for Authentication, Users, Guards, Sites, Shifts, and Notifications, supporting full CRUD operations with role-based access control.

Frontend Routes

Key frontend routes include /, /guards, /sites, /shifts, /reports, /notifications, and /users, with access controlled by user roles.

User Roles

• Admin: Full access to all functionalities, managing guards, sites, shifts, and reports.
• Coordinator: Shift planning, guard assignment, operational site management, and reporting.
• Guard: View assigned shifts, future time-punching, notifications, and personal profile.
• Client: View assigned sites, service reporting, and KPIs.

Key Features

• Dashboard Operativa: Live KPIs (active shifts, total guards, active sites, expiring certifications) and real-time shift status.
• Gestione Guardie: Complete profiles with skill matrix (armed, fire safety, first aid, driver's license), certification management with automatic expiry, and unique badge numbers.
• Gestione Siti/Commesse: Service types with specialized parameters (fixed post hours, patrol passages, inspection frequency, response time) and minimum requirements (guard count, armed, driver's license). Sites include service schedule (start/end time) and contract management (reference code, validity period with start/end dates). Contract status is visualized with badges (active/expiring/expired) and enforces shift creation only within active contract periods.
• Pianificazione Operativa Interattiva: Three-step workflow for shift assignment:
  1. Select date → view uncovered sites with coverage status
  2. Select site → view filtered resources (guards and vehicles matching requirements)
  3. Assign resources → create shift with atomic guard assignments and vehicle allocation
• Pianificazione Turni: 24/7 calendar, manual guard assignment, basic constraints, and shift statuses (planned, active, completed, cancelled).
• Reportistica: Total hours worked, monthly hours per guard, shift statistics, and data export capabilities.
• Advanced Planning: Management of guard constraints (preferences, max hours, rest days), site preferences (preferred/blacklisted guards), contract parameters, training courses, holidays, and absences with substitution system.

External Dependencies

• Replit Auth: For OpenID Connect (OIDC) based authentication.
• Neon: Managed PostgreSQL database service.
• Tailwind CSS: For utility-first CSS styling.
• Shadcn UI: For UI components.
• Zod: For schema validation.
• TanStack Query: For data fetching and state management.
• Wouter: For client-side routing.
• date-fns: For date manipulation and formatting.
• PM2: Production process manager for Node.js applications.
• Nginx: As a reverse proxy for the production environment.
• Let's Encrypt: For SSL/TLS certificates.
• GitLab CI/CD: For continuous integration and deployment.