Saltar a contenido

0024. Dominio clientes — octavo slice: prospectos y su conversión

Estado: Propuesto Fecha: 2026-10-01 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/clientes/, tests/unit/clientes/

Contexto

mae_prospectos registra posibles clientes con su estado (catálogo), ciudad y promotor (UUID de otros servicios). Al convertirse guarda cliente_id y fecha_conversion (los dos o ninguno; cliente_id único). docs-sql pide crear el cliente y enlazarlo en una sola transacción, y que la conversión no se deshaga. En el SIGFAPRO anterior (CambiarProsACliente) «marcar como cliente» sólo cambiaba in_cliente: no creaba ni enlazaba el cliente, y no se podía medir la conversión (informe gerencial del 30/09/2026).

Decisión

  • Rutas (tag clientes-maestras):
Método y ruta Qué hace
GET /api/v1/prospectos Lista, del más reciente al más antiguo (también los borrados)
GET /api/v1/prospectos/{id} Devuelve uno (404 si no existe)
POST /api/v1/prospectos Registra un prospecto (201)
PUT /api/v1/prospectos/{id} Reemplaza su ficha (200)
POST /api/v1/prospectos/{id}/convertir Lo convierte en cliente (200)
DELETE /api/v1/prospectos/{id} Borrado lógico (204)
  • Filtros del listado, opcionales y combinables en el mismo GET: ?estado_prospecto_id=<uuid> (fase del embudo), ?promotor_id=<uuid> (promotor asignado) y ?convertido=true|false (si ya tiene cliente_id). Sin filtros devuelve todos; con varios se aplican juntos (por ejemplo, ?promotor_id=X&convertido=false: los pendientes de ese promotor). Es la convención REST: la ruta nombra el recurso y el query string lo filtra, igual que en locales, vínculos, perfiles y asignaciones.
  • Endpoint aparte sólo para acciones: /convertir no filtra, hace algo (crea o enlaza un cliente y cambia el prospecto); por eso tiene su ruta y es un POST.
  • Al crear: estado existente (404) y activo (409); 409 si otro prospecto activo tiene el mismo nombre exacto, sin distinguir mayúsculas (la versión correcta de la regla anterior, que comparaba con ILIKE '%…%').
  • El PUT reemplaza la ficha; la conversión no cambia por ahí (422).
  • Conversión — «crea o enlaza», como propone el informe. En la URL va el id del prospecto; el cuerpo lleva uno de dos campos (422 si van los dos o ninguno):
  • {"cliente": {…}} con los mismos campos que POST /clientes: se inserta el cliente en mae_clientes y se enlaza el prospecto (cliente_id y fecha_conversion = hoy) en la misma transacción; si algo falla no queda ni el cliente ni la conversión.
  • {"cliente_id": "…"}: enlaza un cliente existente, activo y que no venga de otro prospecto (por ejemplo, uno registrado a mano antes).
  • Se convierte una sola vez (409) y nunca si el prospecto está borrado.
  • Las reglas del cliente nuevo están en _validar_cliente_nuevo, que usan crear_cliente y la conversión: única excepción a «sin helpers» en el service, porque es la misma validación en dos casos de uso.
  • No se validan transiciones de estado (DESCARTADO…) hasta que el negocio defina los estados. Borrar un prospecto conserva su vínculo con el cliente.

Alternativas descartadas

  • Un endpoint por filtro (/prospectos/convertidos, /prospectos/por-promotor/{id}…) — no se pueden combinar sin crear una ruta por cada combinación, repite casi la misma consulta en cada función y cada filtro nuevo cambiaría la URL que usa el frontend.
  • Sólo enlazar un cliente ya creado — dos transacciones: si la segunda falla, queda un cliente sin su prospecto.
  • Copiar las validaciones del cliente en la conversión — ~70 líneas duplicadas que se desincronizarían.
  • Duplicado por coincidencia parcial del nombre — rechazaba nombres válidos y dejaba pasar duplicados (informe, práctica 7).

Consecuencias

  • clientes expone 40 operaciones; las 8 tablas del dominio tienen CRUD.
  • La conversión se puede medir: ?convertido=true y fecha_conversion.
  • Pendientes: agenda y actividades (fuerza de ventas), carga masiva Excel, permisos por rol, catálogos de país, canal y marca, y varios contactos por prospecto (docs-sql). El informe pide confirmar con exportación si la opción se necesita.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.