170 lines
7.6 KiB
Markdown
170 lines
7.6 KiB
Markdown
# 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
|
|
```
|