[DOCS] Design modulo questionari fornitori + portale OTP + AI consulente normativo

Pacchetto di design completo (nessun codice applicato, nessuna migrazione eseguita):
- DESIGN aggiornato con 5 review agenti + 3 decisioni utente + pilastro AI consulente (sez. 12-14)
- docs/supplier-portal/template-nis2-base.questions.json: 26 domande GV.SC (Allegato 2 ACN) con nis2_ref/vuln_flag e fonti certe verbatim
- docs/supplier-portal/AI_CONSULENTE_NORMATIVO.md: corpus normativo aggiornato + persona consulente (modello TRPG)
- docs/supplier-portal/UX_MINI_SPEC.md: mini-spec portale fornitore (stati/copy/autosave/mobile/a11y/editor no-code)
- docs/sql/032-035: migrazioni idempotenti proposte (modulo, suppliers, portale auth, migrazione 027->campaigns)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/DESIGN_MODULO_QUESTIONARI_FORNITORI.md

@@ -48,6 +48,33 @@ Valore: due-diligence continua dei fornitori (Art. 21.2(d) NIS2; coerente con EN
 
 ---
 
+## 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)
 
 ```
@@ -124,7 +151,8 @@ supplier_otp
 
 | Fase | Contenuto | Rischio |
 |---|---|---|
-| **1** | Categorie (seed + CRUD) + template/domande configurabili in DB (migra le 8 domande) + render dinamico. Riusa il link-token attuale. | Basso |
+| **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 |
@@ -151,7 +179,12 @@ Tutto additivo; nessuna modifica distruttiva ai moduli esistenti.
 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**, poi implementazione partendo dalla **Fase 1**.
+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:
@@ -160,3 +193,79 @@ Ad ogni fase che cambia funzionalità, aggiornare SEMPRE:
 - **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 |