Saltar a contenido

0020. Catálogo cat_estados_cobro: columna tipo en vez de banderas

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

Contexto

Cada empresa define sus estados de cobro con el código y el nombre que quiera, pero la lógica de cobros (trx_avisos_cobro, trx_cobros_campo) necesita saber qué estado recibe un cobro nuevo y cuáles lo cierran. El borrador del modelo de datos lo resuelve con tres banderas obligatorias (is_inicial, is_conciliado, is_final) que admiten combinaciones sin sentido: dos iniciales, o un estado inicial y final a la vez.

Decisión

  • Una columna tipo reemplaza las tres banderas, con valores fijos del sistema: INICIAL, EN_PROCESO, CONCILIADO y ANULADO. CONCILIADO y ANULADO son finales, sin guardarlo aparte. Se guarda como VARCHAR(20) con un CHECK (ck_cat_estados_cobro_tipo), no como un ENUM de PostgreSQL.
  • tipo es obligatorio y editable; otro valor, o uno en minúsculas, responde 422.
  • Un solo estado INICIAL sin borrar por empresa. El service responde 409 al crear un segundo o al pasar otro a INICIAL, y un índice UNIQUE parcial (uq_cat_estados_cobro_empresa_inicial) lo garantiza en la base. Los borrados no cuentan.
  • orden sigue el criterio del ADR 0019.
Tabla Ruta (/api/v1/catalogos/...) Migración
cat_estados_cobro estados-cobro 20261007_004

Alternativas descartadas

  • Las tres banderas del borrador — exigen validaciones cruzadas para impedir combinaciones inválidas.
  • Reconocer el estado por su código — obligaría a códigos fijos en todas las empresas, y el catálogo dejaría de ser configurable.
  • ENUM de PostgreSQL — agregar un valor requiere ALTER TYPE, que tiene restricciones dentro de una transacción; cambiar un CHECK no.

Consecuencias

  • Mover el estado inicial a otro estado requiere dos PUT: primero quitarle INICIAL al actual y después dárselo al nuevo.
  • No se exige que exista un estado INICIAL. Crear un cobro sin él se validará en la lógica de cobros.
  • Cambiar el tipo de un estado ya usado por cobros cambia su significado. Se revisará al crear las tablas de cobros, junto con el borrado de un catálogo referenciado (ADR 0015).
  • Dos altas simultáneas de un INICIAL terminan en 500 por el índice, como ya pasa con el código repetido.

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.