nis2-agile/docs/UI_V3_REVAMP_FLEET_SPEC.md

UI V3 Revamp — Spec operativa per FLOTTA di agenti

Obiettivo: migrare l'interfaccia di NIS2 Agile dal V2 attuale (Bootstrap Italia, sidebar a sinistra) al V3 proposto nei mockup (docs/mockup Ui/): top-nav a mega-menu, tema navy + oro, font Inter, icone Lucide, card/stat moderne. Vincolo madre: è un redesign SOLO di presentazione. Tutto il backend, l'auth, il wiring dati (api.js), l'help, l'i18n, ARIA e il bug-reporter devono continuare a funzionare. NON si tocca PHP/DB/controller. Fonte di verità visiva: i 3 mockup in docs/mockup Ui/ (index.html = chrome + dashboard; assessment.html = pagina-modulo/GAP; calendario.html = app full-page). I mockup sono mock: NON copiarne i dati finti né la logica fittizia — ricablare sui dati reali via api.js.

---

0. TL;DR per chi orchestra

1. FASE 0 (1 agente, sequenziale, foundation) — estrarre il design system in public/css/v3.css + costruire la chrome condivisa public/js/topnav-v3.js (appbar + mega-menu, data-driven) + self-hostare Inter e Lucide in /vendor + migrare dashboard.html come pagina pilota cablata sui dati reali. Blocca: le altre pagine dipendono da questa.
2. FASE 1 (flotta in parallelo, N agenti, worktree isolati) — ogni agente migra un gruppo IA di pagine reali al V3 riusando v3.css + topnav-v3.js, cablando i dati reali.
3. FASE 2 (1–2 agenti, verifica) — smoke per pagina (200, console pulita, dati reali, auth, responsive, a11y), cache-buster, commit.

⚠️ Decisione utente da confermare PRIMA della Fase 1 (vedi §7).

---

1. Design system V3 (estratto dai mockup — usare ESATTAMENTE)

Token CSS (:root in public/css/v3.css):

:root{
  --navy-top:#0A2E54; --navy-nav:#103A61; --navy-hover:#1B4A75; --gold:#F0B429;
  --bg:#EFF4FA; --card:#FFFFFF; --ink:#15263C; --muted:#64748B; --line:#E3E9F0;
  --c-green:#1E8A5A; --c-blue:#1F5FA8; --c-amber:#D98324; --c-red:#C62828;
  --radius:12px; --shadow:0 1px 2px rgba(16,40,80,.06),0 8px 24px rgba(16,40,80,.06);
}

• Font: Inter (400–800). ⚠️ Self-host in /vendor/inter/ (NO Google Fonts CDN: AGID/privacy/PWA-offline). Fallback system-ui.
• Icone: Lucide. ⚠️ Self-host lo UMD in /vendor/lucide/lucide.min.js (NO unpkg CDN: CSP/offline). Uso <i data-lucide="..."> + lucide.createIcons().
• Focus: :focus-visible{outline:2px solid var(--gold)} (a11y).

Chrome condivisa (sostituisce la sidebar V2): .appbar = .bar-top (flag IT, logo-mark, brand, .search, .btn-incident "Registra incidente", .user) + .bar-nav con .nav-item > .nav-link e dropdown .mega / .mega.no-promo (vedi index.html righe 196–217). Attivo: .nav-link.active (bordo oro sotto).

Componenti (classi dai mockup, da portare in v3.css): .card/.card-pad, .stat (+.green/.amber/.blue, .ibox, .val, .bar), .badge-t (+ varianti colore), .btn-primary/.btn-ghost/.btn-incident, .sec-head, .page-head/.crumb, .sca/.act (liste scadenze/attività), .anag* (anagrafica), .doc (documenti), .fab-stack/.fab (trittico), calendario (.daystrip/.weekstrip/.daycell/.mini/.cal-pop per dashboard; .cal-app/.cal-main/.cal-side/.mv-grid/.view-switch/.legend per la pagina Calendario). Responsive (dai mockup): breakpoint ≤900px (collassa griglie/mega, nasconde search) e ≤560px.

FAB trittico: nel mockup sono 3 (Notifiche / Assistenza / AI). ⚠️ NON reinventarli: NIS2 ha già il trittico cablato in common.js (campana notifiche + bug-reporter widget + ARIA chat con voce/puntatore/dati). Il V3 deve riusare quei FAB reali (eventualmente ri-stilarli), non i bottoni statici del mockup.

---

2. Architettura tecnica della migrazione (CRITICA)

Oggi (V2) ogni pagina carica: common.js (helper: auth checkAuth, showModal, showNotification, escHtml, FAB ARIA+bug-reporter, org-switcher) → api.js (client REST) → bundle Bootstrap Italia → common-bi.js (loadSidebar() = sidebar V2) → i18n.js → help.js → <pagina>.js.

Il V3 sostituisce solo la CHROME (sidebar → top-nav) e il CSS, riusando tutti gli helper. Strategia:

• public/css/v3.css — design system completo (token + chrome + componenti). Sostituisce/affianca style.css sulle pagine V3.
• public/js/topnav-v3.js — renderizza l'appbar + mega-menu (come common-bi.js fa per la sidebar), data-driven da un array navGroups (la mappa IA §6), con aria-current sul gruppo attivo, ed espone gli stessi hook usati a init (window.loadSidebar può essere ridefinito a loadTopnav, così le pagine non cambiano l'init). Riusa org-switcher/utente/logout/versione da common.js.
• Per pagina: nuovo <head> (Inter+Lucide self-host + v3.css), nuovo markup (struttura dal mockup), ma stessi script common.js/api.js/i18n.js/help.js/<pagina>.js + topnav-v3.js al posto di common-bi.js. Il <pagina>.js resta quello reale (dati veri); si adatta solo il markup/i selettori se necessario.
• Help/ARIA: aggiornare help.js (_pageMap invariato) e AIService::navigationMapBlock solo se cambiano i nomi delle voci di menu (la nuova IA li raggruppa: vedi §6 — riconciliare con la mappa ARIA, che oggi riflette le sezioni sidebar). Vedi memoria project_aria_chat_wiring.

Conseguenza: non si butta <pagina>.js (è il wiring reale). Si rifà il guscio HTML + la chrome. Questo è ciò che rende parallelizzabile per pagina.

---

3. FASE 0 — Foundation (1 agente, sequenziale, NO parallelo)

Deliverable (in un solo commit, pagina pilota verificata):

1. public/css/v3.css con token + chrome + tutti i componenti dei mockup.
2. public/js/topnav-v3.js (appbar + mega-menu data-driven, riusa helper common.js, aria-current, responsive/mobile toggle).
3. Self-host Inter (/vendor/inter/) e Lucide (/vendor/lucide/lucide.min.js) + relativi @font-face/<script> locali (no CDN).
4. dashboard.html migrata end-to-end al V3, cablata sui dati reali (api.js: overview/score/deadlines/recent-activity ecc., stati loading/empty/error), con il trittico FAB reale (ARIA/bug-reporter/notifiche) e l'help "?".
5. La mappa IA §6 finalizzata in topnav-v3.js. Acceptance F0: dashboard 200, console pulita, dati reali, nav attivo, responsive ≤900/≤560, a11y focus/contrasto, node --check su topnav-v3.js. Commit [FEAT] UI V3 — foundation + dashboard pilota.

---

4. FASE 1 — Migrazione pagine (flotta in parallelo)

• 1 agente per GRUPPO IA (§6), in worktree isolato (isolation: worktree) per evitare conflitti su file condivisi.
• Ogni agente, per ogni pagina del suo gruppo: rifà <head> + markup V3 (dal pattern della dashboard pilota + dai mockup assessment.html/calendario.html per i pattern modulo/app), aggancia topnav-v3.js + v3.css, mantiene il <pagina>.js reale (adatta i selettori se il markup cambia), verifica i dati reali.
• NON inventare endpoint: usare quelli già in api.js. Se manca un dato che il mockup mostra, renderlo "—"/placeholder, non fingerlo. Acceptance F1 per pagina: vedi §8.

---

5. FASE 2 — Verifica & rilascio (1–2 agenti)

• Smoke ogni pagina su prod: 200, console JS pulita, dati reali caricano, checkAuth, i18n IT/EN, help "?", trittico FAB, responsive, a11y (focus/contrasto/aria), nessun CDN esterno (CSP/PWA).
• Cache-buster ?v= aggiornato su tutte le pagine che referenziano v3.css/topnav-v3.js/common.js modificati (la propagazione JS/CSS statica è via bind-mount; nessun USR2 perché non si toccano .php).
• Aggiornare sw.js (cache shell V3) + bump nome cache; manifest theme-color resta #0066CC o si valuta il navy (decisione utente).

---

6. Mappa IA (gruppi mega-menu → pagine reali)

Dal mockup index.html. Riconciliare con TUTTE le ~30 pagine reali; le pagine non presenti nel mockup sono marcate ➕ e vanno collocate dalla flotta (proposta tra parentesi).

• Dashboard → dashboard.html
• Calendario → calendario.html
• Stakeholders (mega): stakeholders.html · supply-chain.html · stakeholder-activities.html
• Struttura interna (mega): organigramma.html · competenze.html · GAP Analysis assessment.html · training.html
• Rischi (mega): Mappa rischi risks.html · Inventario assets.html · policies.html · ➕ Connettori Discovery connettori-discovery.html (Inventario/Operativo)
• Monitoraggio (mega): Segnalazioni whistleblowing.html · internal-audits.html · Audit ACN reports.html · ➕ controlli-periodici.html · ➕ Riesame di Direzione management-review.html
• Lex e ISO (mega): normative.html · Modello SGSI isms.html · misure-requisiti.html
• AI (mega): cross-analysis.html · kb.html
• Guida (mega): guida.html · integrazioniext.html · Impostazioni settings.html · architecture.html · ➕ simulate.html

➕ da decidere: companies.html (consulente), pagine admin (admin/*). Pagine pubbliche (index.html landing, login/register/onboarding, segnala-anonimo.html) NON ricevono la chrome top-nav (restano pubbliche).

---

7. ⚠️ Decisioni da confermare con l'utente PRIMA della Fase 1

1. Big-bang vs graduale: il V3 sostituisce il V2 su tutte le pagine in un'unica ondata, oppure convive dietro flag (es. ?ui=v3 / preferenza utente) durante la transizione? (Consigliato: pagina pilota + rollout graduale per gruppo, non big-bang.)
2. Sidebar → top-nav su tutto: confermare l'abbandono della sidebar V2 (è cambio di IA e di abitudini per gli utenti già formati).
3. Brand/temi: il navy/oro sostituisce il blu Italia #0066CC? Impatta theme-color/manifest/AGID (Bootstrap Italia è un requisito AGID per la PA — verificare che il target NIS2 lo consenta; vedi memoria project_bootstrap_italia_rollout).
4. i18n: i mockup sono solo IT — il V3 deve mantenere il toggle IT/EN (i18n.js).

---

8. Acceptance criteria PER PAGINA (Fase 1)

• Chrome V3 (appbar + mega-menu) presente; gruppo/voce attiva corretta (aria-current).
• Dati REALI via api.js (zero mock); stati loading / empty / error gestiti.
• checkAuth (auth + redirect login) funzionante; i18n IT/EN; help "?"; trittico FAB reale (ARIA + bug-reporter + notifiche).
• Responsive ≤900 e ≤560; a11y WCAG 2.1 AA (focus-visible, contrasto, touch ≥44px, aria-label, zoom non bloccato).
• Nessun CDN esterno (Inter/Lucide self-host); CSP/PWA ok.
• node --check sui JS toccati; pagina 200; console pulita.
• Cache-buster ?v= aggiornato.

---

9. Guardrail VINCOLANTI (per ogni agente)

• Solo UI: NON toccare PHP/controller/DB/migrazioni/api.js (a meno di aggiungere metodi mancanti, da concordare). Il wiring dati è quello esistente.
• Riusare gli helper di common.js (auth, modal, notify, FAB ARIA/bug-reporter, org-switcher) — non duplicarli.
• Self-host font/icone (no CDN: CSP, offline-PWA, privacy, AGID).
• Lock /tmp/agent-working.lock mentre si lavora (il supervisore cron lo rispetta e salta). Rimuoverlo a fine lavoro.
• Worktree isolation per gli agenti paralleli (Fase 1).
• Commit chirurgico per batch: [FEAT] UI V3: <gruppo/pagina> + footer Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>. git push origin main (helper vault dal devenv) — sequenziale tra worktree per evitare race sul push.
• Deploy: HTML/JS/CSS statici → live via bind-mount + cache-buster, nessun USR2 (solo se si toccasse un .php, qui no). Reload host non necessario per sola UI.
• A11y/AGID: mantenere o migliorare il livello attuale (Bootstrap Italia era conforme AGID; il V3 deve restare WCAG 2.1 AA).
• Verità, non finzione: se un dato del mockup non esiste nel backend, mostrarlo come placeholder/empty, non inventarlo.

---

10. Orchestrazione consigliata

• FASE 0: 1 agente (sequenziale). Output = foundation + dashboard pilota. Gate manuale: l'utente valida la pilota prima di aprire la flotta.
• FASE 1: Workflow/Agent con isolation: worktree, 1 agente per gruppo IA (§6) → ~8 agenti paralleli. Ogni agente legge: questo spec + i 3 mockup + la dashboard pilota (pattern) + il <pagina>.js reale.
• FASE 2: 1–2 agenti di verifica + sweep cache-buster + sw.js.
• Riferimenti memoria: project_bootstrap_italia_rollout (il V2 attuale è BI), project_aria_chat_wiring (nav-map ARIA da riconciliare), reference_jsonpaginated_contract (contratto liste), project_prod_topology_host_fpm (deploy).

Nota: questo è il piano. Lanciare la flotta solo dopo le decisioni §7. Per partire in sicurezza: eseguire solo la FASE 0 (foundation + pilota), revisionare, poi aprire la Fase 1.