# RF-MGN-001-006: Registro de Usuarios (Signup)

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

## Descripción

El sistema debe permitir a nuevos usuarios registrarse de forma self-service con validación de email. Aplica para modelos SaaS donde usuarios pueden crear su propia cuenta.

## Actores

- **Actor Principal:** Usuario nuevo (no registrado)
- **Actores Secundarios:** Sistema de Email

## Precondiciones

1. Tenant debe permitir registro público (tenant.allow_signup=true)
2. Sistema de email debe estar configurado
3. Base de datos debe estar disponible

## Flujo Principal

1. Usuario accede a página de registro (/signup)
2. Usuario ingresa: nombre, email, contraseña, confirmación de contraseña
3. Sistema valida que email sea único en el tenant
4. Sistema valida política de contraseña
5. Sistema hashea contraseña con bcrypt
6. Sistema crea usuario con status='pending_verification'
7. Sistema asigna rol por defecto (ej: "User" con permisos básicos)
8. Sistema genera token de verificación de email (UUID, expira en 48h)
9. Sistema guarda token en auth.email_verification_tokens
10. Sistema envía email con link de verificación
11. Usuario recibe email y hace clic en link
12. Sistema valida token
13. Sistema actualiza user.status='active' y user.email_verified=true
14. Sistema marca token como usado
15. Usuario puede iniciar sesión normalmente

## Flujos Alternativos

### FA-1: Email Ya Registrado
1. Si email ya existe en tenant
2. Sistema retorna error 400: "Email ya está registrado"
3. Sistema sugiere "¿Olvidaste tu contraseña?"

### FA-2: Contraseña Débil
1. Si contraseña no cumple política
2. Sistema retorna error 400: "Contraseña debe tener 8+ caracteres, mayúscula, número, símbolo"

### FA-3: Confirmación de Contraseña No Coincide
1. Si password != password_confirmation
2. Sistema retorna error 400: "Las contraseñas no coinciden"

### FA-4: Tenant No Permite Signup
1. Si tenant.allow_signup=false
2. Sistema retorna error 403: "Registro deshabilitado. Contacte al administrador"

### FA-5: Token de Verificación Expirado
1. Usuario hace clic en link después de 48h
2. Sistema retorna error 400: "Token expirado"
3. Sistema ofrece reenviar email de verificación

### FA-6: Usuario Intenta Login Sin Verificar Email
1. Usuario con status='pending_verification' intenta login
2. Sistema retorna error 403: "Verifique su email antes de iniciar sesión"
3. Sistema ofrece reenviar email de verificación

### FA-7: Reenvío de Email de Verificación
1. Usuario solicita reenvío de email
2. Sistema invalida token anterior
3. Sistema genera nuevo token (expira en 48h)
4. Sistema envía nuevo email

## Reglas de Negocio

- **RN-1:** Email debe ser único por tenant
- **RN-2:** Contraseña debe cumplir política de seguridad
- **RN-3:** Usuario creado con status='pending_verification'
- **RN-4:** Token de verificación expira en 48 horas
- **RN-5:** Usuario debe verificar email antes de poder iniciar sesión
- **RN-6:** Rol por defecto en signup: "User" (permisos básicos de lectura)
- **RN-7:** Signup puede deshabilitarse por tenant (allow_signup=false)
- **RN-8:** Máximo 5 intentos de signup por IP por hora (rate limiting)

## Criterios de Aceptación

- [ ] Usuario puede registrarse con nombre, email y contraseña
- [ ] Sistema valida unicidad de email
- [ ] Sistema valida política de contraseña
- [ ] Sistema envía email de verificación con token válido por 48h
- [ ] Usuario puede verificar su email usando token
- [ ] Usuario verificado puede iniciar sesión
- [ ] Usuario sin verificar NO puede iniciar sesión
- [ ] Sistema asigna rol por defecto "User"
- [ ] Tenant puede deshabilitar signup público
- [ ] Rate limiting previene abuso (max 5 signups/hora por IP)
- [ ] Usuario puede solicitar reenvío de email de verificación

## Entidades Involucradas

- **Principales:**
  - auth.users (email, password_hash, name, status, email_verified)
  - auth.email_verification_tokens (token, user_id, expires_at, used_at)
- **Relacionadas:**
  - auth.tenants (allow_signup)
  - auth.roles (rol por defecto)
  - auth.user_roles (asignación de rol)

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

- **Email Template:**
  ```
  ¡Bienvenido {{user.name}}!

  Gracias por registrarte. Para completar tu registro, verifica tu email:

  {{verification_link}}

  Este enlace expira en 48 horas.
  ```
- **Validación Frontend:**
  - Email: formato válido
  - Contraseña: indicador de fortaleza visual
  - Confirmación: validación en tiempo real
- **Rate Limiting:** Por IP + por email (prevenir abuso)
- **CAPTCHA:** Considerar reCAPTCHA para prevenir bots (P1)
- **Backend:** NestJS AuthService.signup()
- **Frontend:** Formulario de registro con validación

## Dependencias

- **RF Dependientes:** RF-MGN-001-001 (Autenticación)
- **Bloqueante para:** Ninguno (funcionalidad opcional)