README.# scouthub-magazzino-be

Backend Node.js/TypeScript per la gestione del **magazzino** Scouthub (materiale scout in dotazione
ai gruppi), pensato per affiancare `scouthub-home-be` e `scouthub-attivita-be` nello stesso ecosistema.

> Stato attuale: schema dati e middleware di autenticazione pronti; espone solo l'healthcheck,
> nessuna route di dominio (liste/magazzino/eventi) ancora implementata.

## Stack

- Node.js ≥ 20, TypeScript
- Express
- Prisma ORM su PostgreSQL (database dedicato `scouthub_magazzino`)
- Autenticazione JWT via Keycloak, stesso realm di `scouthub-home-be`/`scouthub-attivita-be`

## Struttura a livelli

```
src/
  routes/         # definizione degli endpoint Express
  controllers/     # gestione request/response, delega alla service layer
  services/        # business logic
  repositories/    # accesso ai dati tramite Prisma
  auth/            # verifica JWT Keycloak e guard sui ruoli/org_id
  config/          # lettura e validazione delle variabili d'ambiente
  db/              # istanza condivisa di PrismaClient
  middleware/       # error handler
```

Flusso delle richieste: `routes -> controller -> service -> repository (Prisma)`.

## Autenticazione e multi-tenancy (org_id)

- `src/auth/verify-token.middleware.ts` valida il Bearer token contro il JWKS del realm Keycloak
  (`${KEYCLOAK_BASE_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/certs`) e popola
  `req.auth` con `userId`, `email`, `orgId` (dal claim `organization` iniettato da Keycloak
  Organizations) e `roles` (ruoli realm + ruoli sull'organizzazione attiva).
- `src/auth/require-org-id.middleware.ts` da usare dopo `verifyToken` su **tutte** le route
  private (liste, magazzino, eventi): rifiuta la richiesta se il token non porta
  un'organizzazione attiva. Le query verso il database devono sempre filtrare per
  `req.auth.orgId`, mai per un `org_id` letto da params/query/body della richiesta.
- `src/auth/require-moderatore.middleware.ts` da usare solo sulle route di moderazione del
  catalogo materiali (richiede il ruolo realm `moderatore`).

## Variabili d'ambiente

Vedi `.env.example`. Copiarlo in `.env` e valorizzare:

| Variabile | Descrizione |
|---|---|
| `PORT` | Porta HTTP del servizio (default `8083`) |
| `DATABASE_URL` | Connection string Postgres (schema/database `scouthub_magazzino`) |
| `KEYCLOAK_BASE_URL` | Base URL del server Keycloak |
| `KEYCLOAK_REALM` | Realm Keycloak (`scouthub`) |
| `KEYCLOAK_MAGAZZINO_CLIENT_ID` | Client Keycloak dedicato a questo servizio |
| `KEYCLOAK_MAGAZZINO_CLIENT_SECRET` | Secret del client sopra |

## Avvio in locale

```bash
npm install
npx prisma generate
npx prisma migrate deploy   # applica le migration sul database scouthub_magazzino
npm run dev                  # avvia con ts-node-dev su http://localhost:8083
```

## Build e avvio in produzione

```bash
npm run build
npm start
```

## Healthcheck

```
GET /health
```

Risponde `{ "status": "ok", "database": "up" }` se il servizio e la connessione al database sono
funzionanti.

## Test

```bash
npm test
```

Nessun test presente al momento (scaffold); il comando gira con `--passWithNoTests`.