Files

Exteban08 61dafa83ac Update all project documentation to reflect current state

Rewrite README.md, DOCUMENTATION.md, ESTADO_ACTUAL.md and CAMBIOS_SESION.md
to accurately document the full-stack architecture, all modules, API endpoints,
JWT auth, database schema, and features added in February 2026.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-09 07:48:54 +00:00

11 KiB

Raw Blame History

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:

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                              │
├─────────────────────────────────────────────────────────────┤
│  10 tablas: roles, users, projects, concentrators,           │
│  gateways, devices, meters, meter_readings,                  │
│  tts_uplink_logs, refresh_tokens                             │
│  2 vistas: meter_stats_by_project, device_status_summary     │
│  7 archivos SQL (schema + 6 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)
3 roles con permisos JSONB: ADMIN, OPERATOR, VIEWER
Relacion usuario-proyecto para acceso por scope
Hash de contrasenas con bcrypt (12 rounds)
Proteccion de rutas por rol en backend y frontend

2. Dashboard (Home)

KPIs: Total medidores, medidores activos, consumo promedio, alertas
Grafico de barras: Medidores por proyecto (Recharts)
Selector de organismos operadores (CESPT Tijuana, Tecate, Mexicali)
Historial reciente de actividades
Panel de ultimas alertas
Soporte por rol (ADMIN, OPERATOR, VIEWER)

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 Usuarios

CRUD completo (solo ADMIN)
Asignacion de roles
Asignacion de proyecto
Estados: activo/inactivo
Cambio de contrasena

10. Gestion de Roles

3 roles predefinidos: ADMIN, OPERATOR, VIEWER
Permisos granulares JSONB por recurso
CRUD de roles (solo ADMIN)
Conteo de usuarios por rol

11. 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

12. 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

13. Dark Mode

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

14. 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)