|
Download audit/CODE_QUALITY.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 12.6 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/audit/CODE_QUALITY.md
- Command line
-
hf download hf://spaces/Modulo-6/api/audit/CODE_QUALITY.md
-
curl -L -o CODE_QUALITY.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/audit/CODE_QUALITY.md
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 | | |