quick-cita-cr

## 概要 quick-cita-crは、コスタリカのEducación Vialポータルにおける予約空き状況を監視するための個人用ツールです。ユーザー自身のアカウント資格情報を使用してサインインし、設定した実技試験拠点をチェックし、既に見つけた情報をローカルに記録して、新しい日程やより早い日程が表示された際に通知を行います。 READMEによると、本プロジェクトはライブポータルに対してローカルで検証済みです。また、既知の制限事項として、検証中にCloudflareのチャレンジが純粋なヘッドレスモードでは安定して解決しなかったため、無人デプロイメントにはヘッドモード、仮想ディスプレイ、またはウォームアップ済みの永続プロファイルの利用が推奨されています。 ## 報告されている機能 READMEには以下の機能が記載されています： - 拠点ごとの予約監視。 - 新しい日程、より早い最良の日程、および設定可能な「クイックウィンドウ（日数）」に対するアラート。 - SQLiteによる状態管理により、意味のある変更があった場合のみ通知。 - アプリパスワードを使用したGmail SMTP通知。 - クッキーとセッション状態を保持するための永続的なChromeプロファイル。 - 人間に近いタイピング、クリック、遅延、およびスクロール動作。 - `undetected_chromedriver`によるChromeの検知回避フラグ。 - テスト、リンティング、型チェックを備えた`uv`ベースのPythonプロジェクト。 - Linux / Oracle Cloud向けのsystemdユーザータイマーテンプレート。 READMEのステータスセクションでは、ヘッドモードでの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設定は3つのグループで構成されています： - **appointment** — 免許種別、拠点リスト、`quick_window_days`、および初回実行・新日程・最良日程・ウィンドウ内通知のスイッチ。 - **schedule** — 分単位の間隔、ジッター率、一時停止前の最大失敗回数、および失敗後の停止時間。 - **browser** — ヘッドレスフラグ、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ストレージ、およびスナップショットを比較してイベントを検出するウォッチャーにグループ化されています。テスト、GitHub Actions CI、systemdデプロイテンプレート、およびデプロイ/セキュリティドキュメントが併設されています。 ## セキュリティ上の注意 READMEでは、資格情報、`.env`ファイル、SQLiteの状態、ブラウザプロファイル、クッキー、スクリーンショット、ログ、または認証済みHTMLをコミットしないよう警告しており、`docs/security.md`を参照するように指示しています。 ## ライセンス MIT