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 tienecliente_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:
/convertirno filtra, hace algo (crea o enlaza un cliente y cambia el prospecto); por eso tiene su ruta y es unPOST. - 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
PUTreemplaza la ficha; la conversión no cambia por ahí (422). - Conversión — «crea o enlaza», como propone el informe. En la URL va el
iddel prospecto; el cuerpo lleva uno de dos campos (422 si van los dos o ninguno): {"cliente": {…}}con los mismos campos quePOST /clientes: se inserta el cliente enmae_clientesy se enlaza el prospecto (cliente_idyfecha_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 usancrear_clientey 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¶
clientesexpone 40 operaciones; las 8 tablas del dominio tienen CRUD.- La conversión se puede medir:
?convertido=trueyfecha_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.