marco/VigilanzaTurni
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
12e1efaa3d
VigilanzaTurni/replit.md
marco370 7c456271ac Update deployment process to use a new server and simplify commands 
Update deployment documentation and scripts to deploy to vt.alfacom.it, remove Replit references, and simplify the deployment workflow to two commands: `./push-to-gitlab.sh` and `bash deploy/deploy.sh`, including automated database backups.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 42d8028a-fa71-4ec2-938c-e43eedf7df01
Replit-Commit-Checkpoint-Type: intermediate_checkpoint
2025-10-16 10:56:13 +00:00

390 lines
13 KiB
Markdown
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
```bash
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 con backup DB (deploy/deploy.sh)
- Configurazione Nginx reverse proxy con SSL
- Workflow semplificato: 2 comandi (push + deploy)
- Backup automatico database pre-deploy (retention 30 giorni)
- Rollback automatico su errore deployment
- Dominio produzione: vt.alfacom.it
- Documentazione completa (DEPLOYMENT.md, QUICKSTART-DEPLOYMENT.md)
- Helper script push-to-gitlab.sh
## Deployment
### Setup Produzione
Sistema deployment automatico su vt.alfacom.it (AlmaLinux 9):
**Workflow Semplificato (2 comandi):**
```bash
# 1. Push da Replit
./push-to-gitlab.sh
# 2. Deploy su server
ssh root@vt.alfacom.it "cd /var/www/vigilanza-turni && bash deploy/deploy.sh"
```
**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 con backup DB
- `deploy/nginx.conf` - Configurazione Nginx per vt.alfacom.it
- `.env.production.example` - Template variabili ambiente
- `push-to-gitlab.sh` - Helper push GitLab
**Funzionalità Deploy:**
- ✅ Backup automatico database pre-deploy
- ✅ Build frontend Vite + migrations DB
- ✅ Restart graceful PM2
- ✅ Health check post-deploy
- ✅ Rollback automatico su errore
- ✅ Retention backup: 30 giorni
**Security:**
- Password PostgreSQL sicura (non hard-coded)
- SSL/TLS con Let's Encrypt (vt.alfacom.it)
- Firewall configurato (HTTP/HTTPS only)
- Backup compressi in /var/backups/vigilanza-turni/
## 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
Reference in New Issue View Git Blame Copy Permalink