Roles

Tag: roles
Descripción: Operaciones para consulta de roles y permisos en el sistema

---

Introducción al Sistema de Roles

El sistema de roles y permisos permite controlar el acceso a diferentes funcionalidades de la aplicación mediante un modelo jerárquico:

Características Principales

1. Jerarquía de Accesos:

   • Los roles definen conjuntos de permisos que determinan qué acciones puede realizar un usuario
   • Cada usuario puede tener asignado uno o varios roles

2. Permisos:

   • Cada permiso sigue el formato recurso_accion (ej: content_edit)
   • Los permisos pueden combinarse para crear roles con accesos específicos

3. Roles Predefinidos:

   • admin: Acceso completo al sistema
   • user: Rol básico para usuarios registrados
   • Pueden existir roles personalizados según necesidades

---

1. Listar todos los roles (GET /roles)

• Descripción: Obtiene todos los roles del sistema con paginación
• Operation ID: RolesController_findAll
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN)

Query Parameters

Parámetro	Tipo	Requerido	Descripción
page	integer	❌ No	Número de página (default: 1)
limit	integer	❌ No	Límite por página (default: 10)
activeOnly	boolean	❌ No	Filtrar solo roles activos

Responses

Código	Descripción
200	Lista de roles obtenida
401	No autorizado

Ejemplo de respuesta:

{
    "data": [
        {
            "id": 1,
            "name": "admin",
            "description": "Acceso completo al sistema",
            "isActive": true,
            "permissions": ["*"]
        },
        {
            "id": 2,
            "name": "user",
            "description": "Usuario básico",
            "isActive": true,
            "permissions": ["content_view"]
        }
    ],
    "meta": {
        "total": 2,
        "page": 1,
        "limit": 10
    }
}

---

2. Obtener rol por ID (GET /roles/:id)

• Descripción: Obtiene un rol específico por su ID
• Operation ID: RolesController_findOne
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID del rol

Responses

Código	Descripción
200	Rol obtenido exitosamente
401	No autorizado
404	Rol no encontrado

Ejemplo de respuesta:

{
    "id": 1,
    "name": "admin",
    "description": "Acceso completo al sistema",
    "isActive": true,
    "permissions": ["*"],
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
}

---

Resumen de Endpoints de Roles

Método	Endpoint	Descripción	Permiso Requerido
GET	/roles	Listar todos los roles	ROLE_ADMIN
GET	/roles/:id	Obtener rol por ID	ROLE_ADMIN

Modelo de Datos

interface Role {
    id: number;
    name: string;
    description: string;
    isActive: boolean;
    permissions: string[];
    createdAt: string; // ISO date
    updatedAt: string; // ISO date
}

Reglas de Validación

1. Nombre del rol:

   • Entre 2-50 caracteres
   • Solo letras minúsculas, números, guiones y guiones bajos

2. Permisos:

   • Array de strings
   • Cada permiso debe seguir el formato feature_action (ej: content_edit)