# RF-MGN-001-002: Gestión de Roles y Permisos (RBAC)

**Módulo:** MGN-001 - Fundamentos
**Prioridad:** P0 (MVP)
**Story Points:** 13
**Estado:** Definido
**Fecha:** 2025-11-23

## Descripción

El sistema debe permitir la gestión de roles y permisos granulares basados en RBAC (Role-Based Access Control). Los roles agrupan permisos CRUD sobre modelos y los usuarios heredan permisos según sus roles asignados.

## Actores

- **Actor Principal:** Administrador de Sistema
- **Actores Secundarios:** Usuario final (consume permisos)

## Precondiciones

1. Usuario administrador debe estar autenticado
2. Sistema debe tener modelos registrados en auth.models
3. Base de datos debe estar disponible

## Flujo Principal

1. Administrador accede a módulo de Gestión de Roles
2. Administrador crea nuevo rol con nombre y descripción
3. Administrador selecciona modelo (ej: sale.order)
4. Administrador asigna permisos CRUD: create, read, update, delete
5. Sistema crea registros en auth.permissions (rol + modelo + permisos)
6. Administrador asigna rol a usuarios (tabla auth.user_roles)
7. Sistema valida que permisos se apliquen inmediatamente
8. Usuario con rol asignado puede ejecutar acciones permitidas

## Flujos Alternativos

### FA-1: Rol con Herencia
1. Si administrador define parent_role_id
2. Sistema copia permisos del rol padre automáticamente
3. Administrador puede agregar permisos adicionales
4. Usuario hereda permisos del rol padre + permisos específicos

### FA-2: Eliminación de Rol en Uso
1. Si administrador intenta eliminar rol asignado a usuarios
2. Sistema retorna error 400: "Rol en uso. Reasigne usuarios antes de eliminar"

### FA-3: Usuario sin Permisos
1. Usuario intenta acción sin permiso correspondiente
2. Sistema valida permisos en middleware
3. Sistema retorna error 403: "No tiene permisos para esta acción"
4. Sistema registra intento en audit_log

### FA-4: Conflicto de Permisos (Múltiples Roles)
1. Usuario tiene múltiples roles con permisos contradictorios
2. Sistema aplica política "allow overrides deny" (si algún rol permite, se permite)

## Reglas de Negocio

- **RN-1:** Un usuario puede tener múltiples roles
- **RN-2:** Un rol puede tener múltiples permisos sobre múltiples modelos
- **RN-3:** Permisos son granulares: create, read, update, delete por modelo
- **RN-4:** Herencia de roles: hijo hereda todos los permisos del padre
- **RN-5:** Roles predefinidos: Administrator (todos los permisos), User (solo lectura)
- **RN-6:** Administrador tiene permisos absolutos (bypass RBAC)
- **RN-7:** Política de resolución: "allow overrides deny"

## Criterios de Aceptación

- [ ] Administrador puede crear, editar y eliminar roles
- [ ] Administrador puede asignar permisos CRUD por modelo a roles
- [ ] Administrador puede asignar múltiples roles a un usuario
- [ ] Usuario solo puede ejecutar acciones para las que tiene permisos
- [ ] Sistema retorna 403 cuando usuario sin permisos intenta acción
- [ ] Herencia de roles funciona correctamente (hijo hereda permisos del padre)
- [ ] Roles predefinidos (Administrator, User) existen por defecto
- [ ] Cambios de permisos se aplican inmediatamente sin logout
- [ ] Sistema registra intentos de acceso no autorizado en audit_log

## Entidades Involucradas

- **Principales:**
  - auth.roles (name, description, parent_role_id, is_admin)
  - auth.permissions (role_id, model_id, can_create, can_read, can_update, can_delete)
  - auth.user_roles (user_id, role_id)
- **Relacionadas:**
  - auth.models (nombre de modelos del sistema)
  - auth.users (usuarios con roles)

## Referencias

- [ALCANCE-POR-MODULO.md - MGN-001](../../01-definicion-modulos/ALCANCE-POR-MODULO.md#mgn-001-fundamentos)
- [Auth Domain Model](../domain-models/auth-domain.md)
- [Auth Schema DDL](../database-design/schemas/auth-schema-ddl.sql)
- [Gap Analysis MGN-001](../../01-definicion-modulos/gaps/GAP-ANALYSIS-MGN-001.md)

## Notas Técnicas

- **Patrón Odoo:** Similar a res.groups + ir.model.access (pero más simple)
- **Patrón Gamilit:** RBAC con tabla permissions + middleware de validación
- **Middleware:** Guard/Interceptor que valida permisos antes de ejecutar acción
- **Caché:** Cachear permisos de usuario en Redis para performance
- **Backend:** NestJS Guards + CASL para RBAC
- **Frontend:** Hook usePermissions(['sale.order.create']) para condicionar UI

## Dependencias

- **RF Dependientes:** RF-MGN-001-001 (Autenticación)
- **Bloqueante para:** Todos los módulos transaccionales (necesitan validar permisos)