# Documentación Técnica - Script de Diagnóstico Avanzado del Sistema

## 📋 Información General

- **Nombre**: `DiagnosticoSistema_Avanzado.ps1`
- **Versión**: 3.0
- **Lenguaje**: PowerShell 5.1+
- **Compatibilidad**: Windows 10/11, Windows Server 2016+
- **Desarrollado con**: DeepSeek R1 y Claude Sonnet
- **Última actualización**: $(Get-Date -Format 'dd/MM/yyyy')

## 🏗️ Arquitectura del Sistema

### Estructura Modular
```
DiagnosticoSistema_Avanzado.ps1
├── Configuración Global
├── Funciones de Utilidad
├── Funciones de Validación
├── Funciones de Recolección de Datos
├── Funciones de Análisis
├── Funciones de Exportación
└── Función Principal
```

### Flujo de Ejecución
```
Inicio → Validación de Integridad → Recolección de Datos → Análisis → Generación de Reportes → Fin
```

## 🔧 Configuración del Entorno

### Prerrequisitos
```powershell
# PowerShell 5.1 o superior
$PSVersionTable.PSVersion.Major -ge 5

# Módulos requeridos
- Microsoft.PowerShell.Utility
- Microsoft.PowerShell.Management
- NetAdapter (Windows 10/11)
- WindowsFeature (Windows Server)
- ActiveDirectory (opcional, para servidores)
```

### Configuración de Seguridad
```powershell
$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue'
$PSDefaultParameterValues['*:ErrorAction'] = 'Stop'
```

## 📚 API de Funciones

### 1. Funciones de Logging y Utilidad

#### `Write-SecureLog`
**Propósito**: Sistema de logging seguro con niveles y componentes
```powershell
Write-SecureLog -Message "Mensaje" -Level "INFO" -Component "System"
```
**Parámetros**:
- `Message` (string): Mensaje a registrar
- `Level` (string): Nivel de log (ERROR, WARN, INFO, DEBUG)
- `Component` (string): Componente que genera el log

#### `Test-AdministratorPrivileges`
**Propósito**: Verifica si el script se ejecuta como administrador
```powershell
$isAdmin = Test-AdministratorPrivileges
```
**Retorna**: `bool`

### 2. Funciones de Validación

#### `Test-SystemIntegrity`
**Propósito**: Valida acceso a componentes críticos del sistema
```powershell
$integrity = Test-SystemIntegrity
```
**Retorna**: `hashtable` con estado de:
- WMI_Status
- Registry_Access
- FileSystem_Access
- Network_Access
- PowerShell_Execution

#### `Get-SystemType`
**Propósito**: Determina el tipo de sistema operativo
```powershell
$systemType = Get-SystemType -osInfo $osInfo
```
**Retorna**: `string` (Workstation, Domain Controller, Server, Unknown)

### 3. Funciones de Recolección de Datos

#### `Get-RealTimePerformance`
**Propósito**: Recopila métricas de rendimiento en tiempo real
```powershell
$performance = Get-RealTimePerformance
```
**Retorna**: `hashtable` con:
- CPU_Usage (porcentaje)
- Memory_Usage (porcentaje)
- Disk_IO (operaciones/segundo)
- Network_IO (operaciones/segundo)

#### `Get-SecurityAnalysis`
**Propósito**: Analiza componentes de seguridad del sistema
```powershell
$security = Get-SecurityAnalysis
```
**Retorna**: `hashtable` con:
- Windows_Defender (Enabled/Disabled)
- Firewall_Status (Enabled/Disabled)
- UAC_Status (Enabled/Disabled)
- BitLocker_Status (Enabled/Disabled)
- Last_Update (fecha)

#### `Get-SystemAlerts`
**Propósito**: Genera alertas basadas en umbrales del sistema
```powershell
$alerts = Get-SystemAlerts
```
**Retorna**: `array` de alertas con formato:
- "CRÍTICO: [descripción]"
- "ADVERTENCIA: [descripción]"

### 4. Funciones de Exportación

#### `Export-ToHTML`
**Propósito**: Genera reporte HTML con diseño moderno
```powershell
Export-ToHTML -Data $diagnosticData -OutputPath $htmlPath
```
**Parámetros**:
- `Data` (hashtable): Datos del diagnóstico
- `OutputPath` (string): Ruta de salida del archivo

#### `Export-ToJSON`
**Propósito**: Exporta datos en formato JSON estructurado
```powershell
Export-ToJSON -Data $diagnosticData -OutputPath $jsonPath
```

### 5. Funciones de Interfaz

#### `Select-ReportLocation`
**Propósito**: Permite al usuario seleccionar ubicación de reportes
```powershell
$location = Select-ReportLocation
```
**Opciones**:
1. Escritorio (recomendado)
2. Documentos
3. Ubicación personalizada (diálogo)
4. Ubicación actual

## 🔍 Estructura de Datos

### DiagnosticData (hashtable principal)
```powershell
$diagnosticData = @{
    "Timestamp" = "2024-01-01 12:00:00"
    "SystemInfo" = @{
        "Manufacturer" = "Dell Inc."
        "Model" = "Latitude 5520"
        "SerialNumber" = "ABC123"
        "OS" = "Microsoft Windows 10 Pro"
        "Version" = "10.0.19045"
        "Architecture" = "64-bit"
        "SystemType" = "Workstation"
        "Username" = "usuario"
        "IsAdmin" = $true
    }
    "Integrity" = @{ /* resultado de Test-SystemIntegrity */ }
    "Performance" = @{ /* resultado de Get-RealTimePerformance */ }
    "Security" = @{ /* resultado de Get-SecurityAnalysis */ }
    "Alerts" = @( /* resultado de Get-SystemAlerts */ )
    "Comparison" = @{ /* resultado de Get-ComparativeAnalysis */ }
}
```

## 🛠️ Desarrollo y Extensión

### Agregar Nueva Función de Análisis
```powershell
function Get-CustomAnalysis {
    param(
        [hashtable]$SystemData
    )
    
    Write-SecureLog "Iniciando análisis personalizado..." "INFO" "Custom"
    
    $customData = @{
        "CustomMetric1" = "valor1"
        "CustomMetric2" = "valor2"
    }
    
    try {
        # Lógica de análisis
        Write-SecureLog "Análisis personalizado completado" "INFO" "Custom"
    } catch {
        Write-SecureLog "Error en análisis personalizado: $($_.Exception.Message)" "ERROR" "Custom"
    }
    
    return $customData
}
```

### Agregar Nuevo Formato de Exportación
```powershell
function Export-ToCustomFormat {
    param(
        [hashtable]$Data,
        [string]$OutputPath
    )
    
    Write-SecureLog "Generando reporte personalizado..." "INFO" "Export"
    
    try {
        # Lógica de exportación
        $customContent = "Contenido personalizado"
        $customContent | Out-File -FilePath $OutputPath -Encoding UTF8
        Write-SecureLog "Reporte personalizado generado: $OutputPath" "INFO" "Export"
        return $true
    } catch {
        Write-SecureLog "Error al generar reporte personalizado: $($_.Exception.Message)" "ERROR" "Export"
        return $false
    }
}
```

### Modificar Umbrales de Alertas
```powershell
# Constantes configurables (agregar al inicio del script)
$DISK_USAGE_WARNING_THRESHOLD = 80
$DISK_USAGE_CRITICAL_THRESHOLD = 90
$MEMORY_USAGE_WARNING_THRESHOLD = 80
$MEMORY_USAGE_CRITICAL_THRESHOLD = 90
```

## 🧪 Testing y Debugging

### Modo Debug
```powershell
# Agregar al inicio del script para debugging
$VerbosePreference = 'Continue'
$DebugPreference = 'Continue'
```

### Testing de Funciones Individuales
```powershell
# Test de integridad
$integrity = Test-SystemIntegrity
$integrity | ConvertTo-Json

# Test de rendimiento
$performance = Get-RealTimePerformance
$performance | ConvertTo-Json

# Test de seguridad
$security = Get-SecurityAnalysis
$security | ConvertTo-Json
```

### Logs de Debug
```powershell
Write-SecureLog "Variable X = $variableX" "DEBUG" "Component"
```

## 🔒 Consideraciones de Seguridad

### Permisos Requeridos
- **Usuario estándar**: Información básica del sistema
- **Administrador**: Información completa, análisis de seguridad

### Datos Sensibles
- Números de serie de hardware
- Información de red (IPs, MAC)
- Estado de servicios del sistema

### Recomendaciones
1. Ejecutar como administrador para información completa
2. Revisar logs antes de compartir reportes
3. No ejecutar en sistemas de producción sin autorización

## 📊 Métricas y Rendimiento

### Tiempo de Ejecución Típico
- **Estación de trabajo**: 15-30 segundos
- **Servidor**: 30-60 segundos
- **Servidor con AD**: 45-90 segundos

### Uso de Recursos
- **CPU**: Pico del 5-10% durante análisis
- **Memoria**: ~50MB durante ejecución
- **Disco**: ~1-5MB de archivos de salida

### Optimizaciones Recomendadas
1. Usar `-ErrorAction SilentlyContinue` para operaciones no críticas
2. Limitar consultas WMI con `Select-Object`
3. Usar `Get-CimInstance` en lugar de `Get-WmiObject`

## 🐛 Troubleshooting

### Errores Comunes

#### Error: "No se puede indizar en una matriz nula"
**Causa**: Contador de rendimiento no disponible
**Solución**: El script usa método alternativo automáticamente

#### Error: "Acceso denegado"
**Causa**: Permisos insuficientes
**Solución**: Ejecutar como administrador

#### Error: "Módulo no encontrado"
**Causa**: Módulo de PowerShell no disponible
**Solución**: El script maneja esto automáticamente

### Logs de Error
```powershell
# Buscar errores en logs
Get-Content $logFile | Where-Object { $_ -like "*ERROR*" }
```

## 📈 Roadmap de Desarrollo

### Versión 3.1 (Próxima)
- [ ] Refactorización completa a Clean Code
- [ ] Implementación de clases PowerShell
- [ ] Sistema de plugins
- [ ] API REST para integración

### Versión 3.2 (Futura)
- [ ] Análisis de rendimiento histórico
- [ ] Integración con sistemas de monitoreo
- [ ] Reportes automáticos por email
- [ ] Dashboard web

## 📞 Soporte y Contacto

### Para Reportes de Bugs
1. Ejecutar script con `-Verbose`
2. Capturar logs completos
3. Incluir información del sistema
4. Describir pasos para reproducir

### Para Solicitudes de Funcionalidad
1. Describir caso de uso
2. Especificar requisitos técnicos
3. Proporcionar ejemplos de uso

---

**Nota**: Esta documentación se actualiza con cada versión del script. Para la versión más reciente, consultar el repositorio del proyecto.