netgescon-day0/docs/05-backup-unificazione/docs-from-production/debug/API.md

📖 API Reference - Sistema Debug NetGescon

🎯 Overview

Questo documento descrive tutte le API, classi e metodi del Sistema Debug NetGescon.

---

🏗️ Architettura API

graph TB
    A[SystemAnalyzer] --> B[SystemDebugController]
    A --> C[SystemDebug Command]  
    A --> D[FindDuplicateViews Command]
    B --> E[Web Dashboard]
    C --> F[CLI Interface]
    D --> F

---

🔧 SystemAnalyzer Service

Classe Principale

namespace App\Debug\Services;

class SystemAnalyzer

Metodi Pubblici

analyzeDuplicates(): array

Analizza tutti i file duplicati nel sistema.

Return:

[
    'filename.blade.php' => [
        'count' => 5,
        'files' => [
            [
                'path' => '/full/path/to/file',
                'directory' => 'resources/views',
                'type' => 'active',
                'size' => 1024,
                'modified' => 1642781234,
                'readable_date' => '22/07/2025 14:32:15'
            ]
        ],
        'active_file' => [...],
        'risk_level' => 'high|medium|low'
    ]
]

Logica Risk Level:

• high: Multiple file attivi o >5 copie
• medium: 3-5 copie
• low: 2 copie

verifyRoutesAndViews(): array

Verifica coerenza tra route, controller e view.

Return:

[
    [
        'view' => 'admin.missing-page',
        'controller' => 'AdminController@missingMethod',
        'route_uri' => 'admin/missing',
        'route_name' => 'admin.missing',
        'methods' => ['GET']
    ]
]

checkModelRelationships(): array

Controlla relationship dei model Eloquent.

Return:

[
    [
        'model' => 'App\\Models\\Palazzina',
        'method' => 'stabile',
        'type' => 'belongsTo', 
        'related' => 'Stabile',
        'issue' => 'Model non trovato: App\\Models\\Stabile'
    ]
]

getSystemReport(): array

Genera report completo del sistema.

Return:

[
    'timestamp' => '2025-07-22 14:32:15',
    'system_info' => [
        'php_version' => '8.2.0',
        'laravel_version' => '11.0.0',
        'environment' => 'local',
        'debug_mode' => true,
        'storage_writable' => true,
        'views_count' => 245,
        'controllers_count' => 87,
        'models_count' => 23,
        'routes_count' => 156,
        'duplicates_folder_size' => '15.2 MB'
    ],
    'analysis' => [
        'duplicates' => [...],
        'missing_views' => [...],
        'broken_relationships' => [...]
    ],
    'recommendations' => [
        [
            'type' => 'critical|error|warning|success',
            'message' => 'Descrizione problema',
            'action' => 'Azione consigliata'
        ]
    ]
]

---

💻 SystemDebugController

Classe Controller

namespace App\Debug\Controllers;

class SystemDebugController extends Controller

Endpoint API

GET /admin/debug

Dashboard principale del sistema debug.

Response: HTML Dashboard

POST /admin/debug/scan-duplicates

Scansiona file duplicati via AJAX.

Headers:

X-CSRF-TOKEN: required
Accept: application/json

Response:

{
    "success": true,
    "message": "Scansione duplicati completata", 
    "output": "🔍 Ricerca duplicati...\n⚠️ Trovate 124 view duplicate\n📈 Trovati 124 file duplicati"
}

POST /admin/debug/clean-duplicates

Pulisce automaticamente i file duplicati.

Response:

{
    "success": true,
    "message": "Pulizia duplicati completata",
    "output": "🧹 Pulizia automatica duplicati...\n✅ Puliti 109 file duplicati"
}

POST /admin/debug/verify-routes

Verifica route e view del sistema.

Response:

{
    "success": true,
    "message": "Verifica route completata",
    "output": "🛤️ Verifica route e view...\n❌ View [admin.old-page] mancante\n✅ Sistema verificato"
}

POST /admin/debug/check-models

Controlla relationship dei model.

Response:

{
    "success": true, 
    "message": "Controllo model completato",
    "output": "🔗 Controllo relationship dei model...\n💔 Relationship problematici trovati\n📈 Trovati 3 relationship problematici"
}

POST /admin/debug/full-scan

Esegue scansione completa del sistema.

Response:

{
    "success": true,
    "message": "Scansione completa completata", 
    "output": "📊 Scansione completa del sistema...\n✅ Scansione completata!"
}

POST /admin/debug/generate-report

Genera report dettagliato in JSON.

Response:

{
    "success": true,
    "message": "Report generato con successo",
    "output": "📋 Generazione report completo...\n📄 Report salvato: storage/logs/netgescon_debug_2025-07-22_14-32-15.json"
}

---

🖥️ SystemDebug Command

Classe Command

namespace App\Debug\Commands;

class SystemDebug extends Command

Signature

netgescon:debug {--scan} {--duplicates} {--routes} {--models} {--clean} {--report}

Opzioni

Opzione	Tipo	Descrizione	Esempio
--scan	flag	Scansione completa	--scan
--duplicates	flag	Solo duplicati	--duplicates
--routes	flag	Verifica route/view	--routes
--models	flag	Controllo relationship	--models
--clean	flag	Pulizia automatica	--clean
--report	flag	Genera report JSON	--report

Metodi Principali

handle(): void

Entry point del comando.

scanAll(): void

Esegue scansione completa.

findDuplicates(): void

Trova e classifica file duplicati.

verifyRoutes(): void

Verifica route e controller.

checkModels(): void

Controlla relationship dei model.

cleanDuplicates(): void

Pulisce file duplicati automaticamente.

generateReport(): void

Genera report JSON dettagliato.

showSummary(): void

Mostra tabella riassuntiva finale.

---

🔍 FindDuplicateViews Command

Classe Command

namespace App\Debug\Commands;

class FindDuplicateViews extends Command

Signature

netgescon:find-duplicates {--action=scan : Azione da eseguire (scan|move|delete)}

Azioni Disponibili

Azione	Descrizione
scan	Solo scansione (default)
move	Sposta duplicati in backup
delete	Elimina duplicati (pericoloso)

---

📊 Response Format Standard

Success Response

{
    "success": true,
    "message": "Operazione completata con successo",
    "output": "Output console formattato",
    "data": {
        // Dati specifici dell'operazione
    }
}

Error Response

{
    "success": false,
    "message": "Descrizione errore",
    "error": "Dettaglio tecnico errore",
    "code": 500
}

---

🎨 Frontend JavaScript API

Funzioni Principali

executeAction(url, actionName)

Esegue un'azione di debug via AJAX.

Parameters:

• url: Endpoint API da chiamare
• actionName: Nome azione per UI

Example:

executeAction('/admin/debug/scan-duplicates', 'Scansione Duplicati');

addToConsole(message, type)

Aggiunge messaggio alla console debug.

Parameters:

• message: Testo da visualizzare
• type: success|warning|error|info

Example:

addToConsole('Test completato', 'success');
addToConsole('Attenzione: duplicati trovati', 'warning');

CSS Classes

.console-success { color: #28a745; } /* Verde */
.console-warning { color: #ffc107; } /* Giallo */
.console-error   { color: #dc3545; } /* Rosso */  
.console-info    { color: #17a2b8; } /* Blu */

---

🔧 Utility Functions

File System

getFolderSize(string $path): string

Calcola dimensione cartella in formato leggibile.

formatBytes(int $size, int $precision = 2): string

Converte byte in formato leggibile (KB, MB, GB).

countFiles(string $path, string $extension = 'php'): int

Conta file per estensione in una directory.

Analysis

findActiveFile(array $files): ?array

Trova il file attivo tra i duplicati.

Logic:

1. Priorità file in resources/views/
2. Più recente per data modifica

calculateRiskLevel(array $files): string

Calcola livello rischio duplicati.

Rules:

• high: >1 file attivo OR >5 copie totali
• medium: 3-5 copie
• low: 2 copie

---

📝 Configuration

Environment Variables

# .env
DEBUG_SYSTEM_ENABLED=true
DEBUG_AUTO_CLEAN=false  
DEBUG_BACKUP_KEEP_DAYS=30
DEBUG_REPORT_FORMAT=json

Directory Paths

// SystemAnalyzer.php - Configurabile
protected $directories = [
    'resources/views' => 'active',
    '_DUPLICATES_MOVED/resources/views' => 'moved', 
    '_BACKUP_OLD_netgescon-laravel_INACTIVE/resources/views' => 'backup_laravel',
    '_BACKUP_OLD_netgescon_INACTIVE/vendor/laravel/breeze/stubs' => 'backup_breeze'
];

---

🐛 Error Codes

Code	Tipo	Descrizione
200	Success	Operazione completata
400	Client Error	Parametri invalidi
403	Forbidden	Permessi insufficienti
404	Not Found	Route/File non trovato
500	Server Error	Errore interno

Esempi Error Handling

// Frontend
fetch('/admin/debug/scan-duplicates')
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP ${response.status}`);
        }
        return response.json();
    })
    .catch(error => {
        addToConsole(`Errore: ${error.message}`, 'error');
    });

// Backend
try {
    $analyzer = new SystemAnalyzer();
    $result = $analyzer->analyzeDuplicates();
    
    return response()->json([
        'success' => true,
        'data' => $result
    ]);
} catch (\Exception $e) {
    return response()->json([
        'success' => false, 
        'message' => 'Errore durante analisi',
        'error' => $e->getMessage()
    ], 500);
}

---

🧪 Testing API

Unit Test Example

<?php

namespace Tests\Feature\Debug;

use Tests\TestCase;
use App\Debug\Services\SystemAnalyzer;

class SystemAnalyzerTest extends TestCase  
{
    public function test_can_analyze_duplicates()
    {
        $analyzer = new SystemAnalyzer();
        $duplicates = $analyzer->analyzeDuplicates();
        
        $this->assertIsArray($duplicates);
        $this->assertArrayHasKey('count', $duplicates['index.blade.php'] ?? []);
    }
    
    public function test_dashboard_loads()
    {
        $response = $this->actingAs($this->adminUser())
            ->get('/admin/debug');
            
        $response->assertStatus(200);
        $response->assertSee('Sistema Debug NetGescon');
    }
}

API Test via cURL

# Test scansione duplicati
curl -X POST http://localhost:8000/admin/debug/scan-duplicates \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: your-token" \
  -H "Cookie: laravel_session=your-session"

# Test con autenticazione
curl -X POST http://localhost:8000/admin/debug/full-scan \
  --cookie-jar cookies.txt \
  --cookie cookies.txt \
  -H "X-CSRF-TOKEN: $(grep csrf cookies.txt | cut -f7)"

---

📚 Documentazione API completa - Sistema Debug NetGescon v1.0