# 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 4. **Crear capa de repositorio** — extraer `db.query/add/commit/refresh` a clases `CamaRepository`, `SolicitudRepository`, `ReservaRepository` bajo `backend/crud/`. 5. **Mover `cancelar_reserva_por_turno`** de `solicitud_service` al dominio de reservas para eliminar import lazy y responsabilidad incorrecta. 6. **Agregar `response_model`** a los 8 endpoints que lo omiten — crear schemas Pydantic para respuestas anónimas. 7. **Loguear y tipar errores del cliente externo** — reemplazar `except Exception: return None` por logging + excepción de dominio tipada (`ExternalServiceError`). ### Prioridad 3 — Medio 8. **Dividir `cama_service.py`** en `cama_service.py` (gestión de camas) y `reserva_service.py` (quirófanos). 9. **Usar enums en campos de respuesta y query params** — `CamaResponse.tipo/estado/sector`, filtros en GET endpoints. 10. **Documentar errores en OpenAPI** con `responses={401: ..., 403: ..., 404: ..., 409: ..., 502: ...}`. 11. **Mover lógica de agregación** de router al servicio (`routers/camas.py:70-78`). 12. **Mover todos los imports lazy** al encabezado del módulo y resolver las dependencias circulares por diseño. ### Prioridad 4 — Bajo / Backlog 13. Convertir el `external_client.py` monolítico en módulos separados por integración (`integrations/hce.py`, `integrations/monitoreo.py`, etc.). 14. Separar reservas de quirófano en router dedicado `routers/quirofanos.py`. 15. Proteger `/auth/token` con feature flag `settings.debug_mode`. 16. Agregar tests unitarios con mocks del repositorio.