0019. CRUD del dominio sucursales: mae_sucursales¶
Estado: Aceptado Fecha: 2026-09-29 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/sucursales/, app/main.py, tests/unit/sucursales/
Contexto¶
mae_sucursales es el único modelo del dominio sucursales y solo tenía
models.py y schemas.py desde el ADR 0005: no había forma de crear, listar,
actualizar ni eliminar una sucursal por API. El modelo depende de empresas
(empresa_id con clave foránea a mae_empresas, vía EmpresaConFkMixin) y de
catalogos (ciudad_id opcional a cat_ciudades), y codigo es único por
empresa (UNIQUE(empresa_id, codigo)). Las relaciones con usuarios
(rel_usuario_sucursal, en el dominio usuarios) esperan este CRUD para
validar sus referencias.
Decisión¶
Se implementa el CRUD completo de mae_sucursales bajo /api/v1/sucursales,
con la arquitectura de capas router -> service -> repository del ADR 0001
transversal:
GET /api/v1/sucursaleslista las sucursales activas, yGET /api/v1/sucursales/{sucursal_id}devuelve una por suidUUID.POST /api/v1/sucursalescrea con201;PUT /api/v1/sucursales/{sucursal_id}actualiza parcialmente;DELETE /api/v1/sucursales/{sucursal_id}elimina lógicamente con204.- El
empresa_idse valida contramae_empresasantes de escribir y el router traduce la referencia inexistente en404. - El
ciudad_ides opcional: si llega, se valida contracat_ciudadesy el router traduce la referencia inexistente en404. - El
codigoes único por empresa (constraint demae_sucursales): el service lo valida antes de escribir y el router traduce el duplicado en409. - Las FKs se validan en el repository (única capa con acceso a SQLAlchemy, puede
leer cualquier tabla del servicio), con excepciones locales al dominio
sucursales. - El router se monta en
app/main.py, al lado del de catálogos y el de empresas. OpenAPI suma 5 endpoints.
Alternativas descartadas¶
- Esperar a la capa de autenticación —
mae_sucursaleslleva RLS (ADR 0002 transversal), pero la administración autenticada todavía no existe: el CRUD de escritura no depende del token y no hay nada que esperar. Cuando llegue auth, elempresa_idvendrá del token y la política RLS validará el aislamiento. - Reutilizar las excepciones de otros dominios — acoplaría
sucursalesconempresasocatalogospor sus excepciones:sucursalesdeclara las suyas (EmpresaNoEncontradaError,CiudadNoEncontradaError,SucursalCodigoDuplicadoError), aunque compartan nombre con las de otros dominios.
Consecuencias¶
- Desbloquea
rel_usuario_sucursal(dominiousuarios): ya puede validar su referencia a sucursal contra un CRUD real. - OpenAPI del servicio suma los 5 endpoints de sucursales.
- Cuando llegue la capa de autenticación, el
empresa_idvendrá del token: el Create dejará de pedirlo y la política RLS filtrará las sucursales de la empresa del usuario.