File size: 11,479 Bytes
5f12c93 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 | # 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.
|