Download audit/ARCHITECTURE_REVIEW.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 11.5 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/audit/ARCHITECTURE_REVIEW.md
- Command line
-
hf download hf://spaces/Modulo-6/api/audit/ARCHITECTURE_REVIEW.md
-
curl -L -o ARCHITECTURE_REVIEW.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/audit/ARCHITECTURE_REVIEW.md
Revisión de Arquitectura — Módulo 6 (Health Grid)
Fecha: 2026-05-03 | Agente E (Architecture Reviewer) | Stack: FastAPI · SQLAlchemy (sync) · PostgreSQL
Diagrama de capas ACTUAL
┌──────────────────────────────────────────────────────────────┐
│ CLIENTES │
│ (M1 HCE · M2 Turnos · M9 Monitoreo · Browser) │
└───────────────────────┬──────────────────────────────────────┘
│ HTTP
┌───────────────────────▼──────────────────────────────────────┐
│ ROUTERS (camas.py · solicitudes.py · webhooks.py) │
│ [!] Lógica de agregación de estados en router │
│ [!] Construcción de dicts anónimos sin schema │
│ [!] Import lazy dentro de handler │
└───────────────────────┬──────────────────────────────────────┘
│ llamadas a funciones directas
┌───────────────────────▼──────────────────────────────────────┐
│ SERVICES (cama_service.py · solicitud_service.py) │
│ [!] db.query/add/commit/refresh sin capa repositorio │
│ [!] HTTPException lanzadas desde capa de servicio │
│ [!] Imports lazy para evitar ciclos │
└───────────────────────┬──────────────────────────────────────┘
│ acceso ORM directo (sin repositorio)
┌───────────────────────▼──────────────────────────────────────┐
│ MODELOS ORM (cama.py · solicitud.py · reserva.py) │
│ [OK] Bien separados de los schemas Pydantic │
└──────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ CLIENTE EXTERNO — services/external_client.py │
│ [OK] Todas las llamadas outbound centralizadas aquí │
│ [!] httpx SÍNCRONO en app async — bloquea event loop │
│ [!] except Exception silencioso, sin logging ni retry │
└──────────────────────────────────────────────────────────────┘
Diagrama de capas IDEAL propuesto
CLIENTES
│
▼
ROUTERS ← solo validación de input y presentación de output
│
▼
SERVICES ← lógica de negocio pura (sin HTTPException, sin db.commit)
│
▼
REPOSITORIES ← toda la interacción ORM (una clase por entidad)
│
▼
MODELOS ORM
INTEGRATIONS/ ← clientes HTTP async, con excepciones tipadas y logging
├── hce.py ← M1
├── turnos.py ← M2
├── facturacion.py ← M7
├── monitoreo.py ← M9
└── core.py ← M10
Hallazgos por categoría
1. Separación de capas
| Hallazgo | Archivo:línea | Impacto |
|---|---|---|
Contadores de estado calculados en el router (count("DISPONIBLE")) |
routers/camas.py:70-78 |
MEDIO |
| Construcción de dict anónimo de respuesta de disponibilidad sin schema | routers/camas.py:39-53 |
MEDIO |
Workaround {**s.__dict__, "id": s.solicitud_id} en lugar de schema correcto |
routers/solicitudes.py:23,36,48 |
BAJO |
Import lazy JSONResponse dentro del body del handler |
routers/camas.py:172 |
BAJO |
Veredicto: No hay acceso directo a BD en routers. Los problemas son lógica de presentación que se filtró al router. Arquitectura ~90% correcta en esta capa.
2. Capa de repositorio AUSENTE (hallazgo más importante)
No existe una capa CRUD/Repository separada. Todo el acceso ORM (db.query, db.add, db.commit, db.refresh) está embebido directamente en los servicios.
| Hallazgo | Archivo | Impacto |
|---|---|---|
db.query/add/commit/refresh directos en capa de servicio |
cama_service.py, solicitud_service.py |
ALTO |
_get_cama_or_404 definida dos veces en dos servicios distintos |
cama_service.py:23-27 / solicitud_service.py:37-44 |
MEDIO |
cancelar_reserva_por_turno en solicitud_service accede al modelo ReservaQuirofano con import lazy |
solicitud_service.py:325 |
ALTO |
Consecuencias: Dificultad para testear servicios sin base de datos real, lógica de acceso a datos dispersa, duplicación de queries.
3. Imports circulares potenciales
| Hallazgo | Archivo:línea | Causa raíz |
|---|---|---|
| Import lazy para romper ciclo entre servicios | solicitud_service.py:325 |
solicitud_service opera sobre ReservaQuirofano que pertenece al dominio de camas |
| Import lazy de schema dentro de función de servicio | cama_service.py:395 |
Dependencia cruzada entre schemas |
Solución: Mover cancelar_reserva_por_turno al dominio de camas/reservas. Los imports lazy son una señal de diseño de dependencias incorrecto, no la solución.
4. Aislamiento de llamadas externas
| Hallazgo | Archivo:línea | Severidad |
|---|---|---|
httpx.post/get síncrono en app FastAPI async — bloquea event loop |
external_client.py:19-34 |
CRÍTICO |
except Exception: return None silencia todos los errores sin log |
external_client.py:25,33 |
ALTO |
Llamadas externas fire-and-forget intercaladas con db.commit() — inconsistencia posible |
cama_service.py:194-198 / solicitud_service.py:205-206 |
MEDIO |
| No hay mecanismo de retry ni circuit breaker | external_client.py completo |
MEDIO |
Imports datetime dentro de funciones |
external_client.py:72,89,105,126 |
BAJO |
Punto positivo: Todas las llamadas HTTP outbound están centralizadas en external_client.py. Ningún router ni servicio llama directamente a httpx. Esto es correcto y facilita la migración.
5. God files
| Archivo | Líneas | Responsabilidades mezcladas |
|---|---|---|
services/cama_service.py |
~501 | CRUD camas, estados, contraindicaciones, CRUD reservas, conflictos de horario, reservas urgentes con desplazamiento, notificaciones externas |
services/solicitud_service.py |
~353 | Recepción, listado, resolución, alta médica, alertas, cancelación de reservas de quirófano |
Recomendación: Dividir cama_service.py en cama_service.py + reserva_service.py.
6. Inyección de dependencias
| Aspecto | Estado |
|---|---|
get_db() como generador en database.py |
✅ Correcto |
require_roles() factory pattern en auth/dependencies.py |
✅ Correcto |
| Sesión de BD nunca creada ad-hoc en handlers | ✅ Correcto |
external_client.py como funciones puras no inyectables |
⚠️ Impide mocking en tests |
7. Conflación Schema / Model ORM
| Aspecto | Estado |
|---|---|
| Schemas Pydantic y modelos ORM claramente separados | ✅ Correcto |
ConfigDict(from_attributes=True) aplicado correctamente |
✅ Correcto |
CamaResponse.tipo/estado/sector: str en lugar de enum |
⚠️ Debilita validación de salida y documentación OpenAPI |
SolicitudResponse campos enumerados como str |
⚠️ Mismo problema |
AsignacionCamaRequest.tipo: str libre en lugar de Literal |
⚠️ Sin restricción de dominio |
8. Completitud del contrato OpenAPI
| Métrica | Valor |
|---|---|
Endpoints con response_model explícito |
10 / 18 (56%) |
| Endpoints con respuesta anónima / dict | 8 / 18 (44%) |
| Errores 4xx/5xx documentados en OpenAPI | 0 / 18 (0%) |
| Query params tipados con enum | 0 / 5 filtros relevantes |
Endpoints sin response_model:
GET /camas/disponibilidadPOST /camas/{id}/reservasPOST /webhooks/hce/solicitudPOST /webhooks/hce/alta-medicaPOST /webhooks/hce/cirugia-urgentePOST /webhooks/turnos/{id}/cancelacion-quirofanoPOST /webhooks/monitoreo/alerta-emergenciaPOST /webhooks/monitoreo/alerta-resueltaGET /auth/token
Calificación global del contrato OpenAPI: 4 / 10
Los consumidores de la API no tienen contrato formal de errores. Ningún endpoint documenta 401/403/404/409/422/502.
Recomendaciones priorizadas
Prioridad 1 — Crítico / Inmediato
Migrar
external_client.pyahttpx.AsyncClientasync — las llamadas síncronas bloquean el event loop de FastAPI, limitando la concurrencia a 1 request efectivo por llamada externa.Eliminar el default del JWT secret en
config.py:9— hacerlo campo obligatorio sin default.Corregir CORS — listar orígenes explícitos en lugar de wildcard con
allow_credentials=True.
Prioridad 2 — Alto
Crear capa de repositorio — extraer
db.query/add/commit/refresha clasesCamaRepository,SolicitudRepository,ReservaRepositorybajobackend/crud/.Mover
cancelar_reserva_por_turnodesolicitud_serviceal dominio de reservas para eliminar import lazy y responsabilidad incorrecta.Agregar
response_modela los 8 endpoints que lo omiten — crear schemas Pydantic para respuestas anónimas.Loguear y tipar errores del cliente externo — reemplazar
except Exception: return Nonepor logging + excepción de dominio tipada (ExternalServiceError).
Prioridad 3 — Medio
Dividir
cama_service.pyencama_service.py(gestión de camas) yreserva_service.py(quirófanos).Usar enums en campos de respuesta y query params —
CamaResponse.tipo/estado/sector, filtros en GET endpoints.Documentar errores en OpenAPI con
responses={401: ..., 403: ..., 404: ..., 409: ..., 502: ...}.Mover lógica de agregación de router al servicio (
routers/camas.py:70-78).Mover todos los imports lazy al encabezado del módulo y resolver las dependencias circulares por diseño.
Prioridad 4 — Bajo / Backlog
Convertir el
external_client.pymonolítico en módulos separados por integración (integrations/hce.py,integrations/monitoreo.py, etc.).Separar reservas de quirófano en router dedicado
routers/quirofanos.py.Proteger
/auth/tokencon feature flagsettings.debug_mode.Agregar tests unitarios con mocks del repositorio.