refactor(backend): primera ronda de deduplicación, pruebas de caracterización y aislamientos lógicos

[Ochoa-Stack]

refactor/backend-deduplication-round-one

Descripción

En este ciclo, ejecutamos una campaña intensiva de refactorización orientada a erradicar la duplicidad de código, extraer lógicas complejas hacia métodos reutilizables y estandarizar el manejo de errores. Previo a las modificaciones estructurales, instrumentamos pruebas de caracterización para blindar la lógica de negocio y garantizar la inmutabilidad del comportamiento. Finalmente, aplicamos parches de seguridad puntuales y cerramos el ciclo con un análisis introspectivo de la arquitectura resultante.

Detalles técnicos que integramos:

• Extracción y Deduplicación de Lógica (refactor):
  • Ingesta: Extraímos el cálculo de la modalidad remota (is_remote) hacia un módulo independiente e implementamos un script de backfill para actualizar los registros de vacantes históricos.
  • Geocodificación (Nominatim) y Ciudades: Descompusimos el método monolítico geocode_city en pasos nominales explícitos. Centralizamos la normalización de caracteres Unicode duplicada en CityRepository.
  • Usuarios y Administración: Depuramos código muerto eliminando count_active_admins en UserRepository (ahora sin uso), extraímos el manejo de errores de persistencia duplicado, estandarizamos la interpolación en los registros de auditoría (logs) y aislamos la protección del "último administrador" hacia un método compartido.
  • Mantenimiento y Alertas: Desacoplamos el parseo de conexiones de base de datos en el motor de respaldos y extrajimos las plantillas HTML del servicio de alertas, inyectando los registros de fallos que habían sido omitidos.
• Blindaje mediante Pruebas de Caracterización (test):
  • Implementamos suites de caracterización previas a la refactorización para city-repo, nominatim y la lógica de ingesta. Esta técnica nos permitió documentar y proteger el comportamiento existente (incluyendo un falso positivo conocido en la detección de is_remote) garantizando cero regresiones durante la extracción de código.
• Seguridad y Precisión (fix):
  • Rate Limiting: Endurecimos el controlador de autenticación inyectando limitación de tasa sobre el endpoint de inicio de sesión de Google.
  • Privacidad de Datos: Sustituimos el uso de un correo personal por una dirección noreply de GitHub en la cabecera User-Agent utilizada para las peticiones a la API de Nominatim.
  • Precisión Analítica: Acotamos el alcance de la detección is_remote exclusivamente a los campos de título y descripción, incorporando límites de palabra (word boundaries) para erradicar falsos positivos en la ingesta futura.

Nota Estratégica: El ciclo concluyó con una retrospectiva formal de análisis arquitectónico para evaluar las áreas de mejora resultantes, sin introducir mutaciones adicionales al código base en esta iteración.

Tipo de cambio

• feat
• fix
• refactor
• chore
• docs
• test
• ci

Cómo probar

1. Tras el merge, sincronizamos la rama base en nuestro entorno local.
2. En la raíz del backend (cd backend), activamos el entorno virtual.
3. Ejecutamos la suite de pruebas automatizada para certificar que la refactorización no alteró la funcionalidad de las áreas intervenidas (pasando por las nuevas pruebas de caracterización):
   pytest -v
4. Opcionalmente, ejecutamos el script de backfill para regularizar la bandera is_remote sobre la base de datos de desarrollo local, confirmando su capacidad para procesar los registros antiguos sin colapsar.
5. Comprobamos localmente que el inicio de sesión vía Google es ahora susceptible a límites de tasa si se ejecutan peticiones masivas en ráfaga.

Checklist

• Sigue las convenciones de commits del proyecto (separación atómica rigurosa)
• Las pruebas de caracterización garantizan la inmutabilidad de la lógica de negocio pre-existente
• La privacidad de las peticiones de geocodificación fue auditada y saneada
• La deduplicación de repositorios y controladores erradicó redundancias estructurales

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 94.52055% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
backend/app/repositories/user_repository.py	71.42%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!