netgescon-day0/docs/00-MASTER-DOCS-UNIFICATI/03-MANUALI-OPERATIVI/INSTALLAZIONE.md

🛠️ 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

# 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

# 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

# .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

# 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

// 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

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

Personalizzare Fix Automatici

// 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

# .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

// 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)

// 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

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

Email Reports

// 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

// 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

// 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

// 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

// 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

// 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

// 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à

✅ 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

✅ Documentazione condivisa con team
✅ Training session programmata
✅ Best practices comunicate
✅ Quality gates definiti
✅ Workflow integrato nel processo

Production Readiness

✅ 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! 🚀