---
id: "SAAS-003"
title: "Usuarios y RBAC"
type: "Module"
status: "Published"
priority: "P0"
module: "users"
version: "1.0.0"
created_date: "2026-01-07"
updated_date: "2026-01-10"
---

# SAAS-003: Usuarios y RBAC

## Metadata
- **Codigo:** SAAS-003
- **Modulo:** Users + RBAC
- **Prioridad:** P0
- **Estado:** Completado
- **Fase:** 1 - Foundation

## Descripcion

Sistema de gestion de usuarios por tenant con roles y permisos (RBAC): CRUD de usuarios, invitaciones, roles predefinidos y custom, permisos granulares.

## Objetivos

1. CRUD de usuarios por tenant
2. Sistema de invitaciones
3. Roles predefinidos (owner/admin/member)
4. Roles custom por tenant
5. Permisos granulares

## Alcance

### Incluido
- Usuarios pertenecen a un tenant
- Roles: owner, admin, member, viewer
- Roles custom definibles por tenant
- Permisos: users.read, users.write, etc.
- Invitaciones por email
- Limite de usuarios por plan

### Excluido
- Usuarios multi-tenant - fase posterior
- Grupos/equipos - fase posterior
- Permisos por recurso - fase posterior

## Modelo de Datos

### Tablas (schema: users)

**users**
- id, tenant_id, email, name
- avatar_url, role, status
- last_login_at, created_at

**roles**
- id, tenant_id, name, description
- permissions (JSONB), is_system
- created_at

**invitations**
- id, tenant_id, email, role
- token, invited_by
- expires_at, accepted_at

## Sistema de Roles (RBAC)

### Modelo de Datos Flexible

El sistema usa un modelo flexible de roles basado en tablas (no enums fijos):

- `users.roles` - Definicion de roles (custom por tenant)
- `users.user_roles` - Asignacion usuario-rol (many-to-many)
- `users.permissions` - Permisos disponibles
- `users.role_permissions` - Permisos por rol

### Roles Sugeridos (No Fijos)

Aunque los roles son flexibles, se recomienda crear estos roles base:

| Rol | Descripcion | Permisos Tipicos |
|-----|-------------|------------------|
| owner | Propietario del tenant | * (todos) |
| admin | Administrador | users.*, billing.*, settings.* |
| member | Miembro regular | users.read, data.* |
| viewer | Solo lectura | *.read |

**Nota:** Los roles NO son un enum fijo. Cada tenant puede definir sus propios
roles con permisos personalizados via la API de roles

## Permisos Disponibles

```typescript
const PERMISSIONS = [
  // Users
  'users.read', 'users.write', 'users.delete', 'users.invite',
  // Billing
  'billing.read', 'billing.write',
  // Settings
  'settings.read', 'settings.write',
  // Data (modulos de negocio)
  'data.read', 'data.write', 'data.delete',
  // Admin
  'admin.access', 'superadmin.access'
];
```

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /users | Listar usuarios |
| GET | /users/:id | Obtener usuario |
| POST | /users | Crear usuario |
| PUT | /users/:id | Actualizar usuario |
| DELETE | /users/:id | Eliminar usuario |
| POST | /users/invite | Enviar invitacion |
| GET | /invitations | Invitaciones pendientes |
| POST | /invitations/:token/accept | Aceptar invitacion |
| DELETE | /invitations/:id | Cancelar invitacion |
| GET | /roles | Listar roles |
| POST | /roles | Crear rol custom |
| PUT | /roles/:id | Actualizar rol |
| DELETE | /roles/:id | Eliminar rol |

## Flujos

### Invitar Usuario
```
1. Admin entra a Users > Invite
2. Ingresa email y selecciona rol
3. Sistema valida limite del plan
4. Genera token de invitacion
5. Envia email con link
6. Usuario acepta invitacion
7. Completa registro/login
8. Se agrega al tenant
```

### Verificar Permiso
```typescript
// Guard de permisos
@RequiresPermission('users.write')
async createUser(dto: CreateUserDto) {
  // Solo ejecuta si tiene permiso
}

// Service check
if (!user.hasPermission('billing.write')) {
  throw new ForbiddenException();
}
```

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| users.module.ts | Completado | `modules/users/` |
| rbac.module.ts | Completado | `modules/rbac/` |
| roles.guard.ts | Completado | `guards/` |
| DDL users schema | Completado | `ddl/schemas/users/` |

## Dependencias

### Depende de
- SAAS-001 (Auth)
- SAAS-002 (Tenants)
- SAAS-005 (Plans - para limites)

### Bloquea a
- SAAS-008 (Audit - quien hizo que)

## Criterios de Aceptacion

- [x] CRUD usuarios funciona
- [x] Invitaciones funcionan
- [x] Roles se asignan correctamente
- [x] Permisos se verifican
- [x] Limite de usuarios se respeta
- [x] Owner no puede ser eliminado

## Limites por Plan

| Plan | Max Usuarios |
|------|--------------|
| Free | 1 |
| Starter | 5 |
| Pro | 20 |
| Enterprise | Ilimitado |

---

**Ultima actualizacion:** 2026-01-10