# JC4 - Per chi sviluppa

# JC4.1 - Aggiungere una rotta

**In una frase.** Per far arrivare le richieste a un servizio nuovo basta una rotta nel Gateway: gli altri servizi non si toccano.

Una **rotta** è una riga che dice: le richieste che cominciano così vanno a quel servizio. Stanno tutte in una classe sola, quindi chi vuole sapere cosa è raggiungibile da fuori guarda in un posto solo. Aggiungerne una vuol dire copiare quelle che ci sono.

1. **Dai un nome al servizio.** È il nome con cui si iscrive al Monitor servizi: tutto maiuscolo, con i trattini, per esempio `NUOVO-SERVICE`. Sta in `spring.application.name` del servizio.
2. **Aggiungi la rotta nel Gateway.** Apri `GatewayConfig` e copia una rotta esistente. Cambiano tre cose: il nome della rotta (`nuovo-service`), l'inizio dell'indirizzo (`/api/nuovo/**`) e la destinazione (`lb://NUOVO-SERVICE`). Restano uguali `stripPrefix(2)` e il filtro `authenticationFilter`: vanno messi sempre.
3. **Nel servizio non ripetere l'inizio dell'indirizzo.** Il Gateway toglie `/api/nuovo` prima di inoltrare. Se la pagina chiama `/api/nuovo/clienti`, il servizio riceve `/clienti`.
4. **Fai controllare il lasciapassare anche al servizio.** Prendi come modello la `SecurityConfig` di un servizio esistente. Il nome utente lo leggi dall'intestazione `X-User-Id`, che scrive il Gateway.
5. **Ricostruisci e riavvia solo il Gateway.** I servizi già accesi non vanno fermati.
6. **Prova.** Chiama `/api/nuovo/...` dall'app. Un 503 vuol dire che il servizio non è ancora iscritto al Monitor servizi. Un 404 vuol dire che la rotta c'è ma il servizio non ha quell'indirizzo.
7. **Aggiorna la tabella delle rotte** in `docs/architettura/riferimento/ARCHITETTURA-MICROSERVIZI.md`.

Il server web dell'app non va toccato: manda già al Gateway tutto ciò che comincia per `/api/`. Serve una regola in più solo per i collegamenti che restano aperti a lungo.

<p class="callout warning">**Attenzione.**  
• Con un numero diverso da 2 in `stripPrefix` il servizio riceve indirizzi sbagliati.  
• Senza `authenticationFilter` il servizio non riceve il nome utente, e chi chiama potrebbe scriverne uno a piacere.  
• Un servizio raggiungibile senza passare dal Gateway non può fidarsi di `X-User-Id`. </p>

<p class="callout info">**Per chi sviluppa.**  
• File: `backend/middleware/it_gsba_api_gateway/src/main/java/it/gsba/api_gateway/config/GatewayConfig.java`.  
• Verifica: nella cartella del Gateway `./mvnw -o clean package -DskipTests`, vale solo `BUILD SUCCESS`.  
• Anche in sviluppo l'app manda già al Gateway tutto ciò che comincia per `/api`.  
• Prima di cambiare le regole di sicurezza del Gateway si dice cosa cambia e perché: una modifica piccola può spegnere i controlli. </p>

# JC4.2 - Errori 401, 403 e 503: cosa vogliono dire

**In una frase.** Tre numeri dicono dove si è fermata una richiesta: all'ingresso (401), sul permesso (403) o davanti a un servizio spento (503).

Un errore con un numero sembra un guasto. Quasi sempre è una risposta precisa: dice chi ha fermato la richiesta e perché. Saper leggere questi tre numeri evita di chiamare l'assistenza quando basta rientrare o aspettare un minuto.

<table id="bkmrk-numero-vuol-dire-cos"><thead><tr><th>Numero</th><th>Vuol dire</th><th>Cosa fai</th></tr></thead><tbody><tr><td>**401**</td><td>Il Gateway non sa chi sei: il lasciapassare manca o è scaduto</td><td>Rientra con utente e password</td></tr><tr><td>**403**</td><td>Sei entrato, ma il tuo livello non basta per quella cosa</td><td>Chiedi il livello a chi amministra</td></tr><tr><td>**503**</td><td>Il servizio che deve rispondere non è acceso o non è ancora pronto</td><td>Aspetta un minuto e riprova</td></tr></tbody></table>

**401: rientra.** L'app ti riporta da sola alla pagina di accesso. Scrivi utente e password e riprendi.

![La pagina di accesso: è qui che l'app ti riporta dopo un errore 401](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-pagina-di-accesso-e-qui-che-lapp-ti-riporta-dopo-un-errore-401.png)

*La pagina di accesso: è qui che l'app ti riporta dopo un errore 401*

**403: è una questione di livello.** Compare l'avviso **Accesso negato**. Non è un guasto e riprovare non serve: quella operazione chiede un livello più alto del tuo. Chi amministra può dartelo dalla pagina dei ruoli. I livelli sono in Cosa può fare ogni livello (libro «JB - Accesso e permessi», pagina «JB3.2 - Cosa può fare ogni livello»).

**503: aspetta un minuto.** Compare l'avviso **Errore server 503**. Il Gateway funziona, ma il servizio a cui è destinata la richiesta non è nell'elenco del Monitor servizi. Subito dopo un aggiornamento è normale: i servizi stanno ripartendo e si iscrivono uno alla volta. Se dopo qualche minuto l'errore c'è ancora, avvisa chi gestisce il server e di' quale pagina stavi aprendo: basta per capire quale servizio è fermo.

<p class="callout info">**Nota.** Il 401 e il 503 li decide il Gateway. Il 403 lo decide il servizio che riceve la richiesta, perché è lui che sa quale livello serve per ogni operazione.</p>

<p class="callout info">**Per chi sviluppa.**  
• Gli avvisi li mostra `frontend/shell/src/shared/auth/error.interceptor.ts`: 401 porta a `/auth/login`, 403 dà «Accesso negato», da 500 in su «Errore server» con il numero.  
• 401 con un lasciapassare che sembra buono: controlla emittente, chiavi e `SSO_CLIENT_AMMESSI` (`docs/devops/auth/AUTENTICAZIONE.md`).  
• 401 fra due servizi: la chiamata non porta il lasciapassare. Le regole sono in `docs/devops/chiamate-fra-servizi.md`.  
• 502 al posto di 503: è fermo il Gateway, non un servizio. </p>

# JC4.3 - Se qualcosa non va

**In una frase.** I problemi più comuni con Gateway e Monitor servizi, come «vedo questo, faccio questo», e le parole da sapere.

Quando una pagina non risponde, la domanda utile è: dove si è fermata la richiesta? Il numero dell'errore lo dice quasi sempre. Qui trovi cosa fare caso per caso.

## Per chi usa il gestionale

- **Mi ritrovo alla pagina di accesso mentre lavoravo.** Il lasciapassare non vale più. Rientra: è l'errore 401.
- **Vedo «Accesso negato».** Il tuo livello non basta per quella operazione. Chiedi a chi amministra: è l'errore 403.
- **Vedo «Errore server 503» subito dopo un aggiornamento.** I servizi stanno ripartendo. Aspetta un minuto e riprova.
- **Vedo «Errore server 503» su una cosa sola, per esempio le stampe.** È fermo quel servizio. Il resto puoi usarlo. Avvisa chi gestisce il server.
- **Vedo «Server non raggiungibile» o «Errore server 502».** Non risponde il Gateway, oppure è caduta la rete. Controlla la connessione, poi avvisa chi gestisce il server.
- **Le pagine nuove non vanno, le maschere storiche sì.** Può succedere: fanno due strade diverse. Il problema è dalla parte del Gateway.

I tre numeri sono spiegati in [Errori 401, 403 e 503: cosa vogliono dire](https://gsdoc.genesyssoftware.eu/link/37807).

## Per chi gestisce il server

- **Un servizio dà 503 e non passa.** Apri la pagina del Monitor servizi e guarda se è nell'elenco: vedi [Vedere quali servizi sono accesi](https://gsdoc.genesyssoftware.eu/link/37804). Se manca, guarda il registro di quel servizio: non è partito o non raggiunge il Monitor servizi.
- **Tutti i servizi danno 503.** Controlla che il Monitor servizi sia acceso. Senza di lui i servizi non riescono a iscriversi.
- **Tutti ricevono 401, anche appena entrati.** Il Gateway non riesce a verificare i lasciapassare: controlla gli indirizzi dell'Accesso nella configurazione. Se mancano, li rifiuta tutti.
- **Dal mio PC la pagina del Monitor servizi non si apre.** È voluto: si apre solo dal server.
- **Un servizio spento compare ancora nell'elenco.** Il Monitor servizi aspetta prima di cancellarlo.

## Parole da sapere

- **Gateway.** La porta unica: controlla chi sei e manda ogni richiesta al servizio giusto.
- **Monitor servizi.** L'elenco dei servizi accesi, con nome e indirizzo.
- **Servizio.** Un programma che fa una cosa sola: le stampe, i dati del gestionale, le schermate.
- **Richiesta.** Una domanda che la pagina fa a un servizio: «dammi questa tabella», «salva questo».
- **Rotta.** La regola del Gateway che lega l'inizio di un indirizzo a un servizio.
- **Lasciapassare.** La prova che sei entrato: lo firma l'Accesso, dice chi sei e che livello hai, scade dopo poco.
- **Livello.** Quello che puoi fare: lettore, base, avanzato, staff.
- **Iscriversi.** Quello che fa un servizio quando si accende: dice al Monitor servizi «sono qui».
- **Ponte col COBOL.** L'altra strada: porta le maschere storiche nel browser, senza passare dal Gateway.

<p class="callout info">**Per chi sviluppa.** Lo stato si controlla con `/actuator/health` su Gateway e servizi. Variabili e porte: `docs/devops/ENVIRONMENT.md` e `devops/deploy/README.md`.</p>