rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
23786ad49f
erp-core/docs/05-user-stories/mgn-001/US-MGN-001-002-001-crear-y-gestionar-roles.md

10 KiB
Raw Blame History

US-MGN-001-002-001: Crear y Gestionar Roles

RF Asociado: RF-MGN-001-002 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