Saltar a contenido

0015. Dominio catalogos y CRUD estándar de un catálogo

Estado: Parcialmente reemplazado por ADR 0018; complementado por ADR 0016, ADR 0017, ADR 0019, ADR 0020

Fecha: 2026-10-06

Autor: David Garcia

Módulo(s) afectado(s): app/domains/catalogos/, app/shared/schemas.py, app/main.py, alembic/versions/

Modificado por: ADR 0018 — el listado excluye los borrados por defecto (?estado=)

Complementado por: ADR 0016 — agrega cat_tipos_actividad; ADR 0017 — agrega cat_metodos_pago; ADR 0019 — agrega cat_estados_visita; ADR 0020 — agrega cat_estados_cobro

Contexto

El modelo de datos trae doce catálogos cat_* (tipos de promotor, estados de visita, métodos de pago...). Los usan varios de los cuatro dominios del ADR 0002, y un dominio no puede importar de otro. Además, éste es el primer endpoint del servicio: falta fijar cómo se monta la API y quién llena la auditoría.

Decisión

  • Los catálogos viven en un dominio propio, app/domains/catalogos/, con una sección por catálogo en cada archivo, como en crm-svc-clientes.
  • CRUD estándar bajo /api/v1/catalogos/<catalogo>: el listado y GET /{id} incluyen los borrados; el código es único por empresa aunque esté borrado (409) y no se edita; DELETE es borrado lógico (deleted_at, is_activo = false).
  • empresa_id no se asigna en el código: la pone el default de la base (ADR 0006). created_by / updated_by los asigna el service con el usuario del token.
  • Router padre /api/v1 en app/main.py con la dependencia autorizar (ADR 0009): todo dominio se monta en él.
  • AuditoriaResponse y CONFIG_ENTRADA van en app/shared/schemas.py.

Catálogos implementados

Tabla Ruta (/api/v1/catalogos/...) Migración
cat_tipos_promotor tipos-promotor 20261006_001
cat_modalidades_pago_comision modalidades-pago-comision 20261006_002
cat_tipos_equipo tipos-equipo 20261006_003
cat_estados_equipo estados-equipo 20261006_004
cat_estados_requerimiento_visita estados-requerimiento-visita 20261006_005
cat_prioridades_requerimiento prioridades-requerimiento 20261006_006
cat_tipos_evidencia_visita tipos-evidencia-visita 20261006_007
cat_tipos_requerimiento_visita tipos-requerimiento-visita 20261006_008

Pendientes, por tener campos propios además de codigo y nombre: cat_estados_visita, cat_tipos_actividad, cat_metodos_pago y cat_estados_cobro.

Alternativas descartadas

  • Cada catálogo en el dominio que lo usa — un catálogo usado por dos dominios obligaría a importar entre ellos.
  • Pasar empresa_id desde el router, como hace clientes — duplica lo que ya hace el default y abre la puerta a asignar otra empresa.

Consecuencias

  • Un dominio referencia un catálogo sólo por FK en la base, no importando su modelo.
  • El código repetido se comprueba antes de insertar: dos altas simultáneas con el mismo código terminan en 500 (por el UNIQUE) en vez de 409.
  • Borrar un catálogo referenciado no se impide todavía; se resuelve cuando exista la primera tabla que lo use.

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.