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