esameits24-26frontend/README.md

Academy Aziendale — Frontend

Interfaccia web CSR (Client Side Rendering) per la piattaforma formativa interna (esame ITS Web Developer Full Stack 24-26, Prova C).

React + TypeScript, comunicazione con il backend tramite API REST e autenticazione cookie (Auth.js).

URL produzione

Risorsa	URL
Applicazione	https://esameits24-26frontend.andreavillari.it
Backend API	https://esameits24-26backend.andreavillari.it
Swagger	https://esameits24-26backend.andreavillari.it/api/docs

Stack tecnologico

• React 19 + TypeScript
• Vite 8
• React Router 7
• Tailwind CSS 4 + shadcn/ui (Base UI)
• Auth cookie-based con CSRF
• Tema chiaro/scuro (WCAG AA)

Credenziali di test

Password per tutti gli utenti: Password123!

Email	Ruolo	Cosa testare
admin@academy.it	Referente Academy	Catalogo corsi, assegnazioni, dipendenti, statistiche
maria.bianchi@academy.it	Dipendente	I miei corsi, completamento, dashboard
luca.conti@academy.it	Dipendente	—
elena.rossi@academy.it	Dipendente	—

Funzionalità per ruolo

Dipendente

• Dashboard con riepilogo assegnazioni e scadenze
• I miei corsi — elenco, filtri, dettaglio, segna come completato

Referente Academy

• Dashboard con indicatori e link rapidi
• Catalogo corsi — crea, modifica, disattiva, elimina
• Assegnazioni — assegna corsi, modifica date, annulla
• Dipendenti — elenco e ricerca
• Statistiche — aggregati per mese, categoria e dipendente

Avvio in sviluppo

Prerequisiti

• Node.js 20+
• Backend in esecuzione (locale o produzione)

Configurazione

Crea un file .env nella root del frontend (vedi .env.example):

VITE_API_URL=http://localhost:3011

Per puntare al backend di produzione:

VITE_API_URL=https://esameits24-26backend.andreavillari.it

Comandi

npm ci
npm run dev

L'app è disponibile su http://localhost:5173

npm run build    # build produzione in dist/
npm run preview  # anteprima build locale
npm run lint     # ESLint

Avvio con Docker

docker compose up -d --build

Il container espone l'app su http://127.0.0.1:3010 (nginx).

La variabile VITE_API_URL viene passata in fase di build (vedi docker-compose.yml e dockerfile/Dockerfile).

Tema chiaro / scuro

L'applicazione supporta tre modalità (menu in sidebar e pagina login):

• Chiaro
• Scuro — palette ottimizzata per ridurre affaticamento visivo (sfondo ~#121212, testo ~#E0E0E0, colori desaturati)
• Sistema — segue le preferenze del sistema operativo

La preferenza è salvata in localStorage (academy-theme).

Struttura progetto

src/
  api/client.ts       Client HTTP verso il backend
  components/         Layout, sidebar, route guard, UI shadcn
  config/navigation.ts  Voci menu per ruolo
  context/AuthContext.tsx  Stato autenticazione
  lib/                Utility (date, formattazione)
  pages/              Pagine dell'applicazione
  types/              Tipi TypeScript condivisi
  validation/         Validazione client-side (corsi, assegnazioni)

Pagine e route

Route	Ruolo	Descrizione
/login	Guest	Accesso
/dashboard	Tutti	Home personalizzata per ruolo
/i-miei-corsi	Dipendente	Elenco corsi assegnati
/i-miei-corsi/:id	Dipendente	Dettaglio e completamento
/corsi	Referente	Catalogo CRUD
/assegnazioni	Referente	Gestione assegnazioni
/dipendenti	Referente	Elenco dipendenti
/statistiche	Referente	Riepiloghi formativi

Validazione lato client

I form di corsi e assegnazioni validano i dati prima dell'invio. Gli errori del server (status 400) vengono mostrati per campo tramite ApiClientError e toast Sonner.

Deploy

Il deploy su VPS è automatizzato tramite Forgejo Actions (.github/workflows/deploy.yml):

1. Build Vite su runner CI con VITE_API_URL di produzione
2. SSH sul VPS → git pull → docker compose up -d --build

Il job deploy ha command_timeout: 30m per i build Docker sul VPS.

Autore

Andrea Villari — esame ITS 24-26