Saltar a contenido

0005. Contratos de API (schemas Pydantic) para todas las tablas

Estado: Aceptado Fecha: 2026-09-28 Autor: Duval Alcivar Módulo(s) afectado(s): app/core/schemas.py, app/domains/*/schemas.py, tests/

Contexto

Los modelos SQLAlchemy de las 29 tablas ya existen (ADR 0004), pero la API no tiene contratos tipados de respuesta. Sin schemas Pydantic, FastAPI devolvería dicts sin validación de salida, sin documentación OpenAPI y sin protección explícita de los campos sensibles.

Decisión

  • Un schemas.py por dominio, con un schema de lectura XxxRead por cada tabla (29 en total), siguiendo el árbol de app/domains/ del ADR 0002.
  • Una base compartida AuditoriaCampos en app/core/schemas.py con id, is_activo, created_at, updated_at y from_attributes=True para serializar directo desde el ORM.
  • Los contratos de lectura nunca exponen secretos: MaeUsuariosRead sin password, TrxRefreshTokensRead sin token_hash.
  • Las tablas atípicas se declaran aparte: TrxPreTokensRead y LogSesionesRead no heredan AuditoriaCampos (no tienen el calendario completo) y MaeEmpresasRead re-declara id como int (BIGINT Identity, no UUID).
  • Por ahora son solo lectura: los Create/Update llegan cuando exista la administración autenticada.

Alternativas descartadas

  • Devolver dicts sin contratos — sin validación de salida ni OpenAPI; los secretos quedarían expuestos por accidente.
  • Un solo schemas.py global — se eligió por dominio, consistente con el ADR 0002.
  • Schemas de escritura ahora — se difieren hasta la capa de auth; hoy nadie puede crear catálogos desde la API.

Consecuencias

  • OpenAPI autodocumentado para las 29 tablas.
  • Los contratos viven junto a su dominio y crecerán con los Create/Update cuando se agregue escritura.
  • AuditoriaCampos reduce repetición igual que los mixins en los modelos: un cambio en las columnas de auditoría se refleja en un solo lugar.