# 🛡️ REGOLE CONTROLLO QUALITÀ NETGESCON

**Versione Regole**: 1.0.0  
**Ultima Modifica**: 23 Luglio 2025  
**Copertura**: PHP, Blade, JavaScript, TypeScript

---

## 📋 INDICE REGOLE

1. [Layout Usage](#1-layout-usage) - **CRITICAL**
2. [Bootstrap/Tailwind Obsolete](#2-bootstraptailwind-obsolete) - **WARNING**
3. [Componenti NetGescon](#3-componenti-netgescon) - **INFO**
4. [Controller Namespace](#4-controller-namespace) - **ERROR**
5. [Model Relationships](#5-model-relationships) - **INFO**
6. [Helper Deprecati](#6-helper-deprecati) - **WARNING**
7. [Problemi Sicurezza](#7-problemi-sicurezza) - **CRITICAL**
8. [Standard Migration](#8-standard-migration) - **INFO**

---

## 🔴 REGOLE CRITICAL

### 1. Layout Usage
**ID**: `layout_usage`  
**Severità**: 🔴 **CRITICAL**  
**File Target**: `*.blade.php`

#### **Descrizione**
Verifica che tutte le view Blade utilizzino il layout NetGescon standard invece di layout obsoleti o generici.

#### **Pattern Ricerca**
```regex
/(@extends\([\'"]admin\.layouts\.netgescon[\'"].*\)|@extends\([\'"]layouts\.app[\'"].*\))/m
```

#### **Problemi Rilevati**
```blade
❌ SBAGLIATO:
@extends('layouts.app')
@extends('layouts.master')
@extends('adminlte::page')

✅ CORRETTO:
@extends('admin.layouts.netgescon')
```

#### **Fix Automatico**
```php
// Conversione automatica
"@extends('layouts.app')" → "@extends('admin.layouts.netgescon')"
```

#### **Impatto Business**
- 🎨 **Consistenza UI**: Interfaccia uniforme
- 🏷️ **Branding**: Rispetto identità NetGescon  
- 📱 **Responsive**: Layout ottimizzato
- 🚀 **Performance**: CSS ottimizzato

---

### 7. Problemi Sicurezza
**ID**: `security_issues`  
**Severità**: 🔴 **CRITICAL**  
**File Target**: `*.php`

#### **Descrizione**
Rileva potenziali vulnerabilità di sicurezza nel codice PHP, inclusi SQL injection, XSS e input non validati.

#### **Pattern Ricerca**
```regex
/(\$_GET|\$_POST|\$_REQUEST|DB::raw\s*\(\s*[\'"][^\'"]*(SELECT|INSERT|UPDATE|DELETE))/im
```

#### **Problemi Rilevati**
```php
❌ VULNERABILITÀ CRITICA:
$name = $_GET['name'];  // Input non validato
$sql = "SELECT * FROM users WHERE name = " . $_POST['name'];  // SQL Injection
DB::raw("SELECT * FROM table WHERE id = " . $request->id);  // SQL Injection

✅ SICURO:
$name = $request->validated()['name'];  // Validazione Request
$users = User::where('name', $request->name)->get();  // Query Builder
DB::raw('COUNT(*) as total');  // Query statiche sicure
```

#### **Fix Automatico**
❌ **Non disponibile** - Richiede revisione manuale obbligatoria

#### **Impatto Business**
- 🛡️ **Sicurezza Dati**: Protezione database
- ⚖️ **Compliance**: Rispetto normative GDPR
- 💰 **Risk Management**: Evita breach costosi
- 🏆 **Reputazione**: Fiducia clienti

---

## 🟠 REGOLE ERROR

### 4. Controller Namespace
**ID**: `controller_namespace`  
**Severità**: 🟠 **ERROR**  
**File Target**: `app/Http/Controllers/*.php`

#### **Descrizione**
Verifica che tutti i controller abbiano il namespace corretto secondo l'architettura NetGescon.

#### **Pattern Ricerca**
```regex
/namespace App\\\\Http\\\\Controllers\\\\Admin;/m
```

#### **Problemi Rilevati**
```php
❌ NAMESPACE SBAGLIATO:
namespace App\Http\Controllers;
namespace App\Controllers;
namespace Controllers;

✅ NAMESPACE CORRETTO:
namespace App\Http\Controllers\Admin;
```

#### **Fix Automatico**
❌ **Non disponibile** - Può causare breaking changes

#### **Impatto Business**
- 🏗️ **Architettura**: Struttura progetto coerente
- 🔍 **Debugging**: Più facile individuare file
- 📈 **Scalabilità**: Organizzazione per crescita
- 👥 **Team**: Comprensione condivisa

---

## 🟡 REGOLE WARNING

### 2. Bootstrap/Tailwind Obsolete
**ID**: `bootstrap_classes`  
**Severità**: 🟡 **WARNING**  
**File Target**: `*.blade.php`

#### **Descrizione**
Rileva l'utilizzo di classi CSS obsolete (Bootstrap/Tailwind) che dovrebbero essere sostituite con componenti NetGescon.

#### **Pattern Ricerca**
```regex
/(btn-primary|btn-secondary|btn-success|btn-danger|btn-warning|btn-info|bg-blue-500|bg-gray-100|text-gray-900)/m
```

#### **Problemi Rilevati**
```blade
❌ CLASSI OBSOLETE:
<button class="btn btn-primary">Salva</button>
<div class="bg-blue-500 text-white">Card</div>
<p class="text-gray-900">Testo</p>

✅ CLASSI NETGESCON:
<button class="netgescon-btn netgescon-btn-primary">Salva</button>
<div class="netgescon-card">Card</div>
<p class="netgescon-text">Testo</p>
```

#### **Fix Automatico**
```php
// Mappature automatiche
'btn-primary' → 'netgescon-btn netgescon-btn-primary'
'btn-secondary' → 'netgescon-btn netgescon-btn-secondary'
'bg-blue-500' → 'netgescon-bg-primary'
'text-gray-900' → 'netgescon-text'
```

#### **Impatto Business**
- 🎨 **Design System**: Coerenza visiva
- 📱 **Responsive**: Breakpoint ottimizzati
- 🚀 **Performance**: CSS bundle ridotto
- 🔧 **Manutenzione**: Un solo sistema CSS

---

### 6. Helper Deprecati
**ID**: `deprecated_helpers`  
**Severità**: 🟡 **WARNING**  
**File Target**: `*.php`

#### **Descrizione**
Rileva l'uso di helper Laravel deprecati che potrebbero essere rimossi in versioni future.

#### **Pattern Ricerca**
```regex
/(array_get|array_set|str_contains|str_starts_with)\s*\(/m
```

#### **Problemi Rilevati**
```php
❌ HELPER DEPRECATI:
array_get($array, 'key', 'default');
str_contains($string, 'search');
str_starts_with($string, 'prefix');

✅ HELPER MODERNI:
Arr::get($array, 'key', 'default');
Str::contains($string, 'search');
Str::startsWith($string, 'prefix');
```

#### **Fix Automatico**
❌ **Non disponibile** - Richiede import delle classi

#### **Impatto Business**
- 🔄 **Future-Proof**: Compatibilità versioni future
- 📈 **Performance**: Helper ottimizzati
- 📚 **Best Practices**: Codice Laravel moderno
- 🛠️ **Maintenance**: Meno breaking changes

---

## 🔵 REGOLE INFO

### 3. Componenti NetGescon
**ID**: `netgescon_components`  
**Severità**: 🔵 **INFO**  
**File Target**: `*.blade.php`

#### **Descrizione**
Verifica e monitora l'utilizzo corretto dei componenti del design system NetGescon.

#### **Pattern Ricerca**
```regex
/(netgescon-btn|netgescon-card|netgescon-title|netgescon-text|netgescon-input)/m
```

#### **Componenti Monitorati**
```blade
✅ COMPONENTI RILEVATI:
- netgescon-btn (Bottoni)
- netgescon-card (Cards)  
- netgescon-title (Titoli)
- netgescon-text (Testi)
- netgescon-input (Form inputs)
- netgescon-badge (Badge)
- netgescon-alert (Alerti)
```

#### **Fix Automatico**
❌ **Solo monitoraggio** - Nessun fix richiesto

#### **Impatto Business**
- 📊 **Analytics**: Usage pattern componenti
- 🎯 **Adoption**: Tasso adozione design system
- 📈 **Metrics**: KPI qualità interfaccia

---

### 5. Model Relationships
**ID**: `model_relationships`  
**Severità**: 🔵 **INFO**  
**File Target**: `app/Models/*.php`

#### **Descrizione**
Monitora la definizione delle relazioni Eloquent per assicurare architettura database coerente.

#### **Pattern Ricerca**
```regex
/(belongsTo|hasMany|hasOne|belongsToMany)\s*\(\s*[\'"][A-Z]/m
```

#### **Relazioni Monitorate**
```php
✅ RELAZIONI RILEVATE:
public function user() {
    return $this->belongsTo(User::class);
}

public function posts() {
    return $this->hasMany(Post::class);
}

public function tags() {
    return $this->belongsToMany(Tag::class);
}
```

#### **Fix Automatico**
❌ **Solo monitoraggio** - Verifica architettura

#### **Impatto Business**
- 🏗️ **Database Design**: Architettura coerente
- 📊 **Performance**: Query ottimizzate
- 🔗 **Data Integrity**: Relazioni corrette

---

### 8. Standard Migration
**ID**: `migration_standards`  
**Severità**: 🔵 **INFO**  
**File Target**: `database/migrations/*.php`

#### **Descrizione**
Monitora l'aderenza agli standard Laravel per le migration del database.

#### **Pattern Ricerca**
```regex
/(Schema::create|Schema::table|Schema::dropIfExists)/m
```

#### **Standard Monitorati**
```php
✅ STANDARD LARAVEL:
Schema::create('table_name', function (Blueprint $table) {
    $table->id();
    $table->timestamps();
});

Schema::table('table_name', function (Blueprint $table) {
    $table->string('new_column');
});

Schema::dropIfExists('table_name');
```

#### **Fix Automatico**
❌ **Solo monitoraggio** - Verifica standard

#### **Impatto Business**
- 🗃️ **Database Consistency**: Schema uniforme
- 🔄 **Deployment**: Migration affidabili
- 📈 **Scalability**: Struttura estendibile

---

## 🎯 CONFIGURAZIONE PERSONALIZZATA

### **Soglie di Qualità**
```php
// Configurazione severità
'quality_thresholds' => [
    'critical' => 0,      // Zero toleranza
    'error' => 5,         // Massimo 5 errori
    'warning' => 20,      // Massimo 20 warning
    'info' => 'unlimited' // Solo monitoraggio
]
```

### **Esclusioni File**
```php
// File da escludere dalla scansione
'exclude_patterns' => [
    'vendor/*',
    'node_modules/*', 
    'storage/*',
    '_BACKUP_*',
    '*.min.js'
]
```

### **Regole Custom**
```php
// Aggiungere regole specifiche progetto
'custom_rules' => [
    'netgescon_copyright' => [
        'pattern' => '/Copyright.*NetGescon/m',
        'required' => 'Header copyright NetGescon',
        'severity' => 'warning'
    ]
]
```

---

## 📊 METRICHE E KPI

### **Metriche Qualità**
- **Code Quality Score**: `(Total Files - Files With Critical Issues) / Total Files * 100`
- **Fix Rate**: `Auto Fixed Issues / Total Fixable Issues * 100`
- **Compliance Rate**: `Files Without Warnings / Total Files * 100`
- **Technical Debt**: `Sum of all weighted issues by severity`

### **Reporting Periodico**
- 📅 **Daily**: Critical issues = 0
- 📊 **Weekly**: Quality trends e fix rate
- 📈 **Monthly**: Compliance evolution
- 🎯 **Quarterly**: Architecture reviews

---

## 🔧 TROUBLESHOOTING REGOLE

### **Falsi Positivi**
```php
// Gestione eccezioni per regole specifiche
if (Str::contains($filePath, 'legacy/') || 
    Str::contains($filePath, 'external/')) {
    // Skip controlli per codice legacy/esterno
    continue;
}
```

### **Performance Issues**
- ⚡ **File Grandi**: Limitare scansione a 1MB per file
- 🔄 **Cache Results**: Cache risultati per file non modificati  
- 🎯 **Selective Scan**: Scansionare solo file modificati
- 📊 **Batch Processing**: Processare file in batch da 100

### **Memory Management**
```php
// Prevenzione memory exhaustion
ini_set('memory_limit', '512M');
gc_collect_cycles(); // Garbage collection forzata
```

---

## 🚀 BEST PRACTICES

### **Per Sviluppatori**
1. ⚡ **Scan Before Commit**: Scansione pre-commit
2. 🎯 **Fix Critical First**: Priorità problemi critici
3. 📚 **Learn Patterns**: Studiare problemi ricorrenti
4. 🔄 **Automate**: Usare fix automatici quando possibile

### **Per Team Lead**
1. 📊 **Monitor Trends**: Analisi trend qualità
2. 🎓 **Team Training**: Formazione su regole comuni
3. 📋 **Quality Gates**: Soglie qualità per deploy
4. 🏆 **Recognition**: Premiare codice di qualità

### **Per Project Manager**
1. 📈 **Quality Metrics**: KPI qualità nel dashboard
2. 💰 **ROI Tracking**: Benefici sistema qualità
3. 🎯 **Goal Setting**: Obiettivi qualità per team
4. 📊 **Stakeholder Reports**: Report per management

---

**🛡️ Queste regole garantiscono che il codice NetGescon mantenga sempre standard professionali elevati! 🚀**