quick-cita-cr

## O que é quick-cita-cr é uma ferramenta de monitoramento pessoal para vagas de agendamento no portal Educação Vial da Costa Rica. Efetua login com suas credenciais de conta, verifica as agências de prova prática que você configurar, mantém um registro local do que já foi visualizado e notifica quando surgirem datas novas ou anteriores. O README informa que o projeto foi validado localmente contra o portal em produção. Também menciona uma limitação conhecida: durante a validação, os desafios do Cloudflare não foram resolvidos de forma confiável em modo headless puro, sendo recomendado modo com interface, um display virtual ou um perfil persistente pré-carregado para implantações não supervisionadas. ## Funcionalidades reportadas O README lista estas características: - Monitoramento de agendamentos por agência. - Alertas para novas datas, data anterior mais cedo e uma "janela rápida" configurável em dias. - Estado SQLite para que execuções repetidas só alertem sobre mudanças significativas. - Notificações por SMTP do Gmail usando senhas de aplicativo. - Perfil persistente do Chrome para manter cookies e estado da sessão. - Digitação, cliques, atrasos e rolagem com comportamento humano. - Flags anti-detecção do Chrome através do `undetected_chromedriver`. - Projeto Python baseado em `uv` com testes, linting e verificações de tipo. - Modelos de timer do systemd para Linux / Oracle Cloud. A seção de status do README afirma que o desafio do Cloudflare foi resolvido em modo com interface, o login funcionou com perfil persistente, o fluxo de prova prática alcançou a disponibilidade de agências, datas de agendamento foram extraídas e comparadas com o estado do SQLite, e a formatação das notificações por e-mail funcionou. ## Requisitos - Python 3.12 ou 3.13 - `uv` - Chrome ou Chrome for Testing - Uma conta no Educação Vial - Um número de recibo para o fluxo de prova prática - Opcionalmente, uma senha de aplicativo do Gmail para notificações por e-mail ## Primeiros passos Clone o repositório, execute `uv sync`, depois `uv run quick-cita init`. Os segredos ficam em `~/.config/quick-cita-cr/secrets.env` (o README sugere `chmod 600`), e agências mais configurações do navegador ficam em `~/.config/quick-cita-cr/config.yaml`. Diagnósticos estão disponíveis via `uv run quick-cita doctor`. Uma verificação visível única pode ser executada com `uv run quick-cita check --headed`, e monitoramento contínuo com `uv run quick-cita watch --headed`. Há também um comando `demo` que abre um navegador visível, usa o perfil persistente, verifica as agências configuradas e imprime o resumo de agendamentos mesmo sem novos eventos de alerta. ## Áreas de configuração A configuração YAML abrange três grupos: - **appointment** — classe da carteira, lista de agências, `quick_window_days` e interruptores para notificações na primeira execução, novas datas, data anterior mais cedo e dentro da janela. - **schedule** — intervalo em minutos, percentual de jitter, falhas máximas antes de pausar e tempo de pausa após falhas. - **browser** — flag headless, caminho do executável do Chrome, diretório do perfil e timeout. Notificações atualmente suportam e-mail via SMTP do Gmail (host, porta, endereço de remetente, lista de destinatários). Segredos como tipo de identificação, número de identificação, senha, número de recibo e credenciais de e-mail são lidos de variáveis de ambiente ou do arquivo de segredos. ## Chrome sem sudo Para máquinas sem Chrome Linux instalado no sistema e sem `sudo`, o README fornece sequência para baixar o Chrome for Testing em `~/.local/share/quick-cita-cr/chrome-for-testing`, descompactar com um snippet Python curto e tornar o binário e handler crashpad executáveis. O `executable_path` na configuração aponta então para esse binário extraído. ## Desenvolvimento e estrutura Comandos de desenvolvimento incluem `uv sync --all-groups`, `ruff format`, `ruff check`, `mypy` em `src/quick_cita_cr` e `pytest`. A árvore de fontes agrupa automação de navegador (driver, resolvedor Cloudflare, auxiliares de comportamento humano), backends de notificação, CLI Typer, modelos de configuração e segredos, cliente do portal, parser de datas de agendamento, armazenamento SQLite e o observador que compara snapshots e detecta eventos. Testes, CI do GitHub Actions, modelos de implantação systemd e documentação de implantação/segurança ficam ao lado. ## Observação de segurança O README adverte contra comitar credenciais, arquivos `.env`, estado SQLite, perfis de navegador, cookies, screenshots, logs ou HTML autenticado, e aponta para `docs/security.md`. ## Licença MIT.