quick-cita-cr

## 개요 quick-cita-cr은 코스타리카 Educación Vial 포털의 예약 가능 여부를 확인하는 개인용 모니터링 도구입니다. 사용자 자신의 계정 자격 증명으로 로그인하여 설정한 실기 시험(practical-test) 지점을 확인하고, 이미 확인한 내역을 로컬에 기록하며, 새로운 날짜나 더 빠른 날짜가 나타나면 알림을 보냅니다. README에 따르면 이 프로젝트는 라이브 포털을 통해 로컬에서 검증되었습니다. 알려진 제한 사항으로, 검증 과정에서 순수 headless 모드로는 Cloudflare 챌린지가 안정적으로 해결되지 않았으므로, 무인 배포 시에는 headed 모드, 가상 디스플레이 또는 활성화된 지속성 프로필(warmed persistent profile) 사용을 권장합니다. ## 보고된 기능 README에 나열된 주요 기능은 다음과 같습니다: - 지점별 예약 모니터링. - 새로운 날짜, 더 빠른 최적 날짜, 설정 가능한 "퀵 윈도우(quick window)" 기간에 대한 알림. - SQLite 상태 저장을 통해 의미 있는 변경 사항에 대해서만 반복 알림 전송. - 앱 비밀번호를 이용한 Gmail SMTP 알림. - 쿠키 및 세션 상태 유지를 위한 지속성 Chrome 프로필. - 인간과 유사한 타이핑, 클릭, 지연 및 스크롤 동작. - `undetected_chromedriver`를 통한 Chrome 탐지 방지 플래그. - 테스트, 린팅 및 타입 체크가 포함된 `uv` 기반 Python 프로젝트. - Linux / Oracle Cloud를 위한 systemd 사용자 타이머 템플릿. README의 상태 섹션에 따르면, headed 모드에서 Cloudflare 챌린지가 해결되었고, 지속성 프로필로 로그인이 작동했으며, 실기 시험 흐름을 통해 지점 가용성에 도달했고, 예약 날짜를 추출하여 SQLite 상태와 비교했으며, 이메일 알림 형식이 정상 작동함을 확인했습니다. ## 요구 사항 - Python 3.12 또는 3.13 - `uv` - Chrome 또는 Chrome for Testing - Educación Vial 계정 - 실기 시험 흐름을 위한 영수증 번호 - (선택 사항) 이메일 알림을 위한 Gmail 앱 비밀번호 ## 시작하기 리포지토리를 클론하고 `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** — 분 단위 간격, 지터(jitter) 퍼센트, 일시 중지 전 최대 실패 횟수 및 실패 후 일시 중지 시간. - **browser** — headless 플래그, Chrome 실행 파일 경로, 프로필 디렉토리 및 타임아웃. 알림은 현재 Gmail SMTP(호스트, 포트, 발신 주소, 수신자 목록)를 통한 이메일을 지원합니다. ID 유형, 식별 번호, 비밀번호, 영수증 번호 및 이메일 자격 증명과 같은 비밀 정보는 환경 변수나 비밀 파일에서 읽어옵니다. ## sudo 없는 Chrome 설치 시스템에 Linux Chrome이 설치되어 있지 않고 `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`, `src/quick_cita_cr`에 대한 `mypy`, 그리고 `pytest`가 포함됩니다. 소스 트리는 브라우저 자동화(드라이버, Cloudflare 해결사, 인간 행동 헬퍼), 알림 백엔드, Typer CLI, 설정 및 비밀 모델, 포털 클라이언트, 예약 날짜 파서, SQLite 저장소, 그리고 스냅샷을 비교하여 이벤트를 감지하는 와처(watcher)로 구성됩니다. 테스트, GitHub Actions CI, systemd 배포 템플릿, 배포/보안 문서가 함께 포함되어 있습니다. ## 보안 주의사항 README는 자격 증명, `.env` 파일, SQLite 상태, 브라우저 프로필, 쿠키, 스크린샷, 로그 또는 인증된 HTML을 커밋하지 말라고 경고하며, `docs/security.md`를 참조하도록 안내합니다. ## 라이선스 MIT.