Saltar a contenido

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 (tag clientes-maestras). El listado se ordena por codigo y 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, ClienteRepository importa catalogos.models só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_registro es opcional al crear (hoy por defecto) y obligatoria en el PUT, que reemplaza la ficha.
  • tipo_identificacion_id se 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_economico y unidad_comercial (sólo tipo_identificacion_id, que vive en svc-identidad, va sin nombre). Cliente tiene 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 en clientes/models.py); el repository las carga con joinedload (lista _REFERENCIAS_CLIENTE) en el listado, el detalle y la relectura tras crear o actualizar, y el schema toma cada nombre con AliasPath(<relación>, "nombre"). Los demás nombres se agregan igual.
  • contacto_principal_id no se envía al crear; se elige en el PUT del cliente, con un vínculo activo en rel_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 en Cliente.
  • 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

  • clientes expone 15 operaciones.
  • Borrar un catálogo usado por clientes todavía está permitido: impedirlo obligaría a catalogos a leer mae_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.