Sistema de Clientes

Tabla de Contenidos

1. Contexto de Negocio
2. Modelo de Datos
3. Ciclo de Vida del Cliente
4. Tenant Isolation
5. Relacion Client - Event
6. Asignacion de Responsable
7. Datos Fiscales
8. Adquisicion y Seguimiento
9. API y Permisos
10. Frontend (Admin Panel)

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 gestiona 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 organizacion. 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 intervencion humana para determinar el momento adecuado de cada transicion.

4. Tenant Isolation

Cada cliente pertenece a una sola organizacion a traves del campo organizationId. Esto significa que:

• Cada organizacion tiene su propia base de clientes — Un mismo cliente real que trabaje con dos organizaciones distintas tendra dos registros Client independientes.
• Las queries filtran por organizacion — El service filtra automaticamente por organizationId del usuario autenticado.
• El email es unico por organizacion — El constraint @@unique([email, organizationId]) permite que dos organizaciones tengan clientes con el mismo email.

Super Admin y organizacion

Cuando un Super Admin crea un cliente, debe seleccionar la organizacion destino mediante el OrganizationSelector. Para usuarios normales (Platform Admin, Org Owner, Org Admin), la organizacion se asigna automaticamente desde su contexto de autenticacion.

5. Relacion Client - Event

La relacion entre Client y Event es 1:N con FK nullable:

Reglas de la relacion

Vinculacion futura

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

1. Formulario de creacion 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 informacion del cliente vinculado

6. Asignacion de Responsable

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

Flujo en el Admin Panel

Reglas

• Solo se muestran usuarios activos de la organizacion correspondiente
• Al cambiar de organizacion (Super Admin), se limpia automaticamente 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 modulos que necesiten seleccionar un miembro del equipo

7. Datos Fiscales

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

Validacion del RFC

La validacion es basica (regex de formato). No incluye validacion ante el SAT (Servicio de Administracion Tributaria), que seria necesaria para un sistema de facturacion completo. Esto es suficiente para el MVP.

Relacion 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 informacion especifica 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 validacion frontend) permite al equipo registrar informacion relevante sobre el cliente: preferencias, historial de comunicaciones, acuerdos verbales, etc.

9. API y Permisos

Endpoints

Guards

Filtros de busqueda (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

Validacion Zod (client.ts)

Referencias

Archivos fuente (Backend)

Archivos fuente (Frontend)