# EPICA: EPIC-MGN-003 - Roles y Permisos (RBAC)

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MGN-003 |
| **Nombre** | Roles y Permisos (RBAC) |
| **Modulo** | roles |
| **Fase** | Fase 1 - Foundation |
| **Prioridad** | P0 (Critico) |
| **Estado** | Ready |
| **Story Points** | 26 |
| **Sprint(s)** | Sprint 3 (RBAC completo) |
| **Plan Detalle** | [SPRINT-PLAN-FASE-1.md](../SPRINT-PLAN-FASE-1.md) |

---

## Descripcion

Sistema de control de acceso basado en roles (RBAC) que permite definir roles jerarquicos, permisos granulares por recurso/accion, asignacion de roles a usuarios, roles especificos por tenant y herencia de permisos.

Es fundamental para garantizar que cada usuario solo pueda acceder a las funcionalidades que le corresponden segun su rol en la organizacion.

---

## Objetivo de Negocio

Implementar un sistema de permisos que:
- Garantice segregacion de funciones
- Permita administracion granular de accesos
- Soporte multiples niveles de roles
- Sea auditable y trazable
- Se adapte a diferentes estructuras organizacionales

---

## Stakeholders

| Rol | Nombre/Equipo | Responsabilidad |
|-----|---------------|-----------------|
| Product Owner | Equipo Producto | Definicion de roles base |
| Tech Lead | Equipo Backend | Implementacion de guards |
| Seguridad | Equipo Infra | Validacion de modelo RBAC |
| Administradores | Clientes | Feedback de usabilidad |

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MGN003-001 | Como superadmin, quiero crear roles personalizados para adaptar permisos a mi organizacion | P0 | 5 | Ready |
| US-MGN003-002 | Como admin, quiero asignar roles a usuarios para definir sus permisos | P0 | 3 | Ready |
| US-MGN003-003 | Como superadmin, quiero definir permisos granulares por recurso/accion para control fino | P0 | 8 | Ready |
| US-MGN003-004 | Como admin, quiero ver que permisos tiene un usuario para verificar accesos | P0 | 3 | Ready |
| US-MGN003-005 | Como sistema, quiero validar permisos en cada request para proteger recursos | P0 | 5 | Ready |
| US-MGN003-006 | Como admin, quiero duplicar roles existentes para crear variaciones rapidamente | P2 | 2 | Backlog |

**Total Story Points:** 26 SP

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] CRUD de roles con nombre, descripcion y jerarquia
- [ ] Catalogo de permisos por modulo/recurso/accion
- [ ] Asignacion multiple de roles a usuarios
- [ ] Roles predefinidos: SuperAdmin, Admin, User, Viewer
- [ ] Herencia de permisos entre roles
- [ ] Visualizacion de permisos efectivos por usuario

**No Funcionales:**
- [ ] Performance: Validacion de permisos < 5ms (con cache)
- [ ] Seguridad: Principio de minimo privilegio
- [ ] Usabilidad: Interfaz intuitiva para asignar permisos

**Tecnicos:**
- [ ] Cobertura de tests > 85%
- [ ] Guards implementados en backend
- [ ] Directivas de permisos en frontend
- [ ] Cache de permisos por usuario

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-MGN-001 Auth | Ready | Si |
| EPIC-MGN-002 Users | Ready | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-MGN-004 Tenants | Roles por tenant |
| Todos los modulos | Proteccion de endpoints |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `core_auth` (extension)
- [ ] Tablas: 4 (roles, permissions, role_permissions, user_roles)
- [ ] Funciones: 2 (obtener_permisos_usuario, verificar_permiso)
- [ ] RLS Policies: Si (roles por tenant)

**Backend:**
- [ ] Modulo: `roles`
- [ ] Entities: 4 (Role, Permission, RolePermission, UserRole)
- [ ] Endpoints: 10 (CRUD roles + permisos + asignacion)
- [ ] Guards: PermissionsGuard, RolesGuard
- [ ] Decorators: @RequirePermission, @RequireRole
- [ ] Tests: 30+

**Frontend:**
- [ ] Paginas: 3 (RolesList, RoleDetail, UserPermissions)
- [ ] Componentes: 8 (RoleForm, PermissionTree, RoleAssigner, etc.)
- [ ] Stores: 1 (rolesStore)
- [ ] Directivas: v-permission, v-role

---

## Modelo de Permisos

```
Estructura de Permiso:
{modulo}:{recurso}:{accion}

Ejemplos:
- users:user:read
- users:user:create
- users:user:update
- users:user:delete
- roles:role:manage
- tenants:tenant:admin
```

**Roles Predefinidos:**

| Rol | Descripcion | Permisos |
|-----|-------------|----------|
| SuperAdmin | Acceso total al sistema | *.* |
| TenantAdmin | Admin de un tenant | {tenant}:*.* |
| Manager | Gestion operativa | Lectura + escritura modulos operativos |
| User | Usuario estandar | Lectura + escritura limitada |
| Viewer | Solo lectura | *:*:read |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Complejidad del modelo | Media | Alto | POC previo, documentacion clara |
| Performance sin cache | Alta | Alto | Redis cache de permisos |
| Escalabilidad de permisos | Media | Medio | Wildcards, herencia |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [x] Modelo de permisos aprobado
- [x] Sin bloqueadores activos

## Definition of Done (DoD)

- [ ] Codigo implementado y revisado
- [ ] Tests pasando (unit, integration, e2e)
- [ ] Guards funcionando en todos los endpoints
- [ ] Cache implementado
- [ ] Documentacion actualizada
- [ ] Demo realizada
- [ ] Product Owner aprobo

---

## Documentacion Relacionada

- Requerimientos: `docs/03-requerimientos/RF-rbac/`
- Especificaciones: `docs/04-modelado/especificaciones-tecnicas/ET-rbac-*.md`
- User Stories: `docs/05-user-stories/MGN-003/`
- ADR: `docs/97-adr/ADR-006-rbac-sistema-permisos.md`

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creacion de epica | Requirements-Analyst |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Ultima actualizacion:** 2025-12-05