initializare

CLAUDE.md

@@ -0,0 +1,113 @@
+# 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