api / audit /ARCHITECTURE_REVIEW.md
Mate11
Pirmer commit
5f12c93
|
Raw History Blame Contribute Delete
11.5 kB

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/disponibilidad
  • POST /camas/{id}/reservas
  • POST /webhooks/hce/solicitud
  • POST /webhooks/hce/alta-medica
  • POST /webhooks/hce/cirugia-urgente
  • POST /webhooks/turnos/{id}/cancelacion-quirofano
  • POST /webhooks/monitoreo/alerta-emergencia
  • POST /webhooks/monitoreo/alerta-resuelta
  • GET /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

  1. Migrar external_client.py a httpx.AsyncClient async — las llamadas síncronas bloquean el event loop de FastAPI, limitando la concurrencia a 1 request efectivo por llamada externa.

  2. Eliminar el default del JWT secret en config.py:9 — hacerlo campo obligatorio sin default.

  3. Corregir CORS — listar orígenes explícitos en lugar de wildcard con allow_credentials=True.

Prioridad 2 — Alto

  1. Crear capa de repositorio — extraer db.query/add/commit/refresh a clases CamaRepository, SolicitudRepository, ReservaRepository bajo backend/crud/.

  2. Mover cancelar_reserva_por_turno de solicitud_service al dominio de reservas para eliminar import lazy y responsabilidad incorrecta.

  3. Agregar response_model a los 8 endpoints que lo omiten — crear schemas Pydantic para respuestas anónimas.

  4. Loguear y tipar errores del cliente externo — reemplazar except Exception: return None por logging + excepción de dominio tipada (ExternalServiceError).

Prioridad 3 — Medio

  1. Dividir cama_service.py en cama_service.py (gestión de camas) y reserva_service.py (quirófanos).

  2. Usar enums en campos de respuesta y query params — CamaResponse.tipo/estado/sector, filtros en GET endpoints.

  3. Documentar errores en OpenAPI con responses={401: ..., 403: ..., 404: ..., 409: ..., 502: ...}.

  4. Mover lógica de agregación de router al servicio (routers/camas.py:70-78).

  5. Mover todos los imports lazy al encabezado del módulo y resolver las dependencias circulares por diseño.

Prioridad 4 — Bajo / Backlog

  1. Convertir el external_client.py monolítico en módulos separados por integración (integrations/hce.py, integrations/monitoreo.py, etc.).

  2. Separar reservas de quirófano en router dedicado routers/quirofanos.py.

  3. Proteger /auth/token con feature flag settings.debug_mode.

  4. Agregar tests unitarios con mocks del repositorio.