## In breve Quando SegnalaCi manda una segnalazione al CzRM del Comune e l'invio non riesce, il messaggio viene rimesso in coda e riprovato più tardi dal [retry-orchestrator](https://gitlab.com/opencity-labs/retry-orchestrator). È il comportamento giusto per i problemi passeggeri: un rallentamento di rete, il CzRM momentaneamente irraggiungibile. Oggi però il messaggio che consegniamo alla coda non dice **di che tipo di errore si tratta**. L'orchestratore vede un payload opaco: sa quante volte l'ha già rigiocato, ma non sa distinguere un intoppo passeggero da un problema che non si risolverà mai da solo — per esempio un dato che il CzRM rifiuta perché risulta già presente su un'altra utenza. **Nessuna segnalazione va persa**: restano tutte in coda, e quando i tentativi previsti dalla policy si esauriscono finiscono nella DLQ. Il problema è che né una persona né una policy possono trattare diversamente i due casi, perché il dato per distinguerli non viaggia nel messaggio. Un esempio misurato durante il collaudo: una singola segnalazione riprovata **16 volte in 4 giorni**, con attese progressive fino a 12 ore, sempre fallendo allo stesso modo. ## Cosa facciamo in questa issue Aggiungiamo a `retry_meta` due informazioni che **solo Ticketron può produrre**: | Campo | A cosa serve | |-------|--------------| | `error_kind` | capire se il problema può risolversi da solo oppure no | | `first_failed_at` | sapere da quanto tempo un caso è fermo | Questa issue si ferma qui: **aggiunge i dati al messaggio, non cambia cosa succede ai messaggi.** È la parte interamente sotto il nostro controllo, e senza quei dati nessuna decisione successiva — automatica o manuale — è esprimibile. Non è un lavoro di monitoraggio: non introduce metriche, cruscotti o allarmi. Il contenuto arricchito viaggia nel messaggio ed è destinato a chi lo riprocessa. ## Cosa NON facciamo qui, e perché - **Il contatore dei tentativi.** Lo mantiene già l'orchestratore: il suo dispatcher scrive e incrementa `retry_meta.retry_counter` a ogni passaggio. Aggiungerne uno nostro significherebbe due contatori con semantiche diverse sullo stesso oggetto. - **Fermare i tentativi infiniti.** È già implementato: `RetrieveDestinationTopic` instrada verso la DLQ quando il counter supera la somma della policy. I 16 tentativi in 4 giorni sono un valore di `KAFKA_DISPATCHER_POLICY`, cioè una configurazione, non una funzione mancante. - **Sistemare i casi già bloccati oggi.** Alcune utenze del CzRM hanno dati disallineati che nessuna modifica al codice può correggere: serve un intervento manuale sul CzRM, concordato con l'ente. Tracciato separatamente. ## Da verificare prima di iniziare Questa issue nasceva dall'assunto che il caso più frequente di errore definitivo — il rifiuto del codice fiscale già presente su un'altra utenza — fosse stato risolto dalla MR !104. I dati di produzione successivi al rilascio 1.1.2 mostrano che quell'errore continua a presentarsi a un ritmo di circa 33 casi al giorno. **Va accertato se la !104 non copra quel caso o se esista una seconda causa**, perché cambia la stima di quanti casi bloccati ci aspettiamo. ## Criteri di accettazione * Dal messaggio in coda è possibile sapere se l'errore è passeggero o definitivo * Dal messaggio in coda è possibile sapere da quando il caso è fermo * Il `retry_meta` scritto dall'orchestratore dopo il primo hop **non** viene alterato da Ticketron * Il comportamento attuale non cambia: nessun messaggio viene scartato, tutto continua a essere rimesso in coda come oggi ## Test Test **automatici**, unit test Go sul pacchetto che costruisce il messaggio di retry e sugli handler che lo producono. La strategia è a tabella: per ogni caso si costruisce un messaggio di ingresso noto, si forza l'errore corrispondente e si verifica il payload prodotto campo per campo, non solo l'assenza di errori. I casi di guasto sistemico usano un client CzRM che restituisce l'errore voluto. - [ ] Un messaggio che fallisce per la prima volta esce dalla coda con `error_kind` valorizzato e `first_failed_at` impostato - [ ] Un messaggio che porta già un `retry_meta` esce **invariato**: né i campi nuovi né quelli dell'orchestratore vengono riscritti - [ ] Un errore passeggero (timeout, errore 5xx del CzRM) risulta classificato come tale - [ ] Un errore definitivo (400 su dato duplicato) risulta classificato come tale - [ ] **Guasto sistemico**: con credenziali errate — che il sistema classifica come errore definitivo — i messaggi continuano a essere rimessi in coda e **non** vengono scartati - [ ] I messaggi al primo passaggio continuano a portare l'indicazione del topic di origine, come oggi - [ ] I messaggi processati con successo non contengono nessuno dei campi nuovi --- ## Dettaglio tecnico <details> <summary>Espandi</summary> ### Origine Follow-up di #80 e della MR !104, dove il punto era stato analizzato e lasciato fuori scope per non ritardare il collaudo in corso. `sendSegnalazioneToCzrm` e gli altri handler impostano `shouldPutMessagetoRetryQueue = true` su **ogni** ramo d'errore, senza consultare `httperr.Classify`. `Classify` è stato introdotto dalla !104 e ulteriormente esteso dalla !109, quindi il dato per decidere ora esiste — ma non viene propagato a valle. ### Chi consuma il topic di retry Il re-inject vive nel repository [`opencity-labs/retry-orchestrator`](https://gitlab.com/opencity-labs/retry-orchestrator) (Go, in produzione, 1.0.3). Il suo dispatcher legge il nostro topic, incrementa `retry_meta.retry_counter`, calcola `next_attempt_at` e instrada il messaggio su un topic di attesa scelto in base a `KAFKA_DISPATCHER_POLICY`; il retry handler attende e **rimette il messaggio sul topic indicato da `retry_meta.original_topic`**, dove Ticketron lo riprocessa. Esaurita la policy, il messaggio va nella DLQ. Questo chiude la domanda aperta il 4 settembre su `stanzadelcittadino-application-registry`: il suo `RETRY_SCHEDULER_DESTINATION_TOPIC` è un topic singolo (`applications` in produzione) e non rispetta `original_topic`, quindi non è il componente che rigioca i messaggi di Ticketron. ### Modifica richiesta Aggiungere a `retry_meta` i campi `error_kind` e `first_failed_at`, accanto all'esistente `original_topic`. **`BuildMessageWithRetryMetaField` va lasciato com'è** nel ramo che restituisce il messaggio invariato quando `retry_meta` è già presente: ```go if _, ok := message["retry_meta"]; !ok { // ... aggiunge original_topic return byteMessage } return m // <- corretto: dopo il primo hop il retry_meta è dell'orchestratore ``` Una precedente stesura di questa issue indicava quel ramo come un bug da correggere per primo. È l'opposto: se Ticketron riscrivesse un `retry_meta` esistente, il `checkRetryCounterValidity` del dispatcher — che tiene una cache su `event_id` e rifiuta gli eventi il cui counter non avanza — scarterebbe il messaggio con errore. I campi nuovi vanno scritti **solo** nel ramo del primo fallimento. ### Perché non basta "non rimettere in coda gli errori definitivi" Era la formulazione originale di questa issue ed è stata scartata per due ragioni: 1. `applicationEventHandler.ProcessMessage()` ritorna sempre `nil`, quindi l'offset viene comunque committato: il topic di retry è l'unica cosa che tiene in vita il messaggio. Non produrlo significa perdita definitiva della segnalazione di un cittadino. 2. I guasti **sistemici** si presentano come `Permanent`: un 400 sull'endpoint token per credenziali errate, un 404 su scrittura per `CZRM_BASENAME` o `CZRM_API_VERSION` sbagliati. Con una regola secca, durante un incidente di configurazione si scarterebbero in silenzio tutte le segnalazioni in transito. Anche gli errori sintetici come `errors.New("no case id")` sono `Permanent` per default. ### Dati personali e retention Non vengono introdotti topic nuovi: i campi si aggiungono al `retry_meta` di messaggi già esistenti. I due campi aggiunti (`error_kind`, `first_failed_at`) sono metadati tecnici e non contengono dati personali. Il payload che li ospita contiene però i dati della segnalazione del cittadino, come già oggi: la modifica non amplia il perimetro dei dati trattati. ### Nota sui numeri Il conteggio originale di _128 fallimenti in 4 giorni su 18 record CzRM distinti_ è stato ricavato dai log di QA, dove girano anche le esecuzioni notturne della e2e: parte di quei fallimenti può venire dai fixture di test. Il meccanismo diagnosticato resta valido — le due segnalazioni tracciate riga per riga non cambiano — è il numero aggregato a essere inaffidabile. Metodo per ricavare il valore reale in #83. </details>