# Panel de Carga CSV

## Descripcion

El Panel de Carga CSV es una aplicacion web independiente que permite subir datos de medidores y lecturas mediante archivos CSV, sin necesidad de autenticacion. Esta diseñado para uso interno y facilita la carga masiva de datos.

## Acceso

- **URL**: https://panel.gestionrecursoshidricos.com
- **Puerto local**: 5174
- **Autenticacion**: No requerida

---

## Interfaz de Usuario

```
┌─────────────────────────────────────────────────────────────────┐
│  Panel de Carga de Datos - GRH                                  │
│  Sistema de Gestion de Recursos Hidricos                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────────┐  ┌─────────────────────────┐       │
│  │  TOMAS DE AGUA          │  │  LECTURAS               │       │
│  │  (Medidores)            │  │                         │       │
│  │                         │  │                         │       │
│  │  Campos requeridos:     │  │  Campos requeridos:     │       │
│  │  - serial_number        │  │  - meter_serial         │       │
│  │  - name                 │  │  - reading_value        │       │
│  │  - concentrator_serial  │  │                         │       │
│  │                         │  │                         │       │
│  │  [Descargar plantilla]  │  │  [Descargar plantilla]  │       │
│  │                         │  │                         │       │
│  │  ┌───────────────────┐  │  │  ┌───────────────────┐  │       │
│  │  │ Arrastra CSV aqui │  │  │  │ Arrastra CSV aqui │  │       │
│  │  │ o haz clic        │  │  │  │ o haz clic        │  │       │
│  │  └───────────────────┘  │  │  └───────────────────┘  │       │
│  │                         │  │                         │       │
│  │  [ SUBIR ARCHIVO ]      │  │  [ SUBIR ARCHIVO ]      │       │
│  └─────────────────────────┘  └─────────────────────────┘       │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Resultado de la carga:                                    │  │
│  │  Total: 100 | Insertados: 95 | Actualizados: 3 | Errores: 2│  │
│  │                                                            │  │
│  │  Errores:                                                  │  │
│  │  - Fila 15: Concentrador "XXX" no encontrado               │  │
│  │  - Fila 42: Valor de lectura invalido                      │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Carga de Medidores (Tomas de Agua)

### Formato del CSV

```csv
serial_number,name,concentrator_serial,area_name,location,meter_type,status,installation_date
MED001,Medidor 001,Mexico-GRH,ZONA A,Depto 101,LORA,ACTIVE,2024-01-15
MED002,Medidor 002,Mexico-GRH,ZONA A,Depto 102,LORA,ACTIVE,2024-01-15
MED003,Medidor 003,Mexico-GRH,ZONA B,Depto 201,LORAWAN,ACTIVE,2024-01-16
```

### Campos

| Campo | Requerido | Tipo | Descripcion | Ejemplo |
|-------|-----------|------|-------------|---------|
| serial_number | **Si** | Texto | Numero de serie unico del medidor | MED001 |
| name | **Si** | Texto | Nombre descriptivo | Medidor Depto 101 |
| concentrator_serial | **Si** | Texto | Serial del concentrador existente | Mexico-GRH |
| area_name | No | Texto | Nombre del area o zona | ZONA A |
| location | No | Texto | Ubicacion especifica | Depto 101, Piso 1 |
| meter_type | No | Texto | Tipo de medidor (default: LORA) | LORA |
| status | No | Texto | Estado inicial (default: ACTIVE) | ACTIVE |
| installation_date | No | Fecha | Fecha de instalacion (YYYY-MM-DD) | 2024-01-15 |

### Tipos de Medidor Validos
- `LORA` (default)
- `LORAWAN`
- `GRANDES CONSUMIDORES`
- `WATER`
- `GAS`
- `ELECTRIC`

### Estados Validos
- `ACTIVE` (default)
- `INACTIVE`
- `OFFLINE`
- `MAINTENANCE`
- `ERROR`

### Logica de Upsert

El sistema utiliza el campo `serial_number` como identificador unico:

- **Si el serial_number YA EXISTE**: Se **actualiza** el medidor con los nuevos valores
- **Si el serial_number NO EXISTE**: Se **crea** un nuevo medidor

Esto permite:
1. Agregar nuevos medidores
2. Actualizar medidores existentes
3. Hacer ambas operaciones en un solo archivo

### Ejemplo de CSV para Actualizacion

```csv
serial_number,name,concentrator_serial,area_name,location,meter_type,status,installation_date
MED001,Medidor Actualizado,Mexico-GRH,ZONA B,Nueva Ubicacion,LORA,MAINTENANCE,2024-01-15
```

Solo se actualizaran los campos proporcionados (no vacios).

---

## Carga de Lecturas

### Formato del CSV

```csv
meter_serial,reading_value,received_at,reading_type,battery_level,signal_strength
MED001,1234.56,2024-01-20 10:30:00,MANUAL,85,-45
MED002,567.89,2024-01-20 10:35:00,MANUAL,90,-42
MED003,890.12,2024-01-20 10:40:00,AUTOMATIC,78,-50
```

### Campos

| Campo | Requerido | Tipo | Descripcion | Ejemplo |
|-------|-----------|------|-------------|---------|
| meter_serial | **Si** | Texto | Serial del medidor existente | MED001 |
| reading_value | **Si** | Numero | Valor de la lectura | 1234.56 |
| received_at | No | Fecha/Hora | Fecha y hora de la lectura | 2024-01-20 10:30:00 |
| reading_type | No | Texto | Tipo de lectura (default: MANUAL) | MANUAL |
| battery_level | No | Entero | Nivel de bateria (0-100) | 85 |
| signal_strength | No | Entero | Intensidad de senal (dBm) | -45 |

### Tipos de Lectura Validos
- `AUTOMATIC` - Lectura automatica del dispositivo
- `MANUAL` - Lectura ingresada manualmente (default)
- `SCHEDULED` - Lectura programada

### Notas Importantes

1. **El medidor debe existir**: El `meter_serial` debe corresponder a un medidor ya registrado en el sistema
2. **Fecha por defecto**: Si no se especifica `received_at`, se usa la fecha/hora actual
3. **Actualizacion automatica**: Al insertar una lectura, se actualiza automaticamente el `last_reading_value` del medidor

---

## Proceso de Carga

### Paso 1: Descargar Plantilla
1. Haga clic en "Descargar plantilla CSV"
2. Se descargara un archivo con los encabezados correctos y una fila de ejemplo

### Paso 2: Preparar el Archivo
1. Abra la plantilla en Excel, Google Sheets o cualquier editor de texto
2. Complete los datos manteniendo el formato CSV
3. Guarde el archivo como `.csv` (valores separados por comas)

### Paso 3: Subir el Archivo
1. Arrastre el archivo al area de carga, o haga clic para seleccionarlo
2. Verifique que aparezca el nombre del archivo
3. Haga clic en "Subir Archivo"

### Paso 4: Revisar Resultados
El sistema mostrara:
- **Total**: Numero total de filas procesadas
- **Insertados**: Registros nuevos creados
- **Actualizados**: Registros existentes modificados
- **Errores**: Filas que no pudieron procesarse

### Errores Comunes

| Error | Causa | Solucion |
|-------|-------|----------|
| "serial_number es requerido" | Celda vacia | Agregar serial |
| "concentrator_serial es requerido" | Celda vacia | Agregar serial del concentrador |
| "Concentrador no encontrado" | Serial incorrecto | Verificar serial del concentrador |
| "Medidor no encontrado" | Serial de medidor incorrecto (lecturas) | Verificar que el medidor exista |
| "Valor de lectura invalido" | No es numero | Usar formato numerico (ej: 1234.56) |
| "Nivel de bateria invalido" | Fuera de rango | Usar valor entre 0 y 100 |

---

## Ejemplos Practicos

### Ejemplo 1: Cargar 3 Medidores Nuevos

```csv
serial_number,name,concentrator_serial,area_name,location,meter_type,status,installation_date
RES-001,Departamento 101,Mexico-GRH,TORRE A,Piso 1,LORA,ACTIVE,2024-01-15
RES-002,Departamento 102,Mexico-GRH,TORRE A,Piso 1,LORA,ACTIVE,2024-01-15
RES-003,Departamento 201,Mexico-GRH,TORRE A,Piso 2,LORA,ACTIVE,2024-01-15
```

### Ejemplo 2: Actualizar Ubicacion de Medidores

```csv
serial_number,name,concentrator_serial,area_name,location,meter_type,status,installation_date
RES-001,,Mexico-GRH,,Nueva Ubicacion,,,
RES-002,,Mexico-GRH,,Bodega 1,,,
```

Solo los campos con valor seran actualizados.

### Ejemplo 3: Cargar Lecturas Diarias

```csv
meter_serial,reading_value,received_at,reading_type,battery_level,signal_strength
RES-001,125.50,2024-01-20 08:00:00,MANUAL,95,-40
RES-002,89.75,2024-01-20 08:05:00,MANUAL,92,-38
RES-003,156.25,2024-01-20 08:10:00,MANUAL,88,-45
```

### Ejemplo 4: Cargar Lecturas sin Fecha (Usa Fecha Actual)

```csv
meter_serial,reading_value,received_at,reading_type,battery_level,signal_strength
RES-001,130.25,,,85,
RES-002,92.50,,,90,
RES-003,161.00,,,85,
```

---

## API Endpoints

El panel utiliza los siguientes endpoints de la API:

### Medidores

**Subir CSV:**
```http
POST /api/csv-upload/meters
Content-Type: multipart/form-data

file: archivo.csv
```

**Descargar plantilla:**
```http
GET /api/csv-upload/meters/template
```

### Lecturas

**Subir CSV:**
```http
POST /api/csv-upload/readings
Content-Type: multipart/form-data

file: archivo.csv
```

**Descargar plantilla:**
```http
GET /api/csv-upload/readings/template
```

---

## Configuracion Tecnica

### Variables de Entorno

Crear archivo `.env` en `upload-panel/`:

```env
VITE_API_URL=https://api.gestionrecursoshidricos.com/api
```

Para desarrollo local:
```env
VITE_API_URL=http://localhost:3000/api
```

### Ejecutar Localmente

```bash
cd upload-panel
npm install
npm run dev
```

El panel estara disponible en: http://localhost:5174

### Compilar para Produccion

```bash
npm run build
```

Los archivos compilados estaran en `upload-panel/dist/`