# 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. [Historico de Tomas](#historico-de-tomas)
8. [Organismos Operadores](#organismos-operadores)
9. [Panel de Carga CSV](#panel-de-carga-csv)
10. [Notificaciones](#notificaciones)
11. [Administracion de Usuarios](#administracion-de-usuarios)
12. [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 (Jerarquia de 3 niveles)

| Rol | Permisos | Visibilidad |
|-----|----------|-------------|
| **ADMIN** | Acceso completo a todas las funciones | Ve todos los datos del sistema |
| **ORGANISMO_OPERADOR** | Gestion de usuarios y visualizacion de su organismo | Ve datos de los proyectos de su organismo |
| **OPERATOR** | Operacion de medidores de su proyecto | Ve datos de su proyecto asignado |

### Menu Lateral por Rol

| Seccion | ADMIN | ORGANISMO_OPERADOR | OPERATOR |
|---------|-------|-------------------|----------|
| Dashboard | Si | Si | Si |
| Project Management | Si | Si | Si |
| Users Management | Si | Si | No |
| Organismos Operadores | Si | No | No |
| Conectores | Si | No | No |
| Analytics | Si | Si | No |

---

## 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

---

## Historico de Tomas

*Disponible para todos los roles. Cada rol solo ve los medidores de su scope.*

### Acceder al Historico
1. Navegue a **Historico** en la seccion "Project Management" del menu lateral
2. Vera un selector de medidor y un estado vacio inicial

### Seleccionar Medidor
1. Haga clic en el campo de busqueda
2. Escriba para filtrar por:
   - Nombre del medidor
   - Numero de serie
   - Ubicacion
   - Cuenta CESPT
   - Clave catastral
3. Seleccione el medidor del dropdown

### Informacion del Medidor
Al seleccionar un medidor se muestra:
- **Tarjeta de informacion:** Serial, nombre, proyecto, ubicacion, tipo, estado, ultima lectura
- **Cards de consumo:**
  - **Consumo Actual:** Lectura mas reciente (consumo diario)
  - **Consumo Pasado:** Lectura del primer dia del mes anterior
  - **Diferencial:** Diferencia entre actual y pasado (con indicador de tendencia)

### Filtrar por Fechas
1. Use los campos "Desde" y "Hasta" para definir un rango
2. Los datos se actualizan automaticamente
3. Use el boton "Limpiar" para remover los filtros

### Grafica de Consumo
- Grafica de area con gradiente azul
- Eje X: fechas, Eje Y: valor de lectura (m3)
- El rango del eje Y se ajusta automaticamente a los datos

### Tabla de Lecturas
- Columnas: Fecha/Hora, Lectura (m3), Tipo, Bateria, Senal
- Paginacion configurable: 10, 20 o 50 registros por pagina
- Indicadores visuales de bateria y senal

### Exportar CSV
1. Haga clic en el boton **"Exportar CSV"** en el encabezado
2. Se descargara un archivo `historico_{serial}_{fecha}.csv`

---

## Organismos Operadores

*Solo disponible para usuarios con rol ADMIN*

### Ver Organismos
1. Haga clic en **"Organismos Operadores"** en el menu lateral
2. Vera la tabla con todos los organismos registrados

### Crear Organismo
1. Haga clic en **"Nuevo Organismo"**
2. Complete los campos:
   - **Nombre:** Nombre del organismo (ej: CESPT Tijuana)
   - **Codigo:** Codigo unico (ej: CESPT-TJ)
   - **Contacto:** Nombre de la persona de contacto
   - **Email:** Correo electronico de contacto
   - **Telefono:** Numero de telefono
   - **Estado:** Activo/Inactivo
3. Haga clic en **"Guardar"**

### Editar Organismo
1. Haga clic en el icono de edicion del organismo
2. Modifique los campos necesarios
3. Haga clic en **"Guardar"**

### Vincular Proyectos y Usuarios
- Los proyectos se vinculan a un organismo via el campo `organismo_operador_id` en la pagina de Proyectos
- Los usuarios con rol ORGANISMO_OPERADOR se vinculan a un organismo via la pagina de Usuarios

---

## 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

*Disponible para ADMIN (ve todos) y ORGANISMO_OPERADOR (ve los de su organismo)*

### Ver Usuarios
1. Navegue a **Usuarios** en el menu lateral
2. Vera la lista de usuarios filtrada segun su rol

### 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, ORGANISMO_OPERADOR, u OPERATOR
   - **Organismo Operador**: Para ORGANISMO_OPERADOR - organismo asignado
   - **Proyecto**: 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`