Saltar a contenido

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/sucursales lista las sucursales activas, y GET /api/v1/sucursales/{sucursal_id} devuelve una por su id UUID.
  • POST /api/v1/sucursales crea con 201; PUT /api/v1/sucursales/{sucursal_id} actualiza parcialmente; DELETE /api/v1/sucursales/{sucursal_id} elimina lógicamente con 204.
  • El empresa_id se valida contra mae_empresas antes de escribir y el router traduce la referencia inexistente en 404.
  • El ciudad_id es opcional: si llega, se valida contra cat_ciudades y el router traduce la referencia inexistente en 404.
  • El codigo es único por empresa (constraint de mae_sucursales): el service lo valida antes de escribir y el router traduce el duplicado en 409.
  • 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_sucursales lleva 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, el empresa_id vendrá del token y la política RLS validará el aislamiento.
  • Reutilizar las excepciones de otros dominios — acoplaría sucursales con empresas o catalogos por sus excepciones: sucursales declara las suyas (EmpresaNoEncontradaError, CiudadNoEncontradaError, SucursalCodigoDuplicadoError), aunque compartan nombre con las de otros dominios.

Consecuencias

  • Desbloquea rel_usuario_sucursal (dominio usuarios): 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_id vendrá del token: el Create dejará de pedirlo y la política RLS filtrará las sucursales de la empresa del usuario.