Para la consulta de usuarios con permisos de aprobación, ver Usuarios aprobadores. Para aplicar esos permisos en una pantalla Angular, ver Implementación de permisos en frontend.
Esta guía describe los flujos implementados en libs/maestros para invitar usuarios, asignarles roles y administrar las capacidades asociadas a esos roles. Se basa en el frontend actual; la validación final de identidad, autorización y persistencia corresponde a los servicios backend.
La funcionalidad está dentro de libs/maestros/src/lib/feature-maestros/src/lib/:
| Funcionalidad | Archivos principales |
|---|---|
| Usuarios | usuario/usuario-list.component.ts, usuario/usuario.layout.ts, usuario/data-access/usuario.service.ts, usuario/domain/usuario.model.ts, usuario/store/usuario.store.ts |
| Roles y recursos | rol/rol-list.component.ts, rol/rol-recursos.component.ts, rol/data-access/rol.service.ts |
| Permisos del rol | rol/rol-permisos.component.ts, rol/data-access/rol-permiso.service.ts |
| Acciones del rol por recurso | rol/data-access/rol-acciones-modal.service.ts, rol/data-access/rol-acciones-dialog.component.ts |
| Catálogo de acciones y triggers | acciones-triggers/acciones-triggers.component.ts, acciones-triggers/data-access/acciones-triggers.service.ts, acciones-triggers/domain/acciones-triggers.model.ts |
La ruta principal del módulo se declara en src/lib/maestros.routes.ts; las subrutas de usuario, rol y acciones/triggers se conectan desde las rutas de la funcionalidad de maestros.
Usuario ── recibe uno o más ──> Roles
│
├── tienen permisos asignados
└── tienen recursos/opciones
└── cada recurso admite acciones
Recurso + código de acción ── puede asociarse a ──> Trigger/control de frontend
En el código se manejan como configuraciones relacionadas pero distintas:
customerRoleIds): roles del cliente que se asignan al usuario.code) que se permite para el recurso en ese rol.Un trigger no concede por sí mismo permiso al usuario. La autorización efectiva depende de la configuración de roles/permisos y de las comprobaciones de backend; el trigger conecta una acción con un control de interfaz.
La pantalla es un CRUD del maestro de usuarios del cliente. El alta se hace por invitación: el frontend envía los datos a POST {mastersBaseUrl}/usuario/create-invitacion. Según el contrato documentado en UsuarioService, el backend crea o vincula la identidad de Simappe, crea el usuario inactivo, genera el token y envía el correo con un enlace de activación. El frontend no captura ni asigna una contraseña en este flujo.
El formulario se presenta como un recorrido de tres pasos:
El username es obligatorio y se valida contra el backend con una consulta asíncrona con debounce de 400 ms (GET .../usuario/existe-username). Es editable durante el alta, pero queda bloqueado al editar el usuario. Se requieren datos personales, documento, correo válido y al menos un rol.
Los roles se cargan de POST {mastersBaseUrl}/roles/page-response, con paginación y búsqueda por etiqueta o tipo base (authority). La selección de roles se conserva entre páginas: la fuente de verdad es una lista acumulada de IDs (rolesSeleccionadosIds), no solo lo visible en la página actual. El formulario envía esos IDs bajo customerRoleIds.
Al abrir la edición:
GET .../usuario/roles?id=<id> para precargar los IDs de roles.onBeforeUpdate llama PUT .../usuario/roles?id=<id> con el conjunto de IDs seleccionado. El backend aplica las altas y bajas.Conviene tener presente que esta actualización de roles se dispara desde un hook separado del guardado base de los datos personales. Si se modifica el flujo, revisar cómo se reportan los errores de ambas operaciones y si deben coordinarse para evitar que una se guarde sin la otra.
Las acciones disponibles dependen del estado estadoUsuario y de activado:
| Estado | Acción en frontend | Resultado esperado |
|---|---|---|
| INACTIVO y nunca activado | Regenerar invitación | Invalida enlaces vigentes, genera otro y reenvía el correo (POST .../regenerar-invitacion?username=...). |
| ACTIVO y activado | Reiniciar contraseña | Reutiliza la regeneración para enviar un enlace de restablecimiento. |
| ACTIVO | Inactivar | PUT .../inactivar?id=...; desactiva la identidad y el estado de negocio. |
| INACTIVO y ya activado | Activar | PUT .../activar?id=...; puede reactivar identidad existente. |
| INACTIVO y nunca activado | Eliminar | DELETE .../eliminar?id=...; el backend rechaza el borrado si ya se definió contraseña. |
El frontend refleja la respuesta del backend en avisos y refresca el listado cuando corresponde. Las reglas de seguridad deben reforzarse en backend, incluso si la interfaz oculta acciones no aplicables.
La pantalla de permisos usa dos tablas: Disponibles y Asignados. Se marcan filas y se pasan de una tabla a otra; estos cambios quedan pendientes en memoria hasta pulsar Guardar. Descartar limpia los cambios sin enviarlos.
Al guardar, el frontend calcula las operaciones pendientes y las ejecuta en serie: primero revoca permisos retirados usando el ID de asignación, después asigna los nuevos usando el código del rol y el código del permiso. Si alguna operación falla, no muestra éxito y recarga la pantalla desde el backend para mostrar el estado que efectivamente quedó guardado.
El catálogo de permisos es pequeño y la pantalla deriva las opciones disponibles cruzando el catálogo contra los permisos asignados. Esta configuración de permisos del rol es distinta de los roles de usuario seleccionados en el formulario de invitación.
La pantalla de recursos también mantiene cambios pendientes entre las listas de disponibles y asignados. Al guardar arma el conjunto final de IDs de recursos y lo envía con PUT {simappeAdmin}/role/{id}/options (ruta construida por RolService como /{rolId}/options). La plataforma persiste el delta.
Las acciones de un recurso se configuran solo cuando el recurso ya está guardado como asignado al rol. Si se acaba de agregar, hay que guardar primero y luego abrir Acciones.
El modal de acciones del rol carga la lista efectiva de acciones para el par rol + recurso, desde POST .../{rolId}/options/{optionId}/actions/page-response. El backend entrega los códigos, nombres y estado efectivo, incluyendo si el valor se hereda del rol o es personalizado para ese recurso.
El usuario puede activar o desactivar acciones. Al guardar, el frontend envía el conjunto deseado como { code, granted } por PUT .../{rolId}/options/{optionId}/actions. La plataforma persiste las excepciones: si una acción vuelve a tener el mismo valor que hereda del rol, deja de ser una personalización. El modal muestra la opción de restablecer para regresar a la herencia.
Los códigos de acción son identificadores funcionales; el frontend presenta el nombre resuelto por backend y mantiene el código para guardar. Evitar basar la autorización en el nombre mostrado.
La pantalla Acciones y Triggers se administra por recurso:
Las llamadas actuales están divididas entre dos APIs:
| Dato u operación | Servicio/API usada por el frontend |
|---|---|
| Catálogo de recursos | GET /simappe-admin/api/v1/option/read |
| Catálogo de acciones | GET /simappe-admin/api/v1/action/read |
Acciones aplicables al recurso (option_action) |
GET /simappe-admin/api/v1/option-action/by-option?optionId=... |
| Aplicar acción al recurso | POST /simappe-admin/api/v1/option-action/create con { optionId, actionId } |
| Quitar acción del recurso | DELETE /simappe-admin/api/v1/option-action/delete?id=... |
| Consultar triggers del recurso | GET {mastersBaseUrl}{triggersEndpoint}/by-recurso?opcionCodigo=... |
| Crear trigger | POST {mastersBaseUrl}{triggersEndpoint}/create con opcionCodigo, accionCodigo y disparadorCodigo |
| Eliminar trigger | DELETE {mastersBaseUrl}{triggersEndpoint}/delete?id=... |
La pantalla filtra del selector recursos cuyo código comienza por MENU_. Para los triggers, el selector de acción ofrece solo las acciones que actualmente aplican al recurso. El control asociado se ingresa como código, que debe corresponder a un control conocido por la implementación del frontend. Al cambiar acciones o triggers, la pantalla recarga la configuración desde el backend.
En términos de responsabilidades, Simappe administra recursos, catálogo de acciones y su mapa de aplicabilidad. Nebula Masters administra los triggers del frontend. El componente consume los registros entregados por cada API y no intenta reconstruir su semántica.
Para habilitar una capacidad a un usuario, revisar el circuito completo:
usuario/usuario-list.component.ts, usuario/usuario.layout.ts, usuario/data-access/usuario.service.ts, usuario/domain/usuario.model.ts.rol/rol-permisos.component.ts, rol/data-access/rol-permiso.service.ts.rol/rol-recursos.component.ts, rol/data-access/rol.service.ts, rol/data-access/rol-acciones-modal.service.ts, rol/data-access/rol-acciones-dialog.component.ts.acciones-triggers/acciones-triggers.component.ts, acciones-triggers/data-access/acciones-triggers.service.ts, acciones-triggers/domain/acciones-triggers.model.ts.Los nombres base de API se leen desde API_CONFIG; confirmar esa configuración al cambiar ambientes o rutas.