# Carga Masiva de Puntos de Suministro

## Descripción General

Este módulo permite la carga masiva de puntos de suministro mediante un archivo Excel. Los puntos de suministro son ubicaciones físicas (casas, empresas, talleres, etc.) que pueden tener uno o más CUPS asociados (eléctricos y/o gas).

## Características

- **Crear nuevos puntos**: Dejando vacío el campo `CodPunSum`
- **Actualizar existentes**: Indicando el código en `CodPunSum`
- **Validaciones robustas**: Cliente, localidad y tipo de vía se validan contra la base de datos
- **Manejo de errores**: Reportes detallados por fila con errores específicos
- **Transaccional**: Todo el proceso en una transacción, rollback en caso de error crítico

## Formato del Archivo Excel

### Estructura de Columnas

| Columna | Campo | Tipo | Obligatorio | Descripción | Ejemplo |
|---------|-------|------|-------------|-------------|---------|
| A | CodPunSum | Número | No | Código del punto (vacío=crear, valor=actualizar) | 123 o vacío |
| B | CIF_Cliente | Texto | **Sí** | CIF/NIF del cliente (debe existir en sistema) | B12345678 |
| C | Nombre_Punto | Texto | No | Nombre descriptivo del punto | Oficina Principal |
| D | Tipo_Via | Texto | No | Tipo de vía (debe coincidir con catálogo) | CALLE |
| E | Nombre_Via | Texto | No | Nombre de la vía | MAYOR |
| F | Numero | Texto | No | Número del portal | 123 |
| G | Bloque | Texto | No | Bloque del edificio | A |
| H | Escalera | Texto | No | Escalera | 1 |
| I | Planta | Texto | No | Planta/piso | 3 |
| J | Puerta | Texto | No | Puerta | B |
| K | Codigo_Postal | Texto | No | CP de 5 dígitos | 28013 |
| L | Localidad | Texto | No | Nombre de la localidad | MADRID |
| M | Provincia | Texto | No | Provincia (informativo) | MADRID |
| N | Observaciones | Texto | No | Observaciones adicionales | Sede central |
| O | Estado | Número | No | 1=Activo, 0=Inactivo (default: 1) | 1 |

### Tipos de Vía Válidos

Los tipos de vía deben coincidir con los registrados en la tabla `T_TipoVia`. Ejemplos comunes:

- CALLE
- AVENIDA
- PLAZA
- PASEO
- CARRETERA
- CAMINO
- URBANIZACIÓN
- TRAVESÍA
- RONDA
- VÍA

## Proceso de Carga

### 1. Descargar Plantilla

```
GET /configuracion/plantilla/puntos-suministro
```

Descarga un archivo `.xls` con:
- Encabezados formateados
- Fila de ejemplo con datos reales
- Instrucciones de uso

### 2. Completar Plantilla

1. Abrir el archivo descargado
2. Completar los datos según las especificaciones
3. **IMPORTANTE**: Eliminar las filas de instrucciones antes de cargar
4. Guardar el archivo

### 3. Cargar Archivo

```
POST /configuracion/carga-masiva/puntos-suministro
Content-Type: multipart/form-data

archivo: [archivo.xls]
```

**Respuesta exitosa:**

```json
{
    "success": true,
    "message": "Procesamiento completado: 45 exitosos, 2 errores",
    "data": {
        "total": 47,
        "exitosos": 45,
        "actualizados": 20,
        "creados": 25,
        "errores": 2,
        "detalles_errores": [
            {
                "fila": 5,
                "error": "Cliente con CIF B99999999 no encontrado",
                "datos": [...]
            },
            {
                "fila": 12,
                "error": "Localidad con CP 99999 no encontrada",
                "datos": [...]
            }
        ]
    }
}
```

**Respuesta con error:**

```json
{
    "success": false,
    "message": "Error al procesar la carga masiva: Archivo corrupto",
    "status": 500,
    "data": null
}
```

## Validaciones

### 1. Cliente (CIF_Cliente)

- **Campo obligatorio**
- Debe existir un cliente con el CIF indicado en `T_Cliente.NumCifCli`
- Se busca coincidencia exacta
- Error si no se encuentra

### 2. Localidad (CodigoPostal + Localidad)

- Se busca por código postal en `T_Localidad.CPLoc`
- Opcionalmente se filtra por nombre de localidad
- Si no se encuentra localidad con el CP, se genera error
- Si el CP existe, se asocia aunque el nombre de localidad no coincida exactamente

### 3. Tipo de Vía (TipoVia)

- Se busca por descripción o abreviatura en `T_TipoVia`
- Búsqueda con `LIKE` para mayor flexibilidad
- Ejemplos: "CALLE", "C/", "Calle" → todos coinciden con "CALLE"
- Error si no se encuentra ninguna coincidencia

### 4. Estado

- Valores permitidos: `0` (Inactivo) o `1` (Activo)
- Valor por defecto: `1` (Activo)

## Mapeo de Campos

| Campo Excel | Campo BD | Tabla | Tipo |
|-------------|----------|-------|------|
| CodPunSum | CodPunSum | T_PuntoSuministro | INT (PK) |
| CIF_Cliente | CodCli | T_PuntoSuministro | INT (FK → T_Cliente) |
| TipoVia | CodTipVia | T_PuntoSuministro | INT (FK → T_TipoVia) |
| NombreVia | NomViaPunSum | T_PuntoSuministro | VARCHAR |
| Numero | NumViaPunSum | T_PuntoSuministro | VARCHAR |
| Bloque | BloPunSum | T_PuntoSuministro | VARCHAR |
| Escalera | EscPunSum | T_PuntoSuministro | VARCHAR |
| Planta | PlaPunSum | T_PuntoSuministro | VARCHAR |
| Puerta | PuePunSum | T_PuntoSuministro | VARCHAR |
| CodigoPostal | CPLocSoc | T_PuntoSuministro | VARCHAR |
| Localidad | CodLoc | T_PuntoSuministro | INT (FK → T_Localidad) |
| Observaciones | ObsPunSum | T_PuntoSuministro | TEXT |
| Estado | EstPunSum | T_PuntoSuministro | TINYINT |

## Ejemplo de Uso

### Crear Nuevo Punto de Suministro

```excel
CodPunSum | CIF_Cliente | Nombre_Punto      | Tipo_Via | Nombre_Via | Numero | ... | Estado
----------|-------------|-------------------|----------|------------|--------|-----|-------
          | B12345678   | Oficina Central   | CALLE    | MAYOR      | 45     | ... | 1
```

### Actualizar Punto Existente

```excel
CodPunSum | CIF_Cliente | Nombre_Punto      | Tipo_Via | Nombre_Via | Numero | ... | Estado
----------|-------------|-------------------|----------|------------|--------|-----|-------
1523      | B12345678   | Oficina Renovada  | AVENIDA  | CASTELLANA | 120    | ... | 1
```

## Manejo de Errores

### Errores Comunes

1. **Cliente no encontrado**
   - Error: "Cliente con CIF B12345678 no encontrado"
   - Solución: Verificar que el cliente existe o crearlo previamente

2. **Localidad no encontrada**
   - Error: "Localidad con CP 28013 no encontrada"
   - Solución: Verificar el CP o crear la localidad

3. **Tipo de vía no encontrado**
   - Error: "Tipo de vía 'BOULEVARD' no encontrado"
   - Solución: Usar un tipo de vía válido del catálogo

4. **Código de punto no existe**
   - Error: "Punto de Suministro con código 9999 no encontrado para actualizar"
   - Solución: Verificar el código o dejarlo vacío para crear nuevo

### Estrategia de Rollback

- Si ocurre un error **crítico** (archivo corrupto, fallo de BD), se hace rollback de toda la transacción
- Los errores de **validación por fila** se reportan pero no detienen el proceso
- Las filas válidas se procesan correctamente
- Al final se obtiene un resumen completo con éxitos y errores

## Logs

El sistema registra:

- Inicio del procesamiento
- Cada punto creado/actualizado con su ID y número de fila
- Errores específicos por fila
- Resumen final del procesamiento

Ubicación: `storage/logs/laravel.log`

## Consideraciones

1. **Rendimiento**: Archivos de hasta 10MB (aprox. 10,000 registros)
2. **Tiempo**: El proceso puede tardar varios minutos para archivos grandes
3. **Transaccionalidad**: Usa transacciones de base de datos para garantizar integridad
4. **Auditoría**: Los campos `created_by` y `updated_by` se actualizan automáticamente con el usuario autenticado
5. **Timestamps**: Laravel maneja automáticamente `created_at` y `updated_at`

## Mejores Prácticas

1. **Siempre descargar la plantilla** para tener el formato correcto
2. **Eliminar instrucciones** antes de cargar el archivo
3. **Validar datos** en Excel antes de cargar (filtros, validación de datos)
4. **Probar con pocos registros** primero para validar el formato
5. **Revisar el reporte** de errores y corregir antes de volver a intentar
6. **Backup**: Hacer respaldo de datos antes de actualizaciones masivas

## Troubleshooting

### El archivo no se carga

- Verificar extensión (.xls, .xlsx, .csv)
- Verificar tamaño (máx. 10MB)
- Verificar que no esté corrupto

### Todos los registros fallan

- Verificar que eliminó las filas de instrucciones
- Verificar que los encabezados coinciden exactamente
- Revisar el formato de los datos

### Algunos registros fallan

- Revisar el detalle de errores en la respuesta
- Corregir los datos específicos
- Volver a cargar solo las filas que fallaron

## Endpoints

| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | `/configuracion/carga-masiva-puntos-suministro` | Vista del formulario |
| GET | `/configuracion/plantilla/puntos-suministro` | Descargar plantilla Excel |
| POST | `/configuracion/carga-masiva/puntos-suministro` | Procesar archivo |

## Permisos

- Usuario debe estar autenticado
- Middleware: `auth`
- El usuario autenticado se registra en `created_by` / `updated_by`