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.