Saltar a contenido

0017. Dominio clientes — primer slice: grupos económicos

Estado: Propuesto Fecha: 2026-09-30 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/clientes/, app/shared/schemas.py, app/main.py, tests/unit/clientes/

Contexto

Con los 8 catálogos completos (ADR 0008 a 0016) empieza el dominio clientes: 8 tablas (mae_*, trx_*, rel_*) que ya tienen modelo y migración con RLS, pero ningún endpoint. mae_grupos_economicos no depende de nada, así que abre el dominio y fija su molde. svc-identidad y svc-fuerza-ventas aún no están disponibles.

Decisión

  • Un solo dominio clientes, como define la estructura de la plataforma: un ClienteRepository y un ClienteService con una sección por tabla, igual que catalogos (ADR 0008). El router se monta en app/main.py.
  • Rutas planas por recurso de negocio bajo /api/v1 (/api/v1/grupos-economicos), con filtros por cliente_id en las tablas que cuelguen del cliente. Swagger y Orval se ordenan con tags por tipo de tabla (clientes-maestras, clientes-transaccionales, clientes-relaciones), un sub-router por grupo; la URL no cambia.
  • AuditoriaCampos pasa a app/shared/schemas.py: ya la usan dos dominios (ADR 0005).
  • Borrado lógico visible, como en los catálogos: el scope global que oculta los borrados en svc-identidad (su ADR 0015) no se adopta.
  • Grupos económicos: CRUD con los códigos y reglas del ADR 0008; el nombre admite 150 caracteres (docs-sql).
  • Para los slices siguientes: los UUID de otros servicios (ciudad_id, tipo_identificacion_id, promotor_id) se aceptan sin validar hasta que esos servicios existan; las referencias a catálogos las valida ClienteRepository leyendo las tablas cat_*, como hace el repository de empresas en svc-identidad (su ADR 0016).

Alternativas descartadas

  • Un dominio por tabla — la estructura de la plataforma define un solo dominio clientes para este servicio.
  • URL por tipo de tabla (/api/v1/maestras/...) — expone la clasificación de la base; si una tabla cambia de tipo (grupos pasó de cat_ a mae_), la URL se rompe.
  • Todo bajo /api/v1/clientes/... — /clientes/grupos-economicos choca con /clientes/{cliente_id} y depende del orden de las rutas.
  • Copiar AuditoriaCampos en cada dominio — la misma clase repetida.
  • Validar ya los UUID de otros servicios — no hay servicio contra el cual validarlos; bloquearía el avance.

Consecuencias

  • clientes expone 5 operaciones; los catálogos siguen en 40.
  • La regla "un grupo con clientes activos no se borra" se evalúa al agregar el CRUD de mae_clientes.
  • Cuando existan identidad y fuerza de ventas, un ADR nuevo definirá cómo se validan sus UUID (evento o consulta).

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.