# 🛠️ INSTALLAZIONE E CONFIGURAZIONE - SISTEMA CONTROLLO QUALITÀ

**Versione**: 1.0.0  
**Piattaforma**: Laravel 10+ con NetGescon  
**Requisiti**: PHP 8.1+, MySQL 5.7+

---

## ⚡ INSTALLAZIONE RAPIDA

### **Status Attuale**
✅ **SISTEMA GIÀ INSTALLATO E OPERATIVO!**

Il sistema è stato implementato il 23 Luglio 2025 e include:
- ✅ Controller completo
- ✅ Views responsive  
- ✅ Routes configurate
- ✅ Navigazione integrata
- ✅ Documentazione completa

### **Verifica Installazione**
```bash
# 1. Verifica file esistenti
ls -la app/Http/Controllers/Admin/CodeQualityController.php
ls -la resources/views/admin/code-quality/index.blade.php

# 2. Test access URL
curl -I https://yourdomain.com/admin/code-quality

# 3. Check routes
php artisan route:list | grep code-quality
```

---

## 📁 STRUTTURA FILE INSTALLATI

### **Controller**
```
📂 app/Http/Controllers/Admin/
└── 📄 CodeQualityController.php (8.2KB)
    ├── index() - Dashboard principale
    ├── scan() - Engine scansione AJAX  
    ├── autofix() - Fix automatici
    ├── scanCodeQuality() - Core logic
    ├── analyzeFile() - Analisi singolo file
    ├── getFilesToScan() - File discovery
    ├── shouldApplyRule() - Rule filtering
    ├── getLineContext() - Context viewer
    ├── filterBySeverity() - Severity filter
    ├── generateSummary() - Statistics
    └── applyAutoFix() - Automated fixes
```

### **Views**
```
📂 resources/views/admin/code-quality/
└── 📄 index.blade.php (12.5KB)
    ├── NetGescon layout integration
    ├── Configuration form
    ├── Real-time scanning
    ├── Results dashboard
    ├── Statistics cards
    ├── Interactive fix buttons
    └── JavaScript automation
```

### **Routes**
```
📂 routes/
└── 📄 web.php (modified)
    ├── Route::prefix('code-quality')
    ├── GET  /admin/code-quality (index)
    ├── POST /admin/code-quality/scan  
    └── POST /admin/code-quality/autofix
```

### **Documentazione**
```
📂 docs/sistema-controllo-qualita/
├── 📄 README.md (Sistema overview)
├── 📄 REGOLE-CONTROLLO.md (8 regole dettagliate)
├── 📄 GUIDA-PRATICA.md (Workflow operativi)
└── 📄 INSTALLAZIONE.md (Questo file)
```

---

## ⚙️ CONFIGURAZIONE POST-INSTALLAZIONE

### **1. Permissions Setup**
```bash
# Assicura permessi corretti per fix automatici
chmod 755 app/Http/Controllers/
chmod 644 app/Http/Controllers/Admin/CodeQualityController.php
chmod 755 resources/views/admin/code-quality/
chmod 644 resources/views/admin/code-quality/index.blade.php

# Permessi scrittura per fix automatici
chmod 775 app/
chmod 775 resources/views/
find app/ -type f -name "*.php" -exec chmod 664 {} \;
find resources/views/ -type f -name "*.blade.php" -exec chmod 664 {} \;
```

### **2. Environment Configuration**
```bash
# .env additions (opzionale)
CODE_QUALITY_ENABLED=true
CODE_QUALITY_MAX_FILE_SIZE=1048576  # 1MB
CODE_QUALITY_TIMEOUT=30             # 30 secondi
CODE_QUALITY_MEMORY_LIMIT=512M
```

### **3. Cache Optimization**
```bash
# Clear cache per nuove routes
php artisan route:clear
php artisan cache:clear
php artisan config:clear

# Optimize for production
php artisan route:cache
php artisan config:cache
```

---

## 🔧 PERSONALIZZAZIONE AVANZATA

### **Aggiungere Regole Custom**
```php
// In CodeQualityController.php - $qualityRules array

'custom_netgescon_rule' => [
    'name' => 'NetGescon Custom Check',
    'description' => 'Verifica standard specifici NetGescon',
    'pattern' => '/your-custom-regex-pattern/m',
    'required' => 'Soluzione richiesta',
    'severity' => 'warning|error|critical|info'
],
```

### **Configurare Esclusioni**
```php
// In getFilesToScan() method
$excludePatterns = [
    'vendor/*',
    'node_modules/*',
    'storage/logs/*',
    '_BACKUP_*',
    '*.min.js',
    '*.min.css',
    // Aggiungi pattern custom
    'legacy/*',
    'external/*',
    'temp/*'
];
```

### **Personalizzare Fix Automatici**
```php
// In applyAutoFix() method
switch ($ruleKey) {
    case 'your_custom_rule':
        $content = preg_replace(
            '/old-pattern/', 
            'new-pattern', 
            $content
        );
        break;
        
    // Aggiungi altri fix custom
}
```

---

## 🔌 INTEGRAZIONE CI/CD

### **GitHub Actions**
```yaml
# .github/workflows/code-quality.yml
name: NetGescon Code Quality

on: [push, pull_request]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          
      - name: Install Dependencies
        run: composer install --no-dev --optimize-autoloader
        
      - name: Run Code Quality Check
        run: |
          php artisan code:quality:scan --format=json --output=quality-report.json
          
      - name: Upload Quality Report
        uses: actions/upload-artifact@v3
        with:
          name: quality-report
          path: quality-report.json
```

### **Webhook Integration**
```php
// routes/api.php - per integrazione esterna
Route::post('/webhook/code-quality', function (Request $request) {
    // Trigger scansione automatica su push
    $controller = new CodeQualityController();
    $results = $controller->scan($request);
    
    // Invia notifica su Slack/Teams se critical > 0
    if ($results['summary']['by_severity']['critical'] > 0) {
        // Send alert notification
    }
    
    return response()->json($results);
});
```

---

## 📊 MONITORING E ALERTING

### **Database Logging** (Opzionale)
```php
// Migration per logging risultati
Schema::create('code_quality_scans', function (Blueprint $table) {
    $table->id();
    $table->timestamp('scan_date');
    $table->integer('total_files');
    $table->integer('critical_issues');
    $table->integer('error_issues');
    $table->integer('warning_issues');
    $table->integer('info_issues');
    $table->decimal('quality_score', 5, 2);
    $table->json('detailed_results');
    $table->timestamps();
});
```

### **Slack Notifications**
```php
// In controller, after scan completion
if ($summary['by_severity']['critical'] > 0) {
    Notification::route('slack', config('services.slack.webhook'))
        ->notify(new CriticalQualityIssuesNotification($summary));
}
```

### **Email Reports**
```php
// Scheduled command for weekly reports
// app/Console/Commands/WeeklyQualityReport.php
class WeeklyQualityReport extends Command
{
    public function handle()
    {
        $controller = new CodeQualityController();
        $results = $controller->scanCodeQuality('app,resources/views', 'all');
        
        Mail::to(config('app.admin_email'))
            ->send(new QualityReportMail($results));
    }
}
```

---

## 🔍 DEBUGGING E TROUBLESHOOTING

### **Enable Debug Mode**
```php
// In CodeQualityController.php
private $debug = true; // Enable for troubleshooting

private function debugLog($message, $data = null) {
    if ($this->debug) {
        \Log::debug("CodeQuality: $message", $data ? ['data' => $data] : []);
    }
}
```

### **Performance Profiling**
```php
// Add timing to scan methods
$startTime = microtime(true);
$results = $this->scanCodeQuality($scanPath, $severityFilter);
$executionTime = microtime(true) - $startTime;

\Log::info("Code Quality Scan completed", [
    'execution_time' => round($executionTime, 2) . 's',
    'files_scanned' => count($results),
    'memory_used' => memory_get_peak_usage(true) / 1024 / 1024 . 'MB'
]);
```

### **Error Handling**
```php
// Wrap scan operations in try-catch
try {
    $results = $this->scanCodeQuality($scanPath, $severityFilter);
} catch (\Exception $e) {
    \Log::error("Code Quality scan failed", [
        'error' => $e->getMessage(),
        'trace' => $e->getTraceAsString()
    ]);
    
    return response()->json([
        'success' => false,
        'message' => 'Scansione fallita: ' . $e->getMessage()
    ], 500);
}
```

---

## 🔐 SECURITY CONSIDERATIONS

### **File Access Control**
```php
// Verify file access permissions
private function canAccessFile($filePath) {
    // Prevent access to sensitive files
    $forbiddenPaths = [
        '.env',
        'storage/logs/',
        'bootstrap/cache/',
        '.git/'
    ];
    
    foreach ($forbiddenPaths as $forbidden) {
        if (Str::contains($filePath, $forbidden)) {
            return false;
        }
    }
    
    return is_readable($filePath);
}
```

### **Input Validation**
```php
// Validate scan parameters
$request->validate([
    'path' => 'required|string|max:500|regex:/^[a-zA-Z0-9\/_,.-]+$/',
    'severity' => 'required|in:all,critical,error,warning,info'
]);
```

### **Rate Limiting**
```php
// In routes/web.php
Route::prefix('code-quality')->middleware(['throttle:10,1'])->group(function () {
    // Limit to 10 scans per minute per user
});
```

---

## 📋 POST-INSTALL CHECKLIST

### **Verifica Funzionalità**
```bash
✅ Dashboard accessibile (/admin/code-quality)
✅ Scansione funzionante (test su file piccolo)
✅ Fix automatici operativi
✅ Navigazione integrata (header/sidebar)
✅ Permissions corretti per file modification
✅ Performance accettabile (< 30s per scansione media)
✅ Error handling robusto
✅ Logging configurato
```

### **Team Onboarding**
```bash
✅ Documentazione condivisa con team
✅ Training session programmata
✅ Best practices comunicate
✅ Quality gates definiti
✅ Workflow integrato nel processo
```

### **Production Readiness**
```bash
✅ Environment variables configurate
✅ Caching abilitato
✅ Monitoring setup
✅ Backup strategy
✅ Rollback plan
✅ Performance baseline
```

---

## 🚀 NEXT STEPS

### **Immediate (Settimana 1)**
1. 🎯 Team training su utilizzo base
2. 📊 Prima scansione completa progetto
3. 🔧 Personalizzazione regole per NetGescon
4. 📋 Definizione quality gates

### **Short Term (Mese 1)**  
1. 🔄 Integrazione workflow quotidiano
2. 📈 Monitoring metriche qualità
3. 🎯 Fix automatici per problemi comuni
4. 👥 Feedback raccolta da team

### **Long Term (Trimestre 1)**
1. 🤖 CI/CD integration completa
2. 📊 Advanced reporting dashboard
3. 🧠 Machine learning per pattern detection
4. 🌐 Multi-project support

---

## 📞 SUPPORT

### **Documentazione**
- 📖 **README**: Overview completo sistema
- 🛡️ **REGOLE**: Dettaglio 8 regole controllo
- 🎯 **GUIDA**: Workflow pratici operativi  
- 🛠️ **INSTALL**: Questa guida

### **Contatti**
- 🤖 **Sviluppato da**: GitHub Copilot per NetGescon
- 📧 **Support**: Utilizzare sistema ticket NetGescon
- 🔄 **Updates**: Monitorare docs/ per nuove versioni
- 🐛 **Bug Reports**: Via issue tracking interno

---

**🎉 Il Sistema Controllo Qualità NetGescon è ora completamente installato e pronto per elevare la qualità del vostro codice! 🚀**