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
parent 6118ec2813
commit 71623d667f
6 changed files with 2230 additions and 0 deletions
--- a/docs/MANUAL_USUARIO.md
+++ b/docs/MANUAL_USUARIO.md
@@ -0,0 +1,358 @@
+# Manual de Usuario - Sistema GRH
+
+## Indice
+
+1. [Acceso al Sistema](#acceso-al-sistema)
+2. [Dashboard Principal](#dashboard-principal)
+3. [Gestion de Proyectos](#gestion-de-proyectos)
+4. [Gestion de Concentradores](#gestion-de-concentradores)
+5. [Gestion de Medidores](#gestion-de-medidores)
+6. [Consumo y Lecturas](#consumo-y-lecturas)
+7. [Panel de Carga CSV](#panel-de-carga-csv)
+8. [Notificaciones](#notificaciones)
+9. [Administracion de Usuarios](#administracion-de-usuarios)
+10. [Auditoria](#auditoria)
+
+---
+
+## Acceso al Sistema
+
+### URL de Acceso
+- **Sistema Principal**: https://sistema.gestionrecursoshidricos.com
+- **Panel de Carga CSV**: https://panel.gestionrecursoshidricos.com
+
+### Inicio de Sesion
+
+1. Ingrese a la URL del sistema
+2. Introduzca su correo electronico
+3. Introduzca su contraseña
+4. Haga clic en "Iniciar Sesion"
+
+### Roles de Usuario
+
+| Rol | Permisos |
+|-----|----------|
+| **ADMIN** | Acceso completo a todas las funciones |
+| **OPERATOR** | Gestion de medidores y lecturas de su proyecto asignado |
+| **VIEWER** | Solo visualizacion de datos |
+
+---
+
+## Dashboard Principal
+
+El dashboard muestra un resumen general del sistema:
+
+### Indicadores Clave (KPIs)
+- **Total de Medidores**: Cantidad total de medidores registrados
+- **Lecturas del Dia**: Numero de lecturas recibidas hoy
+- **Alertas Activas**: Notificaciones pendientes de atencion
+- **Proyectos Activos**: Proyectos en estado activo
+
+### Alertas Recientes
+Lista de las ultimas alertas del sistema, incluyendo:
+- Flujo negativo detectado
+- Medidores sin comunicacion
+- Alertas de mantenimiento
+
+### Actividad Reciente
+Historial de las ultimas acciones realizadas en el sistema.
+
+---
+
+## Gestion de Proyectos
+
+### Ver Proyectos
+1. Navegue a **Proyectos** en el menu lateral
+2. Vera la lista de todos los proyectos
+3. Use los filtros para buscar proyectos especificos
+
+### Crear Proyecto
+1. Haga clic en **"Nuevo Proyecto"**
+2. Complete los campos:
+   - **Nombre**: Nombre del proyecto (requerido)
+   - **Descripcion**: Descripcion detallada
+   - **Area**: Nombre del area geografica
+   - **Ubicacion**: Direccion o coordenadas
+   - **Tipo de Medidor**: Tipo por defecto para el proyecto
+3. Haga clic en **"Guardar"**
+
+### Editar Proyecto
+1. Haga clic en el icono de edicion del proyecto
+2. Modifique los campos necesarios
+3. Haga clic en **"Guardar"**
+
+### Estadisticas del Proyecto
+- Haga clic en un proyecto para ver sus estadisticas
+- Incluye: total de medidores, lecturas, consumo promedio
+
+---
+
+## Gestion de Concentradores
+
+Los concentradores son dispositivos que agrupan multiples medidores.
+
+### Ver Concentradores
+1. Navegue a **Concentradores** en el menu lateral
+2. Filtre por proyecto si es necesario
+
+### Crear Concentrador
+1. Haga clic en **"Nuevo Concentrador"**
+2. Complete los campos:
+   - **Serial**: Numero de serie unico (requerido)
+   - **Nombre**: Nombre descriptivo (requerido)
+   - **Proyecto**: Proyecto al que pertenece (requerido)
+   - **Ubicacion**: Ubicacion fisica
+   - **IP**: Direccion IP (opcional)
+3. Haga clic en **"Guardar"**
+
+### Estados del Concentrador
+| Estado | Descripcion |
+|--------|-------------|
+| ACTIVE | Funcionando correctamente |
+| INACTIVE | Desactivado manualmente |
+| OFFLINE | Sin comunicacion |
+| MAINTENANCE | En mantenimiento |
+| ERROR | Con fallas |
+
+---
+
+## Gestion de Medidores
+
+### Ver Medidores
+1. Navegue a **Medidores** en el menu lateral
+2. Use los filtros disponibles:
+   - Por proyecto
+   - Por concentrador
+   - Por estado
+   - Por tipo
+   - Busqueda por serial/nombre
+
+### Crear Medidor Individual
+1. Haga clic en **"Nuevo Medidor"**
+2. Complete los campos:
+   - **Serial**: Numero de serie unico (requerido)
+   - **Nombre**: Nombre descriptivo (requerido)
+   - **Concentrador**: Concentrador asociado (requerido)
+   - **Area**: Nombre del area
+   - **Ubicacion**: Ubicacion especifica (ej: "Depto 101")
+   - **Tipo**: LORA, LORAWAN, o GRANDES CONSUMIDORES
+   - **Estado**: Estado inicial
+   - **Fecha Instalacion**: Fecha de instalacion
+3. Haga clic en **"Guardar"**
+
+### Carga Masiva de Medidores (Excel)
+1. Haga clic en **"Carga Masiva"**
+2. Descargue la plantilla Excel
+3. Complete la plantilla con los datos
+4. Suba el archivo Excel
+5. Revise los resultados
+
+### Tipos de Medidor
+| Tipo | Descripcion |
+|------|-------------|
+| LORA | Medidores con comunicacion LoRa |
+| LORAWAN | Medidores LoRaWAN |
+| GRANDES CONSUMIDORES | Medidores de alto consumo |
+
+### Ver Detalle del Medidor
+- Haga clic en un medidor para ver:
+  - Informacion general
+  - Ultima lectura
+  - Historial de lecturas
+  - Graficos de consumo
+
+---
+
+## Consumo y Lecturas
+
+### Ver Lecturas
+1. Navegue a **Consumo** en el menu lateral
+2. Filtre por:
+   - Proyecto
+   - Concentrador
+   - Medidor especifico
+   - Rango de fechas
+   - Tipo de lectura
+
+### Tipos de Lectura
+| Tipo | Descripcion |
+|------|-------------|
+| AUTOMATIC | Lectura automatica del dispositivo |
+| MANUAL | Lectura ingresada manualmente |
+| SCHEDULED | Lectura programada |
+
+### Crear Lectura Manual
+1. Haga clic en **"Nueva Lectura"**
+2. Seleccione el medidor
+3. Ingrese el valor de lectura
+4. Opcionalmente ingrese:
+   - Nivel de bateria (0-100)
+   - Intensidad de senal (dBm)
+5. Haga clic en **"Guardar"**
+
+### Carga Masiva de Lecturas (Excel)
+1. Haga clic en **"Carga Masiva"**
+2. Descargue la plantilla
+3. Complete con los datos
+4. Suba el archivo
+5. Revise los resultados
+
+### Graficos de Consumo
+- Visualice el consumo historico en graficos
+- Filtre por periodo de tiempo
+- Exporte datos si es necesario
+
+---
+
+## Panel de Carga CSV
+
+El panel de carga CSV permite subir datos de medidores y lecturas sin necesidad de autenticacion.
+
+### Acceso
+- URL: https://panel.gestionrecursoshidricos.com
+
+### Cargar Medidores
+
+1. En la seccion **"Tomas de Agua"**
+2. Descargue la plantilla CSV haciendo clic en "Descargar plantilla CSV"
+3. Complete el archivo con los datos:
+
+```csv
+serial_number,name,concentrator_serial,area_name,location,meter_type,status,installation_date
+MED001,Medidor 1,Mexico-GRH,ZONA A,Depto 101,LORA,ACTIVE,2024-01-15
+MED002,Medidor 2,Mexico-GRH,ZONA A,Depto 102,LORA,ACTIVE,2024-01-15
+```
+
+**Campos:**
+| Campo | Requerido | Descripcion |
+|-------|-----------|-------------|
+| serial_number | Si | Numero de serie unico del medidor |
+| name | Si | Nombre descriptivo |
+| concentrator_serial | Si | Serial del concentrador existente |
+| area_name | No | Nombre del area |
+| location | No | Ubicacion especifica |
+| meter_type | No | LORA (default), LORAWAN, GRANDES CONSUMIDORES |
+| status | No | ACTIVE (default), INACTIVE, MAINTENANCE |
+| installation_date | No | Fecha YYYY-MM-DD |
+
+4. Arrastre el archivo o haga clic para seleccionarlo
+5. Haga clic en **"Subir Archivo"**
+6. Revise los resultados:
+   - Registros insertados (nuevos)
+   - Registros actualizados (existentes)
+   - Errores encontrados
+
+**Logica de Upsert:**
+- Si el `serial_number` ya existe: se **actualiza** el medidor
+- Si el `serial_number` no existe: se **crea** un nuevo medidor
+
+### Cargar Lecturas
+
+1. En la seccion **"Lecturas"**
+2. Descargue la plantilla CSV
+3. Complete el archivo:
+
+```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
+```
+
+**Campos:**
+| Campo | Requerido | Descripcion |
+|-------|-----------|-------------|
+| meter_serial | Si | Serial del medidor existente |
+| reading_value | Si | Valor numerico de la lectura |
+| received_at | No | Fecha/hora (default: ahora) |
+| reading_type | No | AUTOMATIC, MANUAL, SCHEDULED |
+| battery_level | No | Nivel de bateria 0-100 |
+| signal_strength | No | Intensidad de senal en dBm |
+
+4. Suba el archivo
+5. Revise los resultados
+
+**Nota:** El medidor debe existir previamente para poder cargar lecturas.
+
+---
+
+## Notificaciones
+
+### Ver Notificaciones
+1. Haga clic en el icono de campana en la barra superior
+2. Vera las notificaciones recientes
+
+### Tipos de Notificacion
+| Tipo | Descripcion |
+|------|-------------|
+| NEGATIVE_FLOW | Flujo negativo detectado en un medidor |
+| SYSTEM_ALERT | Alerta general del sistema |
+| MAINTENANCE | Recordatorio de mantenimiento |
+
+### Gestionar Notificaciones
+- **Marcar como leida**: Haga clic en la notificacion
+- **Marcar todas como leidas**: Boton en la parte superior
+- **Eliminar**: Icono de eliminar en cada notificacion
+
+---
+
+## Administracion de Usuarios
+
+*Solo disponible para usuarios con rol ADMIN*
+
+### Ver Usuarios
+1. Navegue a **Usuarios** en el menu lateral
+2. Vera la lista de todos los usuarios
+
+### Crear Usuario
+1. Haga clic en **"Nuevo Usuario"**
+2. Complete los campos:
+   - **Email**: Correo electronico (sera el usuario de login)
+   - **Nombre**: Nombre completo
+   - **Contraseña**: Contraseña inicial
+   - **Rol**: ADMIN, OPERATOR, o VIEWER
+   - **Proyecto**: Solo para OPERATOR - proyecto asignado
+3. Haga clic en **"Guardar"**
+
+### Editar Usuario
+1. Haga clic en el icono de edicion
+2. Modifique los campos necesarios
+3. Haga clic en **"Guardar"**
+
+### Desactivar Usuario
+1. Haga clic en el icono de desactivar
+2. Confirme la accion
+- El usuario no podra iniciar sesion pero sus datos se conservan
+
+---
+
+## Auditoria
+
+*Solo disponible para usuarios con rol ADMIN*
+
+### Ver Logs de Auditoria
+1. Navegue a **Auditoria** en el menu lateral
+2. Vera el historial de acciones del sistema
+
+### Filtros Disponibles
+- Por usuario
+- Por accion (CREATE, UPDATE, DELETE, LOGIN, etc.)
+- Por tabla/entidad
+- Por rango de fechas
+
+### Informacion del Log
+Cada registro muestra:
+- Fecha y hora
+- Usuario que realizo la accion
+- Tipo de accion
+- Entidad afectada
+- Valores anteriores y nuevos (para updates)
+- Direccion IP
+- Resultado (exito/error)
+
+---
+
+## Soporte
+
+Para soporte tecnico o reportar problemas:
+- Contacte al administrador del sistema
+- Revise la documentacion tecnica en `/docs`