nis2-agile/docs/DESIGN_A4_RELATIONAL.md

# DESIGN — A4: Modello relazionale (organigramma RACI ↔ skill / formazione / inventario / procedure / rischi + scadenziario)

> Stato: **IN CORSO**. Contesto: segnalazioni Simon Fattori, punti **2, 3, 4, 5, 6, 7** (accolti in A4). Data: 2026-06-15.
> È l'epic più grande → da realizzare a **FASI**. Ancoraggio normativo verificato (Det. ACN 164179/2025 + D.Lgs. 138/2024). Vedi `reference-dlgs-articles`, `DESIGN_A2_ONBOARDING.md`.
>
> **AVANZAMENTO**: ✅ **4.1 Organigramma** (`041_org_roles.sql`, `OrgRoleController`, `organigramma.html`) — LIVE. ✅ **4.2 Competenze** (`042_competences.sql`: `skills`/`role_skills`/`user_skills`/`skill_course_map`; `CompetenceController`; `competenze.html`) — LIVE. ✅ **4.3 Matrice RACI** (`043_raci.sql`: `raci_assignments` + `procedure_inventory`/`procedure_risk`/`inventory_risk`/`risk_measure`; `RaciController`; `raci.html`+`raci.js`; object_id polimorfico anti-IDOR app-layer) — LIVE (commit `b4d47d5`). ✅ **4.4 Scadenziario** (`044_review_schedule.sql`; `ReviewScheduleController` list/complete/sync; `review-schedule.html`) — LIVE. ✅ **4.5 Stakeholder estesi** (`045_stakeholders.sql` suppliers.stakeholder_type; `SupplyChainController::stakeholderMap`; `stakeholders.html`) — LIVE (commit `c5b00cc`). **🎉 A4 COMPLETA (5/5).**
>
> 🔴 **RETTIFICA NOMI REALI (verificata sul codice)**: questo design parlava di una tabella **`corrective_actions`** che **NON ESISTE**. La tabella delle azioni reale è **`capa_actions`** (mig.004), **figlia obbligatoria** di **`non_conformities`** (NCR) via `ncr_id NOT NULL`, e **non ha** una colonna `source_type`. L'alert "gap → azione" (impl. in 4.2) quindi **NON** crea `corrective_actions`/`source_type`: crea una **`non_conformities`** ancorata al gap (`source='management_review'`, `source_entity_type='competence_gap'`, `source_entity_id=role_skills.id`) + una **`capa_actions`** figlia. Le menzioni di `corrective_actions`/`source_type` qui sotto vanno lette in questo senso.

## 0. Principio
A4 trasforma i moduli oggi "a silos" in un **grafo relazionale** con al centro l'**organigramma** (ruoli/responsabilità) e la **matrice RACI** come hub che lega i ruoli agli oggetti (inventario, procedure, rischi). Obiettivo: compliance *vissuta e dimostrabile in audit* (chi è responsabile di cosa, con quali competenze, con quali scadenze).

## 1. Stato attuale (da ESTENDERE)
| Ambito | Esiste? | Note |
|---|---|---|
| RACI ruoli | Parziale | `isms_roles` (mig.037): `role_name`, `user_id`, `responsibility`, `raci ENUM(R,A,C,I)` — ma **legato a un `isms_model`** (SGSI clausola 5.3), 1 valore RACI per ruolo, **non** matrice ruolo×oggetto |
| Organigramma org-wide | NO | nessuna gerarchia ruoli, nessun "nodo organo di gestione/board" |
| Skill / mansioni / competenze | NO | — |
| Gap competenze | NO | — |
| Formazione | SÌ | `training_courses` / `training_assignments` (`target_role` solo ENUM, non FK a ruolo) |
| Procedure | SÌ | `policies` (+ `policy_versions`, `next_review_date`) |
| Inventario | SÌ | `assets` (+ `relevance_score`/`is_nis2_relevant` GV.OC-04) |
| Rischi | SÌ | `risks` (+ `risk_treatments`, `kri`) |
| Fornitori/stakeholder | SÌ | `suppliers` (Supply Chain) |
| Azioni | SÌ | `non_conformities` / `corrective_actions` (mig.004) |
| Scadenziario centralizzato | NO | scadenze sparse (`policies.next_review_date`, `compliance_controls.next_review_date`, `*.due_date`) |

## 2. Modello entità + relazioni (il cuore)
**Nuove tabelle** (additive):
- **`org_roles`** — organigramma: `id, organization_id, role_name, parent_role_id NULL (gerarchia), holder_user_id NULL, is_governance_body TINYINT (nodo organi di amministrazione/direttivi, Art.23), description, created_at`. *(L'`isms_roles` SGSI può puntare a `org_roles` via `org_role_id` opzionale; non si duplica.)*
- **`skills`** — catalogo competenze: `id, organization_id NULL(=globali), name, area`.
- **`role_skills`** — competenze RICHIESTE da un ruolo: `role_id → org_roles, skill_id, required_level (1-5)`. (m2m ruolo↔skill)
- **`user_skills`** — competenze POSSEDUTE: `user_id, skill_id, level (1-5), acquired_via (course_id NULL → training), evidence`. (m2m utente↔skill, collegato al registro corsi)
- **`skill_course_map`** — skill ↔ corso che la eroga: `skill_id, training_course_id`. (collega competenze ↔ formazione)
- **`raci_assignments`** — **MATRICE RACI** (hub): `id, organization_id, role_id → org_roles, object_type ENUM('inventory','procedure','risk','supplier'), object_id, raci ENUM('R','A','C','I')`. → lega l'organigramma a inventario/procedure/rischi/fornitori (m2m via questa tabella).
- **link m2m diretti** (richiesti dalle segnalazioni 4/5/7): `procedure_inventory(procedure_id, asset_id)`, `procedure_risk(procedure_id, risk_id)`, `inventory_risk(asset_id, risk_id)`, `risk_measure(risk_id, measure_code)` (le misure ACN dell'assessment).
- **`review_schedule`** — **SCADENZIARIO centralizzato**: `id, organization_id, entity_type ENUM('role','skill','inventory','procedure','risk','supplier','measure'), entity_id, owner_role_id NULL, frequency_months, last_reviewed_at, next_review_date, status ENUM('ok','due','overdue'), notes`. Aggrega/sostituisce le scadenze sparse.
- **azione da alert** → **riuso `non_conformities` + `capa_actions`** (mig.004): l'alert (gap competenza, scadenza, rischio) crea una NCR ancorata via `source_entity_type`/`source_entity_id` (es. `'competence_gap'` + `role_skills.id`) e una `capa_actions` figlia. *(NON esiste `corrective_actions`/`source_type`: si riusa l'intero workflow CAPA senza alterarne lo schema.)*

**Relazioni chiave** (tutte m2m dove indicato dalle segnalazioni):
```
org_roles ──< raci_assignments >── (inventory | procedure | risk | supplier)
org_roles ──< role_skills >── skills ──< user_skills >── users
skills ──< skill_course_map >── training_courses
procedures ──< procedure_inventory >── inventory ──< inventory_risk >── risks
procedures ──< procedure_risk >── risks ──< risk_measure >── misure ACN (assessment)
(role|skill|inventory|procedure|risk|supplier) ──1:N── review_schedule
gap competenze / scadenze / rischi ──trigger──> non_conformities ──< capa_actions (workflow CAPA)
```

## 3. Gap competenze (segnalazione 3)
**Gap = `role_skills.required_level` (del ruolo che l'utente ricopre) − `user_skills.level`** per ciascuna skill richiesta. Vista `competence_gap` (calcolata): per ogni utente con `org_roles.holder_user_id`, confronto richiesto vs posseduto. **Alert** quando gap > 0 → apertura **azione** = NCR (`non_conformities`, `source_entity_type='competence_gap'`, `source_entity_id=role_skills.id`) + `capa_actions` figlia (+ in futuro voce nello **`review_schedule`**). Ancoraggio: **PR.AT-01** (tutti), **PR.AT-02** (solo essenziali), **GV.RR-04** (cyber nelle pratiche HR).

## 4. Ancoraggio normativo per entità (must-have)
- **Organigramma/ruoli** → **GV.RR-02** (ruoli, responsabilità e poteri stabiliti/comunicati) + **Art. 23 D.Lgs. 138/2024** (responsabilità organi di amministrazione e direttivi) → **`is_governance_body`** obbligatorio come nodo distinto con potere di approvazione.
- **Skill/formazione** → **PR.AT-01/02**, **GV.RR-04**.
- **Inventario** → **ID.AM-01/02** (+03 essenziali); collegare al **registro GV.OC-04** (`relevance_score`), non duplicarlo.
- **Procedure** → **GV.PO-01** (policy) + **GV.PO-02** (riesame/aggiornamento → scadenziario obbligatorio).
- **Rischi** → **Art. 24 D.Lgs.** + **GV.RM-03** + famiglia **ID.RA**; mappabili sulle misure (37 importanti / 43 essenziali, fino al livello requisito).
- **Stakeholder/fornitori** (segnalazione 6) → **GV.SC-02** include fornitori **+ clienti + partner** (non solo fornitori) + **GV.SC-04/05/07**; non duplicare il modulo Supply Chain esistente.
- **Scadenziario** → la revisione periodica è obbligo per **GV.PO-02**, **GV.SC-07**, **PR.AT**, **DE.CM** (periodicità puntuale come buona prassi dove non fissata).

## 5. Migration (additiva) — sketch
Nuova `041_relational_model.sql`: `org_roles`, `skills`, `role_skills`, `user_skills`, `skill_course_map`, `raci_assignments`, `procedure_inventory`, `procedure_risk`, `inventory_risk`, `risk_measure`, `review_schedule` (+ `corrective_actions.source_type`). Tutte con `organization_id` + FK + UNIQUE sulle coppie m2m. Idempotente (runner come 039/040).

## 6. UI (a fasi)
- **Organigramma**: vista ad albero (ruoli, holder, RACI badge), editor ruolo.
- **Matrice RACI**: griglia ruolo × oggetto con celle R/A/C/I.
- **Gap competenze**: dashboard per utente/ruolo (richiesto vs posseduto) + CTA "apri azione/assegna corso".
- **Scadenziario**: calendario/tabella unica delle revisioni (filtrabile per entità, owner, stato due/overdue).
- Link m2m editabili nelle pagine inventario/procedure/rischi.

## 7. Fasi consigliate (A4 è grande → spezzare)
- **4.1** `org_roles` (organigramma + nodo governance Art.23) + vista albero.
- **4.2** `skills`/`role_skills`/`user_skills`/`skill_course_map` + gap competenze (segn. 3) + alert→azione.
- **4.3** `raci_assignments` (matrice RACI) + link m2m procedure/inventario/rischi (segn. 4/5/7).
- **4.4** `review_schedule` centralizzato (segn. trasversale) + migrazione delle scadenze esistenti.
- **4.5** estensione stakeholder a clienti/partner (segn. 6, GV.SC-02) riusando Supply Chain.

## 8. Cosa NON cambia / riuso
Riuso `training_*`, `policies`, `assets` (+relevance GV.OC-04), `risks`, `suppliers`, `corrective_actions`. `isms_roles` resta per la SoA SGSI (può linkare `org_roles`). Nessuna modifica ai flussi auth/onboarding/incidenti. `entity_type`/schema esistente invariati.