0019. Dominio clientes — tercer slice: clientes¶
Estado: Propuesto Fecha: 2026-09-30 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/clientes/, tests/unit/clientes/
Contexto¶
mae_clientes es la tabla central del servicio. Referencia 5 catálogos
(tipo_cliente_id y tipo_canal_id obligatorios; clase, modelo y unidad
opcionales), un grupo económico opcional, un tipo_identificacion_id de
svc-identidad y un contacto_principal_id que exige un vínculo en
rel_clientes_contactos. Son únicos por empresa el codigo y el documento
(tipo_identificacion_id + numero_documento), aunque el cliente esté
borrado. Puede haber miles de clientes por empresa.
Decisión¶
- Endpoints bajo
/api/v1/clientes(tagclientes-maestras). El listado se ordena porcodigoy por ahora no se pagina: la paginación se definirá con un formato único para todos los servicios de la plataforma. - Referencias: el service valida que cada catálogo y el grupo existan (404)
y estén activos (409). Para leer los catálogos,
ClienteRepositoryimportacatalogos.modelssólo para leer: única excepción a «un dominio no importa de otro», como el repository de empresas en svc-identidad. - Al actualizar se validan sólo las referencias que cambian: si un catálogo que el cliente ya tenía se borró después, editar otros datos sigue posible.
- Código repetido o documento repetido → 409. El documento se puede corregir
por
PUT; el código no. fecha_registroes opcional al crear (hoy por defecto) y obligatoria en elPUT, que reemplaza la ficha.tipo_identificacion_idse acepta sin validar ni revisar el formato del número hasta integrar svc-identidad (ADR 0017).- La respuesta trae el nombre de cada referencia junto a su
*_id:tipo_cliente,tipo_canal,clase_cliente,modelo_comercial,grupo_economicoyunidad_comercial(sólotipo_identificacion_id, que vive en svc-identidad, va sin nombre).Clientetiene una relación por cada una (tipo_cliente,tipo_canal,clase_cliente,modelo_comercial,grupo_economico,unidad_comercial) (relationship(viewonly=True, lazy="raise"), sólo enclientes/models.py); el repository las carga conjoinedload(lista_REFERENCIAS_CLIENTE) en el listado, el detalle y la relectura tras crear o actualizar, y el schema toma cada nombre conAliasPath(<relación>, "nombre"). Los demás nombres se agregan igual. contacto_principal_idno se envía al crear; se elige en elPUTdel cliente, con un vínculo activo enrel_clientes_contactos(ADR 0021).- Un grupo económico con clientes activos no se borra (409); amplía el ADR 0017.
Alternativas descartadas¶
- Leer los catálogos con SQL propio (
text()) — duplica la definición de las tablas y pierde el tipado. - JOIN explícito en el repository que devuelve
(cliente, nombre)— se probó: funciona, pero la tupla crece con cada referencia y cambia las firmas del service y del router. - Relaciones en ambos lados o en
catalogos— un dominio no se toca por las necesidades de otro; la relación vive sólo enCliente. - Validar todas las referencias en cada
PUT— impediría editar un cliente cuyo catálogo se borró después. - Paginación propia de este servicio — cada servicio terminaría con un formato distinto; se espera el formato común de la plataforma.
Consecuencias¶
clientesexpone 15 operaciones.- Borrar un catálogo usado por clientes todavía está permitido: impedirlo
obligaría a
catalogosa leermae_clientes; queda pendiente. - Mientras no haya paginación, el listado devuelve todos los clientes de la empresa; con miles de filas la respuesta crece, y es lo primero que se paginará cuando exista el formato común.
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.