marco370 eef9b6027d Update project overview and clarify date handling rules

Update the project overview section in README.md and introduce mandatory rules for handling date/timezone conversions to prevent bugs, with specific examples and references to affected files and previous commits.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: e5565357-90e1-419f-b9a8-6ee8394636df
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/6d543d2c-20b9-4ea6-93fe-70fe9b1d9f80/e5565357-90e1-419f-b9a8-6ee8394636df/1nTItRR

2025-10-23 09:05:47 +00:00

4.7 KiB

Raw Blame History

VigilanzaTurni - Sistema Gestione Turni per Istituti di Vigilanza

Overview

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

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 tables for users, guards, certifications, sites, shifts, shift_assignments, notifications, customers, and various tables for advanced scheduling and constraints (guard_constraints, site_preferences, contract_parameters, training_courses, holidays, holiday_assignments, absences, absence_affected_shifts). Service types include specialized parameters like fixedPostHours, patrolPassages, inspectionFrequency, and responseTimeMinutes. Sites support multi-location (location field) and contract management (contractReference, contractStartDate, contractEndDate).

Core Features

Multi-Sede Operational Planning: Location-first approach for shift planning, filtering sites, guards, and vehicles by selected branch.
Service Type Classification: Service types are classified as "fisso" (fixed posts) or "mobile" (patrols, inspections) to route sites to appropriate planning modules (Planning Fissi, Planning Mobile).
Planning Fissi: Weekly planning grid showing all sites with active contracts, allowing direct shift creation for multiple days with guard availability checks.
Planning Mobile: Dedicated guard-centric interface for mobile services, displaying guard availability and hours for mobile-classified sites. Includes a map placeholder for future integration.
Customer Management: Full CRUD operations for customers with comprehensive details.
Customer-Centric Reports: New reports aggregating data by customer, replacing site-based billing, with specific counters for fixed posts (hours), patrols (passages), inspections, and interventions. CSV export is supported.
Dashboard Operativa: Live KPIs and real-time shift status.
Gestione Guardie: Complete profiles with skill matrix, certification management, and unique badge numbers.
Gestione Siti/Commesse: Service types with specialized parameters and minimum requirements. Sites include service schedule, contract management, and location assignment.
Pianificazione Turni: 24/7 calendar, manual guard assignment, basic constraints, and shift statuses.
Advanced Planning: Management of guard constraints, site preferences, contract parameters, training courses, holidays, and absences.

User Roles

Admin: Full access.
Coordinator: Shift planning, guard assignment, operational site management, reporting.
Guard: View assigned shifts, time-punching, notifications, personal profile.
Client: View assigned sites, service reporting, KPIs.

Critical Date/Timezone Handling

To prevent timezone-related bugs, especially when assigning shifts, dates should always be constructed from components (new Date(year, month-1, day)) and never parsed from ISO strings directly using parseISO() or new Date(string ISO). Date validation should use regex instead of parseISO().

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.

4.7 KiB Raw Blame History