114 lines
3.5 KiB
Markdown
114 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
BTGO Scraper - Playwright automation for extracting account balances and transaction CSVs from Banca Transilvania George (btgo.ro).
|
|
|
|
**Security Context**: Authorized personal banking automation tool for educational purposes.
|
|
|
|
**⚠️ CRITICAL**: Docker/headless mode is **BLOCKED by WAF**. ONLY works locally with `HEADLESS=false`.
|
|
|
|
## Running the Scraper
|
|
|
|
```powershell
|
|
# Windows setup
|
|
deployment\windows\scripts\setup_dev.ps1
|
|
|
|
# Run scraper (browser visible)
|
|
deployment\windows\scripts\run_scraper.ps1
|
|
|
|
# Run Telegram bot (manual)
|
|
deployment\windows\scripts\run_telegram_bot_manual.ps1
|
|
|
|
# Interactive menu (all options)
|
|
deployment\windows\scripts\menu.ps1
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Flow
|
|
```
|
|
login() → handle_2fa_wait() → read_accounts() → download_transactions() → save_results()
|
|
```
|
|
|
|
### Critical Implementation Details
|
|
|
|
#### 1. Login with Popup (lines ~140-200)
|
|
- Main page → Click "LOGIN" → **Opens popup window**
|
|
- Use `page.expect_popup()` to capture popup reference
|
|
- All operations happen in `self.login_page` (the popup)
|
|
|
|
#### 2. 2FA Auto-Detection (lines ~202-240)
|
|
- URL monitoring: `login.bancatransilvania.ro` → `goapp.bancatransilvania.ro`
|
|
- Poll for `#accountsBtn` element every 2 seconds
|
|
- After 2FA: `self.page = self.login_page` (switch page reference)
|
|
|
|
#### 3. Account Reading (lines ~242-310)
|
|
- Elements: `fba-account-details-card`, `#accountsBtn`
|
|
- Each card: `h4` (name), `span.text-grayscale-label` (IBAN), `strong.sold` (balance)
|
|
- Balance format: `"7,223.26 RON"` → parse to float + currency
|
|
|
|
#### 4. Transaction Download Modal (lines ~312-420)
|
|
|
|
**State Machine:**
|
|
```
|
|
Account 1: Expand card → Click "Tranzacții" → Download → Back → Modal
|
|
Account 2+: Select from modal → [ALREADY on page] → Download → Back
|
|
```
|
|
|
|
**Critical**: After modal selection, you're ALREADY on transactions page. Don't expand/click again.
|
|
|
|
**Modal selectors:**
|
|
- Modal: `.modal-content`
|
|
- Account buttons: `#accountC14RONCRT{last_10_iban_digits}`
|
|
- Example: IBAN `...0637236701` → `#accountC14RONCRT0637236701`
|
|
|
|
### Key Selectors
|
|
|
|
- Login: `get_by_placeholder("ID de logare")`, `get_by_placeholder("Parola")`
|
|
- Post-login: `#accountsBtn`, `goapp.bancatransilvania.ro` domain
|
|
- Accounts: `fba-account-details-card`, `.collapse-account-btn`, `.account-transactions-btn`
|
|
- Modal: `.modal-content`, `#accountC14RONCRT{iban_digits}`
|
|
- CSV: `get_by_role("button", name="CSV")`
|
|
|
|
**Update selectors:** `playwright codegen https://btgo.ro --target python`
|
|
|
|
## Docker Limitation
|
|
|
|
**Docker DOES NOT WORK** - Akamai WAF blocks with "Access Denied".
|
|
|
|
**Symptoms:**
|
|
- "Access Denied" page
|
|
- 0 links detected
|
|
- Screenshot: `data/debug_before_login_*.png` shows error
|
|
|
|
**Solution:** Use Windows local mode with `HEADLESS=false`.
|
|
|
|
## Common Issues
|
|
|
|
### Access Denied (Docker)
|
|
- **Cause**: WAF blocking
|
|
- **Fix**: Run locally with `HEADLESS=false`
|
|
|
|
### Transaction Download Timeout
|
|
- Modal not detected: Check `.modal-content` selector
|
|
- Account ID mismatch: Verify IBAN mapping `#accountC14RONCRT{last_10_digits}`
|
|
- For idx > 1: Already on page, don't expand/click
|
|
|
|
### 2FA Timeout
|
|
- Increase `TIMEOUT_2FA_SECONDS` in `.env`
|
|
- Verify URL redirect to `goapp.bancatransilvania.ro`
|
|
|
|
### "Nu exista card la pozitia X"
|
|
- Trying to access cards in modal context
|
|
- First account needs expand, subsequent accounts don't
|
|
|
|
## Exit Codes
|
|
|
|
- `0`: Success
|
|
- `1`: General error
|
|
- `4`: Config error (.env invalid)
|
|
- `99`: Unexpected error
|