# 📖 API Reference - Sistema Debug NetGescon

## 🎯 Overview

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

---

## 🏗️ Architettura API

```mermaid
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
```php
namespace App\Debug\Services;

class SystemAnalyzer
```

### Metodi Pubblici

#### `analyzeDuplicates(): array`
Analizza tutti i file duplicati nel sistema.

**Return:**
```php
[
    '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:**
```php
[
    [
        '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:**
```php
[
    [
        '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:**
```php
[
    '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
```php
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:**
```json
{
    "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:**
```json
{
    "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:**
```json
{
    "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:**
```json
{
    "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:**
```json
{
    "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:**
```json
{
    "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  
```php
namespace App\Debug\Commands;

class SystemDebug extends Command
```

### Signature
```bash
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
```php  
namespace App\Debug\Commands;

class FindDuplicateViews extends Command
```

### Signature
```bash
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
```json
{
    "success": true,
    "message": "Operazione completata con successo",
    "output": "Output console formattato",
    "data": {
        // Dati specifici dell'operazione
    }
}
```

### Error Response  
```json
{
    "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:**
```javascript
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:**
```javascript
addToConsole('Test completato', 'success');
addToConsole('Attenzione: duplicati trovati', 'warning');
```

### CSS Classes
```css
.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
```bash
# .env
DEBUG_SYSTEM_ENABLED=true
DEBUG_AUTO_CLEAN=false  
DEBUG_BACKUP_KEEP_DAYS=30
DEBUG_REPORT_FORMAT=json
```

### Directory Paths
```php
// 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

```javascript
// 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');
    });
```

```php
// 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
<?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
```bash
# 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**