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.pypor dominio, con un schema de lecturaXxxReadpor cada tabla (29 en total), siguiendo el árbol deapp/domains/del ADR 0002. - Una base compartida
AuditoriaCamposenapp/core/schemas.pyconid,is_activo,created_at,updated_atyfrom_attributes=Truepara serializar directo desde el ORM. - Los contratos de lectura nunca exponen secretos:
MaeUsuariosReadsinpassword,TrxRefreshTokensReadsintoken_hash. - Las tablas atípicas se declaran aparte:
TrxPreTokensReadyLogSesionesReadno heredanAuditoriaCampos(no tienen el calendario completo) yMaeEmpresasReadre-declaraidcomoint(BIGINT Identity, no UUID). - Por ahora son solo lectura: los
Create/Updatellegan 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.pyglobal — 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/Updatecuando se agregue escritura. AuditoriaCamposreduce repetición igual que los mixins en los modelos: un cambio en las columnas de auditoría se refleja en un solo lugar.