[DOCS] Analisi+design modulo Controlli periodici (control monitoring: frequenza + esecuzioni/evidenza + NC/AC) — documentato con esempi GRC/Eramba

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/DESIGN_CONTROLLI_PERIODICI.md

@@ -0,0 +1,70 @@
+# Analisi + Design — Modulo "Controlli periodici" (control monitoring con frequenza + NC/AC)
+
+> Proposta progettuale · 2026-06-17 · richiesta utente: "i controlli periodici dobbiamo averne evidenza → oltre al modulo Audit, un modulo controlli con frequenza e generazione NC o AC". Documentata con esempi esterni (GRC/ISMS) + recon del codice.
+
+## Perché (problema)
+La valutazione ISO ha mostrato che il software **documenta** i controlli ma serve **evidenza che i controlli OPERINO nel tempo** (clausola 9.1 monitoraggio/misurazione, controllo A.8.16 "Monitoring activities"; gap residuo su A.7/A.8). L'audit interno (§9.2) è **puntuale**; serve un livello **ricorrente** tra un audit e l'altro: il classico *Continuous/Periodic Control Monitoring* dei GRC.
+
+## Esempi esterni studiati (per non reinventare)
+- **Continuous Controls Monitoring (CCM)** nei GRC (Scytale, LogicGate, RegScale): validare che i controlli restino efficaci *tra* le revisioni formali; test a **frequenza** definita, raccolta **evidenze**, **task assegnati all'owner** per rimediare ai fallimenti, **non-conformity log + corrective action** come prova all'audit.
+- **Drata / Vanta**: "continuous control monitoring rather than periodic checks" + evidence automation + visibilità su **control ownership** e gap.
+- **Eramba** (open GRC, il modello più calzante): l'**Internal Control** ha owner, **metodologia di test, frequenza, raccolta evidenze, accountability**; i controlli sono **auditati periodicamente** (record con esito + evidenza); i fallimenti generano **finding/eccezioni** → **azione correttiva** (modulo Project) e confluiscono nel **riesame**.
+- **ISO/IEC 27001**: §9.1 (cosa/come/quando/chi misurare), A.8.16 (attività di monitoraggio), §10.2 (NC e azioni correttive). NB: ISO = buona prassi volontaria; per NIS2 è comunque buona governance (GV.PO-02/DE.CM).
+
+Sintesi del pattern comune: **Controllo (owner+frequenza+metodo) → Esecuzione periodica (esito+evidenza) → se fallisce: finding → NC/azione correttiva → riesame**. È esattamente ciò che l'utente chiede.
+
+## Posizionamento vs esistente (NON duplicare)
+| Esistente | Cos'è | Differenza |
+|---|---|---|
+| `compliance_controls` (Audit&Report) | Registro stato d'implementazione dei controlli (status/%/next_review) | NON ha frequenza né log di esecuzioni |
+| `review_schedule` (Scadenziario) | Cadenza generica di revisioni (frequency_months, complete) | Generico, niente esito/evidenza/NC per esecuzione |
+| `internal_audits` (§9.2, nuovo) | Audit **puntuale** con checklist | Non ricorrente per singolo controllo |
+| `non_conformities`+`capa_actions` | NC + azioni correttive | Da **riusare** come destinazione |
+
+→ Il nuovo modulo è il livello mancante: **controlli RICORRENTI con registro esecuzioni (evidenza) + generazione NC/AC**. Può **linkare** un controllo del SoA/NIS2 (così diventa l'**evidenza operativa** dei controlli tecnici A.7/A.8 — chiude proprio il gap della valutazione).
+
+## Modello dati (mig.057, additivo, runner-safe)
+1. **`periodic_controls`**: id, organization_id, code (CTL-NNN), title, description, category, `control_ref` VARCHAR NULL (codice SoA/NIS2 collegato, es. 'A.8.13'), owner_role_id NULL (FK org_roles), `frequency` ENUM('giornaliero','settimanale','mensile','trimestrale','semestrale','annuale','custom'), `frequency_days` INT NULL (se custom), `method` TEXT (metodologia di verifica), `next_due_date` DATE, `last_executed_at` DATE NULL, status ENUM('active','suspended') DEFAULT 'active', created_by, ts. FK org CASCADE.
+2. **`periodic_control_executions`** (= l'evidenza): id, control_id FK CASCADE, executed_at DATE, executed_by INT NULL, `outcome` ENUM('conforme','non_conforme','parziale','non_applicabile'), notes TEXT, ncr_id INT NULL (NC generata), ts. Allegati su **evidence_files** (entity_type='periodic_control_execution'). KEY(control_id).
+3. **ALTER `non_conformities`**: aggiungere il valore **'monitoring'** all'ENUM `source` (runner-safe MODIFY preservando i valori) per le NC nate dai controlli periodici.
+
+## Logica
+- **Frequenza + auto-advance**: alla registrazione di un'esecuzione, `last_executed_at`=data e `next_due_date` avanza della frequenza (mesi/giorni). (Stesso spirito di `review_schedule::complete`.)
+- **Esecuzione = evidenza**: ogni run registra esito + note + (opz.) file in evidence_files → storico = prova all'auditor del monitoraggio periodico.
+- **Generazione NC/AC** su esito non_conforme/parziale:
+  - **NC**: crea `non_conformities` (source='monitoring', source_entity_type='periodic_control_execution', source_entity_id, title dal controllo, severity, status='open', ncr_code generato) e salva ncr_id sull'esecuzione → poi si gestisce in NCR/CAPA.
+  - **AC (azione correttiva)**: in ISO l'azione segue una NC → "Genera azione" crea la NC + una prima `capa_actions` (action_type='corrective') in un colpo. (capa_actions è figlia di non_conformities: si rispetta la struttura mig.004.)
+- **Calendario**: `periodic_controls.next_due_date` → nuova sorgente nel `CalendarController` (type 'periodic_control', stato overdue/due_soon/upcoming), deep-link alla pagina.
+- **Owner**: org_roles (chi è responsabile del controllo).
+
+## Backend — `PeriodicControlController` (slug `periodic-controls`)
+- `GET list` (+ stato scadenza calcolato) · `GET {id}` (con storico esecuzioni) · `POST create` (code CTL-NNN, calcola next_due) · `PUT {id}` · `DELETE {id}`
+- `POST {id}/executions` (registra esecuzione: outcome/notes → avanza next_due; se non conforme può creare NC/AC) · `GET {id}/executions`
+- `POST {id}/executions/{exId}/raiseNcr` (o parametro nella POST execution: `generate: 'nc'|'ac'|'none'`)
+- `GET {id}/report` (scheda controllo + storico stampabile)
+- Ruoli scrittura: org_admin/compliance_manager/auditor. Anti-IDOR, logAudit. Seed CLI idempotente.
+
+## Frontend — `controlli-periodici.html`
+- Lista controlli (codice, titolo, owner, frequenza, **prossima scadenza con badge** in ritardo/in scadenza, ultimo esito) + "+ Nuovo controllo".
+- Dettaglio: dati controllo + **storico esecuzioni** (data/esito/note/evidenze) + "Registra esecuzione" (esito + note + upload + opzione **Genera NC/AC**) + link al controllo SoA collegato + report.
+- Voce sidebar (sezione Audit&Report, vicino ad "Audit interni"); help/i18n/KB.
+
+## Integrazione & riuso
+NCR/CAPA (NC/AC), evidence_files (evidenze), CalendarController (nuova sorgente), org_roles (owner), compliance_controls/SoA (link `control_ref`), pattern controller/pagina da `internal_audits`. Niente duplicazione di `compliance_controls`/`review_schedule`.
+
+## Stima (rif. moduli A/B già fatti, complessità simile)
+| Fase | Contenuto | Stima |
+|---|---|---|
+| 1 | mig.057 (2 tabelle + ALTER source ENUM) + seeder + `PeriodicControlController` (CRUD + executions + NC/AC + next_due) + router/api | ~0,75 sessione |
+| 2 | `controlli-periodici.html` (lista + dettaglio + registra esecuzione + report) + CalendarController nuova sorgente + sidebar/help/i18n/KB + deploy+smoke | ~0,75 sessione |
+| 3 | verifica flotta + fix | ~0,5 sessione |
+| **Tot** | modulo completo, LIVE | **~2 sessioni** |
+
+## Esito atteso
+Si ottiene l'**evidenza del monitoraggio periodico** (storico esecuzioni con esiti+allegati) per ogni controllo ricorrente, con generazione NC/AC sui fallimenti e scadenze nel calendario — il livello "continuous control monitoring" che mancava, e l'**evidenza operativa** che l'auditor chiede per i controlli A.7/A.8.
+
+## Fonti
+- Scytale — Continuous Controls Monitoring (CCM); LogicGate — CCM guide; RegScale — CCM for GRC
+- Drata / Vanta — continuous control monitoring (vs periodic checks)
+- Eramba — Internal Control monitoring (owner/frequenza/evidenza/finding→azione) per ISO 27001
+- ISMS.online — ISO 27001:2022 §10.2 Non-conformità e azioni correttive; ISO §9.1 + A.8.16