## User stories 1. Come **cittadino** di un ente che usa l'intermediario LinkNext/EntraNext voglio **pagare online gli avvisi PagoPA** in modo da **non dover accedere a un portale esterno per completare il pagamento**. 2. Come **amministratore** di un ente voglio **configurare l'intermediario LinkNext/EntraNext (credenziali, sottoservizi, voci di costo) dall'area di amministrazione** in modo da **abilitare i pagamenti senza richiedere un intervento tecnico**. 3. Come **operatore** voglio che **lo stato dei pagamenti si aggiorni automaticamente in base all'esito comunicato dall'intermediario** in modo da **avere una rendicontazione sempre allineata senza controlli manuali**. 4. Come **cittadino** voglio **vedere e pagare in Opencity anche le posizioni debitorie pendenti già presenti sull'intermediario** (non nate da una mia pratica sulla piattaforma) in modo da **avere un unico punto in cui vedere e saldare tutto ciò che devo, senza dover consultare portali diversi**. ## Descrizione del problema Oggi la piattaforma Area Personale non supporta l'intermediario di pagamento **LinkNext/EntraNext** (fornito da **Next Step Solution**), utilizzato da alcuni enti per la gestione delle posizioni debitorie e dei pagamenti PagoPA tramite WISP. Gli enti che adottano questo intermediario non possono essere abilitati ai pagamenti su Opencity: le pratiche che generano una posizione debitoria non trovano un payment-proxy compatibile. Sono impattati gli **enti clienti** che usano Next Step Solution e, di conseguenza, i **cittadini** che non possono pagare gli avvisi PagoPA direttamente dalla piattaforma e devono ricorrere a un portale esterno. > **Nota di classificazione (epica Maintenance Q3) — decisione del Prodotto.** L'attività è mantenuta nell'epica Maintenance Q3 in quanto estende una capacità **già esistente** della piattaforma — i connettori di pagamento in area personale — a un nuovo provider. Non introduce un nuovo flusso utente: sia il pagamento online (modello 1) sia l'import delle posizioni debitorie al login sono pattern già in produzione per gli altri intermediari (Efil, MyPay, JPPA). Il lavoro è replicare quel pattern consolidato per LinkNext/EntraNext, non progettare un nuovo flusso di dominio. ## Descrizione della soluzione Sviluppare un nuovo payment-proxy **`linknext-payment-proxy`** sul modello dei payment-proxy esistenti (advanced-systems, iris, silfi, mypay, ecc.), che copra **due casi d'uso**: > **Implementazione di riferimento (golden standard).** Gli altri payment-proxy sono stati sviluppati tempo fa, quando diverse pratiche (osservabilità completa, convenzione metriche `oc_payments_*`, DoD sicurezza, gestione segreti, CloudEvents) non erano ancora consolidate. Questo servizio va costruito come **implementazione di riferimento** della fleet: replica funzionalmente il pattern esistente, ma alza l'asticella qualitativa e diventa lo standard a cui allineare il **refactoring futuro** degli altri proxy. Ogni scelta (struttura repo, metriche, naming, test, sicurezza) va fatta pensando alla sua riusabilità come modello. **Caso d'uso A — Pagamento online generato da Opencity (flusso "push")** - consuma gli eventi dal topic Kafka `payments` e, per ogni evento, crea la posizione debitoria sull'intermediario; - implementa il flusso già verificato in fase di collaudo: 1. **Login** → ottiene il `bearer_token`; 2. **Inserisci Posizioni In Attesa** → ottiene `IdentificativoTransazione` e URL di redirect verso il WISP PagoPA; 3. _(il cittadino paga sul WISP e rientra sul callback)_; 4. **Ricevi Esito Transazione** → recepisce l'esito; 5. **Verifica Posizione** → polling periodico sullo stato, per allineare lo stato anche quando il cittadino non torna sul callback; - gestisce il download dei **documenti** (avviso PagoPA, ricevuta telematica RT). **Caso d'uso B — Import delle posizioni debitorie già esistenti sull'intermediario (flusso "pull")** Alcune posizioni debitorie esistono già sull'intermediario ma sono ancora **pendenti** e non sono nate da una pratica in Opencity. Il proxy deve poterle **importare** e allineare in Opencity, sul modello dell'endpoint `POST /update-user-dues` di `mypay-payment-proxy`: - espone un endpoint API che, dato un `tenant_id` e un **codice fiscale del contribuente**, interroga l'intermediario con **"Ricevi Posizioni Debitorie"** (la collection copre le varianti: solo attive, attive + pagate, filtro per sottoservizio); - per ciascuna posizione restituita, **crea o aggiorna** il pagamento corrispondente in SdC (dedup per identificativo posizione/IUV) e **produce l'evento** sul topic `payments`; - restituisce un **summary** dell'operazione: `fetched`, `processed`, `inserted`, `updated`, `not_processed` (+ lista), con `correlation_id`/`source` per il tracciamento. **Innesco (per ora on-demand al login del cittadino):** al login del cittadino viene emesso un evento su Kafka; un **servizio esterno** lo consuma e chiama l'endpoint di import del proxy con il `tenant_id` e il codice fiscale del cittadino. Il proxy quindi **espone l'API di import** e non consuma direttamente l'evento di login — l'orchestrazione dell'innesco è responsabilità del servizio esterno. La sincronizzazione periodica non è in scope per ora. **Comuni a entrambi i casi:** API di configurazione per tenant / servizi / schema, coerenti con gli altri proxy. ### Contratti API dell'intermediario (base_url = ambiente) Autenticazione via `bearer_token` ottenuto dal login; tutte le chiamate successive lo inviano nell'header `Authorization`. | \# | Metodo | Path | Parametri chiave | |----|--------|------|------------------| | Login | `POST` | `/linknext/login` | body: `Identificativo`, `IdentificativoConnettore`, `Versione`, `Username`, `Password` → restituisce `AuthToken`/`bearer_token` | | Sottoservizi ente | `GET` | `/linknext/sottoservizi` | — | | Voci di costo | `GET` | `/linknext/vocidicosto/{codice_sottoservizio}` | path: `codice_sottoservizio` | | **Inserisci posizioni (modello 1)** | `POST` | `/linknext/carrello/posizioni` | body: `UrlBack`, `UrlReturn`, `UrlNotificaRT`, `PagamentoDifferito`, `ModalitaTest`, `PosizioniDebitorie` → restituisce `IdentificativoTransazione` + URL redirect WISP | | **Esito transazione** | `POST` | `/linknext/carrello/esito` | body: `IdentificativoTransazione` | | Verifica posizione (per pratica) | `GET` | `/linknext/posizione/Gestionale/{riferimento_pratica_esterna}` | path: `riferimento_pratica_esterna` | | Verifica posizione (per IUV) | `GET` | `/linknext/posizione/IUV/{iuv}` | path: `iuv` | | **Ricevi posizioni debitorie (import)** | `POST` | `/linknext/soggetto/posizioni` | body: `CodiceFiscale`, `FiltroStati`, `FiltriSottoServizi` (opz.), `PagedRequest` | | Avviso PagoPA | `GET` | `/linknext/posizione/documento/Gestionale/{riferimento_pratica_esterna}/pagopa` | path: `riferimento_pratica_esterna` | | Documento PDF posizione | `GET` | `/linknext/posizione/documento/Gestionale/{riferimento_pratica_esterna}` | path: `riferimento_pratica_esterna` | | RT per pagamento | `GET` | `/linknext/pagamenti/rt/{idPagamento}` | path: `idPagamento` | | RT per posizione | `GET` | `/linknext/pagamenti/rt/Gestionale/{riferimento_pratica_esterna}` | path: `riferimento_pratica_esterna` | I flussi critici usano: **creazione posizione** → `POST /linknext/carrello/posizioni`; **verifica stato** → `GET /linknext/posizione/...`; **ricezione esito** → `POST /linknext/carrello/esito`; **import** → `POST /linknext/soggetto/posizioni`. ## Criteri di accettazione _(Da validare con il Product Manager prima dell'inizio dello sviluppo: sono il contratto su cosa significa "fatto".)_ - Un pagamento generato da una pratica su un ente configurato con LinkNext/EntraNext produce una posizione debitoria valida sull'intermediario e restituisce l'URL di redirect verso il WISP PagoPA. - Al rientro dal WISP l'esito della transazione viene recepito e lo stato del pagamento nella Stanza del Cittadino riflette l'esito reale (pagato / non pagato). - Il polling periodico sullo stato della posizione mantiene allineato lo stato del pagamento anche quando il cittadino non torna sul callback. - Per una posizione pagata sono scaricabili l'avviso PagoPA e la ricevuta telematica (RT). - La configurazione dell'ente (sottoservizi, voci di costo) è recuperabile e utilizzabile nella creazione del pagamento. - Richiedendo l'import per un codice fiscale, le posizioni debitorie pendenti presenti sull'intermediario compaiono in SdC come pagamenti pagabili; l'operazione è idempotente (rieseguendola non si creano duplicati, le posizioni già note vengono aggiornate) e restituisce un riepilogo con quante posizioni sono state recuperate, inserite e aggiornate. ## Casi di test _API: i test sono automatici (hurl); qui va inserito il link alla pipeline e la spunta di verifica da parte di un collega developer._ _Servizio di test:_ https://servizi.comune-qa.bugliano.pi.it/lang/it/servizi/pagamento-immediato-linknext/access - [ ] La creazione di una posizione debitoria online va a buon fine - Produrre un evento sul topic `payments` per un ente configurato con LinkNext/EntraNext - Verificare che il proxy invochi "Inserisci Posizioni In Attesa" e ottenga `IdentificativoTransazione` + URL di redirect WISP - [ ] Un esito "pagato" aggiorna correttamente lo stato del pagamento - [ ] Il polling recupera lo stato quando il cittadino non torna sul callback _(caso limite)_ - Una volta completato il pagamento chiudere la finestra del browser - Attendere il ciclo di polling (circa 15 minuti) e verificare venga allineato lo stato del pagamento - [ ] L'avviso PagoPA e la RT sono scaricabili per una posizione pagata - [ ] Credenziali di autenticazione errate sono gestite senza creare posizioni _(caso limite)_ - Configurare credenziali errate - Verificare che l'errore sia gestito e che nessuna posizione venga creata - [ ] ~~L'import delle posizioni pendenti di un cittadino crea i pagamenti in SdC~~ - ~~Predisporre sull'intermediario alcune posizioni debitorie pendenti per un codice fiscale~~ - ~~Invocare l'endpoint di import con `tenant_id` + codice fiscale~~ - ~~Verificare che le posizioni siano recuperate ("Ricevi Posizioni Debitorie"), i pagamenti creati e gli eventi prodotti su `payments`, e che il summary riporti `fetched`/`inserted` corretti~~ - [ ] ~~L'import è idempotente su posizioni già importate _(caso limite)_~~ - ~~Rieseguire l'import sullo stesso codice fiscale~~ - ~~Verificare che non si creino duplicati e che le posizioni già note risultino `updated`, non `inserted`~~ - [ ] ~~L'import di un codice fiscale senza posizioni pendenti non produce nulla _(caso limite)_~~ - ~~Verificare risposta con summary a zero e nessun evento prodotto~~ - [ ] **~~End-to-end (cittadino):~~** ~~al login il cittadino vede in area personale tutti i propri pagamenti pendenti~~ - ~~Predisporre sull'intermediario alcune posizioni debitorie pendenti per il codice fiscale di un cittadino di test~~ - ~~Fare **login** in area personale come quel cittadino sull'ambiente di QA~~ - ~~Verificare che la catena di innesco funzioni end-to-end (evento di login → servizio esterno → import del proxy) e che **tutte** le posizioni pendenti compaiano tra i pagamenti pagabili in area personale, senza duplicati~~ ## Rischi di sicurezza Questa issue introduce una nuova superficie di attacco (nuovo microservizio + gestione auth/segreti) e va trattata come `security`. **Superfici identificate e mitigazioni:** - **Autenticazione e gestione dei segreti** — il proxy si autentica sull'intermediario con `username`/`password` dell'ente per ottenere un `bearer_token`. Queste credenziali sono salvate come parte della **configurazione del tenant** in un file JSON dentro un **bucket S3 protetto**; l'accesso al bucket avviene con credenziali AWS che a loro volta sono cifrate/iniettate tramite **Docker secrets** (pattern in uso sulla fleet). Le credenziali non vanno mai in chiaro nei log e il `bearer_token` non va persistito nei log. - **Trattamento di dati personali** — il payload tratta il **codice fiscale del contribuente** e i riferimenti di pratica (dati personali non aggregati). Mitigazioni: nessun PII nei log, TLS verso l'endpoint, minimizzazione dei dati trasmessi. - **Nuova esposizione di rete** — chiamate in uscita verso `*.entranext.it` e ricezione di un **callback di esito** in ingresso. Il callback non deve essere considerato fonte di verità da solo: prima di marcare una posizione come pagata, l'esito va **riverificato lato server** tramite "Verifica Posizione" con l'`IdentificativoTransazione`, per evitare aggiornamenti di stato non autorizzati. - **Endpoint di import per codice fiscale** — l'endpoint del caso B accetta un codice fiscale e restituisce/importa tutte le posizioni debitorie di quel soggetto: se non protetto, consente l'**enumerazione delle posizioni debitorie altrui** (esposizione di dati personali/IDOR). Deve essere accessibile solo a chiamanti autorizzati (autenticazione servizio-servizio / poller interno), non esposto pubblicamente, con logging degli accessi. **Controlli di sicurezza obbligatori (DoD Sicurezza — nuova superficie di attacco):** - Solo i metodi HTTP dichiarati sono usabili sugli endpoint di configurazione (verifica con Nuclei); - Gli endpoint protetti rispondono `401`/`403` se chiamati senza autenticazione; - I tentativi di accesso falliti sono loggati a livello `warning`; - Metriche di errore di sicurezza esposte con label distinte: chiamate con verbi proibiti, chiamate non autenticate, errori 403; - Snyk su Dockerfile e dipendenze: nessun `critical`/`high` con exploit noto; - DAST con Nuclei sull'ambiente QA e secret scanner (deepfence) puliti. ## Osservabilità Il servizio espone metriche Prometheus secondo la **convenzione fleet `oc_payments_*`** condivisa da tutti i payment-proxy: naming comune, provider distinto **solo** dalla label `app_name`, nomi disaccoppiati da protocollo (SOAP/REST) e da tecnologia sostituibile. Essendo un servizio **nuovo**, si applicano da subito i nomi corretti — nessun dual-emit né debito da migrare. La dashboard Grafana riusa i pannelli della fleet filtrando per `app_name=linknext-payment-proxy`. Label base: `env`, `app_name=linknext-payment-proxy`. Metriche minime da esporre: - **HTTP (`oc_payments_http_*`)** — fonte canonica, non delegata all'exporter del framework: - `oc_payments_http_requests_total{method,path_template,status_code}` — Traffic + Errors (include i `401`/`403` richiesti dalla DoD Sicurezza; `path_template`, mai il path con id valorizzato); - `oc_payments_http_request_duration_seconds{method,path_template}` — Latency; - `oc_payments_http_inflight_requests` — Saturation. - **Provider LinkNext/EntraNext (`oc_payments_provider_*`)** — label `operation` dalla tassonomia comune, `error_type` enum chiuso (`rejected|timeout|connection|protocol_error`); il codice di errore nativo dell'intermediario va nei log strutturati, non in label: - `oc_payments_provider_requests_total{operation,result}`, `oc_payments_provider_latency_seconds{operation}`, `oc_payments_provider_errors_total{operation,error_type}`, `oc_payments_provider_inflight_requests{operation}`. - Mapping endpoint → `operation`: `POST /carrello/posizioni` → `create`; `POST /carrello/esito` → `verify`; `GET /posizione/...` → `check_status`; `POST /soggetto/posizioni` → `query_positions`; `GET /posizione/documento/.../pagopa` → `get_notice`; `GET /pagamenti/rt/...` → `get_receipt` (login/versione: tracciate come chiamate HTTP in uscita, fuori dall'enum di business). - **Kafka (`oc_payments_kafka_*`)** — priorità alta (gap più critico sui proxy attuali): - `oc_payments_kafka_messages_consumed_total{topic,event_version,result}`, `oc_payments_kafka_messages_produced_total{topic,result}` (evita il fallimento silenzioso nel produce), `oc_payments_kafka_event_processing_duration_seconds{outcome}`, `oc_payments_kafka_consumer_lag{topic,partition}` (Saturation, critico). - **Storage config (`oc_payments_storage_*`)** se le configurazioni tenant/servizio usano MinIO/S3. - **Cache (`oc_payments_cache_*`)** — se il proxy cachea le letture dei pagamenti (pattern della fleet, es. Redis su mypay); nome disaccoppiato dal backend: - `oc_payments_cache_operations_total{operation,result}` (`operation`=`get|set|invalidate`, `result`=`hit|miss|error`) — Traffic/Errors; - `oc_payments_cache_operation_duration_seconds{operation}` — Latency. Senza queste, un backend cache down è indistinguibile da un normale cache miss. - **Readmodel (`oc_payments_readmodel_*`)** — se il proxy legge da un readmodel (ksqlDB/Directus); nome disaccoppiato dal backend: - `oc_payments_readmodel_query_duration_seconds{query_type}` (`single|bulk`) — Latency; - `oc_payments_readmodel_errors_total{error_type}` (`timeout|http_error|parse_error`) — Errors; - `oc_payments_readmodel_healthy` (gauge 0/1) — Saturation. ## Eventi Kafka (OpenCity Platform Events) Il proxy **consuma** e **produce** sul topic `payments` (topic esistente, non nuovo). In conformità alla convenzione OpenCity Platform Events: - **PII nel payload**: **sì**. Gli eventi di pagamento contengono il **codice fiscale del contribuente** (dato personale non aggregato), presente sia nel flusso di import (caso B) sia nei pagamenti generati dalla Stanza. Va trattato come tale (no PII nei log, TLS, minimizzazione) e va confermata la base giuridica/retention lato piattaforma. - **Retention del topic `payments`**: **5 anni**. Il codice fiscale del contribuente (PII) resta quindi sul topic per l'intero periodo: la gestione dei log e delle copie applicative deve tenerne conto (no PII nei log, minimizzazione). - **Schema e contratto**: gli eventi seguono l'envelope CloudEvents (`ce_type` = `it.opencity.payments.<domain>.<event>`, `ce_source` = `urn:opencity:payments:<tenant-uuid>`); aggiornare l'`asyncapi.yml` del servizio e pubblicare/riusare lo schema JSON del payload su `schemas.opencityitalia.it` con versione (`v1`, `v2`, …). ## Dettagli **Setup repo (nuovo microservizio — standard aziendale):** - [ ] Bootstrap del repo `linknext-payment-proxy` dal template payment-proxy, visibilità pubblica - [ ] File obbligatori: `README.md` (10 punti), `LICENSE` AGPL-3.0, `Dockerfile` (FROM via dependency proxy + OCI labels), `docker-compose.yml` con dati di test, `.gitlab-ci.yml` con `include` di `devops.yml` - [ ] `SNYK_ENABLED=true` nelle variabili CI + policy di cancellazione immagini non taggate **Sviluppo:** - [ ] Consumer Kafka del topic `payments` → creazione posizione debitoria (caso A) (routing per tenant via header CloudEvents `ce_source`/`ce_type`; `tenant-uuid` da variabile d'ambiente, non hardcoded) - [ ] Endpoint di **import posizioni debitorie** (caso B): input `tenant_id` + codice fiscale → "Ricevi Posizioni Debitorie" → create/update pagamenti (dedup per identificativo/IUV) + produzione eventi su `payments` + summary - [ ] Client API intermediario: login, inserisci posizioni, ricevi esito, verifica posizione, ricevi posizioni debitorie, documenti - [ ] API di configurazione tenant / servizi / schema, documentate in OpenAPI e validate con OAS Checker senza errori - [ ] Gestione dei segreti (credenziali ente): configurazione tenant in JSON su bucket S3 protetto; credenziali di accesso al bucket cifrate via Docker secrets (pattern della fleet) - [ ] Gli eventi di pagamento prodotti su Kafka (import e aggiornamenti di stato) seguono la convenzione CloudEvents (`ce_type` = `it.opencity.payments.<domain>.<event>`, `ce_source` con `tenant-uuid`) **Test & QA:** - [ ] Test API automatici (hurl) in `tests/` + stage CI end-to-end verde - [ ] Deploy in QA con tutte le condizioni di test predisposte dal developer - [x] Documentazione su Gitbook (docs.opencityitalia.it): https://app.gitbook.com/o/-MRQtav6dxPB0RkAwAX7/sites/site_j0AUY/s/3Lijwdi7sVujjCdIagU2/~/edit/~/changes/328/integrazioni/pagamenti **Production readiness (primo deploy del servizio):** - [ ] Build multipiattaforma CI (x86 e arm) - [ ] Docker healthcheck configurato (usato da Traefik per il blue/green) - [ ] Errori inviati a Sentry con ambiente e versione corretti - [ ] Alert Slack configurati (`#alerts` critici, `#test` warning) ## Definition of Done Trattandosi di un nuovo microservizio con API, nuova superficie di attacco e primo deploy in produzione, si applicano integralmente le DoD aziendali: **DoD API**, **DoD Sicurezza**, **Production readiness** e **Changelog** (scritto dalla prospettiva di operatore/cittadino/admin). La issue è _done_ solo se tutti i criteri applicabili sono soddisfatti; in caso contrario torna in backlog, non si chiude.