api / audit /ARCHITECTURE_REVIEW.md
Mate11
Pirmer commit
5f12c93
|
Raw History Blame
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
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.