scouthub/scouthub-magazzino-be/README.md

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

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

npm run build
npm start

Healthcheck

GET /health

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

Test

npm test

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