Add scouthub-magazzino-be

2026-07-25 11:54:03 +02:00
parent 7f1d0d5ce3
commit 9ceb05cda2
58 changed files with 9711 additions and 0 deletions
@@ -0,0 +1,89 @@
+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`.