# scouthub-magazzino-fe

Frontend Angular per la gestione del **magazzino** Scouthub (catalogo materiali, liste per
uscite/eventi, giacenze, checklist evento), affianca `scouthub-attivita-fe` e `scouthub-home-fe`
nello stesso ecosistema. Parla con `scouthub-magazzino-be` per le API e con Keycloak per
l'autenticazione.

Componenti standalone (nessun NgModule), routing con lazy loading per feature, Angular Material
per la UI.

## Stato del progetto

Tutte le feature principali sono implementate: catalogo materiali pubblico con proposta di nuovi
materiali, liste modello, liste per organizzazione (anche a partire da un modello), gestione
giacenze di magazzino, creazione/dettaglio evento con checklist, e un'area di moderazione riservata
al ruolo `moderatore` per approvare/rifiutare i materiali proposti.

## Struttura cartelle

```
src/app/
  core/
    auth/
      keycloak.provider.ts          provideKeycloakAngular() — login OIDC Authorization Code + PKCE
      roles.ts                      MODERATORE_ROLE + extractRealmRoles()
    require-auth.guard.ts           requireAuthGuard — richiede login, altrimenti avvia keycloak.login()
  catalogo/            feature "catalogo materiali" (/, lazy-loaded, in gran parte pubblica)
    catalogo-materiali/             elenco materiali del catalogo pubblico
    catalogo-liste-modello/         elenco liste modello (standard per tipo evento)
    proponi-materiale/              form di proposta di un nuovo materiale (richiede login)
    *-api.service.ts                client HTTP verso /materiali, /liste-modello, /tipi-evento
  liste/                feature "liste materiale per org" (/liste, lazy-loaded, richiede login)
    liste-list/                     elenco liste dell'organizzazione
    lista-editor/                   creazione/modifica di una lista (anche da modello)
  magazzino/            feature "giacenze di magazzino" (/magazzino, lazy-loaded, richiede login)
  eventi/               feature "eventi e checklist" (/eventi, lazy-loaded, richiede login)
    crea-evento/                    creazione di un evento a partire da una lista
    evento-dettaglio/               dettaglio evento con checklist portato/non portato
  moderazione/          feature "moderazione catalogo" (/moderazione, lazy-loaded, richiede login
                        + ruolo realm moderatore)
    require-moderatore.guard.ts  guard di routing basata sul claim realm_access.roles del token
src/environments/    environment.ts / environment.development.ts
public/
  silent-check-sso.html   richiesto dal flusso check-sso silenzioso di Keycloak
```

### Modulo di autenticazione

- **Login**: `provideKeycloak` (in `keycloak.provider.ts`) usa il client pubblico
  `scouthub-frontend` — **condiviso con tutti gli altri frontend** (`scouthub-attivita-fe`,
  `scouthub-home-fe`, `scouthub-eventi-fe`) — con Authorization Code
  Flow + PKCE, `onLoad: 'check-sso'` e refresh automatico del token via `withAutoRefreshToken`
  (logout automatico dopo 5 minuti di inattività).
- **requireAuthGuard** (`core/require-auth.guard.ts`): se l'utente non è autenticato avvia
  `keycloak.login()` con redirect di ritorno sulla stessa rotta richiesta; altrimenti lascia
  proseguire. Applicato a tutte le rotte tranne il catalogo pubblico e le liste modello.
- **requireModeratoreGuard** (`moderazione/require-moderatore.guard.ts`): legge i ruoli
  realm dal token (`extractRealmRoles`) e consente l'accesso solo se è presente
  `moderatore`, altrimenti reindirizza a `/`. Va sempre applicato **dopo** `requireAuthGuard`
  (presuppone un utente già autenticato).
- Le chiamate verso `magazzinoApiBaseUrl` ricevono automaticamente l'header
  `Authorization: Bearer <token>` tramite l'interceptor `includeBearerTokenInterceptor` di
  `keycloak-angular`, condizionato via regex sull'URL base dell'API in `app.config.ts`.

### Feature `catalogo` (`/`)

Catalogo materiali e liste modello pubblici: consultabili anche senza autenticazione, in linea con
l'idea di un catalogo condiviso tra tutte le organizzazioni. Solo `proponi-materiale`
(`POST /materiali/proposte`) richiede login, perché la proposta viene associata all'organizzazione
dell'utente (`propostoDaOrgId`) e finisce nella coda di moderazione.

### Feature `liste` (`/liste`)

Elenco e editor delle liste materiale della propria organizzazione. Una lista può essere creata da
zero o a partire da una lista modello del catalogo pubblico. Richiede login e un'organizzazione
attiva sul token (il backend filtra sempre per `orgId`, mai da input client).

### Feature `magazzino` (`/magazzino`)

Gestione delle giacenze di magazzino dell'organizzazione (quantità, stato buono/da
riparare/mancante, posizione). Richiede login.

### Feature `eventi` (`/eventi`)

Creazione di un evento a partire da una lista e, nel dettaglio evento, gestione della checklist di
cosa è stato effettivamente portato/non portato. Richiede login.

### Feature `moderazione` (`/moderazione`)

Coda di revisione dei materiali proposti dalle organizzazioni (approvazione/rifiuto), riservata a
chi ha il ruolo realm `moderatore`.

## Prerequisiti

- Node.js 20+
- I servizi dell'ecosistema Scouthub in esecuzione: Keycloak e `scouthub-magazzino-be`
  (vedi `docker-compose.yml` e `scouthub-magazzino-be/README.md` nella root del repo)

## Configurazione ambiente

`src/environments/environment.ts` (produzione) e `environment.development.ts` (dev, usato
automaticamente da `ng serve`/`ng build --configuration development`) espongono:

- `keycloakBaseUrl` — URL base dell'istanza Keycloak (default `http://localhost:8081`, coerente
  con `KEYCLOAK_PORT` in `.env` alla root del repo)
- `keycloakRealm` — realm Keycloak (`scouthub`)
- `keycloakClientId` — client pubblico condiviso già definito in `keycloak/realm-export.json`
  (`scouthub-frontend`)
- `magazzinoApiBaseUrl` — URL base di `scouthub-magazzino-be` (default `http://localhost:8083`)

## Collegare Keycloak in locale

1. Avviare Keycloak (e Postgres) dalla root del repo:
   ```bash
   docker compose up -d keycloak-db keycloak
   ```
   Il realm `scouthub` viene importato automaticamente da `keycloak/realm-export.json` al primo
   avvio (`--import-realm`).
2. Il client pubblico `scouthub-frontend` ha `redirectUris`/`webOrigins` che includono anche
   `http://localhost:4203` (porta di default di questo progetto, vedi sotto) — se si cambia porta,
   aggiornare `keycloak/realm-export.json` di conseguenza e reimportare il realm (o aggiornarlo
   da console admin Keycloak).
3. `provideKeycloakAngular()` (`src/app/core/auth/keycloak.provider.ts`) inizializza il client con
   `onLoad: 'check-sso'`: all'avvio l'app verifica in un iframe nascosto se esiste già una sessione
   Keycloak, senza forzare un redirect immediato per le pagine pubbliche.

## Collegare scouthub-magazzino-be in locale

1. Avviare `scouthub-magazzino-be` seguendo il suo README (`npm run dev`, porta di default `8083`).
2. Le richieste verso `magazzinoApiBaseUrl` ricevono automaticamente l'header
   `Authorization: Bearer <token>` tramite l'interceptor `includeBearerTokenInterceptor` di
   `keycloak-angular`, configurato in `app.config.ts`.

## Development server

Questo progetto usa la porta `4203` (per non collidere con `scouthub-attivita-fe` sulla `4200` e
`scouthub-home-fe` sulla `4201`):

```bash
ng serve
```

Apri il browser su `http://localhost:4203/`.

## Build

```bash
ng build
```

Artefatti di build in `dist/scouthub-magazzino-fe`.

## Test

```bash
ng test
```

Esegue gli unit test con Vitest.

## Versione Angular CLI usata per lo scaffold

```
Angular CLI       : 22.0.7
Angular           : 22.0.8
Node.js           : 24.16.0
Package Manager   : npm 11.12.0
Operating System  : win32 x64
```