erp-core/docs/01-fase-foundation/MGN-003-roles

MGN-003: Roles y Permisos

Metadata

Campo	Valor
ID	MGN-003
Nombre	Roles y Permisos (RBAC)
Fase	01 - Foundation
Prioridad	P0 (Critico)
Story Points	40 SP
Estado	Documentado
Dependencias	MGN-001, MGN-002

---

Descripcion

Sistema de control de acceso basado en roles (Role-Based Access Control) que permite:

• Definir roles con conjuntos de permisos
• Crear permisos granulares por modulo/accion/recurso
• Asignar multiples roles a usuarios
• Verificar permisos en tiempo de ejecucion
• Roles de sistema predefinidos (admin, user, etc.)

---

Modelo de Permisos

Permission = module:action:resource

Ejemplos:
- users:read:all      -> Leer todos los usuarios
- users:read:own      -> Leer solo su usuario
- users:write:all     -> Escribir todos los usuarios
- sales:create:orders -> Crear ordenes de venta
- reports:export:*    -> Exportar cualquier reporte

---

Roles de Sistema

Rol	Descripcion	Permisos
super_admin	Administrador global	Todos (::*)
tenant_admin	Admin de tenant	Todos en su tenant
user	Usuario basico	Lectura propia

---

Endpoints API

Metodo	Path	Descripcion
GET	/api/v1/roles	Listar roles
POST	/api/v1/roles	Crear rol
GET	/api/v1/roles/:id	Obtener rol
PATCH	/api/v1/roles/:id	Actualizar rol
DELETE	/api/v1/roles/:id	Eliminar rol
GET	/api/v1/permissions	Listar permisos
POST	/api/v1/users/:id/roles	Asignar rol a usuario
DELETE	/api/v1/users/:id/roles/:roleId	Quitar rol
GET	/api/v1/users/:id/permissions	Permisos de usuario

---

Guards y Decoradores

// Decorador de roles
@Roles('admin', 'manager')
@Get('admin-only')
adminEndpoint() {}

// Decorador de permisos
@RequirePermission('users', 'read', 'all')
@Get('users')
getUsers() {}

// Guard combinado
@UseGuards(JwtAuthGuard, RolesGuard, PermissionsGuard)

---

Documentacion

• Mapa del modulo: _MAP.md
• Trazabilidad: TRACEABILITY.yml

---

Generado por: Requirements-Analyst Fecha: 2025-12-05