AdminGit2026/nis2-agile
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
nis2-agile/CLAUDE.md
DevEnv nis2-agile a0fc0bd042 [DOCS] CLAUDE.md aggiornato: FeedbackService, controller, endpoint, contatore file 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-10 09:07:20 +01:00

22 KiB
Raw Permalink Blame History

NIS2 Agile - Documentazione Progetto

PRIMA DI INIZIARE

  • Leggi sempre questo file prima di iniziare qualsiasi lavoro
  • Il progetto e' al 100% di completamento + Sprint Simulazioni + Audit Chain + Sistema Feedback AI (~34.000 righe, 85+ file sorgente)
  • 15 commit su main, tutto deployato e testato su Hetzner
  • E2E test completati, bug fixing, Docker verificato, UI polished
  1. docs/CONTEXT_LAST_SESSION.md - Contesto ultima sessione (continuita cross-browser)

Poi dimmi cosa hai capito dello stato attuale e dove eravamo rimasti.

A FINE SESSIONE

OBBLIGATORIO: Prima di chiudere, aggiornare SEMPRE:

Aggiorna docs/CONTEXT_LAST_SESSION.md con:

  • Data sessione
  • Cosa hai fatto in questa sessione
  • File creati o modificati
  • File deployati su Hetzner
  • Problemi aperti / errori non risolti
  • Prossimi passi consigliati

Se hai modificato schema DB, architettura o URL, aggiorna anche CLAUDE.md.

Panoramica

NIS2 Agile e' 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, classificazione incidenti e suggerimenti rischi.

Target: PMI, Enterprise, Consulenti/CISO.

Stack Tecnologico

  • Backend: PHP 8.4 vanilla (no framework, Front Controller pattern)
  • Database: MySQL 8.x (nis2_agile_db)
  • Frontend: HTML5/CSS3/JavaScript vanilla
  • Auth: JWT HS256 (2h access + 7d refresh)
  • AI: Anthropic Claude API (claude-sonnet-4-5-20250929)
  • Server: Hetzner CPX31 (135.181.149.254)
  • VCS: Gitea (git.certisource.it)
  • URL Produzione: https://nis2.agile.software/

Visibilita Cross-Project

agile-services (Read/Write BIDIREZIONALE)

IMPORTANTE: Questo progetto utilizza i microservizi condivisi di agile-services con accesso Read/Write bidirezionale.

Regole di integrazione

  1. Leggere SEMPRE agile-services-istructio.md nella root del progetto per capire come interagire con i servizi
  2. Puoi leggere E modificare i file in agile-services (path locale: c:\Projects\agile-services, path container: /projects/agile-services)
  3. I servizi disponibili includono: vault, document, payment, certificate, subscription, billing, practice, company, supplier, investigation, whatsapp
  4. Le credenziali di accesso ai servizi sono documentate in agile-services-istructio.md
  5. Ogni nuovo servizio creato per NIS2 deve essere registrato anche in agile-services per essere riutilizzabile
  6. agile-services puo' leggere e modificare file di NIS2 — la visibilita e' bidirezionale

Accesso

  • Path locale: c:\Projects\agile-services
  • Path container: /projects/agile-services (read-write)
  • File istruzioni: ./agile-services-istructio.md (nella root del progetto)

trpg.agile (Read-Only)

NIS2 puo' leggere il codice di TRPG Agile per riferimento e pattern, ma NON deve modificare nessun file.

  • Path locale: c:\Projects\trpg.agile
  • Permessi: SOLO LETTURA
  • Scopo: Consultare pattern UI/UX, architettura frontend, convenzioni codice
  • DIVIETO: NON modificare, NON creare, NON cancellare file in trpg.agile

lg231.agile (Read-Only)

NIS2 puo' leggere il codice di 231 Agile per riferimento e pattern, ma NON deve modificare nessun file.

  • Path locale: c:\Projects\lg231.agile
  • Permessi: SOLO LETTURA
  • Scopo: Consultare architettura microservizi PHP/Slim 4, pattern multi-tenancy, struttura database
  • DIVIETO: NON modificare, NON creare, NON cancellare file in lg231.agile

sustainai.agile (Read-Only)

NIS2 puo' leggere il codice di SustainAI Agile per riferimento e pattern, ma NON deve modificare nessun file.

  • Path locale: c:\Projects\sustainai.agile
  • Permessi: SOLO LETTURA
  • Scopo: Consultare pattern UI/UX (identico a NIS2), struttura frontend, convenzioni CSS/JS
  • DIVIETO: NON modificare, NON creare, NON cancellare file in sustainai.agile

Riepilogo Visibilita

Progetto Permesso Direzione
agile-services Read/Write Bidirezionale (NIS2 <-> agile-services)
trpg.agile Read-Only NIS2 -> trpg (solo lettura)
lg231.agile Read-Only NIS2 -> lg231 (solo lettura)
sustainai.agile Read-Only NIS2 -> sustainai (solo lettura)

REGOLA: Non accedere MAI a progetti non elencati in questa tabella. Nel dubbio, chiedere all'utente.

Regola Fondamentale

Il progetto NIS2 Agile e' 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
├── .env                               # Variabili ambiente (NON committare)
├── .gitignore
├── application/
│   ├── config/
│   │   ├── config.php                 # Costanti app, CORS, JWT, AI, rate limiting
│   │   ├── database.php               # Classe Database (PDO singleton)
│   │   └── env.php                    # Caricamento .env
│   ├── controllers/                   # 19 controller (tutti implementati 100%)
│   │   ├── BaseController.php         # Auth JWT, multi-tenancy, JSON responses (576 righe)
│   │   ├── AdminController.php        # Gestione piattaforma (super_admin)
│   │   ├── AssessmentController.php   # Gap analysis e questionari NIS2 (80 domande)
│   │   ├── AssetController.php        # Inventario asset e dipendenze
│   │   ├── AuditController.php        # Controlli, evidenze, report, export CSV
│   │   ├── AuthController.php         # Login, register, JWT, rate limiting
│   │   ├── DashboardController.php    # Overview, score, deadlines, heatmap
│   │   ├── IncidentController.php     # Incidenti Art.23 (24h/72h/30d) + email
│   │   ├── NonConformityController.php# NCR/CAPA non-conformità e azioni correttive
│   │   ├── OnboardingController.php   # Wizard onboarding con visura/CertiSource
│   │   ├── OrganizationController.php # CRUD org, membri, classificazione NIS2
│   │   ├── PolicyController.php       # Policy, approvazione, AI generation
│   │   ├── RiskController.php         # Risk register, trattamenti, matrice, AI suggest
│   │   ├── SupplyChainController.php  # Fornitori, valutazione, risk overview
│   │   ├── TrainingController.php     # Corsi, assegnazioni, compliance formativa
│   │   ├── ServicesController.php     # Services API (read-only, API Key + scope)
│   │   ├── WebhookController.php      # CRUD api_keys + webhook_subscriptions
│   │   ├── WhistleblowingController.php # Segnalazioni anonime Art.32 NIS2
│   │   ├── NormativeController.php    # Feed NIS2/ACN/DORA con ACK tracciato
│   │   └── FeedbackController.php     # Sistema segnalazioni bug/UX con risoluzione AI autonoma
│   ├── services/                      # 6 servizi
│   │   ├── AIService.php              # Anthropic Claude API (gap, risk, policy, incident)
│   │   ├── EmailService.php           # Email CSIRT, training, welcome, invite
│   │   ├── RateLimitService.php       # Rate limiting file-based
│   │   ├── ReportService.php          # Report esecutivo HTML, export CSV
│   │   ├── WebhookService.php         # Delivery webhook HMAC-SHA256, retry 3x
│   │   └── FeedbackService.php        # createReport, classifyWithAI, broadcastResolution
│   │   └── VisuraService.php          # AI extraction PDF visura + CertiSource API
│   ├── models/                        # (vuoto - logica nei controller)
│   └── data/
│       └── nis2_questionnaire.json    # 80 domande gap analysis (10 categorie Art.21)
├── public/
│   ├── index.php                      # Front Controller / Router
│   ├── .htaccess                      # Rewrite rules + Authorization header
│   ├── api-status.php                 # Health check
│   ├── index.html                     # Landing page
│   ├── login.html                     # Login
│   ├── register.html                  # Registrazione
│   ├── onboarding.html                # Wizard 5-step (visura/CertiSource/manuale)
│   ├── setup-org.html                 # Setup org (legacy, ora usa onboarding.html)
│   ├── dashboard.html                 # Dashboard principale
│   ├── assessment.html                # Gap analysis wizard
│   ├── risks.html                     # Risk management + matrice 5x5
│   ├── incidents.html                 # Gestione incidenti Art.23
│   ├── policies.html                  # Policy management + AI generate
│   ├── supply-chain.html              # Fornitori + assessment sicurezza
│   ├── training.html                  # Formazione + assegnazioni
│   ├── assets.html                    # Inventario asset
│   ├── reports.html                   # Report compliance + audit log
│   ├── settings.html                  # Impostazioni org/profilo/membri
│   ├── companies.html                 # Gestione aziende (consulente)
│   ├── architecture.html              # Pagina architettura sistema
│   ├── admin/
│   │   ├── index.html                 # Admin dashboard
│   │   ├── organizations.html         # Gestione organizzazioni
│   │   └── users.html                 # Gestione utenti
│   ├── css/
│   │   └── style.css                  # CSS principale (~1600 righe)
│   ├── js/
│   │   ├── api.js                     # Client API (270 righe, tutti gli endpoint)
│   │   ├── common.js                  # Utility condivise (sidebar, notifiche, etc.)
│   │   ├── i18n.js                    # Internazionalizzazione IT/EN
│   │   └── help.js                    # Help contestuale online
│   └── uploads/                       # Upload directory (gitignored)
│       └── visure/                    # PDF visure camerali
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── nginx.conf
│   └── php.ini
└── docs/
    ├── sql/
    │   ├── 001_initial_schema.sql     # Schema DB completo (20 tabelle)
    │   ├── 002_email_log.sql          # Tabella email_log
    │   ├── 003_voluntary_compliance.sql # ALTER organizations: voluntary_compliance
    │   ├── 004_ncr_capa.sql           # Tabelle non_conformities, corrective_actions
    │   ├── 005_consultant_support.sql # ALTER user_organizations: ruolo consultant
    │   ├── 006_security_improvements.sql # Indici performance + soft delete + trigger audit immutabile
    │   ├── 007_services_api.sql         # api_keys, webhook_subscriptions, webhook_deliveries
    │   ├── 008_whistleblowing.sql       # whistleblowing_reports, whistleblowing_timeline
    │   ├── 009_normative_updates.sql    # normative_updates, normative_ack (seed 5 aggiornamenti)
    │   ├── 010_audit_hash_chain.sql     # prev_hash, entry_hash, severity su audit_logs
    │   └── reset-demo.sql              # Reset dati demo (mantiene id<=4)
    ├── context/
    │   └── CONTEXT_SCHEMA_DB.md
    ├── prompts/
    └── credentials/
        ├── credentials.md
        └── hetzner_key                # SSH key per Hetzner

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

Flusso Utente

  1. Registrazione → redirect a onboarding.html
  2. Onboarding (5 step): Scelta metodo → Visura/CertiSource/Manuale → Dati aziendali → Profilo → Classificazione NIS2
  3. Login → se ha org → dashboard.html, altrimenti → onboarding.html
  4. Dashboard → navigazione sidebar a tutti i moduli

Database (29 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, email_log, non_conformities, corrective_actions

Schema: docs/sql/ (9 migrazioni: 001→009)

Servizi

AIService.php

  • analyzeGapAssessment() - Analisi assessment con raccomandazioni
  • suggestRisks() - Suggerimenti rischi per settore/asset
  • generatePolicy() - Generazione bozze policy NIS2
  • classifyIncident() - Classificazione e severity incidenti
  • Modello: claude-sonnet-4-5-20250929, API: https://api.anthropic.com/v1/messages

EmailService.php

  • Notifiche CSIRT: early warning 24h, notification 72h, final report 30d
  • Training assignment e reminder
  • Welcome email, member invite
  • Template HTML professionale con branding NIS2 Agile

RateLimitService.php

  • File-based (/tmp/nis2_ratelimit/)
  • Login: 5/min, 20/h | Register: 3/10min | AI: 10/min, 100/h

ReportService.php

  • Report esecutivo HTML (stampabile come PDF)
  • Export CSV: rischi, incidenti, controlli, asset (separatore ;, BOM UTF-8)

VisuraService.php

  • Estrazione AI da PDF visura camerale (Claude con document type)
  • Fetch dati da CertiSource API (GET /api/company/enrich?vat=)
  • Mapping ATECO → settore NIS2

AuditService.php (NUOVO)

  • Hash chain SHA-256: ogni record include prev_hash → entry_hash linkato
  • log(): inserisce con hash catena, auto-severity (info/warning/critical)
  • verifyChain(): verifica integrità per org, rileva record manomessi
  • exportCertified(): export JSON con SHA-256 del contenuto, salva in audit_exports
  • Adattato da lg231-agile/shared/audit-lib/src/AuditTrailService.php

WebhookService.php (NUOVO)

  • Delivery HMAC-SHA256 Stripe-like, header X-NIS2-Signature
  • Retry 3x backoff (0s/5min/30min), log in webhook_deliveries

FeedbackService.php (NUOVO)

  • createReport(): INSERT + classifyWithAI() sincrono (10s timeout)
  • classifyWithAI(): chiama AIService::classifyFeedback(), aggiorna DB silenziosamente
  • broadcastResolution(): email a tutti i membri org via EmailService::sendFeedbackResolved()
  • Worker autonomo: scripts/feedback-worker.php (cron 30min, docker exec nis2-agile-devenv + Claude Code CLI)

simulate-nis2.php (ROOT — NUOVO)

  • Script simulazione demo 3 aziende × 5 scenari (CLI + SSE streaming)
  • Aziende: DataCore (IT/Essential), MedClinic (Sanità/Important), EnerNet (Energia/Critical)
  • Scenari: Onboarding + Assessment | Ransomware Art.23 | Data Breach | Whistleblowing | Audit Chain
  • Reset: docs/sql/reset-demo.sql (cancella org/utenti con id>4 e email %.demo%)

Deploy

  • SSH: ssh -i docs/credentials/hetzner_key root@135.181.149.254
  • Path server: /var/www/nis2-agile/
  • Apache config: /etc/apache2/sites-enabled/nis2-agile-software.conf (HTTP) + nis2-agile-software-le-ssl.conf (HTTPS, dopo DNS+certbot)
  • Deploy: cd /var/www/nis2-agile && git pull origin main
  • DB: Vedi docs/DB_ACCESS.md per credenziali (password in .env)
  • Attivazione SSL nis2.agile.software:
    1. Cloudflare: aggiungere nis2.agile.software A 135.181.149.254 (proxy OFF — grigio)
    2. Hetzner: bash /opt/devenv/scripts/setup-nis2-agile-software.sh
  • Vecchio dominio: nis2.certisource.it resterà attivo finché redirect non è configurato dallo script

Git

Cronologia Commit

7080695 [FEAT] Ruolo Consulente + Wizard Registrazione v2
ba21534 [DEPLOY] Migrazione a subdomain nis2.agile.software
92f9366 Merge branch 'main'
d3eac7c [CORE] Rimosso credenziali da CLAUDE.md + aggiunto docs/DB_ACCESS.md
a0fd543 [CORE] Aggiunto settings Claude Code con permessi ampi
0a73983 [FIX] Dockerignore: allow docker/php.ini for build context
4bd2326 [CORE] Aggiunto integrazione agile-services
52fd45f [FEAT] i18n IT/EN, Help Online contestuale, pagina Architettura
4e3408e [FEAT] Visura auto-fill, adesione volontaria, modulo NCR/CAPA
517cab7 [FIX] Fix annual_turnover field name in setup-org.html
68f8cab [POLISH] Docker setup fix + UI polish + project completion
bcc5a2b [FIX] E2E testing - fix router, EmailService, frontend data mapping

API Endpoints Completi

Base: /api/{controller}/{action}/{id?} (su subdomain https://nis2.agile.software/)

Auth: POST register, login, logout, refresh, change-password | GET me | PUT profile

Organizations: POST create, classify | GET current, list, {id}/members | PUT {id} | POST {id}/invite | DELETE {id}/members/{sid}

Assessments: GET list, {id}, {id}/questions, {id}/report | POST create, {id}/respond, {id}/complete, {id}/ai-analyze | PUT {id}

Dashboard: GET overview, compliance-score, upcoming-deadlines, recent-activity, risk-heatmap

Risks: GET list, {id}, matrix | POST create, {id}/treatments, ai-suggest | PUT {id}, treatments/{sid} | DELETE {id}

Incidents: GET list, {id} | POST create, {id}/timeline, {id}/early-warning, {id}/notification, {id}/final-report, {id}/ai-classify | PUT {id}

Policies: GET list, {id}, templates | POST create, {id}/approve, ai-generate | PUT {id} | DELETE {id}

Supply Chain: GET list, {id}, risk-overview | POST create, {id}/assess | PUT {id} | DELETE {id}

Training: GET courses, assignments, compliance-status | POST courses, assign | PUT assignments/{sid}

Assets: GET list, {id}, dependency-map | POST create | PUT {id} | DELETE {id}

Audit: GET controls, evidence/list, report, logs, iso27001-mapping, executive-report, export | PUT controls/{sid} | POST evidence/upload

Onboarding: POST upload-visura, fetch-company, complete

Admin: GET organizations, users, stats

NCR/CAPA: GET list, {id}, stats | POST create, fromAssessment, {id}/capa, {id}/sync, webhook | PUT {id}, capa/{subId}

Services API (X-API-Key): GET status, compliance-summary, risks-feed, incidents-feed, controls-status, assets-critical, suppliers-risk, policies-approved, openapi

Webhooks: GET api-keys, subscriptions, deliveries | POST api-keys, subscriptions, subscriptions/{id}/test, retry | PUT subscriptions/{id} | DELETE api-keys/{id}, subscriptions/{id}

Whistleblowing: POST submit, {id}/assign, {id}/close | GET list, {id}, stats, track-anonymous | PUT {id}

Normative: GET list, {id}, pending, stats | POST {id}/ack, create

Feedback: POST submit | GET mine, list, {id} | PUT {id} | POST {id}/resolve

Stato Completamento

Tutti i moduli sono implementati e testati:

  • Test end-to-end: tutti gli endpoint API verificati
  • Bug fixing: router rewrite, EmailService parse fix, frontend data mapping
  • Docker setup: Dockerfile, docker-compose.yml, nginx.conf, php.ini verificati
  • UI polish: animazioni, skeleton loaders, mobile backdrop, print styles, a11y

Bug Risolti (E2E Testing)

  1. Router /{id}/subAction - Pattern matching riscritto completamente per gestire GET /assessments/1/questions, GET /organizations/2/members, etc.
  2. EmailService parse error - PHP non supporta ?? dentro {$var} string interpolation, estratto a variabile
  3. Frontend data mapping - Dashboard, Assessment, Onboarding avevano nomi campo diversi dal backend
  4. Field name mismatches - annual_turnover→annual_turnover_eur, question_id→question_code, compliance_level→response_value

Ultimo aggiornamento: 2026-02-20

Infrastruttura DevEnv

Risorsa Valore
Container nis2-agile-devenv
IDE https://certisource.it/dev-nis2-ide/
API https://certisource.it/dev-nis2-api/
Browser https://certisource.it/dev-nis2-browser/
Porte 8454 / 3046 / 3047 / 6091
Password IDE Nis2AgileDev2026!
Produzione https://nis2.agile.software/

Documentazione Commerciale AgentAI (aggiornato 2026-03-09)

QUESTO ANNULLA LE ISTRUZIONI PRECEDENTI sulla documentazione commerciale. Standard completo: /opt/devenv/COMMERCIAL_STANDARDS.md Stato prodotti: /opt/agent-ai/hub/AGENTAI_SPECS.md

Regole NUOVE (in vigore)

  • Landing page e presentazione vanno nel TUO repo (docs/agentai/ o dove preferisci)
  • products.json (/opt/agent-ai/hub/products.json) e SOLO un indice con URL assoluti
  • Aggiorna products.json con https://tuo-dominio/path-al-file.html
  • La landing DEVE includere un link/bottone per registrazione o richiesta informazioni
  • mktg.agile.software legge products.json per campagne marketing

Regole OBSOLETE (non fare piu)

  • NON scrivere file in /opt/agent-ai/hub/landing/
  • NON scrivere file in /opt/agent-ai/hub/presentations/
  • NON usare path relativi in products.json
  • Le directory landing/ e presentations/ nel hub sono VUOTE

Workflow

  1. Scrivi landing/presentazione nel tuo repo
  2. Commit + push (webhook aggiorna /var/www/)
  3. Chiedi conferma utente
  4. Aggiorna products.json con URL assoluto
  5. Verifica URL raggiungibile

REGOLA

SEMPRE chiedere conferma utente PRIMA di generare documenti commerciali.

REGOLA: Sincronizzazione CLAUDE.md

  • Dopo QUALSIASI modifica a: URL produzione, dominio, porta, path, schema DB, architettura -> AGGIORNARE CLAUDE.md IMMEDIATAMENTE
  • CLAUDE.md e la "single source of truth" del progetto
  • A fine sessione: verificare che CLAUDE.md rifletta lo stato reale