add AGENTS.md

2026-04-23 22:26:54 +02:00
parent 6b05eb38d7
commit 64e47e05e7
1 changed files with 63 additions and 0 deletions
@@ -0,0 +1,63 @@
+# AGENTS.md
+
+## Project
+
+Python bot automating appointment requests (French immigration/visa). Multi-threaded HTTP workers + MongoDB tracking + RabbitMQ queuing. FastAPI wrapper (`api/`) provides HTTP/WebSocket control plane.
+
+## Install
+
+```bash
+pip install -r requirements.txt     # main bot
+pip install pymongo                  # NOT in requirements.txt but required by db/mongo_manager.py
+pip install -r api_requirements.txt  # FastAPI wrapper only
+```
+
+## Run Commands
+
+```bash
+python scheduler.py              # production cron (Mon–Sat 10:30 Europe/Paris)
+python scheduler_test.py         # test variant (Mon–Sun)
+python request_sender_test.py    # manual run — edit hardcoded `file_list` at bottom first
+python scheduler_link_validator.py
+
+uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload  # FastAPI server
+```
+
+## No Tests / No Lint / No Typecheck
+
+`*_test.py` files are **standalone scripts**, not pytest tests. Run them with `python`, not `pytest`. There is no test framework, no linter, no formatter, no CI configured.
+
+## Key Quirks
+
+- **`utiles.py` (intentional typo)** — time utility module. Imported as `from utiles import is_time_between`. Do not rename.
+- **`requirements.txt` incomplete** — `pymongo` missing; must be installed separately.
+- **`venv/` is committed** — do not delete.
+- **`.env` file required** for FastAPI server: `API_KEY`, `API_HOST`, `API_PORT`, `LOG_LEVEL`, `ALLOWED_ORIGINS`, `DEFAULT_THREAD_NUMBER`, `DEFAULT_STOP_HOUR`, `DEFAULT_STOP_MINS`.
+- **MongoDB env vars** — `MONGO_USERNAME` and `MONGO_PASSWORD` must be set; `db/mongo_manager.py` raises `ValueError` if missing. Hardcoded host: `mongo2.lpaconsulting.fr`.
+- **RabbitMQ credentials** hardcoded in `queue_message/CookiesPublisher.py`. Host: `appointment.lpaconsulting.fr:5672`.
+- **`curl_cffi`** used for HTTP (not `requests`/`httpx`) to bypass TLS fingerprinting / bot detection.
+- **Module-level side effects** — importing `request_sender.py` calls `init_logger()` at import time (no `__main__` guard).
+
+## External Service Dependencies
+
+Bot will fail without network access to:
+- MongoDB at `mongo2.lpaconsulting.fr` (needs env vars)
+- RabbitMQ at `appointment.lpaconsulting.fr:5672`
+- Proxy servers defined in `workers/proxies_constants.py` and `workers/proxy_constants.py`
+
+## Structure
+
+```
+api/              FastAPI control plane (start/stop, log streaming)
+captcha/          CAPTCHA solver wrapper
+db/               MongoDB singleton (MONGO_STORE_MANAGER)
+mail/             IMAP helpers
+models/           Data POJOs (ContactPojo, LinkPojo, etc.)
+proxy_manager/    Proxy list management
+queue_message/    RabbitMQ publisher/consumer (pika)
+utils/            Misc helpers (logging, cookies, JS data)
+workers/          Core HTTP workers (sender, link validator, cookie generator)
+excel_reader.py   Reads .xlsx contact lists via openpyxl
+utiles.py         Time utility (note spelling)
+scheduler.py      Production APScheduler entry point
+```