consultoria-as/GRH
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Exteban08
2026-02-09 10:44:16 +00:00
parent 613fb2d787
commit da976b9003
8 changed files with 497 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
docs/API.md
View File

@@ -187,6 +187,7 @@ Authorization: Bearer {accessToken}
GET /meters?page=1&pageSize=50
Authorization: Bearer {accessToken}
```
*Resultados filtrados automaticamente por scope del usuario (ADMIN ve todos, ORGANISMO ve su organismo, OPERATOR ve su proyecto)*
**Parametros de consulta:**
| Parametro | Tipo | Descripcion |
@@ -202,11 +203,50 @@ Authorization: Bearer {accessToken}
### Obtener Medidor
```http
GET /meters/:id
Authorization: Bearer {accessToken}
```
### Lecturas del Medidor
```http
GET /meters/:id/readings?page=1&pageSize=50
Authorization: Bearer {accessToken}
```
*Resultados filtrados por scope del usuario*
**Parametros de consulta:**
| Parametro | Tipo | Descripcion |
|-----------|------|-------------|
| page | number | Numero de pagina |
| pageSize | number | Registros por pagina (max 100) |
| start_date | date | Fecha inicio (YYYY-MM-DD) |
| end_date | date | Fecha fin (YYYY-MM-DD) |
**Respuesta:**
```json
{
"success": true,
"data": [
{
"id": "uuid",
"meter_id": "uuid",
"reading_value": 1234.56,
"reading_type": "AUTOMATIC",
"battery_level": 85,
"signal_strength": -45,
"received_at": "2024-01-20T10:30:00Z",
"meter_serial_number": "MED001",
"meter_name": "Medidor 001",
"project_id": "uuid",
"project_name": "ADAMANT"
}
],
"pagination": {
"page": 1,
"pageSize": 50,
"total": 150,
"totalPages": 3
}
}
```
### Crear Medidor
@@ -382,6 +422,54 @@ GET /csv-upload/readings/template
---
## Organismos Operadores
### Listar Organismos
```http
GET /organismos-operadores
Authorization: Bearer {accessToken}
```
*Requiere rol ADMIN*
### Obtener Organismo
```http
GET /organismos-operadores/:id
Authorization: Bearer {accessToken}
```
### Crear Organismo
```http
POST /organismos-operadores
Authorization: Bearer {accessToken}
Content-Type: application/json
{
"name": "CESPT Tijuana",
"code": "CESPT-TJ",
"contact_name": "Juan Perez",
"contact_email": "juan@cespt.gob.mx",
"contact_phone": "664-123-4567",
"is_active": true
}
```
*Requiere rol ADMIN*
### Actualizar Organismo
```http
PUT /organismos-operadores/:id
Authorization: Bearer {accessToken}
Content-Type: application/json
```
### Eliminar Organismo
```http
DELETE /organismos-operadores/:id
Authorization: Bearer {accessToken}
```
*Requiere rol ADMIN*
---
## Usuarios
### Listar Usuarios
@@ -389,7 +477,7 @@ GET /csv-upload/readings/template
GET /users
Authorization: Bearer {accessToken}
```
*Requiere rol ADMIN*
*Requiere rol ADMIN o ORGANISMO_OPERADOR. Resultados filtrados por scope.*
### Crear Usuario
```http
@@ -402,10 +490,11 @@ Content-Type: application/json
"password": "contraseña123",
"name": "Nombre Usuario",
"role_id": "uuid-rol",
"project_id": "uuid-proyecto"
"project_id": "uuid-proyecto",
"organismo_operador_id": "uuid-organismo"
}
```
*Requiere rol ADMIN*
*Requiere rol ADMIN o ORGANISMO_OPERADOR*
### Actualizar Usuario
```http
@@ -441,12 +530,12 @@ GET /roles
Authorization: Bearer {accessToken}
```
**Roles disponibles:**
| Rol | Descripcion |
|-----|-------------|
| ADMIN | Acceso completo al sistema |
| OPERATOR | Gestion de medidores y lecturas de su proyecto |
| VIEWER | Solo lectura |
**Roles disponibles (jerarquia de 3 niveles):**
| Rol | Descripcion | Scope |
|-----|-------------|-------|
| ADMIN | Acceso completo al sistema | Ve todos los datos |
| ORGANISMO_OPERADOR | Gestiona proyectos de su organismo | Ve datos de proyectos de su organismo |
| OPERATOR | Opera medidores de su proyecto | Ve datos de su proyecto asignado |
---

72
docs/ARQUITECTURA.md
View File

@@ -54,6 +54,7 @@
│ │ │ - meters │ │ - meter │ │ - meter │ │ │
│ │ │ - readings │ │ - reading │ │ - reading │ │ │
│ │ │ - users │ │ - user │ │ - user │ │ │
│ │ │ - organismos│ │ - organismo │ │ - organismo │ │ │
│ │ │ - csv-upload│ │ - etc... │ │ - csv-upload│ │ │
│ │ │ - webhooks │ │ │ │ - tts │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
@@ -83,6 +84,7 @@
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ users │ │ projects │ │concentrators│ │ │
│ │ │ roles │ │ gateways │ │ meters │ │ │
│ │ │ organismos │ │ │ │ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
@@ -125,11 +127,24 @@
│ id (PK) │──┐ │ id (PK) │ ┌──│ id (PK) │
│ name │ └───▶│ role_id (FK) │ │ │ name │
│ description │ │ project_id (FK) │◀───┤ │ description │
│ permissions │ │ email │ │ │ area_name │
└─────────────┘ │ password_hash │ │ │ status │
│ name │ │ │ created_by (FK) │──▶ users
│ is_active │ │ │ meter_type_id │──▶ meter_types
└─────────────────┘ │ └─────────────────┘
│ permissions │ │ organismo_op_id │──┐ │ │ area_name │
└─────────────┘ │ email │ │ │ │ status │
│ password_hash │ │ │ │ organismo_op_id │──┐
│ name │ │ │ │ created_by (FK) │──▶ users
│ is_active │ │ │ │ meter_type_id │──▶ meter_types
└─────────────────┘ │ │ └─────────────────┘ │
│ │ │
┌─────────────────┐ │ │ │
│ organismos_ │◀─┘─┼───────────────────────┘
│ operadores │ │
├─────────────────┤ │
│ id (PK) │ │
│ name │ │
│ code │ │
│ contact_name │ │
│ contact_email │ │
│ is_active │ │
└─────────────────┘ │
│ │
│ │
┌─────────────────┐ │ │
@@ -183,6 +198,36 @@
└─────────────────┘
## Scope Filtering (Control de Acceso por Datos)
Todos los servicios del backend aplican filtrado automatico basado en el rol del usuario autenticado:
```
┌──────────────────────────────────────────────────────────┐
│ Scope Filtering │
├──────────────────────────────────────────────────────────┤
│ │
│ ADMIN (roleName = 'ADMIN') │
│ └── Sin filtro, ve TODOS los registros │
│ │
│ ORGANISMO_OPERADOR (organismoOperadorId = X) │
│ └── WHERE project_id IN ( │
│ SELECT id FROM projects │
│ WHERE organismo_operador_id = X │
│ ) │
│ │
│ OPERATOR (projectId = Y) │
│ └── WHERE project_id = Y │
│ │
├──────────────────────────────────────────────────────────┤
│ Utility: water-api/src/utils/scope.ts │
│ Se aplica en: meter, reading, project, user, │
│ concentrator, notification services │
└──────────────────────────────────────────────────────────┘
```
---
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ audit_logs │ │ notifications │ │ meter_types │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
@@ -206,7 +251,7 @@
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador unico |
| name | ENUM | ADMIN, OPERATOR, VIEWER |
| name | ENUM | ADMIN, ORGANISMO_OPERADOR, OPERATOR |
| description | TEXT | Descripcion del rol |
| permissions | JSONB | Permisos detallados |
@@ -219,9 +264,23 @@
| name | VARCHAR | Nombre completo |
| role_id | UUID FK | Rol asignado |
| project_id | UUID FK | Proyecto asignado (OPERATOR) |
| organismo_operador_id | UUID FK | Organismo asignado (ORGANISMO_OPERADOR) |
| is_active | BOOLEAN | Estado de la cuenta |
| last_login | TIMESTAMP | Ultimo acceso |
#### `organismos_operadores`
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador unico |
| name | VARCHAR | Nombre del organismo |
| code | VARCHAR | Codigo unico (ej: CESPT-TJ) |
| contact_name | VARCHAR | Nombre del contacto |
| contact_email | VARCHAR | Email de contacto |
| contact_phone | VARCHAR | Telefono de contacto |
| is_active | BOOLEAN | Estado activo |
| created_at | TIMESTAMP | Fecha de creacion |
| updated_at | TIMESTAMP | Fecha de actualizacion |
#### `refresh_tokens`
| Campo | Tipo | Descripcion |
|-------|------|-------------|
@@ -244,6 +303,7 @@
| area_name | VARCHAR | Nombre del area |
| location | TEXT | Ubicacion |
| status | ENUM | ACTIVE, INACTIVE, COMPLETED |
| organismo_operador_id | UUID FK | Organismo operador propietario |
| meter_type_id | UUID FK | Tipo de medidor por defecto |
| created_by | UUID FK | Usuario creador |

4
docs/INSTALACION.md
View File

@@ -49,8 +49,12 @@ psql -U water_user -d water_project -f add_notifications.sql
psql -U water_user -d water_project -f add_meter_extended_fields.sql
psql -U water_user -d water_project -f add_meter_project_relation.sql
psql -U water_user -d water_project -f add_meter_types.sql
psql -U water_user -d water_project -f add_organismos_operadores.sql
psql -U water_user -d water_project -f add_user_meter_fields.sql
```
**Nota:** `add_organismos_operadores.sql` crea la tabla `organismos_operadores`, agrega columnas FK en `projects` y `users`, y agrega el rol `ORGANISMO_OPERADOR`. `add_user_meter_fields.sql` agrega campos como `cespt_account` y `cadastral_key`.
### 3. Configurar Variables de Entorno
```bash

119
docs/MANUAL_USUARIO.md
View File

@@ -8,10 +8,12 @@
4. [Gestion de Concentradores](#gestion-de-concentradores)
5. [Gestion de Medidores](#gestion-de-medidores)
6. [Consumo y Lecturas](#consumo-y-lecturas)
7. [Panel de Carga CSV](#panel-de-carga-csv)
8. [Notificaciones](#notificaciones)
9. [Administracion de Usuarios](#administracion-de-usuarios)
10. [Auditoria](#auditoria)
7. [Historico de Tomas](#historico-de-tomas)
8. [Organismos Operadores](#organismos-operadores)
9. [Panel de Carga CSV](#panel-de-carga-csv)
10. [Notificaciones](#notificaciones)
11. [Administracion de Usuarios](#administracion-de-usuarios)
12. [Auditoria](#auditoria)
---
@@ -28,13 +30,24 @@
3. Introduzca su contraseña
4. Haga clic en "Iniciar Sesion"
### Roles de Usuario
### Roles de Usuario (Jerarquia de 3 niveles)
| Rol | Permisos |
|-----|----------|
| **ADMIN** | Acceso completo a todas las funciones |
| **OPERATOR** | Gestion de medidores y lecturas de su proyecto asignado |
| **VIEWER** | Solo visualizacion de datos |
| Rol | Permisos | Visibilidad |
|-----|----------|-------------|
| **ADMIN** | Acceso completo a todas las funciones | Ve todos los datos del sistema |
| **ORGANISMO_OPERADOR** | Gestion de usuarios y visualizacion de su organismo | Ve datos de los proyectos de su organismo |
| **OPERATOR** | Operacion de medidores de su proyecto | Ve datos de su proyecto asignado |
### Menu Lateral por Rol
| Seccion | ADMIN | ORGANISMO_OPERADOR | OPERATOR |
|---------|-------|-------------------|----------|
| Dashboard | Si | Si | Si |
| Project Management | Si | Si | Si |
| Users Management | Si | Si | No |
| Organismos Operadores | Si | No | No |
| Conectores | Si | No | No |
| Analytics | Si | Si | No |
---
@@ -204,6 +217,83 @@ Los concentradores son dispositivos que agrupan multiples medidores.
---
## Historico de Tomas
*Disponible para todos los roles. Cada rol solo ve los medidores de su scope.*
### Acceder al Historico
1. Navegue a **Historico** en la seccion "Project Management" del menu lateral
2. Vera un selector de medidor y un estado vacio inicial
### Seleccionar Medidor
1. Haga clic en el campo de busqueda
2. Escriba para filtrar por:
- Nombre del medidor
- Numero de serie
- Ubicacion
- Cuenta CESPT
- Clave catastral
3. Seleccione el medidor del dropdown
### Informacion del Medidor
Al seleccionar un medidor se muestra:
- **Tarjeta de informacion:** Serial, nombre, proyecto, ubicacion, tipo, estado, ultima lectura
- **Cards de consumo:**
- **Consumo Actual:** Lectura mas reciente (consumo diario)
- **Consumo Pasado:** Lectura del primer dia del mes anterior
- **Diferencial:** Diferencia entre actual y pasado (con indicador de tendencia)
### Filtrar por Fechas
1. Use los campos "Desde" y "Hasta" para definir un rango
2. Los datos se actualizan automaticamente
3. Use el boton "Limpiar" para remover los filtros
### Grafica de Consumo
- Grafica de area con gradiente azul
- Eje X: fechas, Eje Y: valor de lectura (m3)
- El rango del eje Y se ajusta automaticamente a los datos
### Tabla de Lecturas
- Columnas: Fecha/Hora, Lectura (m3), Tipo, Bateria, Senal
- Paginacion configurable: 10, 20 o 50 registros por pagina
- Indicadores visuales de bateria y senal
### Exportar CSV
1. Haga clic en el boton **"Exportar CSV"** en el encabezado
2. Se descargara un archivo `historico_{serial}_{fecha}.csv`
---
## Organismos Operadores
*Solo disponible para usuarios con rol ADMIN*
### Ver Organismos
1. Haga clic en **"Organismos Operadores"** en el menu lateral
2. Vera la tabla con todos los organismos registrados
### Crear Organismo
1. Haga clic en **"Nuevo Organismo"**
2. Complete los campos:
- **Nombre:** Nombre del organismo (ej: CESPT Tijuana)
- **Codigo:** Codigo unico (ej: CESPT-TJ)
- **Contacto:** Nombre de la persona de contacto
- **Email:** Correo electronico de contacto
- **Telefono:** Numero de telefono
- **Estado:** Activo/Inactivo
3. Haga clic en **"Guardar"**
### Editar Organismo
1. Haga clic en el icono de edicion del organismo
2. Modifique los campos necesarios
3. Haga clic en **"Guardar"**
### Vincular Proyectos y Usuarios
- Los proyectos se vinculan a un organismo via el campo `organismo_operador_id` en la pagina de Proyectos
- Los usuarios con rol ORGANISMO_OPERADOR se vinculan a un organismo via la pagina de Usuarios
---
## Panel de Carga CSV
El panel de carga CSV permite subir datos de medidores y lecturas sin necesidad de autenticacion.
@@ -297,11 +387,11 @@ MED002,567.89,2024-01-20 10:35:00,MANUAL,90,-42
## Administracion de Usuarios
*Solo disponible para usuarios con rol ADMIN*
*Disponible para ADMIN (ve todos) y ORGANISMO_OPERADOR (ve los de su organismo)*
### Ver Usuarios
1. Navegue a **Usuarios** en el menu lateral
2. Vera la lista de todos los usuarios
2. Vera la lista de usuarios filtrada segun su rol
### Crear Usuario
1. Haga clic en **"Nuevo Usuario"**
@@ -309,8 +399,9 @@ MED002,567.89,2024-01-20 10:35:00,MANUAL,90,-42
- **Email**: Correo electronico (sera el usuario de login)
- **Nombre**: Nombre completo
- **Contraseña**: Contraseña inicial
- **Rol**: ADMIN, OPERATOR, o VIEWER
- **Proyecto**: Solo para OPERATOR - proyecto asignado
- **Rol**: ADMIN, ORGANISMO_OPERADOR, u OPERATOR
- **Organismo Operador**: Para ORGANISMO_OPERADOR - organismo asignado
- **Proyecto**: Para OPERATOR - proyecto asignado
3. Haga clic en **"Guardar"**
### Editar Usuario