# NIS2 Agile - Documentazione Progetto

## PRIMA DI INIZIARE
- Leggi sempre questo file prima di iniziare qualsiasi lavoro
- File specializzati per area di lavoro:
  - Assessment/Gap Analysis: docs/prompts/PROMPT_ASSESSMENT.md
  - Risk Management: docs/prompts/PROMPT_RISK.md
  - Incident Management: docs/prompts/PROMPT_INCIDENTS.md

## Panoramica
NIS2 Agile è una piattaforma SaaS multi-tenant per supportare le aziende nella compliance alla Direttiva NIS2 (EU 2022/2555) e al D.Lgs. 138/2024 italiano. Include AI integration (Claude API) per gap analysis, generazione policy e suggerimenti.

Target: PMI, Enterprise, Consulenti/CISO.

## Stack Tecnologico
- Backend: PHP 8.4 vanilla (no framework)
- Database: MySQL 8.x (nis2_agile_db)
- Frontend: HTML5/CSS3/JavaScript vanilla
- Auth: JWT HS256 (2h access + 7d refresh)
- AI: Anthropic Claude API (Sonnet 4.5)
- Server: Hetzner CPX31 (135.181.149.254)
- VCS: Gitea (git.certisource.it)
- Routing: Front Controller pattern (public/index.php)

## Regola Fondamentale
Il progetto NIS2 Agile è COMPLETAMENTE ISOLATO dagli altri applicativi (CertiSource, AGILE_DFM). Database dedicato, utente dedicato, path dedicati. Non condividere MAI credenziali tra applicativi.

## Struttura Progetto
```
nis2.agile/
├── CLAUDE.md                          # Questo file - documentazione progetto
├── application/
│   ├── config/
│   │   ├── config.php                 # Costanti app, CORS, JWT, password policy
│   │   ├── database.php               # Classe Database (PDO singleton)
│   │   └── env.php                    # Caricamento variabili ambiente da .env
│   ├── controllers/
│   │   ├── BaseController.php         # Classe base: auth JWT, multi-tenancy, JSON responses
│   │   ├── AdminController.php        # Gestione piattaforma (super_admin)
│   │   ├── AssessmentController.php   # Gap analysis e questionari NIS2
│   │   ├── AssetController.php        # Inventario asset e dipendenze
│   │   ├── AuditController.php        # Controlli compliance, evidenze, report
│   │   ├── AuthController.php         # Login, register, JWT, refresh token
│   │   ├── DashboardController.php    # Overview, score, deadlines, heatmap
│   │   ├── IncidentController.php     # Gestione incidenti (24h/72h/30d)
│   │   ├── OrganizationController.php # CRUD organizzazioni, membri, classificazione
│   │   ├── PolicyController.php       # Gestione policy, approvazione, AI generation
│   │   ├── RiskController.php         # Risk register, trattamenti, matrice rischi
│   │   ├── SupplyChainController.php  # Fornitori, valutazione, risk overview
│   │   └── TrainingController.php     # Corsi, assegnazioni, compliance formativa
│   ├── services/
│   │   └── AIService.php              # Integrazione Anthropic Claude API
│   ├── models/                        # (riservato per modelli futuri)
│   └── data/
│       ├── nis2_questionnaire.json    # Domande questionario gap analysis
│       └── policy_templates/          # Template policy NIS2
├── public/
│   ├── index.php                      # Front Controller / Router
│   ├── api-status.php                 # Health check endpoint
│   ├── css/                           # Fogli di stile
│   ├── js/
│   │   └── api.js                     # Client API JavaScript
│   └── admin/                         # Pannello admin frontend
├── docker/
│   ├── Dockerfile                     # Build PHP-FPM
│   ├── docker-compose.yml             # Orchestrazione servizi
│   ├── nginx.conf                     # Configurazione Nginx
│   └── php.ini                        # Configurazione PHP custom
├── docs/
│   ├── sql/
│   │   └── 001_initial_schema.sql     # Schema database completo
│   ├── context/
│   │   └── CONTEXT_SCHEMA_DB.md       # Schema documentato
│   ├── prompts/                       # Prompt specializzati per AI
│   └── credentials/
│       ├── credentials.md             # Note credenziali
│       └── hetzner_key                # Chiave SSH Hetzner
├── .env                               # Variabili ambiente (NON committare)
└── .gitignore
```

## Multi-Tenancy
- Ogni tabella dati ha `organization_id`
- Header `X-Organization-Id` per selezionare org attiva
- Ruoli: `super_admin`, `org_admin`, `compliance_manager`, `board_member`, `auditor`, `employee`, `consultant`
- `requireOrgAccess()` in BaseController verifica membership
- Super admin bypassa tutti i controlli di membership

## API Endpoints

Tutti gli endpoint seguono il pattern: `/nis2/api/{controller}/{action}/{id?}`

### AuthController (`/api/auth/`)
| Metodo | Endpoint                | Azione           | Descrizione                      |
|--------|-------------------------|------------------|----------------------------------|
| POST   | /api/auth/register      | register         | Registrazione nuovo utente       |
| POST   | /api/auth/login         | login            | Login con email/password          |
| POST   | /api/auth/logout        | logout           | Logout e invalidazione token     |
| POST   | /api/auth/refresh       | refresh          | Refresh JWT token                |
| GET    | /api/auth/me            | me               | Profilo utente corrente          |
| PUT    | /api/auth/profile       | updateProfile    | Aggiorna profilo                 |
| POST   | /api/auth/change-password | changePassword | Cambio password                  |

### OrganizationController (`/api/organizations/`)
| Metodo | Endpoint                              | Azione         | Descrizione                        |
|--------|---------------------------------------|----------------|------------------------------------|
| POST   | /api/organizations/create             | create         | Crea organizzazione                |
| GET    | /api/organizations/current            | getCurrent     | Org corrente dell'utente           |
| GET    | /api/organizations/list               | list           | Lista organizzazioni accessibili   |
| PUT    | /api/organizations/{id}               | update         | Aggiorna organizzazione            |
| GET    | /api/organizations/{id}/members       | listMembers    | Lista membri organizzazione        |
| POST   | /api/organizations/{id}/invite        | inviteMember   | Invita membro                      |
| DELETE | /api/organizations/{id}/members/{sid} | removeMember   | Rimuovi membro                     |
| POST   | /api/organizations/classify           | classifyEntity | Classifica entità NIS2             |

### AssessmentController (`/api/assessments/`)
| Metodo | Endpoint                         | Azione        | Descrizione                        |
|--------|----------------------------------|---------------|------------------------------------|
| GET    | /api/assessments/list            | list          | Lista assessment                   |
| POST   | /api/assessments/create          | create        | Crea nuovo assessment              |
| GET    | /api/assessments/{id}            | get           | Dettaglio assessment               |
| PUT    | /api/assessments/{id}            | update        | Aggiorna assessment                |
| GET    | /api/assessments/{id}/questions  | getQuestions   | Domande questionario              |
| POST   | /api/assessments/{id}/respond    | saveResponse   | Salva risposta                    |
| POST   | /api/assessments/{id}/complete   | complete       | Completa assessment               |
| GET    | /api/assessments/{id}/report     | getReport      | Report assessment                 |
| POST   | /api/assessments/{id}/ai-analyze | aiAnalyze      | Analisi AI del gap                |

### DashboardController (`/api/dashboard/`)
| Metodo | Endpoint                          | Azione          | Descrizione                      |
|--------|-----------------------------------|-----------------|----------------------------------|
| GET    | /api/dashboard/overview           | overview        | Overview compliance              |
| GET    | /api/dashboard/compliance-score   | complianceScore | Score compliance                 |
| GET    | /api/dashboard/upcoming-deadlines | deadlines       | Scadenze imminenti               |
| GET    | /api/dashboard/recent-activity    | recentActivity  | Attività recenti                 |
| GET    | /api/dashboard/risk-heatmap       | riskHeatmap     | Heatmap rischi                   |

### RiskController (`/api/risks/`)
| Metodo | Endpoint                       | Azione           | Descrizione                      |
|--------|--------------------------------|------------------|----------------------------------|
| GET    | /api/risks/list                | list             | Lista rischi                     |
| POST   | /api/risks/create              | create           | Crea rischio                     |
| GET    | /api/risks/{id}                | get              | Dettaglio rischio                |
| PUT    | /api/risks/{id}                | update           | Aggiorna rischio                 |
| DELETE | /api/risks/{id}                | delete           | Elimina rischio                  |
| POST   | /api/risks/{id}/treatments     | addTreatment     | Aggiungi trattamento             |
| PUT    | /api/risks/treatments/{sid}    | updateTreatment  | Aggiorna trattamento             |
| GET    | /api/risks/matrix              | getRiskMatrix    | Matrice dei rischi               |
| POST   | /api/risks/ai-suggest          | aiSuggestRisks   | Suggerimenti AI rischi           |

### IncidentController (`/api/incidents/`)
| Metodo | Endpoint                            | Azione            | Descrizione                      |
|--------|-------------------------------------|-------------------|----------------------------------|
| GET    | /api/incidents/list                 | list              | Lista incidenti                  |
| POST   | /api/incidents/create               | create            | Crea incidente                   |
| GET    | /api/incidents/{id}                 | get               | Dettaglio incidente              |
| PUT    | /api/incidents/{id}                 | update            | Aggiorna incidente               |
| POST   | /api/incidents/{id}/timeline        | addTimelineEvent  | Aggiungi evento timeline         |
| POST   | /api/incidents/{id}/early-warning   | sendEarlyWarning  | Early warning (24h)              |
| POST   | /api/incidents/{id}/notification    | sendNotification  | Notifica (72h)                   |
| POST   | /api/incidents/{id}/final-report    | sendFinalReport   | Report finale (30d)              |
| POST   | /api/incidents/{id}/ai-classify     | aiClassify        | Classificazione AI incidente     |

### PolicyController (`/api/policies/`)
| Metodo | Endpoint                     | Azione           | Descrizione                      |
|--------|------------------------------|------------------|----------------------------------|
| GET    | /api/policies/list           | list             | Lista policy                     |
| POST   | /api/policies/create         | create           | Crea policy                      |
| GET    | /api/policies/{id}           | get              | Dettaglio policy                 |
| PUT    | /api/policies/{id}           | update           | Aggiorna policy                  |
| DELETE | /api/policies/{id}           | delete           | Elimina policy                   |
| POST   | /api/policies/{id}/approve   | approve          | Approva policy                   |
| POST   | /api/policies/ai-generate    | aiGeneratePolicy | Genera policy con AI             |
| GET    | /api/policies/templates      | getTemplates     | Lista template policy            |

### SupplyChainController (`/api/supply-chain/`)
| Metodo | Endpoint                          | Azione          | Descrizione                      |
|--------|-----------------------------------|-----------------|----------------------------------|
| GET    | /api/supply-chain/list            | list            | Lista fornitori                  |
| POST   | /api/supply-chain/create          | create          | Aggiungi fornitore               |
| GET    | /api/supply-chain/{id}            | get             | Dettaglio fornitore              |
| PUT    | /api/supply-chain/{id}            | update          | Aggiorna fornitore               |
| DELETE | /api/supply-chain/{id}            | delete          | Elimina fornitore                |
| POST   | /api/supply-chain/{id}/assess     | assessSupplier  | Valuta fornitore                 |
| GET    | /api/supply-chain/risk-overview   | riskOverview    | Overview rischio supply chain    |

### TrainingController (`/api/training/`)
| Metodo | Endpoint                          | Azione            | Descrizione                      |
|--------|-----------------------------------|-------------------|----------------------------------|
| GET    | /api/training/courses             | listCourses       | Lista corsi                      |
| POST   | /api/training/courses             | createCourse      | Crea corso                       |
| GET    | /api/training/assignments         | myAssignments     | Le mie assegnazioni              |
| POST   | /api/training/assign              | assignCourse      | Assegna corso                    |
| PUT    | /api/training/assignments/{sid}   | updateAssignment  | Aggiorna assegnazione            |
| GET    | /api/training/compliance-status   | complianceStatus  | Status compliance formativa      |

### AssetController (`/api/assets/`)
| Metodo | Endpoint                     | Azione         | Descrizione                      |
|--------|------------------------------|----------------|----------------------------------|
| GET    | /api/assets/list             | list           | Lista asset                      |
| POST   | /api/assets/create           | create         | Crea asset                       |
| GET    | /api/assets/{id}             | get            | Dettaglio asset                  |
| PUT    | /api/assets/{id}             | update         | Aggiorna asset                   |
| DELETE | /api/assets/{id}             | delete         | Elimina asset                    |
| GET    | /api/assets/dependency-map   | dependencyMap  | Mappa dipendenze                 |

### AuditController (`/api/audit/`)
| Metodo | Endpoint                        | Azione          | Descrizione                      |
|--------|---------------------------------|-----------------|----------------------------------|
| GET    | /api/audit/controls             | listControls    | Lista controlli compliance       |
| PUT    | /api/audit/controls/{sid}       | updateControl   | Aggiorna controllo               |
| POST   | /api/audit/evidence/upload      | uploadEvidence  | Carica evidenza                  |
| GET    | /api/audit/evidence/list        | listEvidence    | Lista evidenze                   |
| GET    | /api/audit/report               | generateReport  | Genera report audit              |
| GET    | /api/audit/logs                 | getAuditLogs    | Log audit                        |
| GET    | /api/audit/iso27001-mapping     | getIsoMapping   | Mapping ISO 27001                |

### AdminController (`/api/admin/`)
| Metodo | Endpoint                  | Azione             | Descrizione                      |
|--------|---------------------------|--------------------|----------------------------------|
| GET    | /api/admin/organizations  | listOrganizations  | Lista tutte le organizzazioni    |
| GET    | /api/admin/users          | listUsers          | Lista tutti gli utenti           |
| GET    | /api/admin/stats          | platformStats      | Statistiche piattaforma          |

## Database Schema
- **Tabelle**: organizations, users, user_organizations, refresh_tokens, assessments, assessment_responses, risks, risk_treatments, incidents, incident_timeline, policies, suppliers, training_courses, training_assignments, assets, compliance_controls, evidence_files, audit_logs, ai_interactions, rate_limits
- **Schema completo**: docs/sql/001_initial_schema.sql
- **Schema documentato**: docs/context/CONTEXT_SCHEMA_DB.md

## AI Integration
- **Servizio**: application/services/AIService.php
- **Funzionalità**: gap analysis, risk suggestions, policy generation, incident classification
- **Modello**: claude-sonnet-4-5-20250929
- **API Key**: da .env (ANTHROPIC_API_KEY)
- **Rate limiting**: tabella rate_limits, controllo per utente/organizzazione
- **Logging**: tabella ai_interactions per tracciare tutte le chiamate AI

## Moduli NIS2 (Art. 21)
1. **Gap Analysis & Assessment** (Art. 21) - Questionario strutturato con analisi AI
2. **Risk Management** (Art. 21.2.a) - Risk register, matrice, trattamenti
3. **Incident Management** (Art. 23) - Timeline 24h/72h/30d, early warning, notifiche
4. **Policy Management** (Art. 21) - CRUD policy, approvazione, generazione AI
5. **Supply Chain Security** (Art. 21.2.d) - Valutazione fornitori, risk overview
6. **Training & Awareness** (Art. 20) - Corsi, assegnazioni, compliance formativa
7. **Asset Management** (Art. 21.2.i) - Inventario, classificazione, mappa dipendenze
8. **Audit & Compliance** (Art. 21.2.f) - Controlli, evidenze, report, mapping ISO 27001

## Deploy
- **SSH**: `ssh -i docs/credentials/hetzner_key root@135.181.149.254`
- **Path server**: `/var/www/nis2-agile/`
- **Deploy**: scp via SSH (manuale)
- **Docker**: `docker-compose up -d`

## Git
- **Repository**: https://git.certisource.it/AdminGit2026/nis2-agile
- **Branch**: main
- **Commit format**: `[AREA] Descrizione`
- **Aree**: `[CORE]`, `[AUTH]`, `[ASSESSMENT]`, `[RISK]`, `[INCIDENT]`, `[POLICY]`, `[SUPPLY]`, `[TRAINING]`, `[ASSET]`, `[AUDIT]`, `[FRONTEND]`, `[AI]`, `[DOCS]`, `[DOCKER]`

## Comandi Utili
```bash
# Sviluppo locale
php -S localhost:8080 -t public/

# Applicare schema database
mysql -u nis2_user -p nis2_agile_db < docs/sql/001_initial_schema.sql

# Docker
cd docker && docker-compose up -d

# SSH al server
ssh -i docs/credentials/hetzner_key root@135.181.149.254

# Deploy manuale
scp -i docs/credentials/hetzner_key -r application/ root@135.181.149.254:/var/www/nis2-agile/
scp -i docs/credentials/hetzner_key -r public/ root@135.181.149.254:/var/www/nis2-agile/
```

*Ultimo aggiornamento: 2026-02-17*