nis2-agile/docs/DESIGN_MODULO_QUESTIONARI_FORNITORI.md

# Design — Modulo Questionari Fornitori + Portale Fornitore

> Stato: **DESIGN DEFINITIVO da approvare** (nessun codice scritto). Da rivedere prima dell'implementazione.
> Autore: sessione 2026-05-31. Origine: richiesta utente (Cristiano Benassati).
> **Decisioni utente confermate**: (1) categorie **predefinite + personalizzabili**; (2) auth fornitore via **magic-link / OTP email** (NO password); (3) scadenze/ricorrenze **configurabili** (nessun default imposto); (4) portale sullo **stesso dominio** `nis2.agile.software` → pagina `supplier-portal.html`.
> Base esistente riusata: `SupplyChainController` (self-assessment link-token, P3), `supplier-assessment.html`, tabella `supplier_questionnaires` (mig. 027), relay email AgileHub (`/api/emails/send-raw`, `X-Internal-Key`).

---

## 1. Obiettivo

Evolvere il self-assessment fornitori (oggi: 8 domande hardcoded, link usa-e-getta) in un **modulo questionari configurabile** con **portale fornitore** ad accesso OTP, che gestisce **categorie**, **domande estensibili** (anche per procedure interne), **scadenze/ricorrenze** e **aggiornamenti nel tempo**.

Valore: due-diligence continua dei fornitori (Art. 21.2(d) NIS2; coerente con ENISA supply chain / NIST 800-161), riutilizzabile anche per procedure interne (privacy, 231, ESG, qualità).

---

## 2. Cosa esiste già (riuso)

| Esistente | Riuso nel nuovo modulo |
|---|---|
| `SupplyChainController::sendQuestionnaire` (link-token sha256 + scadenza) | base per generare l'accesso OTP/campagna |
| `publicQuestionnaire` / `submitPublicQuestionnaire` (no-auth via token) | base compilazione online |
| `supplier-assessment.html` (pagina pubblica) | diventa il **portale fornitore** dinamico |
| relay email `/api/emails/send-raw` + `X-Internal-Key` | invio OTP e notifiche scadenza |
| pattern token `sq_` + sha256 + scadenza + single-use | riusato per OTP e accesso |
| costante `QUESTIONNAIRE` (8 domande) | migrata in DB come template "NIS2 base" di default |

---

## 3. Autenticazione fornitore — MAGIC-LINK / OTP (scelta utente)

**Principio**: nessuna password fornitore (zero credenziali da custodire/rubare). Accesso a ogni sessione tramite codice/temporale via email.

### Flusso
1. L'azienda registra il fornitore (anagrafica) con **email referente**.
2. Quando serve accesso (campagna o login spontaneo), il fornitore va su `supplier-portal.html` e inserisce la **propria email** → riceve un **magic-link** (token `sp_` + 32 byte) **e/o un codice OTP a 6 cifre**, validi ~15 minuti, single-use.
3. Cliccando il link / inserendo l'OTP, si apre una **sessione fornitore** (token di sessione separato, durata breve, es. 2h) limitata al **solo** profilo di quel fornitore.
4. Nel portale il fornitore vede: anagrafica propria, questionari assegnati (aperti/scaduti/completati), scadenze, storico.

### Sicurezza (vincolante)
- Tabella **separata** `supplier_users` — MAI in `users` interni. Nessun ruolo interno, nessun accesso a dati di altri fornitori o dell'organizzazione cliente.
- OTP: hash in DB (mai in chiaro), scadenza 15 min, max 5 tentativi, rate-limit per email/IP, invalidazione dopo uso.
- Sessione fornitore: JWT dedicato con claim `supplier_user_id` + `supplier_id` (NON `user_id`); scope whitelisted ai soli endpoint `/api/supplier-portal/*`.
- Enumerazione: risposta sempre "se l'email è registrata riceverai il codice" (opaca).
- Audit: login OTP, apertura/compilazione questionario loggati (`logAudit`).
- GDPR: l'email del referente è dato personale → retention + cancellazione su richiesta.

---

## 3.5 Caricamento anagrafica fornitori (per-azienda-cliente: CSV + API key) — requisito utente 2026-05-31

**Principio**: i fornitori NON si auto-registrano. L'**anagrafica fornitori è di proprietà dell'azienda cliente** ed è **diversa per ogni org**. L'azienda cliente popola la propria lista fornitori; solo dopo, il singolo referente fornitore accede via OTP/magic-link (§3) per compilare i questionari a lui assegnati.

### Tre canali di ingestion (lato azienda cliente)
1. **Manuale** — form esistente sulla scheda fornitore (`supply-chain.html`). Già presente.
2. **Import CSV/Excel** — upload file → preview/mapping colonne → `bulkUpsert` idempotente. **Riuso del pattern già implementato** `AssetController::import()` + `bulkUpsert()` (mig. 025 asset `external_ref`/`discovery_source`). Dedup per `(organization_id, vat_number)` o `(organization_id, external_ref)`.
3. **API key all'azienda cliente** — integrazione programmatica (es. il gestionale/ERP del cliente spinge i fornitori). **Riuso dell'infra esistente** `api_keys` + pattern `X-API-Key` di `ServicesController` (come gli endpoint `ingestAssets`/`ingestIncident` già scritti). Nuovo scope dedicato **`write:suppliers`**. Endpoint upsert idempotente per `external_ref`.

### Impatto schema (additivo su `suppliers`)
- `external_ref VARCHAR NULL` — chiave di upsert idempotente dal sistema sorgente del cliente (come `assets.external_ref`).
- `source ENUM('manual','csv','api') DEFAULT 'manual'` — provenienza del record (tracciabilità/audit).
- `UNIQUE(organization_id, external_ref)` per evitare doppioni in re-import/re-push (NULL multipli ammessi → i record manuali senza ref non confliggono).

### API (lato azienda)
- `POST /api/supply-chain/import` (JWT interno) — body CSV/JSON, `bulkUpsert` con report righe ok/scartate (pattern asset import).
- `POST /api/services/suppliers` (X-API-Key, scope `write:suppliers`) — upsert idempotente per `external_ref`; un'API key è **scoped alla singola org** (come tutte le `api_keys`), hashed, revocabile, con audit.

### Sicurezza
- API key per-org, hashed in DB, scope minimo `write:suppliers`, revocabile, scadenza; ogni write logga `logAudit`. **Mai** scope cross-org.
- CSV: validazione tipo/encoding, dimensione massima, sanitizzazione campi (no formula-injection in celle `=/+/-/@`), dedup, nessuna esecuzione lato server.
- `external_ref` è opaco dal lato cliente: non usarlo mai per costruire path/query non parametrizzate.

> **Distinzione chiave**: questo §3.5 è il caricamento **dell'anagrafica** (lato azienda, API key/CSV/manuale). Il §3 è l'**accesso del referente fornitore** (OTP/magic-link) per compilare i questionari. Due piani separati, due meccanismi di auth separati.

---

## 4. Schema dati (migrazioni nuove, additive)

```
supplier_categories
  id, organization_id (NULL = preset di sistema), name, slug, description, active
  -- SEED predefinito (personalizzabile): Cloud/IaaS, MSP/MSSP, Software/SaaS,
  --   Hardware/Manutenzione, Consulenza, Logistica, Telecomunicazioni, Altro

questionnaire_templates
  id, organization_id, category_id (FK, NULL = tutte le categorie),
  name, version, scope ENUM('nis2','privacy','quality','231','esg','custom'),
  recurrence_months (NULL = una tantum, configurabile),
  due_days_default (NULL = nessun default), is_active, created_by, created_at
  -- versioning come policy_versions: snapshot a ogni pubblicazione

questionnaire_questions
  id, template_id, order_index, code, text,
  type ENUM('yes_no_partial','scale_1_5','single_choice','multi_choice','text','number','file'),
  options JSON, weight, required, help_text

questionnaire_campaigns
  id, organization_id, supplier_id, template_id, template_version,
  status ENUM('draft','sent','in_progress','completed','expired','overdue'),
  access_token_hash, sent_to_email, sent_at,
  due_at (NULL ammesso), recurrence_months, next_recurrence_at,
  reminder_offsets JSON (es. [-14,-7,-1]; configurabile), next_reminder_at, reminder_count,
  score, risk_level, completed_at

questionnaire_answers
  id, campaign_id, question_id, answer_value, answer_text, file_ref, answered_at

supplier_users           -- account fornitore (OTP, no password)
  id, supplier_id, email, display_name, status, last_login_at, created_at

supplier_otp
  id, supplier_user_id, otp_hash, magic_token_hash, purpose,
  expires_at, used_at, attempts, ip_created
```

`suppliers` esistente: aggiungere `category_id` (FK) — `contact_email` già presente.

---

## 5. API

### Lato azienda (JWT interno)
- `GET/POST/PUT/DELETE /api/supply-chain/categories`
- `GET/POST/PUT /api/supply-chain/templates` (+ versioning)
- `GET/POST/PUT/DELETE /api/supply-chain/templates/{id}/questions`
- `POST /api/supply-chain/{supplierId}/campaigns` (scegli template per categoria, due_at, ricorrenza, reminder)
- `GET /api/supply-chain/campaigns` (cruscotto stato/scadenze)

### Lato fornitore (portale, sessione OTP — namespace dedicato `/api/supplier-portal/*`)
- `POST /api/supplier-portal/request-otp` (body: email) → invia OTP/magic-link (risposta opaca)
- `POST /api/supplier-portal/verify-otp` (email + codice) → sessione fornitore
- `GET /api/supplier-portal/me` → anagrafica + questionari assegnati + scadenze
- `GET /api/supplier-portal/questionnaire/{campaignId}` → template dinamico da compilare
- `POST /api/supplier-portal/questionnaire/{campaignId}/submit` → salva risposte + scoring

### Cron scadenze (`scripts/supplier-questionnaire-cron.sh`, TZ Europe/Rome)
- invia reminder agli offset configurati, marca `overdue`, apre la ricorrenza alla scadenza.

---

## 6. UI

- **supply-chain.html** (lato azienda): tab "Categorie", "Template questionari" (editor domande ordinabile), "Campagne/scadenze" (cruscotto con semaforo in-regola/in-scadenza/scaduto). Sulla scheda fornitore: dropdown categoria + "Avvia campagna".
- **supplier-portal.html** (NUOVA, stesso dominio): step OTP (inserisci email → inserisci codice) → dashboard fornitore (questionari assegnati, scadenze, storico) → compilazione dinamica del template. `noindex,nofollow`, nessun link all'app interna.
- **supplier-assessment.html**: confluisce nel portale o resta come fallback link-token diretto.

---

## 7. Fasi incrementali

| Fase | Contenuto | Rischio |
|---|---|---|
| **0 (PREREQUISITO)** | `EmailService::sendViaRelay()` via relay AgileHub (`X-Internal-Key`, cURL come `SsoHelper::postInternal`, env multi-source per clear_env FPM). Ripuntare `sendQuestionnaire`/`forgotPassword` (oggi usano `mail()` → falliscono in silenzio). **Bloccante: senza, OTP/reminder/inviti non recapitano.** | Basso ma bloccante |
| **1** | Categorie (seed + CRUD) + template/domande configurabili in DB (migra le 8 domande) + render dinamico. Scrivere già le risposte in `questionnaire_answers` (campaign-stub) per non migrare in Fase 2. | Basso |
| **2** | Campagne con scadenze/ricorrenze configurabili + reminder (cron) + cruscotto. | Medio |
| **3** | **Portale fornitore + auth OTP/magic-link** (`supplier_users`, `supplier_otp`, `/api/supplier-portal/*`, supplier-portal.html). | Alto (auth esterna) |
| **4** | Tipi domanda avanzati (allegati/scale/multi) + scoring configurabile per peso. | Medio |

Fasi 1-2 danno già categorie + questionari configurabili + scadenze. Fase 3 aggiunge il portale OTP persistente.

---

## 8. Punti di sicurezza non negoziabili
- `supplier_users`/sessione fornitore totalmente isolati da `users` interni (no IDOR cross-fornitore, no accesso dati org).
- OTP hashed, scadenza breve, rate-limit, risposta opaca.
- Segreti/eventuali integrazioni nel vault, non in DB/Git.
- Tutti gli endpoint `/api/supplier-portal/*` validano che il `campaignId`/risorsa appartenga al `supplier_id` della sessione.

---

## 9. Stima (multi-sessione)
- Fase 1: ~1 sessione · Fase 2: ~1 sessione · Fase 3 (portale+OTP): ~1.5-2 sessioni · Fase 4: ~0.5.
Tutto additivo; nessuna modifica distruttiva ai moduli esistenti.

---

## 10. Decisioni APPROVATE (utente, 2026-05-31)
1. ✅ Set categorie predefinite confermato (Cloud/IaaS, MSP/MSSP, Software/SaaS, Hardware/Manutenzione, Consulenza, Logistica, Telecomunicazioni, Altro) — personalizzabili.
2. ✅ Auth: **OTP a 6 cifre + magic-link, ENTRAMBI** (il fornitore può usare l'uno o l'altro).
3. ✅ **Sessione fornitore = 4 ore**; **validità OTP/magic-link = 15 minuti**, single-use, max 5 tentativi, rate-limit.
4. ✅ Processo: prima **review del design da 5 agenti** (COMPLETATA 2026-05-31, esiti §12), poi implementazione partendo dalla **Fase 0** (prerequisito email relay) → **Fase 1**.
5. ✅ **DECISO (utente, 2026-05-31, post-review)**:
   - (a) **Migrazione + sostituzione**: `questionnaire_campaigns` sostituisce `supplier_questionnaires` (027). Migrazione dati `INSERT…SELECT`, retrocompat dei link `sq_` già inviati, 027 deprecata. Una sola fonte di verità.
   - (b) **Template "NIS2 base" completo GV.SC** già in Fase 1: 8 domande attuali + domande mappate ai 5 fattori GV.SC-07 e agli ambiti GV.SC-01 §2 (con `nis2_ref` e fonti certe). Modulo "compliance-grade" dall'inizio.
   - (c) **Anagrafica fornitori via manuale + CSV + API key cliente** (§3.5) inclusa nel piano.
6. ✅ **Contesto normativo + AI consulente (come TRPG)** — vedi §13. Pilastro trasversale: corpus normativo NIS2 incluso e mantenuto aggiornato nella KB, AI istruita a rispondere come consulente NIS2 reale, sempre ancorata alle fonti certe.

## 11. Promemoria post-implementazione (regola progetto — VINCOLANTE per ogni fase)
Ad ogni fase che cambia funzionalità, aggiornare SEMPRE:
- **Guida** (`public/guida.html`): nuovo capitolo/sezione "Portale fornitori" + àncora; allineare help.js `_guideAnchor`.
- **Help online** (`public/js/help.js`): sezione contestuale per supply-chain (questionari/portale) e per la pagina portale.
- **Traduzioni** (`public/js/i18n.js`): chiavi IT + EN per le nuove UI (categorie, template, campagne, portale, OTP).
- **KB AI / product_knowledge**: aggiornare la knowledge base AI (RAG + product_knowledge AgileHub) con la nuova funzionalità, così l'assistente la conosce.
- `version.json` bump, commit per fase, push da host.

---

## 12. Esiti review 5 agenti (2026-05-31) + correzioni al design

Verdetto comune dei 5 reviewer (sicurezza OTP, UX, architettura/DB, fattibilità stack, GDPR/supply-chain): **impianto solido, NON implementabile "as-is"**. Le correzioni 🔴 qui sotto sono da chiudere prima della Fase 1; le ⚠️ in corso d'opera. Convergenze forti tra più agenti = priorità massima.

### 🔴 Bloccanti (recepiti nel design)
1. **Fase 0 — Email relay** *(fattibilità)*: `EmailService::send()` usa `mail()` (rotto nel container). Aggiungere `sendViaRelay()` via AgileHub `POST /api/emails/send` con `X-Internal-Key`, env multi-source (`getenv()?:$_SERVER?:$_ENV?:default` per clear_env FPM). **L'OTP va inviato via template `/api/emails/send` (NON `send-raw`)** così il codice non finisce nei log `email_log` *(convergenza sicurezza+fattibilità)*.
2. **Auth fornitore = libreria SEPARATA** *(sicurezza+architettura+fattibilità, 3 agenti)*: `SUPPLIER_JWT_SECRET` dedicato (da vault/.env), claim `aud:"supplier-portal"` SENZA `user_id`, `requireSupplierSession()` proprio. **MAI** passare per `BaseController::requireAuth()`/`active_sessions`. Sessione revocabile via tabella `supplier_sessions` (jti verificato a DB). Lockout persistente su `supplier_otp.attempts` + rate-limit DB (non solo `/tmp`), invalidazione OTP precedenti, `hash_equals`.
3. **`questionnaire_answers` con `organization_id`** denormalizzato *(architettura)* + `UNIQUE(campaign_id, question_id)` + FK `ON DELETE CASCADE` → no leak cross-org/IDOR.
4. **Schema → DDL completa** *(architettura)*: PK/FK/indici/tipi reali prima di codare. Indici sargable cron: `(status, next_reminder_at)`, `(status, due_at)`. `UNIQUE(organization_id, slug)` categorie + sentinel `organization_id=0` per i preset.
5. **Coesistenza vs migrazione `supplier_questionnaires` (027)** *(architettura+fattibilità)*: `questionnaire_campaigns` è superset di 027. **DECISIONE NEL DESIGN** (vedi §10 punto 5). Migrazioni nuove numerate **032+**, idempotenti via `information_schema` (no `ADD COLUMN IF NOT EXISTS`), applicate `mysql -h localhost` da Hetzner. Retrocompat token `sq_` + endpoint `public-questionnaire` in produzione.
6. **Versioning template = snapshot dedicato** *(architettura+UX, F17)*: tabella `questionnaire_template_versions(template_id, organization_id, version, questions_snapshot JSON incl. weight, change_note, created_by, UNIQUE(template_id,version))` come `policy_versions`. Le campagne in corso restano congelate alla loro versione.
7. **Contenuto normativo del template "NIS2 base"** *(GDPR/supply-chain)*: coprire i **5 fattori GV.SC-07** + ambiti **GV.SC-01 §2 a-q** applicabili (cancellazione dati a fine fornitura, subfornitura, secure development, ruoli personale GV.SC-02); campo `nis2_ref` per mapping; scoring **per-vulnerabilità** (flag "no MFA"/"no patch"/…) oltre al totale (Art.21.3), modulato per `criticality`. Fonti da aggiungere a `nis2_sources.php`: ENISA Good Practices SC + NIST SP 800-161r1.
8. **GDPR** *(GDPR/supply-chain)*: base giuridica = legittimo interesse Art.6(1)(f) + obbligo legale (c) (LIA); **informativa Art.13/14** in email OTP + landing portale (titolare=cliente, Agile=responsabile Art.28 + sub-processor disclosure); retention quantificata (purge `supplier_otp` 24-48h via cron; risposte/`supplier_users` per durata relazione + ≥5 anni audit); endpoint cancellazione/anonimizzazione Art.17 con tombstone (no distruzione evidenze).
9. **Immutabilità evidenze** *(GDPR/supply-chain)*: `questionnaire_answers` append-only + log submit/scoring in `AuditService` (hash-chain); ogni campagna conserva il proprio snapshot risposte+score (no sovrascrittura); **soft-delete** fornitore (`deleted_at`, no hard `Database::delete`).
10. **Salvataggio parziale (autosave)** *(UX, F11 — priorità assoluta)*: stato `in_progress` + endpoint `PATCH .../answers` (autosave per-domanda con `debounce`), "salva bozza" vs "invia". Le risposte parziali sopravvivono a logout/scadenza sessione.

### 🔴/⚠️ Routing (architettura+fattibilità)
Aggiungere `'supplier-portal' => 'SupplierPortalController'` a `controllerMap`. Modellare gli URL sulle forme che il router **produce davvero** (id numerico primo segmento): `POST:requestOtp`, `POST:verifyOtp`, `GET:me`, `GET:{id}` (campagna), `POST:{id}/submit`, `PATCH:{id}/answers`. La notazione `{campaignId}` del doc NON è riconosciuta.

### ⚠️ UX da chiudere nel design (mini-spec §6)
- **Email invito progettata** (F6): nome committente in oggetto/corpo, motivo, ~tempo, scadenza in chiaro, CTA singola, branding firm.
- **Gestione "email non arriva" + errori OTP umani** (F2/F3): countdown reinvio, "controlla spam", messaggi specifici allo step verifica (errato/scaduto/lockout/già usato) ognuno con via d'uscita; preservare rigenera-link manuale lato azienda.
- **Magic-link primario, OTP fallback** (F1) + niente doppio-consumo da prefetch mail mobile (F4): consumo solo all'apertura sessione esplicita.
- **Editor template no-code** (F16): nascondere slug/code/order_index/options JSON/reminder_offsets/recurrence_months/weight dietro chip/dropdown/drag + preview "come lo vede il fornitore".
- **i18n portale** (F20): lingua IT/EN impostabile dal cliente o selezionabile (fornitori esteri).
- **Ricevuta** (F22): email conferma + PDF risposte scaricabile. **Multi-referente/delega** (F24). **Score al fornitore configurabile, default OFF** (F23). **Progress bar** (F13). **Scadenza sempre visibile** (F7). **Mobile-first + a11y** (F10/F21): elementi nativi, ARIA, touch ≥44px, `autocomplete="one-time-code"`.

### ⚠️ Operativo (fattibilità)
Cron `supplier-questionnaire-cron.sh` (primo `.sh` del progetto): wrapper sottile + runner PHP CLI, `TZ=Europe/Rome`, fuori finestra DST 02:00-03:00, idempotente (UPDATE condizionato), entry in `CRON_REGISTRY.md`, crontab via richiesta utente. Disciplina: `kill -USR2 1` dopo ogni edit PHP, semaforo `/tmp/agent-working.lock`, commit per fase, push da host.

### Stima realistica rivista
~**6-7 sessioni** (vs 4): Fase 0 ~0.5 · Fase 1 ~1-1.5 · Fase 2 ~1.5 · Fase 3 ~2-2.5 · Fase 4 ~0.5-1.

---

## 13. Pilastro trasversale — Contesto normativo incluso/aggiornato + AI "vero consulente" (richiesta utente 2026-05-31, modello TRPG)

**Obiettivo**: NIS2 Agile deve comportarsi come un **consulente NIS2 reale** — conoscere e citare la normativa vigente (NIS2, D.Lgs. 138/2024, Determine/Allegati ACN, ENISA, NIST), tenerla **aggiornata**, e rispondere **sempre ancorata a fonti certe** (mai inventate). Allineamento al pattern già in uso su TRPG.

**Cosa esiste già in NIS2** (da censire e potenziare):
- RAG completo: Qdrant `nis2_kb` (512-dim Voyage), `VectorService`/`EmbedService`/`RagService`, `AIService::askWithRag()`.
- Registro fonti certe `application/config/nis2_sources.php` + `AIService::authoritativeSourcesBlock()` (vieta riferimenti inventati).
- Ingest corpus normativo: `scripts/ingest-nis2-sources.php` (PDF normativi → `nis2_kb` scope SYSTEM).
- Corpus locale: `docs/nis2/` (direttiva ITA, allegati ACN 1-4, ecc.).

**Gap da colmare** (output dell'agente di design dedicato):
1. **Completezza corpus**: verificare che TUTTE le fonti di `nis2_sources.php` siano effettivamente ingerite in `nis2_kb`; aggiungere ENISA Good Practices SC e NIST SP 800-161r1 (citati nel design ma assenti dal registro — F-12).
2. **Aggiornamento**: meccanismo per mantenere il corpus aggiornato (nuove Determine ACN, feed normativo già presente come `normative_updates`) → ingest incrementale + tracciamento versione fonte.
3. **AI "consulente"**: rafforzare i system prompt (persona consulente NIS2, tono, scope, citazione obbligatoria fonti) coerente con lo standard `persona-conversational-rules v2.0` (persona ARIA_SUPPORT_NIS2 già esistente). Ogni risposta normativa cita §/articolo della fonte.
4. **Copertura supply-chain**: il consulente deve saper rispondere su GV.SC-01..07, art.21.2(d)/21.3, e guidare la compilazione dei questionari fornitori (collega §7 fasi a questo pilastro).

**Nota**: questo pilastro è parzialmente indipendente dal modulo questionari ma li potenzia (help in-context durante la compilazione, spiegazione dei `nis2_ref`). Sequenziabile in parallelo alle Fasi.

---

## 14. Stato lavorazione (2026-05-31)
- ✅ Design + 5 review + decisioni utente consolidate (§10, §12, §13).
- ✅ 4 agenti di produzione-design completati e **materializzati come artefatti** (nessun codice applicato, nessun commit):
  - (A) Contenuto template GV.SC → `docs/supplier-portal/template-nis2-base.questions.json` (26 domande, `nis2_ref`/`vuln_flag`, fonti certe verbatim).
  - (B) Pilastro AI consulente + corpus → `docs/supplier-portal/AI_CONSULENTE_NORMATIVO.md`.
  - (C) DDL migrazioni → `docs/sql/032_supplier_questionnaires_module.sql`, `033_suppliers_category_source.sql`, `034_supplier_portal_auth.sql`, `035_migrate_027_to_campaigns.sql` (idempotenti, NON applicate).
  - (D) Mini-spec UX §6 → `docs/supplier-portal/UX_MINI_SPEC.md`.
- ⏳ Prossimo (su conferma utente): commit del pacchetto design su Gitea → implementazione **Fase 0** (email relay) → **Fase 1** (categorie + template GV.SC + import CSV/API + render dinamico), con `kill -USR2 1`/smoke/commit per fase e aggiornamento guida/help.js/i18n/KB AI.

### Roadmap implementazione consolidata (ordine)
| # | Fase | Output | Migrazioni | Rischio |
|---|---|---|---|---|
| 0 | Email relay | `EmailService::sendViaRelay()` + ripuntare sendQuestionnaire/forgotPassword | — | Basso (sblocca + fixa bug prod) |
| 1 | Categorie + template GV.SC + anagrafica (CSV/API) + render | seed 10 categorie + template NIS2 base (26 dom.) + import suppliers | 032, 033 | Basso |
| 2 | Campagne + scadenze/ricorrenze + reminder cron + cruscotto | — | (035 migrazione 027) | Medio |
| 3 | Portale fornitore + auth OTP/magic-link separata + sessioni revocabili | — | 034 | Alto (auth esterna) |
| 4 | Tipi domanda avanzati (file/scale/multi) + scoring per-vulnerabilità + ricevuta PDF | — | — | Medio |
| ‖ | Pilastro AI consulente (parallelo): corpus completo + persona + feed→KB + AI in-context | — | (KB su Hetzner) | Medio |