consultoria-as/GRH
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da976b900361387de3634c348f980b2c147bf25f
GRH/docs/UPLOAD_PANEL.md
Exteban08 71623d667f Add complete project documentation 
Documentation includes:
- README.md: Project overview and architecture
- API.md: Complete API reference with endpoints
- MANUAL_USUARIO.md: User manual in Spanish
- INSTALACION.md: Installation and deployment guide
- ARQUITECTURA.md: Architecture and database schema
- UPLOAD_PANEL.md: CSV upload panel documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 11:27:51 +00:00

11 KiB
Raw Blame History

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

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

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

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

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

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

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

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)

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:

POST /api/csv-upload/meters
Content-Type: multipart/form-data

file: archivo.csv

Descargar plantilla:

GET /api/csv-upload/meters/template

Lecturas

Subir CSV:

POST /api/csv-upload/readings
Content-Type: multipart/form-data

file: archivo.csv

Descargar plantilla:

GET /api/csv-upload/readings/template

Configuracion Tecnica

Variables de Entorno

Crear archivo .env en upload-panel/:

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

Para desarrollo local:

VITE_API_URL=http://localhost:3000/api

Ejecutar Localmente

cd upload-panel
npm install
npm run dev

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

Compilar para Produccion

npm run build

Los archivos compilados estaran en upload-panel/dist/

Reference in New Issue View Git Blame Copy Permalink