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/empresaslista las empresas activas, yGET /api/v1/empresas/{empresa_id}devuelve una por suidentero.POST /api/v1/empresascrea con201;PUT /api/v1/empresas/{empresa_id}actualiza parcialmente;DELETE /api/v1/empresas/{empresa_id}elimina lógicamente con204.- La
identificaciones única (constraint demae_empresas): el service la valida antes de escribir y el router traduce el duplicado en409. - Las FKs opcionales
pais_id,ciudad_idytipo_identificacion_idse 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 en404, con excepciones locales al dominioempresas. logo_documento_idse omite del CRUD: es el documento del logo ymae_documentosno 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_empresases 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:empresasdeclara las suyas (PaisNoEncontradoError,CiudadNoEncontradaError,TipoIdentificacionNoEncontradoError), aunque compartan nombre con las de catálogos. - Incluir
logo_documento_idsin 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_idcontra un CRUD real. - El
identero conIdentitycambia el patrón de rutas de este recurso: el path param esint, nouuid, 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
409antes de llegar a la base. - OpenAPI del servicio suma los 5 endpoints de empresas.