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