template-saas/docs/01-modulos/SAAS-003-users.md

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

Roles Predefinidos

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

Permisos Disponibles

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

// 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

• CRUD usuarios funciona
• Invitaciones funcionan
• Roles se asignan correctamente
• Permisos se verifican
• Limite de usuarios se respeta
• Owner no puede ser eliminado

Limites por Plan

Plan	Max Usuarios
Free	1
Starter	5
Pro	20
Enterprise	Ilimitado

---

Ultima actualizacion: 2026-01-07