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
parent 613fb2d787
commit da976b9003
8 changed files with 497 additions and 107 deletions
--- a/DOCUMENTATION.md
+++ b/DOCUMENTATION.md
@@ -38,7 +38,7 @@ El proyecto es una aplicacion **full-stack** con tres componentes principales:
 │  Express Routes → Controllers → Services → PostgreSQL        │
 ├─────────────────────────────────────────────────────────────┤
 │                  Capa de Datos                                │
-│  PostgreSQL: 10 tablas, 2 vistas, triggers, indices          │
+│  PostgreSQL: 11 tablas, 2 vistas, triggers, indices          │
 ├─────────────────────────────────────────────────────────────┤
 │                  Integraciones Externas                       │
 │  The Things Stack (LoRaWAN), SH-Meters, XMeters              │
@@ -67,7 +67,8 @@ export type Page =
  | "home" | "projects" | "meters" | "concentrators"
  | "consumption" | "auditoria" | "users" | "roles"
  | "sh-meters" | "xmeters" | "tts"
-  | "analytics-map" | "analytics-reports" | "analytics-server";
+  | "analytics-map" | "analytics-reports" | "analytics-server"
+  | "organismos" | "historico";
 ```

 La navegacion es **state-based** (sin React Router). El estado `currentPage` determina que pagina se renderiza.
@@ -91,6 +92,8 @@ La navegacion es **state-based** (sin React Router). El estado `currentPage` det
 | SH-Meters | `conectores/SHMetersPage.tsx` | Conector SH-Meters |
 | XMeters | `conectores/XMetersPage.tsx` | Conector XMeters |
 | TTS | `conectores/TTSPage.tsx` | Conector The Things Stack |
+| Organismos | `OrganismosPage.tsx` | Gestion de organismos operadores (ADMIN) |
+| Historico | `historico/HistoricoPage.tsx` | Historico de lecturas por medidor con grafica, estadisticas y tabla |

 ### Componentes de Layout

@@ -98,7 +101,10 @@ La navegacion es **state-based** (sin React Router). El estado `currentPage` det
 - Menu lateral colapsable con hover expansion
 - Soporte para pin/unpin
 - Menu jerarquico con submenus (Analytics, Conectores)
- Indicadores visuales de pagina activa
+- Visibilidad por rol de 3 niveles:
+  - ADMIN: ve todo (incluye Organismos, Conectores, Auditoria)
+  - ORGANISMO_OPERADOR: ve Dashboard, Project Management, Users, Analytics
+  - OPERATOR: ve Dashboard y Project Management

 **TopMenu.tsx**
 - Breadcrumb de navegacion
@@ -125,18 +131,22 @@ water-api/src/
 ├── config/
 │   ├── index.ts             # Variables de entorno centralizadas
 │   └── database.ts          # Pool de conexiones pg
-├── routes/                  # Definicion de rutas (17 archivos)
+├── routes/                  # Definicion de rutas (18 archivos)
+│   └── organismo-operador.routes.ts  # Rutas CRUD organismos
 ├── controllers/             # Controladores HTTP
-├── services/                # Logica de negocio (18 modulos)
+│   └── organismo-operador.controller.ts
+├── services/                # Logica de negocio (19 modulos)
+│   └── organismo-operador.service.ts
 ├── middleware/
-│   ├── auth.middleware.ts   # Verificacion JWT + extraccion de rol
+│   ├── auth.middleware.ts   # Verificacion JWT + extraccion de rol + requireRole
 │   ├── audit.middleware.ts  # Auto-logging de acciones
 │   └── ttsWebhook.middleware.ts  # Verificacion de secreto webhook
 ├── validators/              # Schemas de validacion Zod
 ├── utils/
-│   ├── jwt.ts               # sign/verify de tokens
+│   ├── jwt.ts               # sign/verify de tokens (incluye organismoOperadorId)
 │   ├── password.ts          # hash/compare con bcrypt
-│   └── logger.ts            # Winston con formato timestamp
+│   ├── logger.ts            # Winston con formato timestamp
+│   └── scope.ts             # Filtrado por scope de rol (ADMIN/ORGANISMO/OPERATOR)
 ├── jobs/
 │   └── negativeFlowDetection.ts  # Cron de deteccion de flujo negativo
 └── types/                   # Interfaces TypeScript
@@ -202,12 +212,21 @@ water-api/src/
 | PUT | `/:id` | Actualizar dispositivo | Si (ADMIN/OPERATOR) |
 | DELETE | `/:id` | Eliminar dispositivo | Si (ADMIN) |

-#### Usuarios (`/api/users`) - Solo ADMIN
+#### Organismos Operadores (`/api/organismos-operadores`) - Solo ADMIN
 | Metodo | Ruta | Descripcion | Auth |
 |--------|------|-------------|------|
-| GET | `/` | Listar usuarios | Si (ADMIN) |
+| GET | `/` | Listar organismos operadores | Si (ADMIN) |
+| GET | `/:id` | Obtener organismo operador | Si (ADMIN) |
+| POST | `/` | Crear organismo operador | Si (ADMIN) |
+| PUT | `/:id` | Actualizar organismo operador | Si (ADMIN) |
+| DELETE | `/:id` | Eliminar organismo operador | Si (ADMIN) |
+
+#### Usuarios (`/api/users`) - ADMIN y ORGANISMO_OPERADOR
+| Metodo | Ruta | Descripcion | Auth |
+|--------|------|-------------|------|
+| GET | `/` | Listar usuarios (filtrado por scope) | Si (ADMIN/ORGANISMO_OPERADOR) |
 | GET | `/:id` | Obtener usuario | Si (ADMIN o self) |
-| POST | `/` | Crear usuario | Si (ADMIN) |
+| POST | `/` | Crear usuario | Si (ADMIN/ORGANISMO_OPERADOR) |
 | PUT | `/:id` | Actualizar usuario | Si (ADMIN o self) |
 | DELETE | `/:id` | Desactivar usuario | Si (ADMIN) |
 | PUT | `/:id/password` | Cambiar contrasena | Si (self) |
@@ -309,7 +328,7 @@ roles ←─── users ←─── refresh_tokens
 ```

 ### ENUMs de PostgreSQL
- `role_name`: ADMIN, OPERATOR, VIEWER
+- `role_name`: ADMIN, ORGANISMO_OPERADOR, OPERATOR
 - `project_status`: ACTIVE, INACTIVE, COMPLETED
 - `device_status`: ACTIVE, INACTIVE, OFFLINE, MAINTENANCE, ERROR
 - `meter_type`: WATER, GAS, ELECTRIC
@@ -319,13 +338,15 @@ roles ←─── users ←─── refresh_tokens

 Ejecutar en orden despues del schema principal:

-1. `schema.sql` - Schema principal con 10 tablas, 2 vistas, seed de roles y admin
+1. `schema.sql` - Schema principal con tablas base, 2 vistas, seed de roles y admin
 2. `add_audit_logs.sql` - Tabla de logs de auditoria
 3. `add_notifications.sql` - Tabla de notificaciones
 4. `add_meter_extended_fields.sql` - Campos extendidos para medidores
 5. `create_meter_types.sql` - Tabla de tipos de medidor
 6. `add_meter_project_relation.sql` - Relacion meter-proyecto
 7. `add_user_project_relation.sql` - Relacion user-proyecto
+8. `add_organismos_operadores.sql` - Tabla organismos_operadores, FK en projects y users, rol ORGANISMO_OPERADOR
+9. `add_user_meter_fields.sql` - Campos adicionales en users y meters (cespt_account, cadastral_key)

 ---

@@ -355,7 +376,7 @@ Ejecutar en orden despues del schema principal:
 ```

 ### Tokens
- **Access Token** - JWT con userId, roleId, roleName, projectId. Expira en 15 minutos.
+- **Access Token** - JWT con userId, roleId, roleName, projectId, organismoOperadorId. Expira en 15 minutos.
 - **Refresh Token** - JWT almacenado hasheado en BD. Expira en 7 dias. Revocable.

 ### Token Refresh Automatico (Frontend)
@@ -374,25 +395,42 @@ water_project_settings_v1 → {theme, compactMode}
 mock_avatar         → Avatar en base64
 ```

-### Control de Acceso por Rol
+### Control de Acceso por Rol (Jerarquia de 3 niveles)

-| Recurso | ADMIN | OPERATOR | VIEWER |
-|---------|-------|----------|--------|
-| Usuarios | CRUD completo | Solo lectura | Sin acceso |
-| Proyectos | CRUD completo | Crear/Leer/Actualizar | Solo lectura |
-| Dispositivos | CRUD completo | Crear/Leer/Actualizar | Solo lectura |
-| Medidores | CRUD completo | Crear/Leer/Actualizar | Solo lectura |
-| Lecturas | CRUD + eliminar | Crear/Leer | Solo lectura |
-| Configuracion | Completa | Solo lectura | Sin acceso |
-| Reportes | Crear/Leer/Exportar | Crear/Leer/Exportar | Solo lectura |
+| Recurso | ADMIN | ORGANISMO_OPERADOR | OPERATOR |
+|---------|-------|-------------------|----------|
+| Organismos | CRUD completo | Sin acceso | Sin acceso |
+| Usuarios | CRUD completo | CRUD (su organismo) | Sin acceso |
+| Proyectos | CRUD completo | Leer (su organismo) | Leer (su proyecto) |
+| Medidores | CRUD completo | Leer (su organismo) | Leer (su proyecto) |
+| Lecturas | CRUD + eliminar | Leer (su organismo) | Leer (su proyecto) |
+| Historico | Todos los medidores | Medidores de su organismo | Medidores de su proyecto |
+| Analytics | Completo | Completo | Sin acceso |
+| Conectores | Completo | Sin acceso | Sin acceso |
+| Auditoria | Completa | Sin acceso | Sin acceso |
+
+### Scope Filtering (Backend)
+
+Todos los servicios aplican filtrado automatico basado en el rol del usuario:
+
+```
+ADMIN          → Sin filtro (ve todos los datos)
+ORGANISMO_OP.  → project_id IN (SELECT id FROM projects WHERE organismo_operador_id = $N)
+OPERATOR       → project_id = $N (solo su proyecto asignado)
+```
+
+El utility `water-api/src/utils/scope.ts` centraliza esta logica.

 ### Helpers del Frontend

 ```typescript
-getCurrentUserRole()       // → "ADMIN" | "OPERATOR" | "VIEWER"
-getCurrentUserId()         // → UUID string
-getCurrentUserProjectId()  // → UUID string | undefined
-isCurrentUserAdmin()       // → boolean
+getCurrentUserRole()              // → "ADMIN" | "ORGANISMO_OPERADOR" | "OPERATOR"
+getCurrentUserId()                // → UUID string
+getCurrentUserProjectId()         // → UUID string | undefined
+getCurrentUserOrganismoId()       // → UUID string | undefined
+isCurrentUserAdmin()              // → boolean
+isCurrentUserOrganismo()          // → boolean
+isCurrentUserOperator()           // → boolean
 ```

 ---
@@ -412,14 +450,15 @@ Wrapper de `fetch` con:

 | Archivo | Descripcion |
 |---------|-------------|
-| `auth.ts` | Login, logout, refresh, getMe, helpers de roles |
+| `auth.ts` | Login, logout, refresh, getMe, helpers de roles (3 niveles) |
 | `client.ts` | Cliente HTTP base con JWT |
-| `meters.ts` | CRUD medidores + lecturas |
+| `meters.ts` | CRUD medidores + lecturas historicas paginadas |
 | `readings.ts` | Lecturas y resumen de consumo |
 | `projects.ts` | CRUD proyectos + nombres |
 | `concentrators.ts` | CRUD concentradores |
 | `users.ts` | CRUD usuarios |
 | `roles.ts` | CRUD roles |
+| `organismos.ts` | CRUD organismos operadores |
 | `analytics.ts` | Metricas, ubicaciones, reportes |
 | `notifications.ts` | Notificaciones del usuario |
 | `audit.ts` | Logs de auditoria |