Saltar a contenido

0033. Datos comerciales del prospecto

Estado: Aceptado Fecha: 2026-10-29 Autor: David Garcia Módulo(s) afectado(s): app/domains/clientes/, alembic/versions/, tests/unit/clientes/

Contexto

Comercial pide cuatro datos nuevos en el prospecto, todos opcionales:

  • Producto que le ofrecemos: hoy no se sabe con qué llegarle a cada empresa. Ejemplos: "atún", "conserva", "industrial", "marca privada".
  • Tamaño (Grande / Mediana / Pequeña): para priorizar a quién atender primero. En el legacy era el catálogo i130t_magnitud_empresa; la ficha de cliente nueva todavía no lo tiene.
  • RUC/NIT: más adelante "Verificar prospectos" lo comparará contra la cartera de clientes, porque comparar sólo por nombre falla cuando el mismo cliente está escrito distinto.
  • Canal comercial (ej. IMP Importadores): lo necesita la fase siguiente para filtrar la lista de prospectos por canal.

marca ya existe y no cambia: es la marca (o las marcas) con que el prospecto vende, ej. ANDINA S.A. vende bajo la marca VANDINA (VANDINA ATÚN, VANDINA SARDINA). No es lo que le ofrecemos.

Decisión

Cuatro columnas nuevas y opcionales en clientes.mae_prospectos. Entran en ProspectoCrearRequest y ProspectoActualizarRequest (los dos heredan de _DatosProspecto) y salen en ProspectoResponse.

  • producto_ofrecido: texto libre, varchar(200).
  • Los ejemplos mezclan producto, categoría, segmento y modelo comercial: una lista cerrada obligaría a inventar una clasificación que negocio aún no tiene.
  • Es una nota para el vendedor, no un dato para filtrar ni reportar.
  • magnitud: enum MagnitudEmpresa con grande, mediana y pequena. Sin sufijo _prospecto: ya vive en la tabla de prospectos, y el cliente usará el mismo nombre cuando lo tenga.
  • En la base es varchar(10) con un CHECK sobre los tres valores, no un ENUM nativo de PostgreSQL: cambiar un ENUM nativo con Alembic es incómodo y el repo ya expresa sus reglas con CHECK.
  • Se guardan valores estables; el texto que se muestra ("Grande") lo pone el frontend.
  • El enum lleva nombre genérico para que la ficha de cliente lo reutilice cuando lo tenga.
  • numero_documento: RUC/NIT normalizado, varchar(20). Mismo nombre que en Cliente, para que la conversión lo pueda proponer tal cual.
  • Antes de validar se quitan espacios, puntos y guiones y se pasa a mayúsculas: "0990012345 001" → "0990012345001", "900.123.456-7" → "9001234567".
  • Ya normalizado debe ser alfanumérico de 5 a 20 caracteres; si no, 422. Un CHECK en la base exige lo mismo.
  • No se valida el dígito verificador: depende del país y el prospecto puede ser de cualquiera.
  • No es único: dos prospectos con el mismo documento son justo lo que "Verificar prospectos" debe detectar.
  • canal_comercial_id: referencia a cat_canales_comerciales, con FK compuesta (empresa_id, canal_comercial_id) como estado_prospecto_id y un índice (empresa_id, canal_comercial_id).
  • El service valida que el canal exista (404) y no esté borrado (409), con la misma regla que el estado del prospecto.
  • El prospecto lleva el canal, no el tipo de canal que pide el cliente: al prospectar se sabe que es un importador, no todavía su subtipo.
  • Historial: los cuatro campos entran en el Seguimiento del prospecto ("Producto ofrecido", "Tamaño", "Número de documento" y "Canal comercial"; el canal se nombra con nombres_de_tabla("cat_canales_comerciales")).
  • Conversión: el backend no copia nada al cliente; el formulario de conversión del frontend propone el numero_documento y limita los tipos de canal a los del canal del prospecto, con opción de ver todos.
  • No se exige que el tipo de canal del cliente pertenezca al canal del prospecto.
  • El canal del prospecto es lo que se supuso al prospectar; tras la conversión manda el del cliente, y la diferencia muestra cuántos prospectos se clasificaron mal.
  • Cambiar de canal al cerrar es un caso real (se creía importador y es distribuidor); exigirlo obligaría a editar el prospecto antes de convertir.
  • Al enlazar un cliente existente (cliente_id) no se puede exigir: ese cliente ya tiene su tipo de canal.
  • Se revisa si el canal empieza a gobernar algo que el cliente debe respetar: carteras o promotores por canal, metas o comisiones por canal, precios o aprobaciones por canal, o reportes oficiales de conversión por canal. Entonces se exigiría sólo al crear un cliente nuevo desde un prospecto con canal, y cambiar de canal pasaría por corregir antes el prospecto (queda en el historial).
  • marca no viaja al cliente: el formulario de conversión deja de proponerla como nombre_comercial. La marca es con qué vende el prospecto (puede tener varias); el nombre comercial del cliente es otro dato y se escribe al convertir.

Alternativas descartadas

  • Producto como catálogo o lista de grupos de producto: queda para cuando haga falta filtrar o reportar por producto; entonces se migra a una relación con los grupos de core-svc-api-productos y el texto queda como nota.
  • Tamaño como catálogo por empresa (como en el legacy): tres valores fijos que no administra nadie no justifican una tabla, endpoints y permisos.
  • Guardar el documento tal como se escribe: obligaría a normalizar en cada comparación y no se podría indexar sin una expresión.
  • Tipo de canal en vez de canal: pide un detalle que al prospectar no se conoce.
  • Exigir que el tipo de canal del cliente sea del canal del prospecto: agrega fricción sin que hoy el canal gobierne nada (ver la decisión).

Consecuencias

  • Migración con cuatro columnas NULL, sin datos que mover.
  • El PUT reemplaza la ficha: un frontend que no envíe los campos nuevos los deja en NULL. El frontend debe desplegarse junto con el backend.
  • En core-frontend, ConvertirProspectoDialog ya no precarga nombre_comercial con prospecto.marca.
  • Quedan para otras fases:
  • Filtros por país, canal y marca (fase siguiente). El país sale de ciudad_id (ciudad → provincia → país en identidad); marca es texto libre y puede tener varias marcas, así que conviene filtrar por "contiene" y no por lista de valores.
  • "Verificar prospectos" y sus reglas de coincidencia por documento (RUC contra cédula, NIT con o sin dígito verificador).
  • Tamaño en la ficha de cliente y copiarlo al convertir.