nis2-agile/docs/HANDOFF_C5_STAKEHOLDER.md

# HANDOFF — Epic C / C5: Modulo Stakeholder (mappatura + Mendelow + attività)

> Documento di passaggio di consegne per un NUOVO prompt che implementerà **C5**, l'ultimo
> punto delle segnalazioni di Simon Fattori. C1–C4 sono GIÀ LIVE. Leggi questo file + la memoria
> `project-epic-c-simon` prima di iniziare. Aggiornato 2026-06-16.

---

## 0. Cosa è già fatto (Epic C)

| Punto | Stato | Riferimenti |
|---|---|---|
| C1 — Elenco Misure/Requisiti config-driven + valutazione per requisito + copia procedure | ✅ LIVE | mig.046/047/048, `FrameworkController`, `misure-requisiti.html`, `org_requisito_state`, `cfg_nis2_*` |
| C2 — «Determinazione» (non «Determina») | ✅ | decisione utente bloccata |
| C3 — rimosso modulo "Analisi GAP ACN" | ✅ LIVE | mig.049 (drop), RaciController ripuntato su `cfg_nis2_misure` |
| C4 — inventario a 2 voci + sottoclassi | ✅ LIVE | mig.050, `cfg_inventory_voci`/`inventory_subclassi`, `assets.voce_code/subclass_id` |
| **C5 — modulo Stakeholder** | ⏳ **DA FARE** | questo documento |

HEAD al passaggio: `8df8a5d`. **Prossima migrazione = `051`**. Versione corrente `1.18.4`.

---

## 1. La spec C5 (testo VERBATIM di Simon — da rispettare alla lettera)

> C5 - la mappatura e la gestione degli stakeholder deve essere organizzata così:
> 1. l'utente seleziona il tipo stakeholder, con descrizione, dall'elenco (`docs/simon/C5_EleStakeH.xlsx`); l'utente può modificare l'elenco aggiungendo voci e tu provvederai alla codifica proseguendo la numerazione dall'ultimo codice che è **Stak.30**.
> 2. l'utente inizia a inserire i suoi stakeholder tramite un'anagrafica semplificata che deve comunque comprendere un **collegamento all'organigramma** per stakeholder interni, un **collegamento alle procedure**, una griglia di due valutazioni con valori da **0 a 5**: «grado di **potere** sull'azienda» e «grado di **interesse** sull'azienda».
> 3. gli stakeholder così valutati saranno collocati su un **grafico a quattro quadranti**: asse **x = interesse**, asse **y = potere**.
>    - **Q1 in alto a sinistra** (interesse 0-2, potere 3-5): *Stakeholder Istituzionali / Keep Satisfied* — Tenerli soddisfatti. Forte potere di blocco, scarso interesse quotidiano. Evitare scontenti improvvisi.
>    - **Q2 in alto a destra** (interesse 3-5, potere 3-5): *Stakeholder Chiave / Gestisci Attivamente* — Gestione attiva e coinvolgimento costante. Decisori principali, supporto vitale.
>    - **Q3 in basso a destra** (interesse 3-5, potere 0-2): *Stakeholder Operativi / Keep Informed* — Tenere informati. Molto coinvolti, scarso peso decisionale.
>    - **Q4 in basso a sinistra** (interesse 0-2, potere 0-2 — vedi §4 nota refuso): *Stakeholder Marginali / Monitorare* — Monitoraggio costante col minimo sforzo. Comunicazioni periodiche non dispendiose.
> 4. il dashboard stakeholder deve prevedere **attività**:
>    4.1 le attività possono essere **azioni e/o questionari** da inviare, con collegamento all'elenco procedure;
>    4.2 il modulo azioni lo trattiamo più avanti *(NB: esiste già il workflow NCR/CAPA — vedi §5)*;
>    4.3 i **questionari** devono prevedere un **sotto-dashboard di ricezione feedback** (questionari compilati o la firma di avvenuta lettura, a seconda del tipo) + possibilità di **commentare** l'attività e **allegare file**;
>    4.4 l'utente deve poter assegnare un'attività a un **codice stakeholder** oppure selezionare **singolarmente** ogni stakeholder (anche di codice diverso);
>    4.5 devono esistere **questionari tipo** con collegamento sia all'elenco procedure sia all'elenco misure/requisiti in **rapporto molti-a-molti**;
>    4.6 ogni attività deve poter essere **pianificata con data e scadenza** e con collegamento a un **calendario del sistema NIS2**.

---

## 2. Fonte dati autoritativa (codifica NON variabile)

- **`docs/simon/C5_EleStakeH.xlsx`** → 30 tipi `Stak.01`–`Stak.30`. **Interni**: Stak.01–06 (Dipendenti, Management, Azionisti, Collaboratori, Sindacalisti, Volontari/Associati). **Esterni**: Stak.07–30 (Clienti finali/aziendali, Fornitori materie prime/servizi, Partner strategici, Rivenditori, Governo/autorità, Camera di commercio, Agenzie di regolamentazione, Comunità locale, ONG, Giornalisti/blogger, Sponsorizzati, Influencer, Banche, Assicurazioni, Sponsor, Investitori privati, Donatori, Associazioni di categoria, Competitor, Attivisti ambientali, Organizzazioni di consumatori, Rappresentanti sindacali).
- **GIÀ DISPONIBILI parsati** in `application/data/nis2_framework_seed.json` → chiave **`stakeholder_types`** (array di `{code,tipo,descr}`, 30 elementi). Riusa quelli o ri-parsa l'xlsx (parser stdlib in cronologia, zipfile+xml, no openpyxl). NON variare codici/descrizioni.
- Nuovi tipi aggiunti dall'utente → **proseguire da `Stak.31`** (codifica automatica).

---

## 3. Validazione normativa (già fatta con `nis2-expert`)

- **Estensione a fornitori/clienti/partner = ancorata a GV.SC-02** (testo verbatim "fornitori, clienti e partner"). OK.
- **La matrice Mendelow (potere/interesse) è BEST PRACTICE, NON un obbligo NIS2.** → etichettarla come tale in AI/help (regola "fonti certe" di `application/config/nis2_sources.php`). NON spacciarla per requisito.
- L'obbligo VERO è GV.SC-02: ruoli/responsabilità di sicurezza per fornitori/clienti/partner + personale terze parti nell'elenco GV.RR-02 p.2. Assicurarsi che il modulo produca QUESTI artefatti, non solo la "bella matrice".
- Ancoraggio comprensione stakeholder: **GV.OC** (contesto organizzativo).

---

## 4. Decisioni di design già prese

- **Config-driven** (direttiva utente, vale per tutto Epic C): tipi e quadranti in **tabelle di configurazione**, NON hardcoded.
- 🔧 **REFUSO confermato (expert + Mendelow + descrizione)**: il **quadrante Q4 (basso-sinistra, Marginali/Monitorare)** nel testo di Simon ha "potere 3-5" ma deve essere **potere 0-2** (basso potere + basso interesse). Implementare con **potere 0-2**. (Q1 alto-sx = potere 3-5/interesse 0-2.) Regola quadranti: potere≥3 = alto, interesse≥3 = alto.
- **Riusare** il modulo Supply Chain / A4 4.5 (`suppliers.stakeholder_type` ENUM supplier/customer/partner, `SupplyChainController::stakeholderMap`, `public/stakeholders.html`) — **estendere, non duplicare**.

---

## 5. Esistente da riusare (NON reinventare)

| Serve a C5 | Esiste già |
|---|---|
| Stakeholder base | `suppliers` (+ `stakeholder_type` ENUM, A4 4.5) · `SupplyChainController::stakeholderMap` · `public/stakeholders.html` |
| Link organigramma (interni) | **`org_roles`** (A4 4.1, `OrgRoleController`) |
| Link procedure | **`policies`** (`PolicyController`) |
| Link misure/requisiti (m2m questionari) | **`cfg_nis2_requisiti`** / `cfg_nis2_misure` (C1) |
| Azioni (4.2) | **`non_conformities` + `capa_actions`** (workflow NCR/CAPA, mig.004) — riusare, NON creare `corrective_actions` (non esiste) |
| Scadenze/calendario (4.6) | **`review_schedule`** (A4 4.4, `ReviewScheduleController`) — valutare se le attività stakeholder ci entrano o serve un calendario dedicato |
| Pattern matrice/valutazione | `org_requisito_state` + modale valutazione di `misure-requisiti.html` (C1) come riferimento UI |

⚠️ **Scelta dati da fare**: estendere `suppliers` con i campi C5 (stakeholder_code, potere, interesse, link org_role, link procedure) **oppure** una tabella compagna `stakeholder_profile(supplier_id, ...)`. Raccomandazione: tabella compagna additiva per non appesantire `suppliers` e tenere C5 isolato. **Decidere a inizio C5.**

---

## 6. Fasi consigliate

- **C5.1 (fondazione)**: `cfg_stakeholder_types` (seed 30 + org-added da Stak.31) + `cfg_stakeholder_quadrants` (4, con range corretti) + anagrafica estesa (tipo, potere/interesse 0-5, link organigramma per interni, link procedure) + **matrice Mendelow** (UI grafico 4 quadranti) + collocazione automatica. Endpoint + pagina (estendere `stakeholders.html`). Help/i18n/KB.
- **C5.2 (operativo)**: **attività** (azioni→NCR/CAPA, questionari) + **questionari tipo** con m2m a procedure e misure/requisiti + **sotto-dashboard feedback** (compilazione / firma lettura) + commenti + allegati + **pianificazione data/scadenza su calendario** (review_schedule o calendario dedicato). Help/i18n/KB.

---

## 7. Convenzioni operative CRITICHE (non sbagliare)

- **DB writes**: SOLO via host SSH → `docker exec nis2-app php ...`. Il devenv NON raggiunge il DB. Chiave host in **`.ssh-temp/`** (ruota ~14h: se scaduta, chiedere all'utente una chiave fresca). Pattern migrazione: scrivi `application/_migrate_051_tmp.php` self-contained (require config+database) → esegui via SSH → **rimuovilo**. Commit del solo `docs/sql/051_*.sql` (record) + eventuale `application/data/*seed*.json`.
- **Migration runner**: il runner fa `PDO::exec` con split su `;` → **MAI `DELIMITER`/stored-procedure**. Usa `CREATE TABLE IF NOT EXISTS` / `ALTER ... ADD` bare + try/catch su errno (1050 tabella esiste, 1060 colonna dup, 1061 indice dup, 1826 FK dup). **UNIQUE con `organization_id` NULL NON deduplica** (NULL≠NULL) → per i default di sistema usa un **check d'esistenza** prima dell'INSERT (vedi `_migrate_050`).
- **PHP hot-reload**: dopo OGNI edit `.php` → `docker exec nis2-app kill -USR2 1` (l'opcache non rilegge da sola).
- **Git push**: DIRETTO dal devenv (helper vault `git-credential-vault`). Commit-early.
- **Frontend / sidebar**: la sidebar V2 attiva è in **`common-bi.js`** (NON solo `common.js` — gotcha: in C3 la voce nuova era stata messa solo in common.js e non compariva). `common-bi.js` ha un **`?v=` PROPRIO** (diverso dagli altri JS) → bumparlo a parte. Cache-buster `?v=YYYYMMDD` su **tutte** le `public/*.html` quando cambi JS condivisi (`sed -i 's/?v=VECCHIA/?v=NUOVA/g'`), + bump `version.json` (MINOR per feature) + nome cache in `public/sw.js` (`nis2-shell-vX.Y.Z`).
- **Help/i18n/KB**: aggiornare `public/js/help.js` (sezione + page-mapping) + `public/js/i18n.js` (chiavi `nav.*`) + ingest KB (`POST /api/knowledgebase/ingest`, super_admin, scope SYSTEM) dopo ogni cambio funzionale.
- **DB API**: `Database::query/fetchAll/fetchOne/insert/update` — **`Database::execute` NON ESISTE**.
- **Multi-tenancy / auth**: ogni query filtra `organization_id`. `getCurrentOrgId()` è valorizzato SOLO dopo `requireOrgAccess()`/`requireOrgRole()`; con `requireAuth()` usa `resolveOrgId()` + verifica accesso a mano (vedi `FrameworkController::catalog` per il pattern anti-IDOR su letture org-opzionali). Scritture: `requireOrgRole(['org_admin','compliance_manager'])`. Il demo guard (isDemo) blocca le scritture sulle org demo.
- **Smoke test**: login tester `s.fattori@agile.software` / **`Tester2026!`** (super_admin) via `POST /api/auth/login` (curl, NON python urllib → Cloudflare 1010). Header `X-Organization-Id`. Org: **151** DataCore (importante), **152** MedClinic (essenziale), **996001/996002** sandbox (isDemo → niente seed/scritture lì). **NON inquinare i golden 151/152**: testa e poi fai cleanup (capture max id → delete > max).
- **Email**: disabilitate (kill-switch); per i questionari "da inviare" NON spedire davvero a go-live mancante — usare `send-raw` solo per test espliciti, altrimenti registrare lo stato senza invio reale.

---

## 8. Alla FINE di C5 (istruzione esplicita dell'utente)

1. **Flotta di agenti per verificare il lavoro** (Workflow multi-agente: sicurezza/correttezza/fedeltà-dato/normativa/UI → verifica avversariale → sintesi; poi correggere i finding). Vedi il workflow usato per C1 come modello.
2. **Help online + traduzioni + KB AI** (giro finale di allineamento).

---

## 9. Open items aperti (segnalare, non rimuovere)

- **92 vs 87 requisiti importanti**: il prodotto usa **92** (file di Simon, vincolante); l'`nis2-expert` contando l'Allegato 1 ufficiale trova **87**. Da riconciliare con Simon sul testo ufficiale. (Allineato a 92 in help.js + nis2_sources.php.)
- **Determinazione 333017/2025**: data esatta (mese senza giorno) in `application/config/nis2_sources.php:60` da verificare sul testo ufficiale.
- **E2E browser di C1–C4**: nuove UI (misure-requisiti, valutazione per requisito, inventario 2 voci) NON collaudate a video — far esercitare ai tester.