Requirements - User Management Module

Resumen Ejecutivo

El módulo User Management es un componente frontend que proporciona una interfaz completa para la gestión de usuarios, incluyendo visualización, operaciones CRUD, búsqueda, filtrado y operaciones masivas, consumiendo APIs REST existentes.

Alcance

En Alcance

• Visualización de usuarios (lista, cards, detalle)
• Operaciones CRUD completas (crear, editar, eliminar usuarios)
• Gestión de estados de usuario (activo, inactivo, suspendido, pendiente)
• Búsqueda y filtrado server-side y client-side
• Operaciones masivas (selección múltiple, cambios batch)
• Gestión de roles y permisos (asignación, visualización)
• Interfaz responsive y optimizada para UX
• Integración con sistema de eventos

Fuera de Alcance

• Autenticación de usuarios (solo presenta datos)
• Almacenamiento de contraseñas o datos sensibles
• Gestión de sesiones de usuario
• Configuración de permisos granulares (solo asignación)
• Auditoría o logging de acciones de usuario
• Integración con servicios externos de identidad

Suposiciones y Restricciones

Suposiciones

• Existe una API REST funcional con endpoints de usuarios
• Los permisos de usuario vienen del backend previamente configurados
• Mock API disponible para desarrollo y testing
• Sistema de eventos global disponible para notificaciones

Restricciones

• Módulo 100% frontend (browser-only)
• Angular 20 con standalone components únicamente
• OnPush change detection strategy obligatorio
• Uso de Signals sobre Observables donde sea posible
• No uso de NgModules
• Integración obligatoria con librerías core de GoGrab Space

Stakeholders

• Administradores del sistema: Gestión completa de usuarios y roles
• Usuarios finales: Visualización de información propia y de equipo
• Desarrolladores: Integración del módulo en aplicaciones
• Testers: Validación de funcionalidades y casos de uso

Historias de Usuario

US-001: Visualización de Usuarios

Como administrador del sistema quiero visualizar la lista de usuarios en diferentes formatos para gestionar eficientemente la información de usuarios.

Criterios de Aceptación:

• AC-001: Lista en formato tabla con columnas: nombre, email, rol, estado, última actividad, acciones
• AC-002: Vista de cards con avatar, datos clave y acciones rápidas
• AC-003: Vista de detalle completo con toda la información del usuario
• AC-004: Navegación fluida entre las diferentes vistas
• AC-005: Responsive design para móviles y tablets

Requerimientos Asociados: R-001, R-002, R-003

US-002: Crear Nuevo Usuario

Como administrador quiero crear nuevos usuarios para incorporar personas al sistema.

Criterios de Aceptación:

• AC-006: Formulario con campos requeridos: nombre, apellido, email, rol
• AC-007: Validación en tiempo real de email único y formato válido
• AC-008: Asignación de rol desde dropdown con roles disponibles
• AC-009: Estado inicial configurable (activo por defecto)
• AC-010: Confirmación antes de crear y feedback de éxito/error

Requerimientos Asociados: R-004, R-005, R-006

US-003: Editar Usuario Existente

Como administrador quiero editar información de usuarios para mantener los datos actualizados.

Criterios de Aceptación:

• AC-011: Modal de edición con formulario precargado
• AC-012: Modificación de todos los campos excepto email (validación especial)
• AC-013: Cambio de rol con validación de permisos
• AC-014: Actualización optimista de UI
• AC-015: Validación de cambios y confirmación

Requerimientos Asociados: R-007, R-008, R-009

US-004: Eliminar/Desactivar Usuario

Como administrador quiero eliminar o desactivar usuarios para gestionar accesos al sistema.

Criterios de Aceptación:

• AC-016: Modal de confirmación con opciones "Desactivar" o "Eliminar"
• AC-017: Validación de usuarios con dependencias antes de eliminar
• AC-018: Información clara sobre consecuencias de cada acción
• AC-019: Confirmación explícita requerida
• AC-020: Actualización inmediata de la lista tras la acción

Requerimientos Asociados: R-010, R-011

US-005: Gestión de Estados de Usuario

Como administrador quiero cambiar estados de usuario para controlar acceso y disponibilidad.

Criterios de Aceptación:

• AC-021: Toggle rápido de estado activo/inactivo desde la lista
• AC-022: Estados disponibles: Activo, Inactivo, Suspendido, Pendiente
• AC-023: Cambio de estado con confirmación para suspensiones
• AC-024: Indicadores visuales claros del estado actual
• AC-025: Opción de reseteo de contraseña para usuarios activos

Requerimientos Asociados: R-012, R-013

US-006: Búsqueda y Filtrado

Como administrador quiero buscar y filtrar usuarios para encontrar información específica rápidamente.

Criterios de Aceptación:

• AC-026: Barra de búsqueda con debounce por nombre y email
• AC-027: Filtros por rol, estado y fecha de creación
• AC-028: Combinación de múltiples criterios de filtrado
• AC-029: Filtrado server-side con query parameters
• AC-030: Chips de filtros activos con opción de remover
• AC-031: Persistencia de filtros durante la sesión

Requerimientos Asociados: R-014, R-015, R-016

US-007: Operaciones Masivas

Como administrador quiero realizar acciones en múltiples usuarios simultáneamente para optimizar tareas repetitivas.

Criterios de Aceptación:

• AC-032: Selección múltiple con checkboxes individuales y "seleccionar todo"
• AC-033: Barra de acciones masivas visible cuando hay selecciones
• AC-034: Cambio de rol batch con confirmación
• AC-035: Activar/desactivar múltiples usuarios
• AC-036: Eliminación múltiple con confirmación detallada
• AC-037: Feedback de progreso para operaciones largas

Requerimientos Asociados: R-017, R-018, R-019

US-008: Gestión de Roles y Permisos

Como administrador quiero gestionar roles de usuario para controlar accesos y funcionalidades.

Criterios de Aceptación:

• AC-038: Visualización de roles disponibles: Admin, User, Viewer
• AC-039: Asignación de rol desde formulario de usuario
• AC-040: Vista de permisos asociados a cada rol
• AC-041: Cambio de rol con validación de permisos del administrador usando Role y Permission de @libs-core/shared-models
• AC-042: Indicación clara del rol actual usando Role.name y Role.description en todas las vistas
• AC-043: Uso de directivas de seguridad (*hasPermission, *hasRole) para mostrar/ocultar controles basados en Permission.name
• AC-044: Validación de permisos en tiempo real con PermissionService usando Permission entities de shared-models

Requerimientos Asociados: R-020, R-021, R-022

US-009: Control de Acceso Basado en Permisos

Como usuario del sistema quiero que las funcionalidades estén protegidas por permisos para garantizar seguridad y accesos apropiados.

Criterios de Aceptación:

• AC-045: Integración con PermissionService usando Permission y Role entities de @libs-core/shared-models
• AC-046: Guards aplicados en rutas: authGuard, permissionGuard, modulePermissionGuard usando Permission.name patterns
• AC-047: Directivas de seguridad en templates para controles UI basadas en Permission entities
• AC-048: Validación de permisos antes de operaciones críticas (CRUD) usando Permission.resource y Permission.action
• AC-049: Manejo de multi-tenant context con ContextService y Permission.tenantId
• AC-050: Cache de permisos para optimizar performance con Permission[] arrays
• AC-051: Refresh automático de permisos al cambiar contexto usando Role.tenantId y Permission.tenantId

Requerimientos Asociados: R-023, R-024, R-025

Requerimientos No Funcionales

Performance (NFR-001)

• Paginación server-side con máximo 50 usuarios por página
• Lazy loading de datos de detalle de usuario
• Debounce de 300ms en búsquedas
• Change Detection OnPush en todos los componentes
• Caché de 5 minutos para requests de roles y estados

Seguridad (NFR-002)

• Integración obligatoria con @libs-core/security y @libs-core/shared-models para autenticación y autorización
• Uso de PermissionService para validación de permisos usando Permission entities (id, tenantId, name, resource, action)
• Guards aplicados: authGuard, permissionGuard, modulePermissionGuard en rutas usando Permission.name patterns
• Directivas de seguridad en templates: *hasPermission, *hasRole, *hasAnyRole basadas en Role y Permission entities
• Multi-tenant context management con ContextService usando Permission.tenantId y Role.tenantId
• Validaciones client-side complementarias (nunca únicas)
• No almacenamiento de datos sensibles en frontend
• Sanitización de inputs de usuario
• Cache de permisos con expiración automática (5 minutos) usando Permission[] arrays

Observabilidad (NFR-003)

• Emisión de eventos del sistema para todas las operaciones CRUD
• Logging de errores con contexto de usuario y acción
• Métricas de performance para operaciones críticas
• Correlación de IDs para trazabilidad

UX/Usabilidad (NFR-004)

• Loading skeletons durante cargas de datos
• Optimistic updates para acciones rápidas
• Responsive design con breakpoints estándar
• Keyboard shortcuts para acciones comunes
• Feedback inmediato para todas las acciones

Compatibilidad (NFR-005)

• Angular 20+ con standalone components
• NGXS para state management - Integración obligatoria con @ngxs/store
• Integración con @libs-core/ui-framework
• Compatibilidad con navegadores modernos (último año)
• Soporte para modo oscuro/claro

Estado y Arquitectura (NFR-006)

• NGXS Store como única fuente de verdad para el estado del módulo
• Actions para todas las operaciones CRUD (UserActions.LoadUsers, UserActions.CreateUser, etc.)
• Selectors tipados para acceso al estado (UserSelectors.getUsers, UserSelectors.getSelectedUser)
• Effects para side effects (HTTP calls, logging, eventos del sistema)
• State inmutable con patrón Redux via NGXS
• Integración con NgxsModuleBridgeService de @libs-core/module-base

Glosario

• CRUD: Create, Read, Update, Delete - operaciones básicas de gestión de datos
• Optimistic Update: Actualización de UI antes de confirmar con el servidor
• Server-side Filtering: Filtrado de datos en el servidor antes de envío al cliente
• Debounce: Técnica para retrasar ejecución hasta que cese la actividad
• OnPush: Estrategia de detección de cambios optimizada de Angular
• Standalone Component: Componente Angular independiente sin NgModule
• Mock API: API simulada para desarrollo y testing
• Multi-tenant: Arquitectura que soporta múltiples inquilinos/organizaciones
• NGXS: State management pattern basado en Redux para Angular
• Actions: Objetos que describen eventos en NGXS (UserActions.LoadUsers)
• Selectors: Funciones puras que extraen datos del store NGXS
• Effects: Side effects manejados fuera del store (HTTP calls, logging)
• Store: Contenedor inmutable del estado de la aplicación en NGXS