# Carga Masiva de CUPS Gas

## Descripción General

Sistema de carga masiva para crear o actualizar registros de CUPS (Código Universal del Punto de Suministro) Gas desde archivos Excel. Este proceso permite importar múltiples puntos de suministro de gas 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 caudal diario
- ✅ 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 |
|---------|-------------|------|-----------|-------|
| CodCupGas | Código CUPS Gas | 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 Gas | Código CUPS | Texto | Sí | Identificador único |
| Nombre Tarifa | Nombre de la tarifa | Texto | No | Se busca por coincidencia parcial |
| 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 |
| Caudal Diario | Caudal diario | Decimal | No | Valor numérico específico de gas |
| Derecho Acceso KW | Derecho de acceso | Decimal | No | Valor numérico |
| Estado | Estado del registro | Entero | No | 1=Activo, 0=Inactivo (default: 1) |

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

### Ejemplo de Datos

```
CodCupGas | CodPunSum | CUPS Gas              | Nombre Tarifa | ConsumoAnual | CaudalDiario | Estado
----------|-----------|----------------------|---------------|--------------|--------------|--------
          | 1         | ES0021000000000001GG | RL.1          | 12000        | 35           | 1
3         | 2         | ES0021000000000002GG | RL.2          | 15000        | 42           | 1
```

## Proceso de Carga

### 1. Descarga de Plantilla

1. Acceder a la página de carga masiva de CUPS Gas
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 `CodCupGas` vacío para **crear** nuevos registros
   - Incluir `CodCupGas` 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`
   - `Caudal Diario`: Valor específico para instalaciones de gas

### 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 Gas"
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 Gas**
   - Búsqueda por nombre usando `LIKE '%{nombre}%'`
   - Solo tarifas activas (`EstTarGas = 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. **Caudal Diario**
   - Valor numérico
   - Campo específico para instalaciones de gas

6. **Actualización**
   - Si `CodCupGas` 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-gas
```

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

### Procesamiento de Carga

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

archivo: [archivo Excel]
```

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

## Estructura de Base de Datos

### Tabla: T_CUPsGas

```sql
CodCupGas (PK)
CodPunSum (FK → T_PuntoSuministro)
CupsGas
CodTarGas (FK → T_TarifaGas)
FecAltCup
FecUltLec
TipServ
ConAnuCup
caudaldiario
DerAccKW
EstCUPs
created_by
updated_by
created_at
updated_at
```

## Diferencias con CUPS Eléctricos

| Aspecto | CUPS Eléctricos | CUPS Gas |
|---------|----------------|----------|
| Potencias | 6 potencias (P1-P6) | No aplica |
| Caudal | No aplica | Caudal diario |
| Complejidad | Mayor (más campos) | Menor |
| Tabla Tarifa | T_TarifaElectrica | T_TarifaGas |
| Columnas Excel | 17 | 11 |

## 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: "RL.1" encontrará "Tarifa RL.1"

3. **Caudal Diario**
   - Valor numérico con decimales
   - Específico para instalaciones de gas
   - Importante para cálculos de consumo

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 gas 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 Gas

```
CodCupGas | CodPunSum | CUPS Gas              | Nombre Tarifa | CaudalDiario | Estado
----------|-----------|----------------------|---------------|--------------|--------
          | 1         | ES0021000000000001GG | RL.1          | 35           | 1
          | 2         | ES0021000000000002GG | RL.2          | 42           | 1
```

### Caso 2: Actualizar CUPS existentes

```
CodCupGas | CodPunSum | CUPS Gas              | Nombre Tarifa | CaudalDiario | Estado
----------|-----------|----------------------|---------------|--------------|--------
3         | 1         | ES0021000000000001GG | RL.1          | 38           | 1
5         | 2         | ES0021000000000002GG | RL.3          | 45           | 1
```

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

```
CodCupGas | CodPunSum | CUPS Gas              | Nombre Tarifa | CaudalDiario | Estado
----------|-----------|----------------------|---------------|--------------|--------
          | 1         | ES0021000000000003GG | RL.1          | 35           | 1
3         | 2         | ES0021000000000001GG | RL.2          | 40           | 1
          | 4         | ES0021000000000004GG | RL.3          | 50           | 1
```

## Comparación de Tarifas

### Tarifas Gas Comunes

- **RL.1**: Residencial de bajo consumo
- **RL.2**: Residencial de consumo medio
- **RL.3**: Residencial de alto consumo
- **RL.4**: Comercial pequeño
- **RL.5**: Comercial medio

## Código Relacionado

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

## Relación con Otros Procesos

Este proceso se complementa con:

1. **Carga Masiva de Puntos de Suministro**: Debe ejecutarse primero para crear los puntos
2. **Carga Masiva de CUPS Eléctricos**: Proceso paralelo para electricidad
3. **Gestión de Tarifas Gas**: Para mantener el catálogo de tarifas actualizado

## Flujo Completo Recomendado

1. ✅ Cargar Puntos de Suministro
2. ✅ Cargar CUPS Gas
3. ✅ Cargar CUPS Eléctricos (si aplica)
4. ✅ Verificar relaciones y datos

## Changelog

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