90 lines
3.1 KiB
Markdown
90 lines
3.1 KiB
Markdown
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`.
|