quick-cita-cr

Qué es quick-cita-cr es una herramienta personal de monitoreo para citas disponibles en el portal Educación Vial de Costa Rica. Inicia sesión con tus credenciales, verifica las sedes de exámenes prácticos configuradas, mantiene registro local de lo observado previamente y notifica cuando aparecen fechas nuevas o más tempranas. El README indica que el proyecto se validó localmente contra el portal en vivo. También menciona una limitación conocida: durante la validación, los desafíos de Cloudflare no se resolvieron de manera confiable en modo headless puro, por lo que se recomienda usar modo headed, una pantalla virtual o un perfil persistente calentado para despliegues no atendidos. Capacidades reportadas El README enumera estas funciones: - Monitoreo de citas por sede. - Alertas para fechas nuevas, una fecha óptima más temprana y una "ventana rápida" configurable de días. - Estado en SQLite para que ejecuciones repetidas solo alerten cambios significativos. - Notificaciones SMTP de Gmail usando contraseñas de aplicación. - Un perfil persistente de Chrome para mantener cookies y estado de sesión. - Escritura, clics, retrasos y desplazamiento similares a humanos. - Banderas anti-detección de Chrome mediante `undetected_chromedriver`. - Proyecto Python basado en `uv` con pruebas, revisión de código y verificación de tipos. - Plantillas de temporizador de usuario de systemd para Linux / Oracle Cloud. La sección de estado del README indica que el desafío de Cloudflare se resolvió en modo headed, el inicio de sesión funcionó con perfil persistente, el flujo de exámenes prácticos alcanzó disponibilidad de sedes, las fechas se extrajeron y compararon contra estado de SQLite, y el formato de notificaciones por correo funcionó. Requisitos - Python 3.12 o 3.13 - `uv` - Chrome o Chrome for Testing - Una cuenta de Educación Vial - Un número de recibo para el flujo de exámenes prácticos - Opcionalmente, una contraseña de aplicación de Gmail para notificaciones por correo Primeros pasos Clona el repositorio, ejecuta `uv sync`, luego `uv run quick-cita init`. Los secretos se almacenan en `~/.config/quick-cita-cr/secrets.env` (el README sugiere `chmod 600`), y las sedes junto con configuración del navegador en `~/.config/quick-cita-cr/config.yaml`. Las diagnósticos están disponibles mediante `uv run quick-cita doctor`. Una verificación visible única se ejecuta con `uv run quick-cita check --headed`, y el monitoreo continuo con `uv run quick-cita watch --headed`. Existe también un comando `demo` que abre navegador visible, usa el perfil persistente, verifica sedes configuradas e imprime resumen de citas incluso sin eventos de alerta. Áreas de configuración La configuración YAML cubre tres grupos: - **appointment** — clase de licencia, lista de sedes, `quick_window_days`, e interruptores para notificaciones en primera ejecución, fechas nuevas, fecha óptima más temprana y dentro de ventana. - **schedule** — intervalo en minutos, porcentaje de jitter, máximos fallos antes de pausar, y duración de la pausa tras fallos. - **browser** — bandera headless, ruta ejecutable de Chrome, directorio de perfil y tiempo de espera. Las notificaciones actualmente soportan correo mediante SMTP de Gmail (host, puerto, dirección de envío, lista de destinatarios). Secretos como tipo de identificación, número de identificación, contraseña, número de recibo y credenciales de correo se leen desde variables de entorno o archivo de secretos. Chrome sin sudo Para máquinas sin Chrome instalado en sistema Linux y sin `sudo`, el README proporciona secuencia para descargar Chrome for Testing en `~/.local/share/quick-cita-cr/chrome-for-testing`, descomprimirlo con snippet Python breve, y marcar binario y manejador crashpad como ejecutables. `executable_path` en la configuración apunta entonces al binario extraído. Desarrollo y estructura Comandos de desarrollo incluyen `uv sync --all-groups`, `ruff format`, `ruff check`, `mypy` en `src/quick_cita_cr`, y `pytest`. El árbol fuente agrupa automatización de navegador (driver, solucionador Cloudflare, ayudantes de comportamiento humano), backends de notificación, CLI Typer, modelos de configuración y secretos, cliente del portal, parser de fechas de citas, almacenamiento SQLite, y watcher que compara snapshots y detecta eventos. Pruebas, GitHub Actions CI, plantillas de despliegue systemd y documentación de seguridad/resguardo acompañan. Nota de seguridad El README advierte contra subir credenciales, archivos `.env`, estado SQLite, perfiles de navegador, cookies, capturas, registros o HTML autenticado, y remite a `docs/security.md`. Licencia MIT.