api / audit /CODE_QUALITY.md
Mate11
Pirmer commit
5f12c93
|
Raw History Blame Contribute Delete
12.6 kB
# 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 |