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.
IMPImportadores): 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: enumMagnitudEmpresacongrande,medianaypequena. 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 unENUMnativo de PostgreSQL: cambiar unENUMnativo 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 enCliente, 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 acat_canales_comerciales, con FK compuesta(empresa_id, canal_comercial_id)comoestado_prospecto_idy 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
Seguimientodel prospecto ("Producto ofrecido", "Tamaño", "Número de documento" y "Canal comercial"; el canal se nombra connombres_de_tabla("cat_canales_comerciales")). - Conversión: el backend no copia nada al cliente; el formulario de
conversión del frontend propone el
numero_documentoy 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).
marcano viaja al cliente: el formulario de conversión deja de proponerla comonombre_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
PUTreemplaza la ficha: un frontend que no envíe los campos nuevos los deja enNULL. El frontend debe desplegarse junto con el backend. - En core-frontend,
ConvertirProspectoDialogya no precarganombre_comercialconprospecto.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);marcaes 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.