From f9baf39599f9dfd8def32c9e40f858a0bee894bf Mon Sep 17 00:00:00 2001
From: DevEnv nis2-agile <dev@certisource.it>
Date: Sat, 27 Jun 2026 10:18:09 +0200
Subject: [PATCH] =?UTF-8?q?[DOCS]=20UI=20V3=20revamp=20=E2=80=94=20spec=20?=
 =?UTF-8?q?operativa=20per=20flotta=20di=20agenti=20(da=20mockup=20docs/mo?=
 =?UTF-8?q?ckup=20Ui)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Analisi dei 3 mockup (top-nav mega-menu, tema navy/oro, Inter, Lucide) → spec per
migrare l'UI dal V2 (Bootstrap Italia/sidebar) al V3: design system (token/chrome/
componenti), architettura migrazione (riusa api.js/auth/help/i18n/FAB, sostituisce
solo chrome+css), work-breakdown a fasi (F0 foundation+dashboard pilota; F1 flotta
1 agente/gruppo IA in worktree; F2 verifica), mappa IA, guardrail, acceptance per
pagina, decisioni utente aperte (§7). Mockup = fonte visiva, dati reali non mock.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/UI_V3_REVAMP_FLEET_SPEC.md | 134 ++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 docs/UI_V3_REVAMP_FLEET_SPEC.md

diff --git a/docs/UI_V3_REVAMP_FLEET_SPEC.md b/docs/UI_V3_REVAMP_FLEET_SPEC.md
new file mode 100644
index 0000000..2a0afde
--- /dev/null
+++ b/docs/UI_V3_REVAMP_FLEET_SPEC.md
@@ -0,0 +1,134 @@
+# 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`):
+```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.