# 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

```typescript
// 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](./_MAP.md)
- **Trazabilidad:** [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml)

---

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