Refactor/UI ux

.github/workflows/ci.yml

@@ -523,13 +523,16 @@ jobs:
         run: docker compose --profile tools run --rm node npm ci --ignore-scripts
 
       - name: Smoke SPA with enforced CSP
-        run: docker compose --profile tools run --rm frontend-audit node scripts/a11y/csp-smoke.mjs https://traefik:8443
+        run: docker compose --profile tools run --rm frontend-audit node scripts/a11y/csp-smoke.mjs
+          https://traefik:8443/overview https://traefik:8443/assistant https://traefik:8443/copilot
 
       - name: Run axe
-        run: docker compose --profile tools run --rm frontend-audit node scripts/a11y/axe-playwright.mjs https://traefik:8443
+        run: docker compose --profile tools run --rm frontend-audit node scripts/a11y/axe-playwright.mjs
+          https://traefik:8443/overview https://traefik:8443/assistant https://traefik:8443/copilot
 
       - name: Run Pa11y
-        run: docker compose --profile tools run --rm frontend-audit node scripts/a11y/pa11y-runner.mjs https://traefik:8443
+        run: docker compose --profile tools run --rm frontend-audit node scripts/a11y/pa11y-runner.mjs
+          https://traefik:8443/overview https://traefik:8443/assistant https://traefik:8443/copilot
 
       - name: Collect stack diagnostics
         if: failure()

Makefile

@@ -16,7 +16,18 @@ TERRAFORM := docker compose --profile tools run --rm -T terraform
 NODE := docker compose --profile tools run --rm -T node
 AWS_CLI := docker compose --profile tools run --rm -T --entrypoint aws aws-cli --endpoint-url=$(LOCALSTACK_ENDPOINT_INTERNAL)
 FRONTEND_AUDIT := docker compose --profile tools run --rm -T frontend-audit
+# RVC9-OB chiede axe e Pa11y sulle interfacce utente principali, al plurale: la
+# sola root reindirizza su /overview e lascerebbe fuori le due pagine piu' dense.
+A11Y_URLS := https://traefik:8443/overview https://traefik:8443/assistant https://traefik:8443/copilot
 TLS_TOOL := docker compose --profile tools run --rm -T tls-tool
+# Pest viene invocato direttamente e con un limite di memoria esplicito, lo
+# stesso usato dal workflow CI. Con i 128M di default dell'immagine PHP la suite
+# esaurisce la memoria durante i test Feature e, poiche' display_errors e' Off,
+# il processo muore senza stampare nulla: si vede solo un exit 255, che diventa
+# uno 0 ingannevole appena l'output finisce in pipe verso tail o grep.
+# `artisan test` non basterebbe: avvia Pest in un sottoprocesso, a cui i flag -d
+# di questa invocazione non arrivano.
+PEST := php -d memory_limit=1G vendor/bin/pest
 TEST_ENV := -e CONFIG_SOURCE=env \
 	-e APP_ENV=testing \
 	-e CACHE_STORE=array \
@@ -81,7 +92,7 @@ verify-backend:
 	docker compose build app
 	docker compose run --rm --no-deps app composer validate --strict
 	docker compose run --rm --no-deps $(TEST_ENV) app php artisan route:list
-	docker compose run --rm --no-deps $(TEST_ENV) app php artisan test
+	docker compose run --rm --no-deps $(TEST_ENV) app $(PEST)
 	docker compose run --rm --no-deps app php vendor/bin/pint --test
 	docker compose run --rm --no-deps $(TEST_ENV) app sh -lc 'if [ -x vendor/bin/phpstan ]; then vendor/bin/phpstan analyse --memory-limit=1G; else echo "phpstan non installato in vendor: skip locale"; fi'
 	bash scripts/ci/check-dependency-rule.sh
@@ -105,13 +116,13 @@ verify-ci-local: verify-fast openapi-validate
 
 test:
 	docker compose build app
-	docker compose run --rm --no-deps $(TEST_ENV) app php artisan test
+	docker compose run --rm --no-deps $(TEST_ENV) app $(PEST)
 
 backend-coverage:
 	docker compose build app
 	mkdir -p coverage
 	chmod 0777 coverage
-	docker compose run --rm --no-deps -v "$(CURDIR)/coverage:/var/www/html/coverage" -e XDEBUG_MODE=coverage $(TEST_ENV) app php -d memory_limit=1G vendor/bin/pest --coverage --path-coverage --coverage-cobertura coverage/cobertura.xml
+	docker compose run --rm --no-deps -v "$(CURDIR)/coverage:/var/www/html/coverage" -e XDEBUG_MODE=coverage $(TEST_ENV) app $(PEST) --coverage --path-coverage --coverage-cobertura coverage/cobertura.xml
 	$(NODE) node scripts/ci/normalize-cobertura-paths.mjs coverage/cobertura.xml /var/www/html
 	$(NODE) node scripts/ci/check-coverage-thresholds.mjs backend coverage/cobertura.xml
 
@@ -164,9 +175,9 @@ frontend-audit: node-install
 frontend-a11y: frontend-s3-local-deploy
 	@if [ ! -f docker/traefik/certs/mvp-local.test.crt ] || [ ! -f docker/traefik/certs/mvp-local.test.key ]; then $(MAKE) local-tls; fi
 	docker compose up -d --wait --force-recreate app nginx edge-cdn traefik
-	$(FRONTEND_AUDIT) node scripts/a11y/csp-smoke.mjs https://traefik:8443
-	$(FRONTEND_AUDIT) node scripts/a11y/axe-playwright.mjs https://traefik:8443
-	$(FRONTEND_AUDIT) node scripts/a11y/pa11y-runner.mjs https://traefik:8443
+	$(FRONTEND_AUDIT) node scripts/a11y/csp-smoke.mjs $(A11Y_URLS)
+	$(FRONTEND_AUDIT) node scripts/a11y/axe-playwright.mjs $(A11Y_URLS)
+	$(FRONTEND_AUDIT) node scripts/a11y/pa11y-runner.mjs $(A11Y_URLS)
 
 openapi-generate: node-install
 	$(NODE) npm run openapi:generate

README.md

@@ -81,7 +81,7 @@ La state machine pubblica task su SQS usando il callback pattern con task token.
 
 Il risultato è una pipeline documentale composta da passaggi isolati, monitorabili e riavviabili, con persistenza dello stato e visibilità sui risultati prodotti.
 
-Sui sotto-documenti prodotti l’operatore lavora in revisione human-in-the-loop: corregge i campi estratti (inclusi email destinatario, codice fiscale e matricola, con validazione dedicata) e li marca come validati. Il dettaglio riporta anche l’email del destinatario, copiabile negli appunti con un comando, e la data e ora di caricamento del documento di origine. Da ogni sotto-documento il sistema compone un messaggio di invio precompilato con destinatario, oggetto e testo, che si può correggere, visualizzare in anteprima ed esportare in PDF. Il recapito avviene fuori dalla piattaforma tramite canali terzi: per questo lo stato di invio coincide con l’avvenuto **scaricamento** del PDF, e non con un invio effettuato dal sistema. Lo storico dei documenti è filtrabile per nome, cognome o azienda, stato di invio, soglia di confidenza e periodo, sempre con i criteri applicati lato API e limitati al tenant chiamante.
+Sui sotto-documenti prodotti l’operatore lavora in revisione human-in-the-loop: corregge i campi estratti (inclusi email destinatario, codice fiscale e matricola, con validazione dedicata) e li marca come validati. Il dettaglio riporta anche l’email del destinatario, copiabile negli appunti con un comando, e la data e ora di caricamento del documento di origine. Da ogni sotto-documento il sistema compone un messaggio di invio precompilato con destinatario, oggetto e testo, che si può correggere, visualizzare in anteprima ed esportare in PDF. Il recapito avviene fuori dalla piattaforma tramite canali terzi: per questo lo stato mostrato è quello di **scaricamento** («Scaricato» / «Non scaricato»), e non un invio effettuato dal sistema. Lo storico dei documenti è filtrabile per nome, cognome o azienda, stato di scaricamento, soglia di confidenza e periodo, sempre con i criteri applicati lato API e limitati al tenant chiamante.
 
 ## Monitoring e osservabilità
 

app/Console/Commands/ListDlqMessages.php

@@ -2,17 +2,24 @@
 
 namespace App\Console\Commands;
 
-use App\Mvp\Observability\MetricsRecorder;
 use Aws\Sqs\SqsClient;
 use Illuminate\Console\Command;
 
+/**
+ * Strumento di diagnosi, non punto di strumentazione: la profondita' della DLQ
+ * e' misurata da DlqDepthProbe a ogni scrape. Questo comando incrementava un
+ * counter `dlq_messages_total` che cresceva solo quando qualcuno lo lanciava a
+ * mano, con un tetto di 10 messaggi, e non tornava mai indietro — gli alert che
+ * ci si basavano erano quindi ciechi prima della prima esecuzione e bloccati in
+ * firing dopo.
+ */
 class ListDlqMessages extends Command
 {
     protected $signature = 'mvp:dlq:list {--queue=documents : Pipeline DLQ to inspect: documents or communications} {--limit=10 : Maximum DLQ messages to inspect}';
 
     protected $description = 'List workflow DLQ messages without deleting them.';
 
-    public function handle(SqsClient $sqs, MetricsRecorder $metrics): int
+    public function handle(SqsClient $sqs): int
     {
         $pipeline = (string) $this->option('queue');
         $queueUrl = match ($pipeline) {
@@ -43,7 +50,6 @@ public function handle(SqsClient $sqs, MetricsRecorder $metrics): int
             'VisibilityTimeout' => 0,
         ]);
         $messages = $result->get('Messages') ?? [];
-        $metrics->recordDomainCounter('dlq_messages_total', ['queue' => $pipeline], count($messages));
 
         if ($messages === []) {
             $this->info('DLQ vuota.');

app/Http/Controllers/Api/V1/SendMessageController.php

@@ -6,6 +6,8 @@
 use App\Http\Controllers\Api\V1\Concerns\ResolvesActor;
 use App\Http\Requests\UpdateSendMessageRequest;
 use App\Models\SubDocument;
+use App\Mvp\Documents\Domain\Exceptions\SendMessageAttachmentUnavailableException;
+use App\Mvp\Documents\Domain\Exceptions\SendMessageNotConfirmedException;
 use App\Mvp\Documents\Domain\Ports\Inbound\SendMessageUseCase;
 use App\Mvp\Support\MvpStateService;
 use Illuminate\Http\JsonResponse;
@@ -20,25 +22,47 @@ class SendMessageController
 {
     use AuthorizesDocuments, ResolvesActor;
 
-    public function sendPreview(Request $request, SubDocument $subDocument, SendMessageUseCase $sendMessage): Response
+    public function sendPreview(Request $request, SubDocument $subDocument, SendMessageUseCase $sendMessage): Response|JsonResponse
     {
         $actor = $this->actor($request);
         $this->authorizeSubDocument($subDocument, $actor);
 
-        $rendered = $sendMessage->preview($subDocument->id, $actor);
+        try {
+            $rendered = $sendMessage->preview($subDocument->id, $actor);
+        } catch (SendMessageNotConfirmedException $exception) {
+            return response()->json([
+                'error' => [
+                    'code' => 'review_not_confirmed',
+                    'message' => $exception->getMessage(),
+                ],
+            ], 422);
+        } catch (SendMessageAttachmentUnavailableException $exception) {
+            return $this->attachmentUnavailable($exception);
+        }
 
         return response($rendered->pdf, 200, [
             'Content-Type' => 'application/pdf',
             'Content-Disposition' => 'inline',
         ]);
     }
 
-    public function sendExport(Request $request, SubDocument $subDocument, SendMessageUseCase $sendMessage): Response
+    public function sendExport(Request $request, SubDocument $subDocument, SendMessageUseCase $sendMessage): Response|JsonResponse
     {
         $actor = $this->actor($request);
         $this->authorizeSubDocument($subDocument, $actor);
 
-        $rendered = $sendMessage->export($subDocument->id, $actor);
+        try {
+            $rendered = $sendMessage->export($subDocument->id, $actor);
+        } catch (SendMessageNotConfirmedException $exception) {
+            return response()->json([
+                'error' => [
+                    'code' => 'review_not_confirmed',
+                    'message' => $exception->getMessage(),
+                ],
+            ], 422);
+        } catch (SendMessageAttachmentUnavailableException $exception) {
+            return $this->attachmentUnavailable($exception);
+        }
 
         return response($rendered->pdf, 200, [
             'Content-Type' => 'application/pdf',
@@ -64,4 +88,14 @@ public function updateSendMessage(
             'state' => $state->forActor($actor),
         ]);
     }
+
+    private function attachmentUnavailable(SendMessageAttachmentUnavailableException $exception): JsonResponse
+    {
+        return response()->json([
+            'error' => [
+                'code' => 'attachment_unavailable',
+                'message' => $exception->getMessage(),
+            ],
+        ], 404);
+    }
 }

app/Models/ExtractedData.php

@@ -18,6 +18,7 @@
  * @property string|null $description
  * @property string|null $recipient_email
  * @property int|null $confidence_score
+ * @property array<string, float|null>|null $field_confidences
  * @property array<string, mixed>|null $ai_payload
  * @property SubDocument|null $subDocument
  */
@@ -38,6 +39,7 @@ class ExtractedData extends Model
         'description',
         'recipient_email',
         'confidence_score',
+        'field_confidences',
         'ai_payload',
     ];
 
@@ -49,6 +51,7 @@ protected function casts(): array
         return [
             'document_date' => 'date',
             'confidence_score' => 'integer',
+            'field_confidences' => 'array',
             'ai_payload' => 'array',
         ];
     }

app/Mvp/Ai/AiOutputValidator.php

@@ -53,7 +53,7 @@ public function validateSplitDocument(mixed $decoded): array
     }
 
     /**
-     * @return array{employee_first_name: ?string, employee_last_name: ?string, company_name: ?string, document_date: ?string, document_type: ?string, description: ?string, confidence_score: ?int}
+     * @return array{employee_first_name: ?string, employee_last_name: ?string, company_name: ?string, document_date: ?string, document_type: ?string, description: ?string, recipient_email: ?string, fiscal_code: ?string, employee_id: ?string, confidence_score: ?int}
      *
      * @throws InvalidAiOutputException
      */
@@ -83,6 +83,13 @@ public function validateExtractFields(mixed $decoded): array
             'document_date' => $string('document_date'),
             'document_type' => $string('document_type'),
             'description' => $string('description'),
+            // Identificativi del destinatario. Qui si normalizza soltanto la
+            // forma: se il valore sia plausibile — checksum del codice
+            // fiscale, sintassi dell'indirizzo — lo decide il caso d'uso, che
+            // e' dove vive la conoscenza del dominio documentale.
+            'recipient_email' => $string('recipient_email'),
+            'fiscal_code' => $string('fiscal_code'),
+            'employee_id' => $string('employee_id'),
             'confidence_score' => isset($decoded['confidence_score']) && is_int($decoded['confidence_score'])
                 ? $decoded['confidence_score']
                 : null,

app/Mvp/Ai/BedrockService.php

@@ -225,13 +225,69 @@ private function extractJsonFromAiResponse(array $rawResponse, string $operation
 
         $decoded = json_decode($cleanJson, true);
 
+        // Seconda occasione: il modello scrive spesso i ritorni a capo dei
+        // paragrafi cosi' come sono, e dentro una stringa JSON quelli sono
+        // caratteri di controllo che invalidano l'intero documento. Il testo
+        // che portano e' buono: si ripara la forma, non il contenuto.
+        if (! is_array($decoded)) {
+            $decoded = json_decode($this->escapeControlCharactersInStrings($cleanJson), true);
+        }
+
         if (! is_array($decoded)) {
             throw new InvalidAiOutputException($operation, ['la risposta del modello non è JSON decodificabile']);
         }
 
         return $decoded;
     }
 
+    /**
+     * Scrive come sequenze di escape i ritorni a capo e le tabulazioni rimasti
+     * dentro le stringhe di un JSON.
+     *
+     * La scansione e' byte per byte: in UTF-8 nessun byte di un carattere
+     * multibyte coincide con la virgoletta, la barra rovesciata o un carattere
+     * di controllo ASCII, quindi non c'e' modo di spezzare una lettera accentata
+     * a meta'.
+     */
+    private function escapeControlCharactersInStrings(string $json): string
+    {
+        $repaired = '';
+        $inString = false;
+        $escaped = false;
+
+        foreach (str_split($json) as $char) {
+            if ($escaped) {
+                $repaired .= $char;
+                $escaped = false;
+
+                continue;
+            }
+
+            if ($char === '\\') {
+                $repaired .= $char;
+                $escaped = true;
+
+                continue;
+            }
+
+            if ($char === '"') {
+                $inString = ! $inString;
+                $repaired .= $char;
+
+                continue;
+            }
+
+            $repaired .= $inString ? match ($char) {
+                "\n" => '\\n',
+                "\r" => '',
+                "\t" => '\\t',
+                default => $char,
+            } : $char;
+        }
+
+        return $repaired;
+    }
+
     /**
      * Il modello testuale descrive anche la copertina: avendo davanti il testo
      * che ha appena scritto, produce una direzione visiva coerente con la
@@ -241,6 +297,14 @@ private function buildCommunicationPrompt(string $userPrompt, string $tone, stri
     {
         return "Agisci come un assistente HR. Genera una comunicazione con tono '{$tone}' e stile '{$style}'.\n"
              ."Argomento: {$userPrompt}\n"
+             // Ne' il PDF ne' l'anteprima interpretano Markdown: un asterisco
+             // arrivato fin li' si legge come un asterisco.
+             .'Scrivi il corpo in testo semplice: niente Markdown, niente cancelletti, asterischi, '
+             .'trattini di elenco, trattini bassi o backtick. Separa i paragrafi con una riga vuota '
+             ."e apri con il segno • ogni voce di un eventuale elenco. Non ripetere il titolo nel corpo.\n"
+             // Chiedere paragrafi e' chiedere ritorni a capo, e dentro una
+             // stringa JSON un ritorno a capo vero rompe il documento.
+             ."Nel JSON i ritorni a capo vanno scritti come \\n dentro le stringhe, mai andando a capo davvero.\n"
              .'Produci anche "imagePrompt": la descrizione in inglese, massimo 60 parole, dell\'immagine di copertina '
              .'coerente con il contenuto che hai generato. Descrivi soggetto, composizione, atmosfera e palette. '
              ."Non includere testo leggibile, loghi, filigrane, volti riconoscibili o dati personali.\n"
@@ -629,7 +693,7 @@ public function splitDocument(string $ocrText, int $pageCount, string $pageBound
      * Extract structured fields for a single recipient from its OCR text.
      * Works on any document type, not just payslips.
      *
-     * @return array{employee_first_name: ?string, employee_last_name: ?string, company_name: ?string, document_date: ?string, document_type: ?string, description: ?string, confidence_score: ?int}
+     * @return array{employee_first_name: ?string, employee_last_name: ?string, company_name: ?string, document_date: ?string, document_type: ?string, description: ?string, recipient_email: ?string, fiscal_code: ?string, employee_id: ?string, confidence_score: ?int}
      *
      * @throws \RuntimeException
      */
@@ -638,8 +702,12 @@ public function extractFields(string $ocrText): array
         $this->ensureConfigured();
 
         $prompt = "Estrai i seguenti campi dal testo OCR di questo documento (qualsiasi tipologia).\n"
-            ."Rispondi SOLO con JSON valido con le chiavi: employee_first_name (nome del destinatario), employee_last_name (cognome del destinatario), company_name (azienda o ente, se presente), document_date (formato YYYY-MM-DD), document_type (tipologia del documento rilevata dal contenuto), description (max 200 caratteri), confidence_score (intero 0-100).\n"
-            ."Usa null per i campi non trovati.\n\n"
+            ."Rispondi SOLO con JSON valido con le chiavi: employee_first_name (nome del destinatario), employee_last_name (cognome del destinatario), company_name (azienda o ente, se presente), document_date (formato YYYY-MM-DD), document_type (tipologia del documento rilevata dal contenuto), description (max 200 caratteri), recipient_email (indirizzo email del destinatario), fiscal_code (codice fiscale del destinatario, 16 caratteri), employee_id (matricola o codice dipendente), confidence_score (intero 0-100).\n"
+            ."Usa null per i campi non trovati.\n"
+            // I tre identificativi valgono solo se stanno scritti nel
+            // documento: un codice fiscale plausibile ma inventato passerebbe
+            // per dato estratto, e l'operatore non ha modo di distinguerlo.
+            ."Per recipient_email, fiscal_code e employee_id riporta esclusivamente valori presenti alla lettera nel testo: se non compaiono, usa null senza dedurli.\n\n"
             ."Per confidence_score usa questa scala:\n"
             ."- 90-100: tutti i campi principali (nome, cognome, azienda, data) sono chiaramente leggibili\n"
             ."- 70-89: la maggior parte dei campi è leggibile ma uno o due sono ambigui o parziali\n"