# Plan: Agregar Rol ORGANISMOS_OPERADORES

## Resumen
Agregar un nuevo rol "ORGANISMOS_OPERADORES" que:
- Se ubica entre ADMIN y OPERATOR en la jerarquía
- Permite asignar **múltiples proyectos** a un usuario (a diferencia de OPERATOR que solo tiene uno)
- Puede ver datos de todos sus proyectos asignados

---

## Fase 1: Base de Datos

### 1.1 Crear migración SQL
**Archivo nuevo:** `water-api/sql/add_organismos_operadores_role.sql`

```sql
-- Agregar nuevo valor al enum role_name
ALTER TYPE role_name ADD VALUE 'ORGANISMOS_OPERADORES' AFTER 'ADMIN';

-- Crear tabla user_projects para relación muchos-a-muchos
CREATE TABLE user_projects (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(user_id, project_id)
);

CREATE INDEX idx_user_projects_user_id ON user_projects(user_id);
CREATE INDEX idx_user_projects_project_id ON user_projects(project_id);

-- Insertar el nuevo rol con permisos
INSERT INTO roles (name, description, permissions) VALUES (
    'ORGANISMOS_OPERADORES',
    'Organismos Operadores - gestiona múltiples proyectos asignados',
    '{
        "users": {"create": false, "read": true, "update": false, "delete": false},
        "projects": {"create": false, "read": true, "update": true, "delete": false},
        "devices": {"create": true, "read": true, "update": true, "delete": false},
        "meters": {"create": true, "read": true, "update": true, "delete": false},
        "readings": {"create": true, "read": true, "update": false, "delete": false},
        "settings": {"create": false, "read": true, "update": false, "delete": false},
        "reports": {"create": true, "read": true, "export": true}
    }'::JSONB
);
```

---

## Fase 2: Backend

### 2.1 Actualizar validador de roles
**Archivo:** `water-api/src/validators/role.validator.ts`
- Línea 7: Agregar 'ORGANISMOS_OPERADORES' al enum
```typescript
export const RoleNameEnum = z.enum(['ADMIN', 'ORGANISMOS_OPERADORES', 'OPERATOR', 'VIEWER']);
```

### 2.2 Actualizar tipos
**Archivo:** `water-api/src/types/index.ts`
- Agregar `projectIds?: string[]` a `JwtPayload`
- Agregar `project_ids?: string[]` a `User` y `UserPublic`

### 2.3 Actualizar servicio de usuarios
**Archivo:** `water-api/src/services/user.service.ts`
- Agregar funciones `getUserProjects(userId)` y `setUserProjects(userId, projectIds[])`
- Modificar `create()` para manejar `project_ids` cuando rol es ORGANISMOS_OPERADORES
- Modificar `update()` igual
- Modificar `getById()` y `getAll()` para incluir project_ids en respuesta

### 2.4 Actualizar servicio de autenticación
**Archivo:** `water-api/src/services/auth.service.ts`
- En `login()`: si rol es ORGANISMOS_OPERADORES, consultar `user_projects` y agregar array al JWT
- En `refresh()`: mismo cambio
- En `getMe()`: retornar `project_ids` array

### 2.5 Actualizar middleware de autenticación
**Archivo:** `water-api/src/middleware/auth.middleware.ts`
- Extraer `projectIds` del JWT y adjuntar a `req.user`

### 2.6 Actualizar validador de usuarios
**Archivo:** `water-api/src/validators/user.validator.ts`
- Agregar `project_ids: z.array(z.string().uuid()).optional()` a schemas

---

## Fase 3: Frontend

### 3.1 Actualizar API de autenticación
**Archivo:** `src/api/auth.ts`
- Agregar `projectIds?: string[]` a `JwtPayload` y `AuthUser`
- Agregar función `getCurrentUserProjectIds(): string[] | null`
- Agregar función `isOrganismosOperadores(): boolean`

### 3.2 Actualizar API de usuarios
**Archivo:** `src/api/users.ts`
- Agregar `project_ids?: string[]` a interfaces `User`, `CreateUserInput`, `UpdateUserInput`

### 3.3 Actualizar UsersPage
**Archivo:** `src/pages/UsersPage.tsx`
- Agregar `projectIds?: string[]` a interfaces
- Agregar componente de selección múltiple de proyectos para ORGANISMOS_OPERADORES
- Mantener selector único para OPERATOR
- Validar que se seleccione al menos un proyecto para ORGANISMOS_OPERADORES

### 3.4 Actualizar Sidebar
**Archivo:** `src/components/layout/Sidebar.tsx`
- Agregar `isOrganismosOperadores` check
- ORGANISMOS_OPERADORES puede ver: Dashboard, Proyectos, Medidores, Concentradores, Consumo, Analytics
- ORGANISMOS_OPERADORES NO puede ver: Users Management, Conectores, Auditoría

### 3.5 Actualizar páginas de datos
**Archivos:**
- `src/pages/meters/useMeters.ts`
- `src/pages/consumption/ConsumptionPage.tsx`
- `src/pages/projects/ProjectsPage.tsx`

Cambios en cada archivo:
- Importar `getCurrentUserProjectIds`
- Filtrar proyectos visibles usando array de IDs
- Permitir cambiar entre proyectos asignados

---

## Orden de Implementación

1. **SQL Migration** - Crear tabla y enum
2. **Backend Types** - Actualizar tipos base
3. **Backend Validators** - Actualizar validaciones
4. **Backend Services** - user.service.ts, auth.service.ts
5. **Backend Middleware** - auth.middleware.ts
6. **Frontend Auth API** - src/api/auth.ts
7. **Frontend Users API** - src/api/users.ts
8. **Frontend UsersPage** - Multi-select UI
9. **Frontend Sidebar** - Visibilidad de menús
10. **Frontend Data Pages** - Filtrado por proyectos

---

## Archivos a Modificar

| Archivo | Cambio |
|---------|--------|
| `water-api/sql/add_organismos_operadores_role.sql` | **NUEVO** - Migración |
| `water-api/src/validators/role.validator.ts` | Agregar enum value |
| `water-api/src/validators/user.validator.ts` | Agregar project_ids |
| `water-api/src/types/index.ts` | Agregar projectIds a tipos |
| `water-api/src/services/user.service.ts` | Funciones multi-proyecto |
| `water-api/src/services/auth.service.ts` | ProjectIds en JWT |
| `water-api/src/middleware/auth.middleware.ts` | Extraer projectIds |
| `src/api/auth.ts` | Funciones helper |
| `src/api/users.ts` | Actualizar interfaces |
| `src/pages/UsersPage.tsx` | Multi-select UI |
| `src/components/layout/Sidebar.tsx` | Visibilidad menús |
| `src/pages/meters/useMeters.ts` | Filtrado multi-proyecto |
| `src/pages/consumption/ConsumptionPage.tsx` | Filtrado multi-proyecto |
| `src/pages/projects/ProjectsPage.tsx` | Filtrado multi-proyecto |

---

## Verificación

1. **Base de datos**: Ejecutar migración y verificar que el rol existe
2. **Backend**:
   - Crear usuario con rol ORGANISMOS_OPERADORES y múltiples proyectos
   - Verificar que JWT incluye array de projectIds
3. **Frontend**:
   - Verificar multi-select aparece solo para ORGANISMOS_OPERADORES
   - Verificar que sidebar muestra/oculta elementos correctamente
   - Verificar que páginas de datos filtran por proyectos asignados