Cómo listar roles de personal
Consulta los roles de empleados configurados para la ubicación activa, filtra por nombre o descripción y revisa qué empleados activos están asignados a cada rol cuando la cuenta también puede ver personal.
En este artículo
La pestaña Roles de empleados muestra el catálogo local de roles de una ubicación. En Marea Gran Via, por ejemplo, permite revisar roles como Sala, Cocina y Barra con su descripción y una insignia de color.
Este flujo es solo de consulta: no crea, edita ni elimina roles. La búsqueda y la paginación se resuelven en la pantalla, mientras que el listado base llega desde la API de roles de la ubicación.
Antes de empezar
- Sesión iniciada en Antylogic con organización y ubicación activas.
- Estar trabajando dentro de una ubicación; los roles de personal pertenecen a una ubicación concreta.
- Tener permiso `staff-roles:view` en la ubicación para cargar el listado.
- Tener `staff:view` o `staff:manage` si se quiere ver la columna Empleados con asignaciones activas.
Instrucciones
- 1.
Abre Roles de empleados
Entra en la gestión de empleados de la ubicación y selecciona la pestaña Roles de empleados. También puedes abrirla directamente con `location/staff?tab=roles`.
- 2.
Revisa la tabla de roles
La tabla muestra Nombre, Descripción y Empleados. El nombre aparece como una insignia de color; si el color no está definido o no se reconoce, la UI usa gris.
- 3.
Interpreta las asignaciones
La columna Empleados se calcula desde el personal activo. En el demo de Marea Gran Via, el rol Sala puede mostrar empleados como Marta Ruiz y Lucia Navarro.
- 4.
Busca por nombre o descripción
Usa el buscador para filtrar el listado sin cambiar datos. Con `roles_query=Sala`, la pantalla reduce la tabla a los roles que coinciden por nombre o descripción.
- 5.
Gestiona páginas y vacíos
La pantalla calcula el tamaño de página según el viewport. Si una búsqueda no tiene coincidencias, se muestra el estado vacío de roles sin modificar el catálogo.
- 6.
Refresca cuando necesites datos actuales
El refresco manual vuelve a pedir `staff-roles` y, si la cuenta puede ver personal, también vuelve a pedir `staff` para actualizar la columna Empleados.
Validaciones y límites
- `GET /api/app/{orgId}/{locationId}/staff-roles` exige `staff-roles:view`.
- El listado solo devuelve roles cuyo `location_id` coincide con la ubicación activa.
- La respuesta de roles incluye `id`, `location_id`, `name`, `description`, `color` y `created_at`.
- El orden base del backend es `name ASC`.
- `roles_query`, `roles_page` y `roles_page_size` son parámetros de la ruta de UI, no del endpoint de listado.
- La búsqueda no distingue mayúsculas y minúsculas y compara nombre más descripción en cliente.
- `roles_page` no numérico, cero o negativo vuelve a 1; si queda fuera de rango, la ruta se corrige a una página válida.
- Los empleados archivados con `deleted_at` no cuentan como asignaciones activas.
- Si la cuenta no puede cargar `staff`, el listado de roles puede seguir funcionando, pero la columna Empleados puede quedar incompleta.
- La acción documentada no crea, actualiza ni elimina roles; esas operaciones pertenecen a acciones hermanas.
Resultado esperado
La ubicación queda consultada con sus roles de personal locales, el filtro aplicado en la pantalla y las asignaciones activas visibles cuando el usuario tiene permiso para leer personal.