marco/VigilanzaTurni
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
VigilanzaTurni/replit.md
marco370 758a697447 Add detailed validation and conflict resolution for patrol shifts 
Implement new API endpoint `/api/patrol-routes/check-overlaps` for shift conflict detection, including fixed posts, other mobile routes, and weekly hour compliance. Introduce a new "force-save" dialog for manual conflict overrides and enhance the patrol route duplication feature to support multi-day operations with overlap validation.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: e0b5b11c-5b75-4389-8ea9-5f3cd9332f88
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/6d543d2c-20b9-4ea6-93fe-70fe9b1d9f80/e0b5b11c-5b75-4389-8ea9-5f3cd9332f88/p38S9Gi
2025-10-29 09:24:38 +00:00

8.2 KiB
Raw Permalink 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. 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. The project aims to provide a robust, scalable solution for security companies, improving operational control and resource allocation.

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
  • Maps: Leaflet + react-leaflet + OpenStreetMap tiles

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 supports managing users, guards, certifications, sites, shifts, shift assignments, notifications, customers, and service types. It also includes tables for advanced scheduling constraints such as guard constraints, site preferences, contract parameters, training courses, holidays, and absences. Service types include specialized parameters like fixedPostHours, patrolPassages, inspectionFrequency, and responseTimeMinutes.

Core Features

  • Multi-Sede Operational Planning: Location-first approach for shift planning, filtering resources by selected branch.
  • Service Type Classification: Classifies services as "fisso" (fixed posts) or "mobile" (patrols, inspections) to route sites to appropriate planning modules.
  • Planning Fissi: Weekly planning grid for fixed posts, enabling shift creation with guard availability checks. Includes weekly shift duplication feature with confirmation dialog and automatic navigation.
  • Planning Mobile: Guard-centric interface for mobile services, displaying guard availability and hours, with an interactive Leaflet map showing sites. Features include:
    • Smart Site Assignment Indicators: Sites already in patrol routes display "Assegnato a [Guard Name]" button with scroll-to functionality; unassigned sites show "Non assegnato" text
    • Drag-and-Drop Reordering: Interactive drag-and-drop using @dnd-kit library for patrol route stops with visual feedback and automatic sequenceOrder persistence
    • Route Optimization: OSRM API integration with TSP (Traveling Salesman Problem) nearest neighbor algorithm; displays total distance (km) and estimated travel time in dedicated dialog
    • Patrol Sequence List View: Daily view of planned patrol routes with stops visualization
    • Custom Shift Timing: Configurable start time and duration for each patrol route (replaces hardcoded 08:00-20:00)
    • Shift Overlap Validation: POST /api/patrol-routes/check-overlaps endpoint verifies:
      • No conflicts with existing fixed post shifts (shift_assignments)
      • No conflicts with other mobile patrol routes
      • Weekly hours compliance with contract parameters (maxHoursPerWeek + maxOvertimePerWeek)
    • Force-Save Dialog: Interactive conflict resolution when saving patrol routes with overlaps or contractual limit violations; shows detailed conflict information and allows coordinator override
    • Multi-Day Duplication: Duplication dialog supports "numero giorni consecutivi" field to create patrol sequences across N consecutive days; includes overlap validation (conservative approach: blocks entire operation if any day has conflicts)
  • Customer Management: Full CRUD operations for customer details and customer-centric reporting with CSV export.
  • Dashboard Operativa: Live KPIs and real-time shift status.
  • Gestione Guardie: Complete profiles with skill matrix, certification management, and badge numbers.
  • Gestione Siti/Commesse: Sites are associated with service types, including schedule, contract management, and location assignment. Automatic geocoding is supported.
  • 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. Includes patrol route persistence and exclusivity constraints between fixed and mobile shifts.
  • Guard Planning Views: Dedicated views for guards to see their fixed post shifts and mobile patrol routes.
  • Site Planning View: Coordinators can view all guards assigned to a specific site over a week.
  • Shift Duplication Features:
    • Weekly Copy (Planning Fissi): POST /api/shift-assignments/copy-week endpoint duplicates all shifts and assignments from selected week to next week (+7 days) with atomic transaction. Frontend includes confirmation dialog with week details and success feedback.
    • Patrol Sequence Duplication (Planning Mobili): POST /api/patrol-routes/duplicate endpoint with dual behavior: UPDATE when target date = source date (modifies guard), CREATE when different date (duplicates route with all stops). Frontend shows daily sequence list with duplication dialog (date picker defaulting to next day, guard selector pre-filled but changeable).
  • Guardie Settimanale: Compact weekly schedule view showing all guards' assignments across the week in a grid format. Features include:
    • Weekly Grid View: Guard names in first column, 7 daily columns (Mon-Sun) with compact cell display
    • Multi-Source Aggregation: GET /api/weekly-guards-schedule endpoint aggregates fixed shifts, patrol routes, and absences by location and week
    • Compact Cell Format: Fixed posts show "Site Name HH:mm-HH:mm", mobile patrols show "Pattuglia HH:mm-HH:mm", absences show status (Ferie/Malattia/Permesso/Riposo)
    • Read-Only Dialogs: Clicking cells opens appropriate dialog (fixed shift details or mobile patrol info) with navigation links to Planning Fissi/Mobile for edits
    • Location and Week Filters: Dropdown for branch selection, week navigation with prev/next buttons displaying "Settimana dal DD MMM al DD MMM YYYY"

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

The system handles timezone conversions for shift times, converting Italy local time from the frontend to UTC for database storage, and back to Italy local time for display, accounting for DST.

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.
  • Leaflet: Interactive map library with react-leaflet bindings and OpenStreetMap tiles.
  • Nominatim: OpenStreetMap geocoding API for automatic address-to-coordinates conversion.
  • OSRM (Open Source Routing Machine): Public API (router.project-osrm.org) for distance matrix calculation and route optimization in Planning Mobile. No authentication required.
  • @dnd-kit: Drag-and-drop library (@dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities) for interactive patrol route reordering.