# 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)
