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`):

```env
VITE_API_URL=http://localhost:3011
```

Per puntare al backend di produzione:

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

### Comandi

```bash
npm ci
npm run dev
```

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

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

## Avvio con Docker

```bash
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