Saltar a contenido

0019. Catálogo cat_estados_visita: orden como orden de presentación

Estado: Aceptado Fecha: 2026-10-07 Autor: David Garcia Módulo(s) afectado(s): app/domains/catalogos/, alembic/versions/20261007_003_crear_cat_estados_visita.py Complementa a: ADR 0015

Contexto

cat_estados_visita define las etapas de una visita (programada, en curso, finalizada...). Además de codigo y nombre trae color_hex (opcional) y orden (INT NOT NULL, sin default ni comentario en el borrador del modelo de datos). Los catálogos se listan por codigo, lo que para estados da un orden alfabético sin relación con el flujo. cat_estados_cobro tiene el mismo campo.

Decisión

  • orden es sólo el orden de presentación (desplegables, columnas de un tablero, indicador de pasos). No define qué transiciones de estado son válidas.
  • El listado ordena por orden y, a igualdad, por codigo.
  • Opcional, entero ≥ 0, con 0 por defecto en la API y en la base (server_default 0), con el criterio de los booleanos de los ADR 0016 y
  • El máximo es el de INT. Es editable, y el PUT que lo omite lo deja en 0.
  • Puede repetirse: no lleva UNIQUE.
  • color_hex se valida como en cat_tipos_actividad (ADR 0016).
Tabla Ruta (/api/v1/catalogos/...) Migración
cat_estados_visita estados-visita 20261007_003

Alternativas descartadas

  • orden obligatorio en la entrada, como en el borrador — obliga a enviar un número aunque la empresa no lo use.
  • UNIQUE por empresa — intercambiar dos estados (1↔2) obligaría a pasar por un valor temporal.
  • Eliminar orden — el frontend tendría que fijar el orden por código de estado, y cada empresa define sus propios estados.

Consecuencias

  • Los estados sin orden quedan primero (0) y ordenados por código.
  • El frontend debe enviar en el PUT el orden vigente; si lo omite, vuelve a 0.
  • Las reglas de transición entre estados, si se necesitan, se deciden aparte.
  • cat_estados_cobro aplicará el mismo criterio para su orden.

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.