File size: 12,572 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
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
# Auditoría de Calidad de Código — Módulo 6 (Health Grid)

> Fecha de análisis: 2026-05-03 | Agente C (Code Quality Scanner) | 18 archivos Python analizados

---

## Tabla Resumen

| # | Categoría | Hallazgos |
|---|-----------|-----------|
| 1 | Código muerto | 6 |
| 2 | Lógica duplicada | 3 |
| 3 | Funciones > 50 líneas | 2 |
| 4 | Manejo de errores inadecuado | 3 |
| 5 | Números mágicos / strings hardcodeados | 9 |
| 6 | Convenciones de nombres inconsistentes | 3 |
| 7 | TODO / FIXME / HACK sin resolver | 1 |
| 8 | Type hints faltantes | 4 |
| 9 | Modelos Pydantic sin validadores | 5 |
| **Total** | | **36** |

---

## Categoría 1 — Código Muerto

### CQ-01
- **Archivo:línea:** `backend/services/cama_service.py:8`
- **Problema:** `and_` y `or_` importados de SQLAlchemy pero nunca usados en el archivo.
- **Sugerencia:** Eliminar del import statement.

### CQ-02
- **Archivo:línea:** `backend/services/external_client.py:72,90,103,125`
- **Problema:** `from datetime import datetime, timezone` importado de forma diferida dentro de 4 funciones distintas. Patrón inusual e ineficiente.
- **Sugerencia:** Mover al nivel de módulo, en los imports del encabezado.

### CQ-03
- **Archivo:línea:** `backend/services/cama_service.py:395`
- **Problema:** `from schemas.reserva import CirugiaUrgenteWebhook` importado dentro de `crear_reserva_urgente` pero el type hint nunca se aplica explícitamente.
- **Sugerencia:** Mover al nivel de módulo y agregar type hint al parámetro `data`.

### CQ-04
- **Archivo:línea:** `backend/routers/webhooks.py:78`
- **Problema:** `is_new = reserva_desplazada is not None or True` siempre evalúa a `True` y la variable `is_new` nunca se usa posteriormente. Variable completamente muerta con lógica incorrecta (el `or True` es un bug).
- **Sugerencia:** Implementar la lógica correcta o eliminar la variable. Investigar la intención original.

### CQ-05
- **Archivo:línea:** `backend/main.py:63`
- **Problema:** Parámetro llamado `usuario` que inmediatamente se asigna a `rol = usuario.upper()`. El nombre del parámetro no refleja su propósito.
- **Sugerencia:** Renombrar el parámetro a `rol` directamente.

### CQ-06
- **Archivo:línea:** `backend/routers/camas.py:172`
- **Problema:** `from fastapi.responses import JSONResponse` importado dentro del cuerpo de la función `crear_reserva`.
- **Sugerencia:** Mover al nivel del módulo junto con los demás imports.

---

## Categoría 2 — Lógica Duplicada

### CQ-07
- **Archivo:línea:** `backend/services/cama_service.py:174-185` / `backend/services/solicitud_service.py:181-192` / `backend/services/solicitud_service.py:227-238`
- **Problema:** Verificación de contraindicaciones del paciente copiada 3 veces con lógica idéntica (llamada a `external_client`, parseo de lista, comparación con tipo de cama).
- **Sugerencia:** Extraer a función auxiliar `verificar_contraindicaciones(paciente_id, cama, db)` en un módulo compartido.

### CQ-08
- **Archivo:línea:** `backend/services/cama_service.py:23-27` / `backend/services/solicitud_service.py:37-44`
- **Problema:** Función `_get_cama_or_404` definida dos veces con lógica idéntica en dos módulos distintos.
- **Sugerencia:** Mover a un módulo `crud/cama.py` o `utils/db_helpers.py` y reutilizar desde ambos servicios.

### CQ-09
- **Archivo:línea:** `backend/services/external_client.py:80,93,108,131,158`
- **Problema:** `datetime.now(timezone.utc).isoformat()` repetido 5 veces en payloads de distintas funciones.
- **Sugerencia:** Extraer a función auxiliar privada `_now_iso() -> str`.

---

## Categoría 3 — Funciones > 50 Líneas

### CQ-10
- **Archivo:línea:** `backend/services/cama_service.py:389-463`
- **Problema:** `crear_reserva_urgente` tiene aproximadamente 75 líneas. Mezcla validación de datos, búsqueda de quirófano disponible, lógica de desplazamiento de reserva existente, creación de nueva reserva y notificaciones externas.
- **Sugerencia:** Extraer el bloque de desplazamiento/cancelación a `_desplazar_reserva_existente(db, cama, nueva_reserva)`.

### CQ-11
- **Archivo:línea:** `backend/services/solicitud_service.py:209-258`
- **Problema:** `_aprobar_traslado` tiene ~49 líneas con 6 responsabilidades mezcladas: validación de cama origen, validación de cama destino, verificación de contraindicaciones, actualización de solicitud, actualización de ambas camas, notificación externa.
- **Sugerencia:** Dividir en: `_validar_traslado(...)`, `_ejecutar_traslado(...)`, `_notificar_traslado(...)`.

---

## Categoría 4 — Manejo de Errores Inadecuado

### CQ-12
- **Archivo:línea:** `backend/services/external_client.py:24-25` y `32-33`
- **Problema:** `except Exception: return None` silencia todos los errores de integración (timeouts, HTTP 5xx, errores de parseo JSON) sin ningún log. Crítico para observabilidad — fallos de notificación a M1/M7/M9/M10 son completamente invisibles.
- **Sugerencia:** Agregar `logger.warning("Error llamando a %s: %s", url, e)` antes del `return None`.

### CQ-13
- **Archivo:línea:** `backend/database.py:19-24`
- **Problema:** `get_db()` cierra la sesión en `finally` pero no realiza `db.rollback()` explícito ante excepciones. Ante una excepción no capturada, la sesión puede quedar en estado inconsistente.
- **Sugerencia:** Agregar `except Exception: db.rollback(); raise` antes del `finally`.

### CQ-14
- **Archivo:línea:** `backend/auth/dependencies.py:16-18`
- **Problema:** `except ValueError` capturado sin ningún log. Imposible detectar intentos de autenticación con tokens manipulados o malformados en producción.
- **Sugerencia:** Agregar `logger.warning("Intento de autenticación con token inválido: %s", e)` antes de relanzar como HTTP 401.

---

## Categoría 5 — Números Mágicos / Strings Hardcodeados

### CQ-15
- **Archivo:línea:** `backend/config.py:6`
- **Problema:** Credenciales `admin:secret` en el valor por defecto de `database_url`.
- **Sugerencia:** Hacer el campo requerido sin default: `database_url: str`.

### CQ-16
- **Archivo:línea:** `backend/config.py:9`
- **Problema:** `"supersecretkey_change_in_production"` como valor por defecto del JWT secret.
- **Sugerencia:** Hacer el campo requerido sin default: `jwt_secret: str`.

### CQ-17
- **Archivo:línea:** `backend/main.py:3`
- **Problema:** Puerto `8006` hardcodeado en el docstring del módulo (y en el Dockerfile).
- **Sugerencia:** Mover a `settings.port` en `config.py`.

### CQ-18
- **Archivo:línea:** `backend/services/external_client.py:21,30`
- **Problema:** Timeout `5.0` segundos hardcodeado en `_post` y `_get`.
- **Sugerencia:** Agregar `http_timeout_seconds: float = 5.0` en `config.py` y usar `settings.http_timeout_seconds`.

### CQ-19
- **Archivo:línea:** `backend/services/cama_service.py:44,69,98,163,174` / `backend/services/solicitud_service.py:174,220`
- **Problema:** Strings literales `"DISPONIBLE"`, `"OCUPADA"`, `"EN_LIMPIEZA"` usados en lugar del `EstadoCamaEnum` ya definido en `schemas/enums.py`.
- **Sugerencia:** Reemplazar con `EstadoCamaEnum.DISPONIBLE`, etc.

### CQ-20
- **Archivo:línea:** `backend/services/solicitud_service.py:58,93,115`
- **Problema:** String `"PENDIENTE"` en lugar de `EstadoSolicitudEnum.PENDIENTE`.
- **Sugerencia:** Usar el enum definido.

### CQ-21
- **Archivo:línea:** `backend/services/cama_service.py:267,467,491`
- **Problema:** Strings `"URGENTE"`, `"PROGRAMADA"`, `"EMERGENCIA"` en lugar de `PrioridadQuirofanoEnum` / `OrigenReservaEnum`.
- **Sugerencia:** Usar los enums definidos.

### CQ-22
- **Archivo:línea:** `backend/services/cama_service.py:217,244,278,329,331,341` / `backend/services/solicitud_service.py:328,338,340`
- **Problema:** Estados de reserva (`"CANCELADA"`, `"RESERVADA"`, `"EN_CURSO"`) como literales en lugar de `EstadoReservaEnum`.
- **Sugerencia:** Usar los enums definidos.

---

## Categoría 6 — Convenciones de Nombres Inconsistentes

### CQ-23
- **Archivo:línea:** `backend/routers/camas.py:27`
- **Problema:** Comentario usa `/{camaId}` (camelCase) mientras todo el código usa `cama_id` (snake_case).
- **Sugerencia:** Actualizar comentario a `/{cama_id}`.

### CQ-24
- **Archivo:línea:** `backend/services/cama_service.py:364-383`
- **Problema:** Variable `q` usada para query SQLAlchemy; obliga a renombrar la variable del loop a `q_cama` para evitar colisión. Nombre poco descriptivo.
- **Sugerencia:** Renombrar `q` a `quirofanos_query` para mayor claridad.

### CQ-25
- **Archivo:línea:** `backend/services/solicitud_service.py` (todo el archivo)
- **Problema:** Abreviatura `sol` para instancias de `Solicitud` es inconsistente con el resto del proyecto donde los modelos usan el nombre completo (`cama`, `reserva`, `db`).
- **Sugerencia:** Renombrar a `solicitud` para uniformidad.

---

## Categoría 7 — TODO / FIXME / HACK sin resolver

### CQ-26
- **Archivo:línea:** `backend/routers/webhooks.py:78`
- **Problema:** Comentario `# simplificado` justifica lógica deliberadamente incorrecta. La expresión `or True` convierte `is_new` en siempre-verdadero, lo que es equivalente a un bug funcional no marcado como tal.
- **Sugerencia:** Implementar la lógica correcta para determinar si la reserva es nueva. Si es temporal, marcarlo con `# TODO: implementar lógica de is_new`.

---

## Categoría 8 — Type Hints Faltantes

### CQ-27
- **Archivo:línea:** `backend/auth/jwt_handler.py:7`
- **Problema:** `extra: dict = None` — tipo incorrecto y nulabilidad no declarada.
- **Sugerencia:** Cambiar a `extra: dict | None = None`.

### CQ-28
- **Archivo:línea:** `backend/services/cama_service.py:389`
- **Problema:** Parámetro `data` en `crear_reserva_urgente` sin type hint.
- **Sugerencia:** `data: CirugiaUrgenteWebhook`.

### CQ-29
- **Archivo:línea:** `backend/services/cama_service.py:466`
- **Problema:** Parámetro `data` en función auxiliar privada sin tipo, retorno también sin declarar.
- **Sugerencia:** Agregar tipos completos al signature.

### CQ-30
- **Archivo:línea:** `backend/main.py:90,98`
- **Problema:** Parámetro `exc` en los dos exception handlers globales sin tipo declarado.
- **Sugerencia:** `exc: RequestValidationError` y `exc: Exception` respectivamente.

---

## Categoría 9 — Modelos Pydantic sin Validadores

### CQ-31
- **Archivo:línea:** `backend/schemas/cama.py:8-14`
- **Problema:** `CamaCreateRequest`: campos `numero` y `hospital_id` aceptan strings vacíos o solo espacios en blanco.
- **Sugerencia:** Agregar `field_validator` que haga `strip()` y verifique que el resultado no sea vacío.

### CQ-32
- **Archivo:línea:** `backend/schemas/solicitud.py:64-83`
- **Problema:** `SolicitudHceWebhook`: no valida que los campos requeridos según `tipo` (INTERNACION vs TRASLADO) estén presentes (ej. TRASLADO requiere `cama_id_origen`).
- **Sugerencia:** Agregar `model_validator(mode="after")` para validación cruzada de campos.

### CQ-33
- **Archivo:línea:** `backend/schemas/reserva.py:8-15`
- **Problema:** `ReservaQuirofanoCreateRequest`: no valida que `fecha_hora_inicio < fecha_hora_fin_estimada`. Una reserva puede crearse con fechas invertidas.
- **Sugerencia:** Agregar `model_validator` que verifique el orden cronológico.

### CQ-34
- **Archivo:línea:** `backend/schemas/cama.py:47-50`
- **Problema:** `AsignacionCamaRequest.tipo` es `str` libre cuando solo acepta `"INGRESO"` o `"TRASLADO"`.
- **Sugerencia:** Cambiar el tipo a `Literal["INGRESO", "TRASLADO"]`.

### CQ-35 & CQ-36
- **Archivo:línea:** `backend/schemas/reserva.py:60-63`
- **Problema:** `CancelacionQuirofanoRequest.tipo_cancelacion` es `Optional[str]` sin restricción de valores válidos.
- **Sugerencia:** Cambiar a `Optional[Literal["CANCELADA_MEDICO", "CANCELADA_PACIENTE", "CANCELADA_SISTEMA"]]` o usar un enum específico.

---

## Impacto estimado por categoría

| Categoría | Impacto funcional | Impacto mantenimiento | Prioridad |
|-----------|------------------|----------------------|-----------|
| Lógica duplicada | MEDIO (divergencia futura) | ALTO | 🔴 Alta |
| Strings hardcodeados (enums) | ALTO (bugs silenciosos de comparación) | ALTO | 🔴 Alta |
| Manejo de errores | ALTO (bugs invisibles en producción) | ALTO | 🔴 Alta |
| Modelos Pydantic sin validadores | ALTO (datos inválidos en BD) | MEDIO | 🔴 Alta |
| Funciones largas | BAJO | ALTO | 🟡 Media |
| Código muerto | BAJO | MEDIO | 🟡 Media |
| Type hints faltantes | BAJO | MEDIO | 🟢 Baja |
| Nombres inconsistentes | BAJO | BAJO | 🟢 Baja |
| TODO sin resolver | MEDIO (bug funcional en webhook) | BAJO | 🟡 Media |