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>

ESTADO_ACTUAL.md

@@ -15,8 +15,8 @@ Sistema full-stack de gestion de medidores de agua con:
 
 ### Jerarquia de datos:
 ```
-Projects → Concentrators → Meters → Readings
-         → Gateways → Devices ↗
+Organismos Operadores → Projects → Concentrators → Meters → Readings
+                                 → Gateways → Devices ↗
 ```
 
 ### URLs de produccion:
@@ -61,11 +61,11 @@ Projects → Concentrators → Meters → Readings
 ┌─────────────────────────────────────────────────────────────┐
 │                      PostgreSQL                              │
 ├─────────────────────────────────────────────────────────────┤
-│  10 tablas: roles, users, projects, concentrators,           │
-│  gateways, devices, meters, meter_readings,                  │
+│  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     │
-│  7 archivos SQL (schema + 6 migraciones)                     │
+│  9 archivos SQL (schema + 8 migraciones)                     │
 │  Triggers de updated_at, indices compuestos, JSONB           │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -77,18 +77,20 @@ Projects → Concentrators → Meters → Readings
 ### 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
+- **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 (CESPT Tijuana, Tecate, Mexicali)
+- Selector de organismos operadores (filtrado por rol)
 - Historial reciente de actividades
 - Panel de ultimas alertas
-- Soporte por rol (ADMIN, OPERATOR, VIEWER)
+- Soporte por rol (ADMIN, ORGANISMO_OPERADOR, OPERATOR)
 
 ### 3. Gestion de Proyectos
 - CRUD completo
@@ -133,40 +135,58 @@ Projects → Concentrators → Meters → Readings
 - Sincronizacion programada a las 9:00 AM
 - Seguimiento de ultima conexion y estado
 
-### 9. Gestion de Usuarios
+### 9. Gestion de Organismos Operadores (NUEVO)
 - CRUD completo (solo ADMIN)
-- Asignacion de roles
-- Asignacion de proyecto
+- 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
 
-### 10. Gestion de Roles
-- 3 roles predefinidos: ADMIN, OPERATOR, VIEWER
+### 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
 
-### 11. Auditoria
+### 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
 
-### 12. Notificaciones
+### 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
 
-### 13. Dark Mode
+### 15. 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
+### 16. Upload Panel
 - Aplicacion separada (`upload-panel/`) para carga CSV
 - Dropzone para archivos
 - Carga de medidores (upsert)
@@ -251,6 +271,21 @@ Columnas opcionales:
 - 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
 
@@ -287,8 +322,8 @@ psql -d water_project -f water-api/sql/schema.sql
 
 ## Proximos Pasos Sugeridos
 
-1. **Rol ORGANISMOS_OPERADORES** - Implementar nuevo rol segun plan existente
-2. **Reportes PDF** - Generacion y descarga de reportes en PDF
-3. **Tests** - Suite de tests con Vitest (frontend) y Supertest (backend)
-4. **CI/CD** - Pipeline de integracion continua
-5. **Docker** - Containerizacion del proyecto completo
+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