Saltar a contenido

0016. CRUD del dominio empresas: mae_empresas

Estado: Aceptado Fecha: 2026-09-29 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/empresas/, app/main.py, tests/unit/empresas/

Contexto

El dominio empresas solo tenía models.py y schemas.py desde el ADR 0005: no había forma de crear, listar, actualizar ni eliminar una empresa por API. mae_empresas es la tabla central de la plataforma: su id es un BigInteger con Identity que hace de empresa_id en el resto de las tablas y servicios, y es global, sin empresa_id sobre sí misma ni RLS (ADR 0012 transversal). Los catálogos por empresa que cuelgan de ella —feriados y bancos, y los dominios que referencian empresa— esperan este CRUD para validar sus referencias.

Decisión

Se implementa el CRUD completo de mae_empresas bajo /api/v1/empresas, con la arquitectura de capas router -> service -> repository del ADR 0001 transversal:

  • GET /api/v1/empresas lista las empresas activas, y GET /api/v1/empresas/{empresa_id} devuelve una por su id entero.
  • POST /api/v1/empresas crea con 201; PUT /api/v1/empresas/{empresa_id} actualiza parcialmente; DELETE /api/v1/empresas/{empresa_id} elimina lógicamente con 204.
  • La identificacion es única (constraint de mae_empresas): el service la valida antes de escribir y el router traduce el duplicado en 409.
  • Las FKs opcionales pais_id, ciudad_id y tipo_identificacion_id se validan contra los catálogos en el repository (única capa con acceso a SQLAlchemy, puede leer cualquier tabla del servicio) y el router traduce la referencia inexistente en 404, con excepciones locales al dominio empresas.
  • logo_documento_id se omite del CRUD: es el documento del logo y mae_documentos no tiene CRUD todavía, así que el Create y el Update no lo piden. Se incorporará cuando exista la administración de documentos.
  • El router se monta en app/main.py, al lado del de catálogos. OpenAPI suma 5 endpoints.

Alternativas descartadas

  • Esperar a la capa de autenticación — mae_empresas es global y sin RLS: es la fuente del aislamiento, no su destino, así que su CRUD no necesita la administración autenticada y no hay nada que esperar.
  • Reutilizar las excepciones de catalogos — acoplaría los dominios por sus excepciones: empresas declara las suyas (PaisNoEncontradoError, CiudadNoEncontradaError, TipoIdentificacionNoEncontradoError), aunque compartan nombre con las de catálogos.
  • Incluir logo_documento_id sin CRUD de documentos — dejaría un campo que solo se puede poblar por SQL directo o con un id que el cliente no puede obtener por API.

Consecuencias

  • Desbloquea los catálogos por empresa (feriados, bancos) y los dominios que cuelgan de empresa: ya pueden validar su empresa_id contra un CRUD real.
  • El id entero con Identity cambia el patrón de rutas de este recurso: el path param es int, no uuid, como en el resto del servicio.
  • La validación de unicidad es de aplicación (service) y de base (constraint); el router traduce el error de dominio en 409 antes de llegar a la base.
  • OpenAPI del servicio suma los 5 endpoints de empresas.