Sistema de Clientes

1. Contexto de Negocio

El modelo de negocio de Nvito es servicio directo al cliente: una persona o empresa contacta a Nvito, contrata un paquete de servicios, y el equipo gestióna su evento. La entidad Client representa a la persona o empresa que contrata y paga por los servicios de evento.

Problemas que resuelve

2. Modelo de Datos

Entidad Client

Enums

ClientType:

ClientStatus:

AcquisitionSource:

Indices

Constraint Unico

(email, organization_id) — Un cliente no puede tener el mismo email dentro de la misma organización. Los valores NULL en email no participan en la unicidad (comportamiento nativo de PostgreSQL).

3. Ciclo de Vida del Cliente

Transiciones

Nota: Las transiciones de estado son manuales (el equipo de Nvito actualiza el estado). No hay automatizacion por ahora, ya que el ciclo comercial requiere intervención humana para determinar el momento adecuado de cada transición.

4. Tenant Isolation

Cada cliente pertenece a una sola organización a traves del campo organizationId. Esto significa que:

• Cada organización tiene su propia base de clientes — Un mismo cliente real que trabaje con dos organizaciones distintas tendrá dos registros Client independientes.
• Las queries filtran por organización — El service filtra automáticamente por organizationId del usuario autenticado.
• El email es único por organización — El constraint @@unique([email, organizationId]) permite que dos organizaciones tengan clientes con el mismo email.

Super Admin y organización

Cuando un Super Admin crea un cliente, debe seleccionar la organización destino mediante el OrganizationSelector. Para usuarios normales (Platform Admin, Org Owner, Org Admin), la organización se asigna automáticamente desde su contexto de autenticación.

5. Relación Client - Event

La relación entre Client y Event es 1:N con FK nullable:

Reglas de la relación

Vinculacion futura

La Fase 5 del plan (pendiente) conectara el selector de cliente directamente en:

1. Formulario de creación de evento — Campo autocomplete para vincular un cliente existente
2. Formulario de contrato — Auto-popular datos del cliente si el evento ya tiene uno vinculado
3. Detalle del evento — Mostrar información del cliente vinculado

6. Asignación de Responsable

El campo assignedToId es una FK a User que representa al miembro del equipo responsable de la relación con el cliente.

Flujo en el Admin Panel

Reglas

• Solo se muestran usuarios activos de la organización correspondiente
• Al cambiar de organización (Super Admin), se limpia automáticamente el responsable seleccionado
• Si el usuario asignado es dado de baja, el onDelete: SetNull en la FK pone assignedToId en NULL
• El componente MemberSelector es reutilizable para otros módulos que necesiten seleccionar un miembro del equipo

7. Datos Fiscales

Los datos fiscales son opcionales y estan pensados para el contexto fiscal mexicano (CFDI):

Validación del RFC

La validación es básica (regex de formato). No incluye validación ante el SAT (Servicio de Administración Tributaria), que seria necesaria para un sistema de facturacion completo. Esto es suficiente para el MVP.

Relación con tipo de cliente

• INDIVIDUAL: RFC de 13 caracteres (4 letras + 6 digitos + 3 alfanumericos)
• COMPANY: RFC de 12 caracteres (3 letras + 6 digitos + 3 alfanumericos)

Los campos fiscales son opcionales independientemente del tipo de cliente, pero son particularmente relevantes para clientes de tipo COMPANY.

8. Adquisicion y Seguimiento

Fuentes de adquisicion

El campo acquisitionSource permite rastrear de donde viene cada cliente para medir la efectividad de los canales de marketing:

El campo acquisitionDetail (VARCHAR 255) complementa la fuente con información específica como el nombre del referido, la campana publicitaria o el evento donde se conocio al cliente.

Notas internas

El campo notes (TEXT, max 2000 caracteres en validación frontend) permite al equipo registrar información relevante sobre el cliente: preferencias, historial de comunicaciones, acuerdos verbales, etc.

9. API y Permisos

Endpoints

Guards

Filtros de búsqueda (GET /admin/clients)

Respuesta paginada

{
  "data": [
    {
      "id": "uuid",
      "name": "Juan Perez",
      "email": "juan@example.com",
      "type": "INDIVIDUAL",
      "status": "ACTIVE",
      "assignedTo": { "id": "uuid", "firstName": "Ana", "lastName": "Garcia" },
      "_count": { "events": 2 }
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

10. Frontend (Admin Panel)

Componentes

Hooks de React Query

Server Actions

Validación Zod (client.ts)

Referencias

Archivos fuente (Backend)

Archivos fuente (Frontend)