# Carga Masiva de CUPS Eléctricos

## Descripción General

Sistema de carga masiva para crear o actualizar registros de CUPS (Código Universal del Punto de Suministro) Eléctricos desde archivos Excel. Este proceso permite importar múltiples puntos de suministro eléctricos de manera eficiente, validando la información y mostrando resultados detallados.

## Características

- ✅ Carga masiva desde archivos Excel (.xls, .xlsx)
- ✅ Creación y actualización de registros
- ✅ Validación de datos en tiempo real
- ✅ Búsqueda de tarifas por nombre (sin necesidad de códigos)
- ✅ Validación de puntos de suministro existentes
- ✅ Manejo de 6 potencias (P1-P6)
- ✅ Procesamiento transaccional (rollback en caso de error crítico)
- ✅ Reporte detallado de errores por fila
- ✅ Interfaz visual con estadísticas
- ✅ Descarga de plantilla Excel pre-formateada

## Formato del Archivo Excel

### Columnas Requeridas

| Columna | Descripción | Tipo | Requerido | Notas |
|---------|-------------|------|-----------|-------|
| CodCupsEle | Código CUPS Eléctrico | Entero | No* | Vacío para crear, con valor para actualizar |
| CodPunSum | Código Punto Suministro | Entero | Sí | Debe existir en la base de datos |
| CUPS Eléctrico | Código CUPS | Texto | Sí | Identificador único |
| Nombre Tarifa | Nombre de la tarifa | Texto | No | Se busca por coincidencia parcial |
| Potencia P1 | Potencia contratada P1 | Decimal | No | Valores numéricos |
| Potencia P2 | Potencia contratada P2 | Decimal | No | Valores numéricos |
| Potencia P3 | Potencia contratada P3 | Decimal | No | Valores numéricos |
| Potencia P4 | Potencia contratada P4 | Decimal | No | Valores numéricos |
| Potencia P5 | Potencia contratada P5 | Decimal | No | Valores numéricos |
| Potencia P6 | Potencia contratada P6 | Decimal | No | Valores numéricos |
| Potencia Max BIE | Potencia máxima BIE | Decimal | No | Valor numérico |
| Fecha Alta | Fecha de alta | Fecha | No | Formato: YYYY-MM-DD |
| Fecha Última Lectura | Fecha última lectura | Fecha | No | Formato: YYYY-MM-DD |
| Tipo Servicio | Tipo de servicio | Texto | No | Según catálogo |
| Consumo Anual | Consumo anual | Decimal | No | Valor numérico |
| Derecho Acceso KW | Derecho de acceso | Decimal | No | Valor numérico |
| Estado | Estado del registro | Entero | No | 1=Activo, 0=Inactivo (default: 1) |

*\*CodCupsEle es opcional para creación, requerido para actualización*

### Ejemplo de Datos

```
CodCupsEle | CodPunSum | CUPS Eléctrico        | Nombre Tarifa | PotP1 | PotP2 | ...
-----------|-----------|----------------------|---------------|-------|-------|-----
           | 1         | ES0021000000000001AA | Tarifa 2.0TD  | 3.45  | 3.45  | ...
5          | 2         | ES0021000000000002AA | Tarifa 3.0TD  | 5.00  | 5.00  | ...
```

## Proceso de Carga

### 1. Descarga de Plantilla

1. Acceder a la página de carga masiva de CUPS Eléctricos
2. Hacer clic en el botón "Descargar Plantilla"
3. Se descargará un archivo `.xls` con:
   - Encabezados formateados
   - Fila de ejemplo con datos reales
   - Instrucciones detalladas

### 2. Preparación del Archivo

1. Abrir la plantilla descargada
2. **IMPORTANTE**: Eliminar las filas de instrucciones (fila 4 en adelante)
3. Completar los datos:
   - Dejar `CodCupsEle` vacío para **crear** nuevos registros
   - Incluir `CodCupsEle` para **actualizar** registros existentes
   - `CodPunSum`: Debe existir en la base de datos
   - `Nombre Tarifa`: Se buscará automáticamente (coincidencia parcial)
   - Fechas en formato `YYYY-MM-DD`

### 3. Carga del Archivo

1. Arrastrar el archivo al área de "Drag & Drop" o hacer clic para seleccionar
2. El sistema mostrará una vista previa de los datos
3. Revisar la información cargada
4. Hacer clic en "Procesar CUPS Eléctricos"
5. Confirmar la operación en el diálogo

### 4. Visualización de Resultados

El sistema muestra:
- **Total**: Cantidad de registros procesados
- **Exitosos**: Registros sin errores
- **Creados**: Nuevos CUPS creados
- **Actualizados**: CUPS modificados
- **Errores**: Cantidad de filas con problemas

Si hay errores, se muestra una tabla detallada con:
- Número de fila con error
- Descripción del error
- Datos de la fila problemática

## Validaciones

### Validaciones de Datos

1. **Punto de Suministro**
   - Debe existir el `CodPunSum` en la tabla `T_PuntoSuministro`
   - Error si no se encuentra

2. **Tarifa Eléctrica**
   - Búsqueda por nombre usando `LIKE '%{nombre}%'`
   - Solo tarifas activas (`EstTarEle = 1`)
   - Error si no se encuentra coincidencia

3. **Código CUPS**
   - Campo requerido
   - No puede estar vacío

4. **Fechas**
   - Formato válido: YYYY-MM-DD
   - Conversión automática

5. **Actualización**
   - Si `CodCupsEle` tiene valor, debe existir el registro
   - Error si el código no existe

### Manejo de Errores

- **Errores por fila**: Se registran pero no detienen el proceso
- **Errores críticos**: Se hace rollback de toda la transacción
- **Log completo**: Todos los errores se guardan en logs del sistema

## API Endpoints

### Descarga de Plantilla

```http
GET /configuracion/plantilla/cups-electricos
```

**Respuesta**: Archivo Excel (.xls)

### Procesamiento de Carga

```http
POST /configuracion/carga-masiva/cups-electricos
Content-Type: multipart/form-data

archivo: [archivo Excel]
```

**Respuesta JSON**:
```json
{
  "success": true,
  "message": "Procesamiento completado: 10 exitosos, 2 errores",
  "data": {
    "total": 12,
    "exitosos": 10,
    "creados": 8,
    "actualizados": 2,
    "errores": 2,
    "detalles_errores": [
      {
        "fila": 5,
        "error": "Punto de Suministro con código 999 no encontrado",
        "datos": [...]
      }
    ]
  }
}
```

## Estructura de Base de Datos

### Tabla: T_CUPsElectrico

```sql
CodCupsEle (PK)
CodPunSum (FK → T_PuntoSuministro)
CUPsEle
CodTarElec (FK → T_TarifaElectrica)
PotConP1
PotConP2
PotConP3
PotConP4
PotConP5
PotConP6
PotMaxBie
FecAltCup
FecUltLec
TipServ
ConAnuCup
DerAccKW
EstCUPs
created_by
updated_by
created_at
updated_at
```

## Buenas Prácticas

1. **Preparación de Datos**
   - Validar datos en Excel antes de cargar
   - Usar la plantilla proporcionada
   - Eliminar filas de instrucciones

2. **Nombres de Tarifas**
   - Usar nombres completos o parciales
   - Verificar que existan en el sistema
   - Ejemplo: "2.0TD" encontrará "Tarifa 2.0TD"

3. **Potencias**
   - Incluir solo las potencias aplicables
   - Dejar en blanco las no utilizadas
   - Valores numéricos con decimales

4. **Fechas**
   - Usar siempre formato ISO: YYYY-MM-DD
   - Ejemplo: 2024-12-15

5. **Testing**
   - Probar con pocos registros primero
   - Verificar resultados antes de cargas masivas
   - Revisar la tabla de errores

## Solución de Problemas

### Error: "Punto de Suministro no encontrado"
**Causa**: El `CodPunSum` no existe
**Solución**: Verificar que el punto de suministro esté registrado

### Error: "Tarifa eléctrica no encontrada"
**Causa**: El nombre de tarifa no coincide o está inactiva
**Solución**: Usar nombre exacto o verificar estado de la tarifa

### Error: "El código CUPS es requerido"
**Causa**: Columna CUPS vacía
**Solución**: Completar el código CUPS para todos los registros

### No se procesan todos los registros
**Causa**: Filas vacías o con formato incorrecto
**Solución**: Eliminar filas vacías y verificar formato

## Ejemplos de Uso

### Caso 1: Crear nuevos CUPS

```
CodCupsEle | CodPunSum | CUPS Eléctrico        | Nombre Tarifa | Estado
-----------|-----------|----------------------|---------------|--------
           | 1         | ES0021000000000001AA | 2.0TD         | 1
           | 2         | ES0021000000000002AA | 3.0TD         | 1
```

### Caso 2: Actualizar CUPS existentes

```
CodCupsEle | CodPunSum | CUPS Eléctrico        | Nombre Tarifa | Estado
-----------|-----------|----------------------|---------------|--------
5          | 1         | ES0021000000000001AA | 2.0TD         | 1
8          | 2         | ES0021000000000002AA | 6.1TD         | 1
```

### Caso 3: Crear y actualizar en mismo archivo

```
CodCupsEle | CodPunSum | CUPS Eléctrico        | Nombre Tarifa | Estado
-----------|-----------|----------------------|---------------|--------
           | 1         | ES0021000000000003AA | 2.0TD         | 1
5          | 2         | ES0021000000000001AA | 3.0TD         | 1
           | 3         | ES0021000000000004AA | 6.1TD         | 1
```

## Código Relacionado

- **Backend Trait**: `app/Traits/ConfiguracionTraits.php::procesarCargaMasivaCupsElectricosTrait()`
- **Controller**: `app/Http/Controllers/ConfiguracionController.php::descargarPlantillaCupsElectricos()`
- **Frontend**: `resources/js/Pages/Eneon/CargasMasivas/CupsElectricos/Index.tsx`
- **Modelo**: `app/Models/CUPsElectrico.php`
- **Rutas**: `routes/web.php` (sección ConfiguracionController)

## Changelog

- **v1.0.0** (2025-01-XX): Implementación inicial con validaciones y reportes