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: unClienteRepositoryy unClienteServicecon una sección por tabla, igual quecatalogos(ADR 0008). El router se monta enapp/main.py. - Rutas planas por recurso de negocio bajo
/api/v1(/api/v1/grupos-economicos), con filtros porcliente_iden 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. AuditoriaCampospasa aapp/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
nombreadmite 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 validaClienteRepositoryleyendo las tablascat_*, 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
clientespara 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ó decat_amae_), la URL se rompe. - Todo bajo
/api/v1/clientes/...—/clientes/grupos-economicoschoca con/clientes/{cliente_id}y depende del orden de las rutas. - Copiar
AuditoriaCamposen 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¶
clientesexpone 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.