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 |
|