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>
This commit is contained in:
Exteban08
297
docs/UPLOAD_PANEL.md
Normal file
297
docs/UPLOAD_PANEL.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# 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/`
|
||||
Reference in New Issue
Block a user