Files

Exteban08 da976b9003 Update all documentation for 3-level roles, organismos, and Histórico

Reflect current project state across all 8 docs: ADMIN/ORGANISMO_OPERADOR/OPERATOR
role hierarchy, scope filtering, organismos_operadores table, Histórico de Tomas
page, new SQL migrations, and updated API endpoints with auth requirements.

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

2026-02-09 10:44:16 +00:00

13 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:

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)