ADR-010: Registro de Usuario dentro del Pipeline de Originacion

Estado: Aceptada
Fecha: 2026-05-18
Autor: Equipo de Arquitectura

Contexto

El pipeline de originacion de credito (ADR-006) necesita registrar al solicitante como usuario en el realm de Keycloak del tenant. Esto permite que el solicitante pueda:

• Re-ingresar al sistema para consultar el estado de su solicitud
• Acceder al Client Portal para ver creditos, documentos y pagos
• Recibir notificaciones y comunicaciones personalizadas
• Iniciar nuevas solicitudes sin repetir el proceso de registro

Sin registro, el solicitante solo tiene acceso mediante un token temporal generado durante la originacion. Si pierde ese token o cierra el navegador, pierde acceso a su solicitud.

El registro tambien es el punto de creacion del perfil Subject 360: la entidad central que agrupa toda la informacion del solicitante a traves de los diferentes servicios de la plataforma.

Decision

El paso user_registration del pipeline crea un usuario en Keycloak (realm del tenant) con el rol applicant. El usuario puede re-ingresar al Client Portal para ver estado, creditos y documentos.

Flujo de Registro

Configuracion del Paso

{
  "type": "user_registration",
  "order": 2,
  "required": true,
  "config": {
    "fields": ["email", "phone", "full_name", "document_number"],
    "uniqueness_check": ["email", "phone"],
    "default_role": "applicant",
    "password_policy": "temporary",
    "send_welcome_email": true,
    "create_subject_360": true
  }
}

Validacion de Unicidad

Antes de crear el usuario, se valida que no exista otro usuario con el mismo email o telefono en el realm del tenant:

async execute(context: PipelineContext, config: StepConfig): Promise<StepResult> {
  const { email, phone } = context.applicantData;

  // Verificar unicidad en Keycloak
  const existingByEmail = await this.keycloak.findUser(context.tenantRealm, { email });
  const existingByPhone = await this.keycloak.findUser(context.tenantRealm, { phone });

  if (existingByEmail || existingByPhone) {
    // Usuario ya existe: vincular solicitud al usuario existente
    const existingUser = existingByEmail || existingByPhone;
    context.userId = existingUser.id;
    return { status: 'linked_existing', userId: existingUser.id };
  }

  // Crear nuevo usuario
  const user = await this.keycloak.createUser(context.tenantRealm, {
    email,
    phone,
    firstName: context.applicantData.firstName,
    lastName: context.applicantData.lastName,
    roles: [config.default_role],
    temporaryPassword: generateTemporaryPassword(),
  });

  // Crear perfil Subject 360
  if (config.create_subject_360) {
    await this.subject360.createProfile({
      userId: user.id,
      tenantId: context.tenantId,
      documentNumber: context.applicantData.document_number,
    });
  }

  context.userId = user.id;
  return { status: 'created', userId: user.id };
}

Roles y Permisos

Rol	Acceso
applicant	Ver estado de solicitud, descargar documentos propios, ver creditos
borrower	Todo lo de applicant + ver pagos, calendario, generar constancias
guest	Solo acceso temporal via token (sin registro)

El rol se promueve automaticamente de applicant a borrower cuando el credito es desembolsado.

Manejo de Registros Abandonados

Los usuarios que se registran pero no completan el pipeline se marcan como abandoned despues de N dias (configurable). Un job periodico:

1. Identifica usuarios con rol applicant sin credito activo por mas de 30 dias
2. Los marca como inactive en Keycloak (no se eliminan)
3. Envia notificacion de "retoma tu solicitud" antes de desactivar

Alternativas Consideradas

Alternativa	Pros	Contras
Sin registro (acceso anonimo via token)	Simple, sin gestion de usuarios	El solicitante pierde acceso si pierde el token, no hay Client Portal
Registro solo despues de aprobacion	Menos usuarios en Keycloak	Mala UX: el solicitante no puede consultar estado durante el proceso
Flujo de registro separado fuera del pipeline	Separacion de concerns	Friccion adicional, dos flujos distintos, peor conversion
Registro dentro del pipeline (elegida)	UX fluida, habilita Client Portal, crea Subject 360	Mas usuarios en Keycloak, necesita manejar abandonos

Consecuencias

Positivas

• Mejor UX: el solicitante puede regresar en cualquier momento a consultar su estado
• Habilita el Client Portal como canal de autoservicio
• Crea el perfil Subject 360 desde el primer contacto (vision unificada del cliente)
• Permite comunicaciones personalizadas (email, push, SMS)
• Facilita solicitudes futuras: el usuario ya existe, no repite registro

Negativas

• Mayor volumen de usuarios en Keycloak (costo de licenciamiento si aplica, gestion)
• Necesidad de manejar registros abandonados (usuarios que nunca completan el proceso)
• Complejidad adicional en la validacion de unicidad (merge de perfiles duplicados)

Riesgos

• Acumulacion de usuarios inactivos en Keycloak si no se implementa limpieza (mitigacion: job de desactivacion periodica)
• Duplicados si el mismo solicitante usa diferentes emails/telefonos (mitigacion: validacion por documento de identidad)
• GDPR/proteccion de datos: usuarios abandonados retienen datos personales (mitigacion: politica de retencion configurable por tenant)

Referencias

• ADR-006: Pipeline Configurable de Originacion
• Keycloak User Management API
• Subject 360 - Architecture