Saltar a contenido

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_fase es 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 de integer), y descripcion hasta 255 caracteres: el error es un 422 y nunca llega a la base.
  • El listado se ordena por orden_fase y después por codigo, 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 codigo como 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*Request hereda 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.