# US-MGN-001-002-001: Crear y Gestionar Roles **RF Asociado:** [RF-MGN-001-002](../../02-modelado/requerimientos-funcionales/mgn-001/RF-MGN-001-002-gestion-roles.md) **Módulo:** MGN-001 - Fundamentos **Epic:** Autenticación y Seguridad **Prioridad:** P0 (MVP) **Story Points:** 5 **Sprint:** Sprint 1 **Estado:** Ready for Development **Fecha:** 2025-11-24 --- ## User Story **Como** administrador del sistema, **Quiero** crear y gestionar roles (crear, editar, eliminar, listar), **Para** organizar permisos de acceso y asignarlos grupalmente a usuarios. --- ## Descripción Detallada Esta user story cubre la gestión CRUD de roles en el sistema. Un rol es un contenedor de permisos que se asigna a usuarios. Los roles pueden tener herencia (un rol hijo hereda permisos del padre) y tienen características como: - Nombre y descripción - Marca si es rol de administrador (bypass de RBAC) - Relación de herencia (parent_role_id) - Lista de usuarios asignados El sistema debe venir con 2 roles predefinidos: 1. **Administrator**: rol admin con is_admin=true (bypass RBAC) 2. **User**: rol básico con permisos de solo lectura en modelos comunes --- ## Criterios de Aceptación ### Escenario 1: Crear rol básico **Dado que** soy administrador autenticado, **Cuando** creo un nuevo rol con nombre "Contador" y descripción "Acceso completo a módulo financiero", **Entonces** el sistema crea el rol en auth.roles y está disponible para asignar a usuarios. ### Escenario 2: Crear rol con herencia **Dado que** existe un rol "User" con permisos básicos, **Cuando** creo un rol "Vendedor" con parent_role_id apuntando a "User", **Entonces** el rol "Vendedor" hereda automáticamente los permisos de "User" y puedo agregar permisos adicionales. ### Escenario 3: Editar rol existente **Dado que** existe un rol "Contador", **Cuando** edito su descripción o cambio su parent_role_id, **Entonces** el sistema actualiza el rol y los cambios se aplican inmediatamente a usuarios que lo tienen asignado. ### Escenario 4: Intentar eliminar rol en uso **Dado que** un rol "Contador" está asignado a 5 usuarios, **Cuando** intento eliminarlo, **Entonces** el sistema retorna error 400 "No se puede eliminar rol asignado a usuarios. Reasigne primero." y muestra lista de usuarios afectados. ### Escenario 5: Eliminar rol sin uso **Dado que** un rol "Test" no está asignado a ningún usuario, **Cuando** lo elimino, **Entonces** el sistema elimina el rol y también elimina sus permisos asociados en auth.permissions. ### Escenario 6: Listar roles con estadísticas **Dado que** existen varios roles en el sistema, **Cuando** listo los roles, **Entonces** veo: nombre, descripción, cantidad de usuarios asignados, cantidad de permisos, jerarquía (padre/hijos). ### Escenario 7: Validar rol administrador protegido **Dado que** intento eliminar o desactivar el rol "Administrator", **Cuando** ejecuto la acción, **Entonces** el sistema retorna error 400 "No se puede eliminar rol Administrator (rol del sistema)". --- ## Reglas de Negocio - **RN-1:** Nombre de rol debe ser único por tenant. - **RN-2:** Rol "Administrator" tiene is_admin=true y bypass de RBAC. - **RN-3:** Herencia de roles: hijo hereda todos los permisos del padre. - **RN-4:** No se puede eliminar rol asignado a usuarios activos. - **RN-5:** No se puede eliminar roles del sistema (Administrator, User). - **RN-6:** Al eliminar rol, se eliminan sus permisos en cascada. - **RN-7:** Herencia puede ser multi-nivel (máximo 3 niveles de profundidad). --- ## Tareas Técnicas (Checklist de Implementación) ### Backend - [ ] Crear endpoint: `POST /api/v1/auth/roles` - Crear rol - [ ] Crear endpoint: `GET /api/v1/auth/roles` - Listar roles con paginación - [ ] Crear endpoint: `GET /api/v1/auth/roles/:id` - Detalle de rol - [ ] Crear endpoint: `PATCH /api/v1/auth/roles/:id` - Actualizar rol - [ ] Crear endpoint: `DELETE /api/v1/auth/roles/:id` - Eliminar rol - [ ] Implementar método: `RolesService.create(createRoleDto)` - [ ] Implementar método: `RolesService.findAll(filters, pagination)` - [ ] Implementar método: `RolesService.update(id, updateRoleDto)` - [ ] Implementar método: `RolesService.delete(id)` con validación de uso - [ ] Crear DTO: `CreateRoleDto` con @IsString, @IsOptional para parent_role_id - [ ] Crear DTO: `UpdateRoleDto` (partial de CreateRoleDto) - [ ] Crear DTO: `RoleResponseDto` con usuarios_count, permissions_count - [ ] Implementar validación: rol no puede ser su propio padre (circular reference) - [ ] Implementar validación: profundidad máxima de herencia (3 niveles) - [ ] Agregar unit tests (8 test cases) - [ ] Agregar integration tests (6 test cases) - [ ] Documentar endpoints en Swagger - [ ] Seed data: crear roles Administrator y User en migration ### Frontend - [ ] Crear página: `RolesListPage.tsx` con tabla paginada - [ ] Crear componente: `RoleFormModal.tsx` (crear/editar) - [ ] Crear componente: `RoleCard.tsx` para vista de grid (opcional) - [ ] Implementar formulario con React Hook Form + Zod - [ ] Crear API client: `rolesApi.create/getAll/getById/update/delete` - [ ] Implementar state management con Zustand o React Query - [ ] Agregar búsqueda y filtros (por nombre, activos/inactivos) - [ ] Implementar confirmación antes de eliminar - [ ] Mostrar warning si rol tiene usuarios asignados - [ ] Agregar component tests (4 test cases) - [ ] Agregar e2e test: "should create and delete role" ### Database - [ ] Verificar tabla: `auth.roles` (name, description, parent_role_id, is_admin, is_system) - [ ] Verificar tabla: `auth.user_roles` (para contar usuarios asignados) - [ ] Verificar tabla: `auth.permissions` (para cascade delete) - [ ] Crear índice: `idx_roles_name_tenant` (UNIQUE) - [ ] Crear índice: `idx_roles_parent_id` para queries de herencia - [ ] Validar foreign key: parent_role_id → auth.roles(id) - [ ] Agregar constraint: CHECK (id != parent_role_id) para evitar auto-referencia - [ ] Crear seed data: INSERT roles Administrator y User --- ## Mockups / Wireframes **Página de Lista de Roles:** - Header con título "Roles y Permisos" + botón "Nuevo Rol" - Tabla con columnas: - Nombre - Descripción - Rol Padre (si aplica) - Usuarios Asignados (count) - Permisos (count) - Acciones (Editar, Eliminar) - Filtros: búsqueda por nombre, mostrar solo activos - Paginación: 20 roles por página **Modal de Crear/Editar Rol:** - Campo: Nombre (input text, requerido) - Campo: Descripción (textarea, opcional) - Campo: Rol Padre (select dropdown con roles existentes, opcional) - Checkbox: "Es Administrador" (is_admin, solo para roles especiales) - Botones: Guardar, Cancelar **Confirmación de Eliminación:** - Modal: "¿Está seguro de eliminar el rol [Nombre]?" - Advertencia si tiene usuarios: "Este rol está asignado a X usuarios. Debe reasignarlos primero." - Botones: Eliminar (rojo), Cancelar --- ## Casos de Prueba (Test Scenarios) ### Pruebas Funcionales 1. **TC-001: Crear rol básico** - **Input:** name="Contador", description="Acceso financiero" - **Expected:** Rol creado, visible en lista 2. **TC-002: Crear rol con herencia** - **Input:** name="Vendedor", parent_role_id=User.id - **Expected:** Rol creado, hereda permisos de User 3. **TC-003: Nombre duplicado** - **Input:** name="Contador" (ya existe) - **Expected:** Error 400 "Nombre de rol ya existe" 4. **TC-004: Editar rol** - **Input:** id=Contador.id, description="Nueva descripción" - **Expected:** Rol actualizado 5. **TC-005: Eliminar rol en uso** - **Input:** id=Contador.id con 5 usuarios asignados - **Expected:** Error 400 con lista de usuarios 6. **TC-006: Eliminar rol sin uso** - **Input:** id=Test.id sin usuarios - **Expected:** Rol eliminado, permisos en cascada eliminados 7. **TC-007: Proteger rol Administrator** - **Input:** DELETE Administrator - **Expected:** Error 400 "Rol del sistema protegido" 8. **TC-008: Herencia circular** - **Input:** RolA.parent=RolB, RolB.parent=RolA - **Expected:** Error 400 "Referencia circular detectada" ### Pruebas No Funcionales 1. **Performance:** Lista de 100 roles en < 200ms 2. **Usabilidad:** - Búsqueda en tiempo real (debounce 300ms) - Feedback visual al guardar/eliminar 3. **Seguridad:** Solo usuarios con permiso 'auth.roles.manage' pueden acceder --- ## Dependencias - **User Stories bloqueantes:** US-MGN-001-001-001 (Login) - **Módulos requeridos:** Ninguno - **Datos maestros necesarios:** Roles Administrator y User creados en seed --- ## Notas de Implementación - Roles del sistema (is_system=true) no pueden eliminarse ni editarse ciertos campos - Implementar soft delete opcional (deleted_at) si se requiere auditoría - Considerar caché de roles en Redis para performance (invalidar al actualizar) - Frontend: usar React Query para auto-revalidación de lista después de mutaciones - Validar permisos: solo users con 'auth.roles.manage' pueden acceder a estos endpoints --- ## Estimación Detallada | Tarea | Estimación | |-------|------------| | Backend Development | 3 horas | | Frontend Development | 3 horas | | Testing (Unit + Integration + E2E) | 2 horas | | Code Review | 1 hora | | **TOTAL** | **9 horas** | **Equivalente:** 5 Story Points --- ## Definition of Done (DoD) - [ ] Código backend implementado según ET-BACKEND-MGN-001-002 - [ ] Código frontend implementado según ET-FRONTEND-MGN-001-002 - [ ] Unit tests escritos y pasando (cobertura > 80%) - [ ] Integration tests escritos y pasando - [ ] E2E test "should create and delete role" pasando - [ ] Code review completado y aprobado - [ ] Documentación Swagger actualizada - [ ] Seed data de roles Administrator y User creado - [ ] Merge a branch `develop` completado - [ ] QA manual completado --- ## Referencias - [RF-MGN-001-002: Gestión de Roles y Permisos](../../02-modelado/requerimientos-funcionales/mgn-001/RF-MGN-001-002-gestion-roles.md) - [ET-BACKEND-MGN-001-002](../../02-modelado/especificaciones-tecnicas/backend/mgn-001/ET-BACKEND-MGN-001-002-gestion-roles.md) - [ET-FRONTEND-MGN-001-002](../../02-modelado/especificaciones-tecnicas/frontend/mgn-001/ET-FRONTEND-MGN-001-002-gestion-roles.md) - [TRACEABILITY-MGN-001.yaml](../../02-modelado/trazabilidad/TRACEABILITY-MGN-001.yaml) - [Auth Schema DDL](../../02-modelado/database-design/schemas/auth-schema-ddl.sql)