longevity: revisione finale — il motore ora si calcola, il consenso è atomico, il codice cliente è tipato fuori dal corpo

Sei correzioni dalla revisione finale del 22/08, ognuna con test scritto prima:

1. salvaDalForm calcolava mai i punteggi (calcolaSessione/salvaScore) dopo il
   salvataggio: un cliente compilava venti domande e vedeva un referto vuoto.
   Ora avviene nella stessa transazione del salvataggio.
2. Il corpo della richiesta dell'endpoint questionario è tipato
   (CorpoQuestionario): client_code non esiste in quel tipo, non è più
   prendibile per errore. Il vecchio test a lista di nomi vietati era vacuo
   (cercava body./corpo., il file usa data.) — sostituito con un test
   comportamentale end-to-end sull'endpoint vero.
3. Il consenso: aggiunto il test sul ramo affermativo (non coperto, vacuo
   quanto il punto 2); la nota di consenso ora è nella stessa transazione dei
   dati sanitari; ha una versione propria (CONSENT_VERSION) invece di quella
   del questionario.
4. La prima apertura del referto ora spiega invece di sembrare rotta: Fitness
   Age con nota quando manca, spiegazione del radar prima del grafico,
   copertura sempre visibile, invito a fare i test in sala col trainer,
   numeri formattati all'italiana.
5. Aggiunto il link per ricompilare il questionario nella pagina del referto
   (prima spariva appena esisteva una compilazione).
6. Il test anti-query ora scandisce tutte le pagine sotto src/pages/longevity/,
   non due nomi a mano. Il test anti-giunzione identity/longevity resta con lo
   stesso limite di sempre (createIdentityDb è esportata per creaCliente) —
   corretto solo il commento perché lo dichiari onestamente.

Report con comandi e output letterali:
.superpowers/sdd/2026-08-22-longevity-interfaccia/review-finale-report.md

src/components/longevity/MacroScore.astro

@@ -6,6 +6,8 @@
 // L'etichetta si deriva dal nome del contenitore (dato, letto da vista.ts), non da un
 // elenco scritto qui: PERFORMANCE/ENERGY/RECOVERY diventano Performance/Energy/Recovery
 // con una trasformazione, non con un dizionario da tenere allineato a mano.
+import { formattaNumero } from '../../lib/longevity/formato';
+
 interface Props {
   nome: string;
   valore: number | null;
@@ -20,7 +22,7 @@ const intensita = valore !== null ? Math.max(valore / 100, 0.15) : 0;
 <div class:list={['lg-card', 'lg-macro__card', { 'lg-card--incompleto': valore === null }]}>
   <p class="lg-score__label">{etichetta}</p>
   <div class="lg-score">
-    <span class="lg-score__value lg-num">{valore !== null ? valore : '—'}</span>
+    <span class="lg-score__value lg-num">{valore !== null ? formattaNumero(valore) : '—'}</span>
     <span class="lg-score__max">/ 100</span>
   </div>
   <div class="lg-score__bar">
@@ -29,9 +31,7 @@ const intensita = valore !== null ? Math.max(valore / 100, 0.15) : 0;
       style={`width:${valore !== null ? valore : 0}%; --lg-intensita:${intensita}`}
     ></span>
   </div>
-  {valore === null && (
-    <p class="lg-muted lg-macro__nota">
-      Copertura dati: {Math.round(copertura * 100)}% — non ancora sufficiente per un numero.
-    </p>
-  )}
+  <p class="lg-muted lg-macro__nota">
+    Copertura dati: {Math.round(copertura * 100)}%{valore === null && ' — non ancora sufficiente per un numero.'}
+  </p>
 </div>

src/components/longevity/Radar.tsx

@@ -37,6 +37,12 @@ export default function RadarAssi({ assi }: Props) {
 
   return (
     <div className="lg-radar">
+      {/* La spiegazione del linguaggio visivo viene PRIMA del grafico che spiega, non dopo:
+          chi legge deve sapere cosa sta guardando prima di guardarlo. */}
+      <p className="lg-radar__intro">
+        L'area piena è quello che sappiamo davvero; il perimetro tratteggiato è il resto
+        dell'asse, dove il dato non c'è ancora.
+      </p>
       <div className="lg-radar__grafico">
         <ResponsiveContainer width="100%" height={360}>
           <RadarChart data={dati} outerRadius="72%">
@@ -68,8 +74,11 @@ export default function RadarAssi({ assi }: Props) {
 
       {incompleti.length > 0 && (
         <div className="lg-radar__mancano">
-          <p className="lg-radar__intro">
-            L'area piena è quello che sappiamo davvero. Il perimetro tratteggiato si completa così:
+          {/* L'invito concreto: l'elenco sotto è nomi di test, da solo non dice cosa fare.
+              Questi test si fanno in palestra con lo staff, non a casa da soli. */}
+          <p className="lg-muted">
+            Questi test si fanno in sala, con il trainer: prenota la prossima sessione per
+            completare il quadro.
           </p>
           {incompleti.map((a) => (
             <div className="lg-radar__voce" key={a.nome}>

src/lib/longevity/formato.ts

@@ -0,0 +1,11 @@
+// Formattazione dei numeri del referto. Un solo posto, perché prima ognuno stampava il
+// numero grezzo di JavaScript (punto, non virgola) direttamente nel template — e un
+// referto italiano con "72.5" al posto di "72,5" si legge come un difetto, non come un
+// dettaglio.
+
+/** Un punteggio o una Fitness Age, formattati con la virgola decimale italiana.
+ * Le ETICHETTE dei punteggi (PERFORMANCE/ENERGY/RECOVERY, nomi di prodotto) non si
+ * toccano: solo i NUMERI si leggono all'italiana in un referto italiano. */
+export function formattaNumero(n: number): string {
+  return n.toLocaleString('it-IT');
+}

src/lib/longevity/questionario.ts

@@ -5,6 +5,12 @@ import { esisteTest } from './registro';
 /** Versione del set di domande. Si incrementa quando cambia una domanda. */
 export const QUEST_VERSION = 'v1.0';
 
+/** Versione del TESTO del consenso al trattamento dei dati sanitari — distinta da
+ * QUEST_VERSION apposta: se cambia la formulazione del consenso senza che cambi una
+ * domanda del questionario, il record del consenso deve poterlo dire. Prima di questa
+ * costante il record portava QUEST_VERSION, la versione sbagliata. */
+export const CONSENT_VERSION = 'v1.0';
+
 /**
  * Campi testuali che si salvano ma non entrano MAI in una formula
  * (indicazione esplicita del cliente, punto 7 della specifica).

src/lib/longevity/vista.ts

@@ -10,8 +10,8 @@
 //   cosa) che un domani va dimostrato tanto quanto un assenso.
 import type Database from 'better-sqlite3';
 import { testAttivi, pesiDi, MODEL_VERSION } from './registro';
-import { salvaCompilazione, QUEST_VERSION } from './questionario';
-import { leggiScore } from './motore';
+import { salvaCompilazione, CONSENT_VERSION } from './questionario';
+import { leggiScore, calcolaSessione, salvaScore } from './motore';
 
 export type CampoQuestionario = {
   id: string;
@@ -49,15 +49,16 @@ function consensoDato(risposta: string): boolean {
   return CONSENSI_AFFERMATIVI.has(risposta.trim().toLowerCase());
 }
 
-/** Registra il fatto del consenso — chi, quando, a che versione del questionario —
- * indipendentemente dall'esito. Legata al cliente sempre; alla sessione solo quando il
- * consenso è affermativo e la sessione esiste davvero. */
+/** Registra il fatto del consenso — chi, quando, a che versione del TESTO del consenso
+ * (CONSENT_VERSION, non QUEST_VERSION: il consenso può cambiare formulazione senza che
+ * cambi una domanda) — indipendentemente dall'esito. Legata al cliente sempre; alla
+ * sessione solo quando il consenso è affermativo e la sessione esiste davvero. */
 function registraConsenso(
   db: Database.Database, clientCode: string, sessioneId: number | null, risposta: string
 ): void {
   const esito = risposta.trim() === '' ? '(non risposto)' : risposta.trim();
   const oggi = new Date().toISOString().slice(0, 10);
-  const testo = `Consenso al trattamento dei dati sanitari: ${esito} — questionario ${QUEST_VERSION}, registrato il ${oggi}`;
+  const testo = `Consenso al trattamento dei dati sanitari: ${esito} — consenso ${CONSENT_VERSION}, registrato il ${oggi}`;
   db.prepare(
     `INSERT INTO profilo_note (client_code, sessione_id, campo_id, testo) VALUES (?, ?, ?, ?)`
   ).run(clientCode, sessioneId, 'consenso_sanitario', testo);
@@ -68,6 +69,15 @@ function registraConsenso(
  * qualunque altra cosa: se non è affermativo, non si apre nessuna sessione — né misure né
  * note di profilo — e la compilazione non entra nel fascicolo. La nota del consenso si
  * scrive comunque, con l'esito letterale ricevuto.
+ *
+ * Quando il consenso è affermativo, TUTTO il resto avviene in un'unica transazione (il
+ * salvataggio dei dati sanitari, il calcolo dei punteggi e il congelamento in `score`, la
+ * nota di consenso): o entra tutto nel fascicolo, o non entra niente. Prima di questa
+ * correzione il calcolo restava scollegato dal salvataggio — nessuno chiamava
+ * calcolaSessione/salvaScore in produzione — e la nota di consenso si scriveva fuori dalla
+ * transazione, quindi un fallimento lì poteva lasciare dati sanitari senza il consenso che
+ * li giustifica. `db.transaction` di better-sqlite3 annida automaticamente con savepoint
+ * quelle interne di `salvaCompilazione` e `salvaScore`.
  */
 export function salvaDalForm(
   db: Database.Database,
@@ -86,17 +96,26 @@ export function salvaDalForm(
     };
   }
 
-  const sessioneId = salvaCompilazione(db, {
-    client_code: input.client_code,
-    data: input.data,
-    eta: input.eta,
-    risposte: input.risposte,
-    liberi: input.liberi,
+  const tx = db.transaction(() => {
+    const sessioneId = salvaCompilazione(db, {
+      client_code: input.client_code,
+      data: input.data,
+      eta: input.eta,
+      risposte: input.risposte,
+      liberi: input.liberi,
+    });
+
+    // Il calcolo e il congelamento dei punteggi sono parte del salvataggio, non un passo
+    // successivo affidato a chi legge: senza questo, una compilazione restava per sempre
+    // senza i suoi punteggi.
+    salvaScore(db, sessioneId, calcolaSessione(db, sessioneId));
+
+    registraConsenso(db, input.client_code, sessioneId, input.consensoSanitario);
+
+    return sessioneId;
   });
 
-  registraConsenso(db, input.client_code, sessioneId, input.consensoSanitario);
-
-  return { ok: true, sessioneId };
+  return { ok: true, sessioneId: tx() };
 }
 
 //
@@ -191,7 +210,7 @@ function mancanoPer(db: Database.Database, sessioneId: number, nomeAsse: string,
 export function refertoDi(
   db: Database.Database,
   sessioneId: number
-): { assi: AsseVista[]; macro: MacroVista[]; fitnessAge: number | null } {
+): { assi: AsseVista[]; macro: MacroVista[]; fitnessAge: number | null; fitnessAgeCopertura: number } {
   const punteggi = leggiScore(db, sessioneId);
   const presenti = sottoDominiPresenti(db, sessioneId);
 
@@ -212,8 +231,12 @@ export function refertoDi(
   });
 
   const fitnessAge = punteggi.fitnessAge?.stato === 'ok' ? punteggi.fitnessAge.valore : null;
+  // Prima apertura: con poche misure la Fitness Age manca quasi sempre. La pagina deve
+  // poter dire QUANTO manca (come fa già ogni carta di macro-score), non solo che manca:
+  // la copertura resta leggibile anche quando lo stato è 'insufficiente'.
+  const fitnessAgeCopertura = punteggi.fitnessAge?.copertura ?? 0;
 
-  return { assi, macro, fitnessAge };
+  return { assi, macro, fitnessAge, fitnessAgeCopertura };
 }
 
 /** L'ultima sessione di un cliente (la più recente per data, a parità di data la più

src/pages/api/longevity/questionario.ts

@@ -9,29 +9,38 @@ export const prerender = false;
 const json = (status: number, body: object) =>
   new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
 
-export const POST: APIRoute = async ({ request, locals }) => {
-  // Il codice cliente si ricava SEMPRE dalla sessione dell'utente loggato (spec §8), mai dal
-  // corpo della richiesta: qui infatti il corpo non viene mai letto per questo campo. La
-  // risoluzione passa da anagrafica.ts (l'unico modulo autorizzato a toccare quella
-  // connessione): questo file apre solo longevity, per salvare.
-  const codice = codicePerUtenteLoggato(locals.user!.id);
-  if (!codice) return json(403, { error: 'Nessun fascicolo cliente associato a questo utente.' });
+/**
+ * Il corpo legittimo della richiesta: SOLO i campi che un cliente può davvero mandare.
+ * `client_code` non è un campo di questo tipo — non per una lista di nomi vietati (una
+ * lista così invecchia appena il file rinomina la variabile, vedi il commento nel test),
+ * ma perché il tipo non lo prevede: chi scrivesse domani `corpo.client_code` non
+ * supererebbe `tsc --noEmit`, il campo non esiste. Il codice cliente resta SEMPRE quello
+ * della sessione (codicePerUtenteLoggato, spec §8), mai un campo letto da qui.
+ */
+type CorpoQuestionario = {
+  risposte: Record<string, number>;
+  liberi: Record<string, string>;
+  consensoSanitario: string;
+  eta?: number;
+};
 
-  let data: Record<string, unknown>;
-  try { data = await request.json(); } catch { return json(400, { error: 'Dati non validi.' }); }
-  if (typeof data !== 'object' || data === null) return json(400, { error: 'Dati non validi.' });
+/** Estrae SOLO i campi di CorpoQuestionario da un JSON grezzo; `null` se il corpo non è
+ * nemmeno un oggetto, o se manca `risposte`. Ogni altra chiave del corpo (incluso un
+ * eventuale `client_code`) viene semplicemente ignorata: non esiste modo di farla arrivare
+ * al chiamante, perché il tipo di ritorno non la contiene. */
+function corpoDaJson(raw: unknown): CorpoQuestionario | null {
+  if (typeof raw !== 'object' || raw === null) return null;
+  const grezzo = raw as Record<string, unknown>;
 
-  const risposteIn = data.risposte;
-  if (typeof risposteIn !== 'object' || risposteIn === null) {
-    return json(400, { error: 'Risposte mancanti.' });
-  }
+  const risposteIn = grezzo.risposte;
+  if (typeof risposteIn !== 'object' || risposteIn === null) return null;
   const risposte: Record<string, number> = {};
   for (const [id, v] of Object.entries(risposteIn as Record<string, unknown>)) {
     if (typeof v === 'number' && Number.isFinite(v)) risposte[id] = v;
   }
 
   // Solo i campi liberi dichiarati: un corpo con chiavi arbitrarie non ne inventa di nuove.
-  const liberiIn = data.liberi;
+  const liberiIn = grezzo.liberi;
   const liberi: Record<string, string> = {};
   if (typeof liberiIn === 'object' && liberiIn !== null) {
     for (const campo of CAMPI_LIBERI) {
@@ -40,8 +49,27 @@ export const POST: APIRoute = async ({ request, locals }) => {
     }
   }
 
-  const consensoSanitario = typeof data.consensoSanitario === 'string' ? data.consensoSanitario : '';
-  const eta = typeof data.eta === 'number' && Number.isFinite(data.eta) ? data.eta : undefined;
+  const consensoSanitario = typeof grezzo.consensoSanitario === 'string' ? grezzo.consensoSanitario : '';
+  const eta = typeof grezzo.eta === 'number' && Number.isFinite(grezzo.eta) ? grezzo.eta : undefined;
+
+  return { risposte, liberi, consensoSanitario, eta };
+}
+
+export const POST: APIRoute = async ({ request, locals }) => {
+  // Il codice cliente si ricava SEMPRE dalla sessione dell'utente loggato (spec §8), mai dal
+  // corpo della richiesta: la risoluzione passa da anagrafica.ts (l'unico modulo autorizzato
+  // a toccare quella connessione). `corpo`, qui sotto, non ha nemmeno un campo da cui
+  // prenderlo per errore.
+  const codice = codicePerUtenteLoggato(locals.user!.id);
+  if (!codice) return json(403, { error: 'Nessun fascicolo cliente associato a questo utente.' });
+
+  let raw: unknown;
+  try { raw = await request.json(); } catch { return json(400, { error: 'Dati non validi.' }); }
+  if (typeof raw !== 'object' || raw === null) return json(400, { error: 'Dati non validi.' });
+
+  const corpo = corpoDaJson(raw);
+  if (!corpo) return json(400, { error: 'Risposte mancanti.' });
+  const { risposte, liberi, consensoSanitario, eta } = corpo;
 
   // La data della compilazione è quella del server, non quella (manomettibile) del client.
   const oggi = new Date().toISOString().slice(0, 10);

src/pages/longevity/io.astro

@@ -9,6 +9,7 @@ import MacroScore from '../../components/longevity/MacroScore.astro';
 import { getLongevityDb } from '../../lib/longevity/db';
 import { codicePerUtenteLoggato } from '../../lib/longevity/anagrafica';
 import { refertoDi, ultimaSessioneDi } from '../../lib/longevity/vista';
+import { formattaNumero } from '../../lib/longevity/formato';
 
 export const prerender = false;
 
@@ -34,12 +35,18 @@ const referto = sessioneId !== null ? refertoDi(db, sessioneId) : null;
 
   {referto && (
     <div class="lg-referto">
-      <section class="lg-card">
+      <section class:list={['lg-card', { 'lg-card--incompleto': referto.fitnessAge === null }]}>
         <p class="lg-score__label">Fitness Age</p>
         <div class="lg-score">
-          <span class="lg-score__value lg-num">{referto.fitnessAge ?? '—'}</span>
+          <span class="lg-score__value lg-num">
+            {referto.fitnessAge !== null ? formattaNumero(referto.fitnessAge) : '—'}
+          </span>
           {referto.fitnessAge !== null && <span class="lg-score__max">anni</span>}
         </div>
+        <p class="lg-muted lg-macro__nota">
+          Copertura dati: {Math.round(referto.fitnessAgeCopertura * 100)}%
+          {referto.fitnessAge === null && ' — non ancora sufficiente per un numero.'}
+        </p>
       </section>
 
       <section class="lg-card">
@@ -52,6 +59,14 @@ const referto = sessioneId !== null ? refertoDi(db, sessioneId) : null;
           <MacroScore nome={m.nome} valore={m.valore} copertura={m.copertura} />
         ))}
       </section>
+
+      <section class="lg-card">
+        <p>
+          InsanityLab Longevity monitora il tuo percorso nel tempo: più compilazioni
+          raccontano come cambi, non solo come stai oggi.
+          <a href="/longevity/questionario">Compila di nuovo il questionario</a>.
+        </p>
+      </section>
     </div>
   )}
 </Longevity>