# Estado Actual del Proyecto GRH

**Fecha:** 2026-02-09
**Ultima actualizacion:** Documentacion actualizada para reflejar el estado completo del proyecto

---

## Resumen del Proyecto

Sistema full-stack de gestion de medidores de agua con:
- **Frontend:** React 18 + TypeScript + Vite (puerto 5173)
- **Backend:** Node.js + Express + TypeScript (puerto 3000)
- **Base de datos:** PostgreSQL
- **Upload Panel:** App separada para carga CSV masiva

### Jerarquia de datos:
```
Organismos Operadores → Projects → Concentrators → Meters → Readings
                                 → Gateways → Devices ↗
```

### URLs de produccion:
- **Frontend:** https://sistema.gestionrecursoshidricos.com
- **Backend:** https://api.gestionrecursoshidricos.com

### Repositorios:
- **Gitea:** https://git.consultoria-as.com/consultoria-as/GRH
- **GitHub:** git@github.com:luanngel/water-project.git

---

## Arquitectura del Sistema

```
┌─────────────────────────────────────────────────────────────┐
│                      FRONTEND (React SPA)                    │
│                    http://localhost:5173                      │
├─────────────────────────────────────────────────────────────┤
│  React 18 + TypeScript + Vite                                │
│  Tailwind CSS (paleta Zinc) + Material-UI 7                  │
│  Recharts (graficos) + Leaflet (mapas)                       │
│  Cliente API con JWT + refresh automatico                    │
│  Dark mode / Light mode / System                             │
└──────────────────────────┬──────────────────────────────────┘
                           │ REST API + JWT Bearer
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                      BACKEND (Express)                       │
│                    http://localhost:3000                      │
├─────────────────────────────────────────────────────────────┤
│  Express + TypeScript + Zod (validacion)                     │
│  JWT access (15m) + refresh (7d) tokens                      │
│  17 archivos de rutas, 18 servicios                          │
│  Helmet, CORS, Bcrypt, Winston logging                       │
│  node-cron (deteccion flujo negativo)                        │
│  Multer + XLSX (carga masiva)                                │
│  Webhooks TTS (The Things Stack / LoRaWAN)                   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                      PostgreSQL                              │
├─────────────────────────────────────────────────────────────┤
│  11 tablas: roles, users, organismos_operadores, projects,    │
│  concentrators, gateways, devices, meters, meter_readings,   │
│  tts_uplink_logs, refresh_tokens                             │
│  2 vistas: meter_stats_by_project, device_status_summary     │
│  9 archivos SQL (schema + 8 migraciones)                     │
│  Triggers de updated_at, indices compuestos, JSONB           │
└─────────────────────────────────────────────────────────────┘
```

---

## Funcionalidades Implementadas

### 1. Autenticacion y Autorizacion
- Login con JWT: access token (15 min) + refresh token (7 dias)
- Refresh automatico de tokens en el cliente (cola de peticiones)
- **Jerarquia de 3 niveles:** ADMIN → ORGANISMO_OPERADOR → OPERATOR
- Scope filtering en todos los servicios backend (via `scope.ts`)
- JWT incluye: userId, roleId, roleName, projectId, organismoOperadorId
- Hash de contrasenas con bcrypt (12 rounds)
- Proteccion de rutas por rol en backend y frontend
- authenticateToken requerido en todas las rutas GET de medidores

### 2. Dashboard (Home)
- KPIs: Total medidores, medidores activos, consumo promedio, alertas
- Grafico de barras: Medidores por proyecto (Recharts)
- Selector de organismos operadores (filtrado por rol)
- Historial reciente de actividades
- Panel de ultimas alertas
- Soporte por rol (ADMIN, ORGANISMO_OPERADOR, OPERATOR)

### 3. Gestion de Proyectos
- CRUD completo
- Estados: ACTIVE, INACTIVE, COMPLETED
- Estadisticas por proyecto (medidores, lecturas, areas)

### 4. Gestion de Concentradores
- CRUD completo
- Vinculados a proyectos
- Estado: ACTIVE, INACTIVE, OFFLINE, MAINTENANCE, ERROR
- IP, firmware, ultima comunicacion

### 5. Gestion de Medidores
- CRUD completo con tabla, sidebar de detalle y modal de edicion
- Tipos de medidor: WATER, GAS, ELECTRIC
- Protocolos: GENERAL, LORA, LORAWAN
- Estados: ACTIVE, INACTIVE, OFFLINE, MAINTENANCE, ERROR
- Carga masiva via Excel y CSV
- Busqueda, filtros por proyecto/tipo/estado
- Ultima lectura visible en tabla
- Campos extendidos: protocolo, MAC, gateway, voltaje, senal, flujo, coordenadas
- Tipos adicionales: LORA, LORAWAN, GRANDES CONSUMIDORES

### 6. Consumo y Lecturas
- CRUD de lecturas
- Tipos: AUTOMATIC, MANUAL, SCHEDULED
- Carga masiva via Excel y CSV
- Filtros por proyecto, medidor, rango de fechas
- Resumen de consumo (total, promedio, min, max)
- Indicadores de bateria y senal
- Exportacion

### 7. Analytics
- **Mapa:** Visualizacion de medidores con coordenadas en mapa Leaflet interactivo
- **Reportes:** Dashboard de estadisticas y reportes de consumo
- **Servidor:** Metricas del sistema (CPU, memoria, uptime, requests)

### 8. Conectores Externos
- **SH-Meters:** Integracion con sistema de medidores SH
- **XMeters:** Integracion con sistema XMeters
- **The Things Stack (TTS):** Webhooks LoRaWAN para uplink, join y downlink/ack
- Sincronizacion programada a las 9:00 AM
- Seguimiento de ultima conexion y estado

### 9. Gestion de Organismos Operadores (NUEVO)
- CRUD completo (solo ADMIN)
- Tabla: organismos_operadores (nombre, codigo, contacto, telefono, estado)
- Vinculacion con proyectos (projects.organismo_operador_id)
- Vinculacion con usuarios (users.organismo_operador_id)
- Pagina frontend: OrganismosPage.tsx

### 10. Gestion de Usuarios
- CRUD completo (ADMIN y ORGANISMO_OPERADOR)
- Asignacion de roles, proyecto y organismo operador
- Filtrado por scope: ADMIN ve todos, ORGANISMO ve los de su organismo
- Estados: activo/inactivo
- Cambio de contrasena

### 11. Gestion de Roles
- 3 roles predefinidos: ADMIN, ORGANISMO_OPERADOR, OPERATOR
- Permisos granulares JSONB por recurso
- CRUD de roles (solo ADMIN)
- Conteo de usuarios por rol

### 12. Historico de Tomas (NUEVO)
- Pagina dedicada para consultar historial de lecturas por medidor
- Selector de medidor con busqueda por nombre, serial, ubicacion, cuenta CESPT y clave catastral
- Tarjeta de informacion del medidor seleccionado
- Cards de consumo: Consumo Actual (diario), Consumo Pasado (primer dia del mes anterior), Diferencial
- Grafica AreaChart (Recharts) con gradiente, eje Y ajustado al rango de datos
- Tabla paginada de lecturas (10/20/50 por pagina)
- Filtros de rango de fechas
- Exportacion CSV
- Filtrado por scope: cada rol solo ve los medidores asignados

### 13. Auditoria
- Registro automatico de todas las acciones via middleware
- Visor de logs con filtros (solo ADMIN)
- Actividad del usuario actual (todos los roles)
- Estadisticas de auditoria
- Busqueda por registro especifico

### 14. Notificaciones
- Notificaciones in-app
- Conteo de no leidas en tiempo real
- Marcar como leida (individual y masiva)
- Generacion automatica por flujo negativo (cron job)
- Dropdown en TopMenu

### 15. Dark Mode
- Soporte completo: Dark / Light / System
- Paleta Zinc de Tailwind
- Aplicado a todas las paginas, modales, tablas, formularios
- Persistencia en localStorage

### 16. Upload Panel
- Aplicacion separada (`upload-panel/`) para carga CSV
- Dropzone para archivos
- Carga de medidores (upsert)
- Carga de lecturas
- Descarga de plantillas
- Visualizacion de resultados y errores

---

## Carga Masiva

### Medidores (Excel / CSV)
Columnas requeridas:
- `serial_number` - Numero de serie del medidor (unico)
- `name` - Nombre del medidor
- `concentrator_serial` - Serial del concentrador existente

Columnas opcionales:
- `meter_id` - ID del medidor
- `location` - Ubicacion
- `type` - LORA, LORAWAN, GRANDES (default: LORA)
- `status` - ACTIVE, INACTIVE, etc. (default: ACTIVE)
- `installation_date` - Fecha de instalacion (YYYY-MM-DD)

Mapeos automaticos de columnas: `device_s/n` → `serial_number`, `device_name` → `name`, `device_status` → `status`, etc.

Normalizacion de status: "Installed" → ACTIVE, "New_LoRa" → ACTIVE, "Enabled" → ACTIVE, "Disabled" → INACTIVE.

### Lecturas (Excel / CSV)
Columnas requeridas:
- `meter_serial` - Serial del medidor existente
- `reading_value` - Valor de la lectura

Columnas opcionales:
- `reading_type` - AUTOMATIC, MANUAL, SCHEDULED (default: MANUAL)
- `received_at` - Fecha/hora (default: ahora)
- `battery_level` - Nivel de bateria (%)
- `signal_strength` - Intensidad de senal (dBm)

---

## Datos en Base de Datos

### Proyectos
- ADAMANT
- OLE
- LUZIA
- ATELIER

### Concentradores
| Serial | Nombre | Proyecto |
|--------|--------|----------|
| 2024072612 | Adamant | ADAMANT |
| 2024030601 | OLE | OLE |
| 2024030402 | LUZIA | LUZIA |
| 2024072602 | ATELIER | ATELIER |

### Medidores
- ADAMANT: 201 medidores
- OLE: 5 medidores

---

## Historial de Correcciones

### 2026-01-23: Fix pantalla blanca y carga masiva
1. **Fix `.toFixed()` con strings** - PostgreSQL devuelve DECIMAL como string. Se envuelve con `Number()`.
2. **Fix modal de carga masiva** - Separar recarga de datos del cierre del modal.
3. **Fix fechas invalidas en carga masiva** - Validacion de formato con regex + mapeos de columnas + normalizacion de status.

### 2026-02-03: Dark mode, Analytics, Conectores, CSV Upload
- Implementacion completa de dark mode con paleta Zinc
- Seccion Analytics: mapa, reportes, servidor
- Seccion Conectores: SH-Meters, XMeters, TTS
- Toggle dark/light theme
- Panel CSV para carga masiva
- Nuevos tipos de medidor: LORA, LORAWAN, GRANDES CONSUMIDORES
- Documentacion completa del proyecto

### 2026-02-04: Favicon y conectores
- Actualizacion de favicon
- Mejoras en tiempo de ultima conexion de conectores
- Plan de implementacion para rol ORGANISMOS_OPERADORES

### 2026-02-09: Organismos Operadores + Historico de Tomas
- Implementacion completa del rol ORGANISMO_OPERADOR (jerarquia de 3 niveles)
- Nueva tabla `organismos_operadores` con migracion SQL
- Scope filtering en todos los servicios backend (meter, reading, project, user, concentrator, notification)
- JWT actualizado con `organismoOperadorId`
- Pagina OrganismosPage.tsx para gestion de organismos (ADMIN)
- Pagina HistoricoPage.tsx para consulta de historial de lecturas por medidor
- Cards de consumo: Actual, Pasado, Diferencial
- Grafica AreaChart con gradiente y eje Y ajustado
- Busqueda por cuenta CESPT y clave catastral
- authenticateToken en rutas GET de medidores
- Sidebar con visibilidad de 3 niveles
- UsersPage actualizada con asignacion de organismo
- ProjectsPage con campo organismo_operador_id

### 2026-02-05: Sincronizacion de conectores
- Cambio de hora de sincronizacion de 2:00 AM a 9:00 AM

---

## Comandos Utiles

```bash
# Iniciar backend (desarrollo)
cd /home/GRH/water-project/water-api
npm run dev

# Iniciar frontend (desarrollo)
cd /home/GRH/water-project
npm run dev

# Iniciar upload panel (desarrollo)
cd /home/GRH/water-project/upload-panel
npm run dev

# Compilar backend para produccion
cd /home/GRH/water-project/water-api
npm run build && npm run start

# Compilar frontend para produccion
cd /home/GRH/water-project
npm run build

# Ejecutar schema de base de datos
psql -d water_project -f water-api/sql/schema.sql
```

---

## Proximos Pasos Sugeridos

1. **Reportes PDF** - Generacion y descarga de reportes en PDF
2. **Tests** - Suite de tests con Vitest (frontend) y Supertest (backend)
3. **CI/CD** - Pipeline de integracion continua
4. **Docker** - Containerizacion del proyecto completo
5. **Alertas avanzadas** - Configuracion de umbrales y notificaciones por email