Об этом проекте

## Что это такое quick-cita-cr — это инструмент для личного мониторинга доступных записей на портале Educación Vial Коста-Рики. Он авторизуется под вашими учетными данными, проверяет настроенные филиалы для практического экзамена, хранит локальную запись уже просмотренных данных и уведомляет вас при появлении новых или более ранних дат. В README указано, что проект был протестирован локально на реальном портале. Также отмечено одно известное ограничение: во время тестирования Cloudflare-вызовы не всегда надежно разрешались в чисто headless-режиме, поэтому для автономных развертываний рекомендуется использовать режим с интерфейсом, виртуальный дисплей или предварительно подготовленный постоянный профиль. ## Заявленные возможности README перечисляет следующие функции: - Мониторинг записей по каждому филиалу. - Уведомления о новых датах, более ранней лучшей дате и в пределах настраиваемого «быстрого окна» дней. - Локальное состояние в SQLite, чтобы повторные запуски уведомляли только о значимых изменениях. - Уведомления по email через Gmail SMTP с использованием паролей приложений. - Постоянный профиль Chrome для сохранения cookies и состояния сессии. - Имитация человеческого поведения: набор текста, клики, задержки, прокрутка. - Флаги антиобнаружения Chrome через `undetected_chromedriver`. - Проект на Python с использованием `uv`, с тестами, линтингом и проверкой типов. - Шаблоны таймеров systemd для Linux / Oracle Cloud. В разделе статуса README говорится, что Cloudflare-вызовы успешно разрешились в режиме с интерфейсом, вход работал с постоянным профилем, поток практического экзамена достиг проверки доступности филиалов, даты записей извлекались и сравнивались с состоянием SQLite, а форматирование email-уведомлений работало корректно. ## Требования - Python 3.12 или 3.13 - `uv` - Chrome или Chrome for Testing - Учетная запись Educación Vial - Номер квитанции для потока практического экзамена - Опционально: пароль приложения Gmail для email-уведомлений ## Начало работы Клонируйте репозиторий, выполните `uv sync`, затем `uv run quick-cita init`. Секреты хранятся в `~/.config/quick-cita-cr/secrets.env` (в README рекомендуется `chmod 600`), а настройки филиалов и браузера — в `~/.config/quick-cita-cr/config.yaml`. Диагностика доступна через `uv run quick-cita doctor`. Одиночную видимую проверку можно запустить командой `uv run quick-cita check --headed`, непрерывный мониторинг — `uv run quick-cita watch --headed`. Есть также команда `demo`, которая открывает видимый браузер, использует постоянный профиль, проверяет настроенные филиалы и выводит сводку по записям даже при отсутствии новых событий. ## Области конфигурации YAML-конфигурация охватывает три группы: - **appointment** — класс лицензии, список филиалов, `quick_window_days`, переключатели для уведомлений при первом запуске, новых датах, более ранней лучшей дате и в пределах окна. - **schedule** — интервал в минутах, процент дрожания, максимальное количество сбоев перед паузой и продолжительность паузы после сбоев. - **browser** — флаг headless, путь к исполняемому файлу Chrome, директория профиля и таймаут. Уведомления в настоящее время поддерживают email через Gmail SMTP (хост, порт, адрес отправителя, список получателей). Секреты, такие как тип ID, номер идентификации, пароль, номер квитанции и учетные данные email, считываются из переменных среды или файла секретов. ## Chrome без sudo Для машин без системной установки Chrome в Linux и без прав `sudo` README предлагает последовательность загрузки Chrome for Testing в `~/.local/share/quick-cita-cr/chrome-for-testing`, распаковки его с помощью короткого Python-скрипта и установки исполняемых прав для бинарника и обработчика crashpad. В конфигурации `executable_path` указывается на этот извлеченный бинарник. ## Разработка и структура Команды разработки включают `uv sync --all-groups`, `ruff format`, `ruff check`, `mypy` для `src/quick_cita_cr` и `pytest`. Исходный код организован по группам: автоматизация браузера (драйвер, решатель Cloudflare, помощники имитации человеческого поведения), бэкенды уведомлений, CLI Typer, модели конфигурации и секретов, клиент портала, парсер дат записи, хранилище SQLite и наблюдатель, сравнивающий снимки и выявляющий события. Тесты, CI GitHub Actions, шаблоны развертывания systemd и документация по развертыванию/безопасности находятся рядом. ## Примечание по безопасности README предупреждает против коммита учетных данных, файлов `.env`, состояния SQLite, профилей браузера, cookies, скриншотов, логов или аутентифицированного HTML и ссылается на `docs/security.md`. ## Лицензия MIT.