# Plataforma de gestión de administradores y permisos

## Objetivo
Este módulo centraliza la administración de usuarios administrativos y el control granular de permisos. Permite:
- Gestionar cuentas administrativas (crear, editar, activar/desactivar, eliminar).
- Definir permisos por módulo y acción.
- Aplicar overrides por usuario para casos especiales.

## Componentes principales
- Gestión de administradores: /index/admin/gestion_user.php
- Gestión de permisos: /index/admin/gestion_permisos.php
- Helper RBAC: /admin/rbac.php
- Control de acceso por ruta: /admin/access_control.php
- Navegación admin: /admin/header.php

## Conceptos de permisos
### Acciones
Las acciones se definen por módulo. Acciones comunes:
- view: ver módulo o página
- create: crear registros
- update: editar registros
- delete: eliminar registros
- toggle: activar/desactivar
- export / approve / * (aplica a todas)

### Módulo
Se recomienda usar la ruta del módulo o una clave estable. Ejemplo:
- /index/admin/gestion_user.php
- /index/admin/gestion_permisos.php

## Modelo RBAC (tablas)
Se crean automáticamente en la base de datos de chat:

### rbac_permissions
- module (varchar): módulo o ruta
- action (varchar): acción
- min_level (int): nivel mínimo requerido
- description (varchar): descripción opcional

### rbac_user_permissions
- user_id (int): ID en gestion_bot
- module (varchar): módulo
- action (varchar): acción
- effect (allow|deny): permitir o denegar

## Flujo de autorización (detalle)
1. **Sesión**: el `header` del admin exige sesión válida y configura el nivel (`nivel`) de la cuenta.
2. **Regla por ruta**: `access_control.php` valida el mínimo nivel permitido según el prefijo de la URL. Si no cumple, redirige.
3. **RBAC por acción**: `rbac.php` evalúa permisos granulares por módulo/acción.
  - Si hay un **override** para el usuario, se aplica primero.
  - Si no hay override, usa el **nivel mínimo** configurado en `rbac_permissions`.
  - Si tampoco hay regla, el sistema **permite** por defecto (comportamiento retrocompatible).
4. **UI protegida**: botones de crear/editar/eliminar se ocultan si la acción no está permitida.

> Recomendación: definir reglas explícitas para evitar permisos implícitos.

## Cómo usar la gestión de administradores (paso a paso)
Pantalla: /index/admin/gestion_user.php

### Funcionalidades
- Ver listado de usuarios
- Filtrar por nivel, estado y sesión
- Crear/editar usuario
- Activar/Desactivar usuario
- Eliminar usuario

### Flujo de trabajo recomendado
1. **Revisar listado** para confirmar si el usuario ya existe.
2. **Crear usuario** con nivel base apropiado.
3. **Definir permisos** (ver sección de permisos) para ajustar acciones específicas.
4. **Validar acceso** iniciando sesión con ese usuario.

### Acciones y permisos del módulo
Módulo: /index/admin/gestion_user.php
- view: ver pantalla
- create: crear usuarios
- update: editar usuarios
- delete: eliminar usuarios
- toggle: activar/desactivar

## Cómo usar la gestión de permisos (paso a paso)
Pantalla: /index/admin/gestion_permisos.php

### Permisos por nivel
1. **Crear o actualizar** un permiso en la tabla de permisos.
2. **Módulo**: usa la ruta exacta del módulo (ej. `/index/admin/gestion_user.php`).
3. **Acción**: indica la acción (view/create/update/delete/toggle o `*`).
4. **Nivel mínimo**: define desde qué nivel se permite la acción.
5. **Guardar** y recargar la página.

### Overrides por usuario
1. **Seleccionar usuario** del listado.
2. **Módulo** y **acción** exactamente iguales a los de `rbac_permissions`.
3. **Efecto**: `allow` permite, `deny` bloquea.
4. **Guardar** y validar comportamiento.

> El override por usuario tiene prioridad sobre el nivel mínimo.

### Ejemplos prácticos
**Caso 1: nivel 4 puede ver pero no editar**
- Módulo: `/index/admin/gestion_user.php`
  - view → nivel 4
  - update → nivel 5
  - delete → nivel 5
  - toggle → nivel 5

**Caso 2: usuario específico con permiso extra**
- En `rbac_permissions` se mantiene `update` en nivel 5.
- En `rbac_user_permissions` se agrega `allow` para ese usuario y acción `update`.

## Ejemplo de política
Objetivo: nivel 4 puede ver administración pero no editar/eliminar.
- /index/admin/gestion_user.php
  - view => nivel 4
  - create => nivel 5
  - update => nivel 5
  - delete => nivel 5
  - toggle => nivel 5

## Buenas prácticas
- Usar rutas estables como clave de módulo.
- Evitar permisos excesivos; usar el mínimo necesario.
- Registrar y revisar cambios de permisos periódicamente.
- Preferir overrides solo para excepciones.
- Documentar la intención de cada regla en la descripción.

## Troubleshooting
### “No autorizado” en una pantalla
- Verificar nivel de sesión.
- Verificar regla en access_control.php.
- Verificar permiso RBAC en rbac_permissions.
- Revisar overrides en rbac_user_permissions.

### Una acción se permite cuando no debería
- Verificar si falta la regla específica en `rbac_permissions`.
- Revisar si existe un override en `rbac_user_permissions`.
- Asegurar que el módulo y la acción coincidan exactamente (incluye mayúsculas/minúsculas).

### Botones no visibles
- La UI oculta acciones según permisos. Revisar permisos del módulo.

## Seguridad
- Evitar exponer endpoints sin verificación RBAC.
- Las validaciones se hacen en backend y frontend.
- Se recomienda usar HTTPS y políticas de sesión seguras.
- Para endpoints AJAX, siempre usar validación RBAC en backend.

## Alcance
Esta documentación no cubre módulos de terceros ni carpetas fuera del dominio de administración (por ejemplo, bdCtnetworkadmin).