0011. CRUD de los catálogos — tercer slice: estados de prospecto¶
Estado: Propuesto Fecha: 2026-09-30 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/catalogos/, tests/unit/catalogos/
Contexto¶
Sigue el molde del ADR 0008. cat_estados_prospecto es el primer catálogo con
un campo propio: orden_fase (integer, CHECK orden_fase > 0, índice
(empresa_id, orden_fase)), y su descripción es varchar(255) en lugar de
text (docs-sql). Las fases reales y su orden aún deben validarse con el
negocio, así que el CRUD no trae datos iniciales.
Decisión¶
- Endpoints bajo
/api/v1/catalogos/estados-prospecto, con los mismos códigos y reglas que canales comerciales (ADR 0008). orden_fasees obligatorio al crear y al actualizar, y sí es editable (reordenar el embudo). El contrato lo valida entre 1 y 2 147 483 647 (tope deinteger), ydescripcionhasta 255 caracteres: el error es un 422 y nunca llega a la base.- El listado se ordena por
orden_fasey después porcodigo, aprovechando el índice de la tabla. - Dos fases pueden tener el mismo
orden_fase: docs-sql no lo declara único.
Alternativas descartadas¶
orden_faseúnico por empresa — docs-sql no lo define y reordenar obligaría a mover varias filas en una transacción.- Dejar que la base rechace el orden o la descripción inválidos — el CHECK
o el
varchar(255)darían un 500 en lugar de un 422 claro. - Ordenar por
codigocomo los demás catálogos — el embudo se lee por fase, no alfabéticamente.
Consecuencias¶
- La API expone 15 operaciones de catálogos (3 catálogos × 5).
EstadoProspecto*Requesthereda de las bases de catálogo y agrega o restringe sus campos; el molde admite campos propios sin romperse.- Las fases (
NUEVO,EN_CALIFICACION…) se cargan cuando el negocio las valide.
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.