eef9b6027d
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
63 lines
4.7 KiB
Markdown
63 lines
4.7 KiB
Markdown
# 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. |