romfast/btgo-playwright
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rescrie README compact, axat pe deploy si depanare

Browse Source 
Reduce de la 475 la 175 linii. Elimina diagrama ASCII de arhitectura
si sectiunile duplicate. Adauga sectiune dedicata pentru eroarea de
viewport-mic / Windows Service session 0, cu trimitere la fix-ul
--window-size din btgo_scraper.py. Reorganizeaza troubleshooting
pe simptome utilizator, nu pe linii de cod.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Marius Mutu
2026-05-15 12:52:42 +03:00
parent 2330b35ad7
commit da31a806af
1 changed files with 129 additions and 408 deletions
Download Patch File Download Diff File Expand all files Collapse all files

537
README.md
View File

@@ -1,474 +1,195 @@
# BTGO Scraper - Automatizare Citire Solduri
# BTGO Scraper
## Prezentare
Automatizare Playwright care se logheaza pe **George (go.bancatransilvania.ro)**, citeste soldurile tuturor conturilor si descarca CSV-urile de tranzactii. Trimite rezultatele pe **Email** si **Telegram**. Poate fi declansata din Telegram printr-un bot (`/scrape`).
Automatizare Playwright pentru extragerea soldurilor și tranzacțiilor din George (btgo.ro).
## Cerinte
## Arhitectură
- **Windows 10/11** (Linux/Docker nu functioneaza — Akamai WAF blocheaza)
- **Python 3.11+** in PATH
- Cont BTGO activ cu 2FA pe telefon
### BTGO Scraper (btgo_scraper.py)
**IMPORTANT — `HEADLESS=false` obligatoriu.** WAF-ul BT blocheaza browser-ele headless. Scraper-ul ruleaza intotdeauna cu fereastra Chromium vizibila.
```
Entry point: btgo_scraper.py
│
├─ config.py (Config.validate())
│ └─ .env (load credentials)
│
├─ sync_playwright() → Chromium browser
│
├─ BTGOScraper.run()
│ ├─ login()
│ │ ├─ page.goto('go.bancatransilvania.ro')
│ │ ├─ page.expect_popup() → self.login_page
│ │ └─ Fill credentials + submit
│ │
│ ├─ handle_2fa_wait()
│ │ └─ Poll URL + #accountsBtn (120s)
│ │
│ ├─ read_accounts()
│ │ ├─ Click #accountsBtn
│ │ ├─ Iterate fba-account-details-card
│ │ └─ Extract: h4, IBAN, strong.sold
│ │
│ ├─ download_transactions() [optional]
│ │ ├─ For each account:
│ │ │ ├─ Expand card (idx=1 only)
│ │ │ ├─ Click "Tranzacții" (idx=1) / Select from modal (idx>1)
│ │ │ ├─ Click CSV button
│ │ │ └─ page.expect_download()
│ │ └─ Save to data/tranzactii_*.csv
│ │
│ ├─ save_results()
│ │ ├─ Write data/solduri_*.csv
│ │ └─ Write data/solduri_*.json
│ │
│ └─ send_notifications() [optional]
│ └─ notifications.py
│ ├─ EmailNotifier.send()
│ │ └─ SMTP (smtplib)
│ └─ TelegramNotifier.send()
│ └─ requests.post(telegram API)
│
Standalone scripts:
│
├─ send_notifications.py (manual notification send)
├─ get_telegram_chat_id.py (telegram setup helper)
└─ test_telegram.py (telegram connectivity test)
```
### Telegram Trigger Bot (telegram_trigger_bot.py)
```
Entry point: telegram_trigger_bot.py
│
├─ .env (TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USER_IDS)
│
├─ TelegramTriggerBot.__init__()
│ ├─ Load config from .env
│ ├─ Parse allowed user IDs
│ └─ Initialize Telegram API (api.telegram.org)
│
├─ run()
│ ├─ send_message(startup notification)
│ └─ While True:
│ ├─ get_updates(long_polling timeout=60s)
│ ├─ Parse incoming messages
│ └─ handle_command()
│ │
│ ├─ /scrape command:
│ │ ├─ is_user_allowed(user_id)
│ │ ├─ send_message("🤖 Scraper pornit...")
│ │ ├─ subprocess.run(['python', 'btgo_scraper.py'])
│ │ │ └─ btgo_scraper.py (full execution)
│ │ └─ send_message("✅ Succes" / "❌ Eroare")
│ │
│ ├─ /status command:
│ │ └─ send_message(bot uptime info)
│ │
│ └─ /help command:
│ └─ send_message(available commands)
│
Windows Service:
│
└─ deployment/windows/nssm/
├─ BTGOTelegramBot (Windows Service)
│ ├─ nssm install BTGOTelegramBot
│ ├─ Auto-restart on failure
│ └─ Log: logs/telegram_bot_*.log
│
Deploy scripts:
├─ deploy.ps1 (full deployment)
├─ install_service.ps1
├─ start_service.ps1
├─ restart_service.ps1
├─ uninstall_service.ps1
└─ menu.ps1 (interactive management)
```
**Puncte cheie depanare:**
- **Scraper login fails**: Check selectors în btgo_scraper.py:159-200
- **Scraper 2FA timeout**: Check URL polling în btgo_scraper.py:202-240
- **Scraper account reading fails**: Check selectors în btgo_scraper.py:242-310
- **Scraper transaction download timeout**: Check modal logic în btgo_scraper.py:312-420
- **Bot commands not working**: Check TELEGRAM_ALLOWED_USER_IDS în .env
- **Bot unauthorized**: User ID not in allowed list
- **Notifications fail**: Check notifications.py + config .env
**Funcționalități:**
- ✅ Citire automată solduri pentru toate conturile
- ✅ Export CSV cu tranzacții pentru fiecare cont
- ✅ Autentificare 2FA automată (auto-detect)
- ✅ Notificări Email și Telegram cu fișierele generate
**⚠️ LIMITARE: Docker/headless NU funcționează** - WAF-ul site-ului blochează activ containere Docker.
## Prerequisites
- Python 3.8+
- Cont BTGO activ cu 2FA
- Windows (Docker nu este suportat)
## Instalare pe VM Windows
## Instalare rapida
```powershell
# Clonare proiect
git clone https://gitea.romfast.ro/romfast/btgo-playwright.git
cd btgo-playwright
# Setup automat (instaleaza Python venv + dependente + Playwright browsers)
git clone <repo-url> E:\proiecte\btgo-playwright
cd E:\proiecte\btgo-playwright
deployment\windows\scripts\setup_dev.ps1
```
# Configurare credentiale in .env
# Editează .env și adaugă:
# BTGO_USERNAME=your_username
# BTGO_PASSWORD=your_password
# HEADLESS=false
Script-ul creeaza `.venv`, instaleaza dependentele si Chromium-ul Playwright.
# Rulare scraper
Apoi editeaza `.env` (copiat automat din `.env.example` la primul run):
```ini
BTGO_USERNAME=user_btgo
BTGO_PASSWORD=parola_btgo
HEADLESS=false # OBLIGATORIU false
TIMEOUT_2FA_SECONDS=300
# Notificari
ENABLE_NOTIFICATIONS=true
EMAIL_ENABLED=true
SMTP_USERNAME=tu@gmail.com
SMTP_PASSWORD=app-password # Gmail: https://myaccount.google.com/apppasswords
EMAIL_TO=tu@gmail.com
# Telegram (notificari + trigger bot)
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=123:ABC...
TELEGRAM_CHAT_ID=-100123... # Negativ pentru grupuri
TELEGRAM_ALLOWED_USER_IDS=12345 # User-ii care pot da /scrape
```
## Rulare zilnica
**Manual (din terminal):**
```powershell
deployment\windows\scripts\run_scraper.ps1
```
### Actualizare după Modificări
Browser-ul se deschide, scraper-ul completeaza credentialele, apoi astepti **2FA pe telefon**. Dupa aprobare ruleaza automat: citeste solduri → descarca tranzactii → trimite Email + Telegram → salveaza in `data/`.
**Meniu interactiv (toate optiunile):**
```powershell
# Pull ultimele modificări
git pull origin main
# Dacă rulează ca Windows Service (bot):
deployment\windows\scripts\restart_service.ps1
# Dacă rulează manual (dev local):
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
## Setup și Rulare
### Setup Automat (RECOMANDAT)
```powershell
# PowerShell (recomandat)
deployment\windows\scripts\setup_dev.ps1
# SAU meniu interactiv complet
deployment\windows\scripts\menu.ps1
```
### Rulare Manuală
## Deploy ca serviciu Windows (recomandat pentru VM)
Bot-ul Telegram ruleaza in background si raspunde la `/scrape`. Necesita **sesiune RDP activa** ca browser-ul sa aiba un desktop pe care sa se deschida.
```powershell
# Scraper direct
deployment\windows\scripts\run_scraper.ps1
# Telegram bot (manual mode)
deployment\windows\scripts\run_telegram_bot_manual.ps1
# SAU meniu interactiv
deployment\windows\scripts\menu.ps1
# Ca Administrator
deployment\windows\scripts\deploy.ps1
```
**Ce se întâmplă:**
1. Browser Chrome se deschide vizibil
2. Login automat
3. Așteaptă aprobare 2FA pe telefon (120s timeout)
4. Citește soldurile tuturor conturilor
5. Descarcă CSV-uri cu tranzacții
6. Salvează rezultate în `data/`
Asta instaleaza serviciul `BTGOTelegramBot` prin NSSM (auto-start cu Windows, auto-restart la crash).
### Configurare `.env`
**Comenzi utile:**
```bash
# Obligatorii
BTGO_USERNAME=your_username
BTGO_PASSWORD=your_password
HEADLESS=false # OBLIGATORIU false!
# Opționale
DOWNLOAD_TRANSACTIONS=true
TIMEOUT_2FA_SECONDS=120
```powershell
deployment\windows\scripts\status.ps1 # status + ultimele logs
deployment\windows\scripts\restart_service.ps1 # restart dupa modificari
deployment\windows\scripts\view_logs.ps1 # viewer interactiv logs
deployment\windows\scripts\uninstall_service.ps1 # dezinstalare
```
## Structură Output
**Update dupa git pull:**
```powershell
deployment\windows\scripts\update.ps1 # git pull + restart serviciu (auto-elevare)
```
**Comenzi disponibile in Telegram:**
| Comanda | Ce face |
|---------------|------------------------------------------------------------|
| `/scrape` | Ruleaza scraper-ul, trimite solduri + fisiere individuale |
| `/scrape_zip` | Ruleaza scraper-ul, trimite arhiva ZIP |
| `/zip` | Trimite ultimele fisiere din `data/` ca ZIP (fara scrape) |
| `/status` | Uptime bot |
| `/help` | Lista comenzi |
## Output
```
data/
├── solduri_2025-11-06_14-30-45.csv # Rezumat solduri
├── solduri_2025-11-06_14-30-45.json # Metadata + solduri
├── tranzactii_Colector_01_2025-11-06.csv # Tranzacții per cont
└── dashboard_2025-11-06_14-30-45.png # Screenshot
solduri_YYYY-MM-DD_HH-MM-SS.csv # rezumat conturi
solduri_YYYY-MM-DD_HH-MM-SS.json # acelasi + metadata
tranzactii_<NumeCont>_YYYY-MM-DD.csv
dashboard_*.png # screenshot post-login
debug_login_popup_*.png # debug login (cand esueaza)
logs/
└── scraper_2025-11-06.log # Log zilnic
scraper_YYYY-MM-DD.log # log zilnic scraper
telegram_bot_*.log # log serviciu Telegram (NSSM)
```
### Format CSV Solduri
## Depanare
```csv
timestamp,nume_cont,iban,sold,moneda,tip_cont
2025-11-06 14:30:45,Colector 01,RO32BTRLRONCRT0637236701,7223.26,RON,colector
### "Nu am gasit elementele de login" / timeout pe `input#user`
Apare cand fereastra Chromium e prea ingusta (sub ~1100px). La acest viewport BT afiseaza un splash de redirect si ascunde formul. Cauza tipica: scraper-ul ruleaza dintr-un Windows Service in **session 0**, fara display real, iar fereastra fizica are dimensiune mica chiar daca codul cere `viewport=1920x1080`.
**Fix deja aplicat in cod:** browser-ul lansat cu `--window-size=1920,1080` (vezi `btgo_scraper.py:388-398`).
**Daca tot apare:** verifica `data\debug_login_popup_*.png` — daca vezi splash-ul "Vei fi redirectionat in screenul de autentificare", inseamna ca window-size nu s-a aplicat. Solutie: porneste scraper-ul printr-o sesiune RDP activa (nu doar serviciu in session 0).
### "Access Denied" pe pagina de login
Akamai WAF a detectat headless mode. Verifica:
```ini
HEADLESS=false # obligatoriu
```
## Notificări (Email & Telegram)
### Email (SMTP)
```bash
# .env
ENABLE_NOTIFICATIONS=true
EMAIL_ENABLED=true
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password # Pentru Gmail: https://myaccount.google.com/apppasswords
EMAIL_FROM=your-email@gmail.com
EMAIL_TO=recipient@gmail.com
```
### Telegram
1. **Crează Bot:**
- Caută @BotFather în Telegram
- Trimite `/newbot`
- Copiază token-ul primit
2. **Obține Chat ID:**
```bash
python get_telegram_chat_id.py
```
3. **Configurare .env:**
```bash
ENABLE_NOTIFICATIONS=true
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrs
TELEGRAM_CHAT_ID=-1001234567890 # Negativ pentru grupuri
```
### Trimitere Manuală Notificări
```bash
python send_notifications.py
```
## Telegram Trigger Bot - Declanșare Remote
### Setup Rapid (Manual Mode)
1. **Configurare .env:**
```bash
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrs
TELEGRAM_ALLOWED_USER_IDS=your_user_id
TELEGRAM_CHAT_ID=-1001234567890 # Pentru grup (negativ!)
```
2. **Pornire bot:**
```powershell
deployment\windows\scripts\run_telegram_bot_manual.ps1
```
3. **Comenzi disponibile:**
- `/scrape` - Execută BTGO scraper + trimite fișiere individuale
- `/scrape_zip` - Execută BTGO scraper + trimite arhivă ZIP
- `/zip` - Trimite ultimele fișiere ca arhivă ZIP (fără scraping)
- `/status` - Status bot
- `/help` - Ajutor
### Deploy ca Windows Service (RECOMANDAT pentru VM)
```powershell
# Deploy complet + instalare serviciu
deployment\windows\scripts\deploy.ps1
# SAU folosește meniul interactiv
deployment\windows\scripts\menu.ps1
```
**Avantaje serviciu:**
- ✅ Pornire automată cu Windows
- ✅ Auto-restart la crash
- ✅ Rulează în background (fără RDP activ)
- ✅ Logging centralizat
**Notă:** Fișierele sunt trimise de **scraper** prin notificări (dacă `ENABLE_NOTIFICATIONS=true`), NU de bot.
**⚠️ Cerință pentru scraper:** Desktop Windows activ (RDP conectată) - browser TREBUIE vizibil!
**Ghid complet:** `deployment/windows/README.md` și `TELEGRAM_BOT_SETUP.md`
## Troubleshooting
### "Access Denied" în Docker
**Cauză:** WAF-ul BT George blochează Docker/headless browsers.
**Soluție:** Rulează DOAR local în Windows cu `HEADLESS=false`.
Si asigura-te ca **NU** rulezi in Docker / WSL fara display.
### Timeout la 2FA
- Mărește timeout: `TIMEOUT_2FA_SECONDS=180` în `.env`
- Verifică notificări activate pe telefon
### Selectors nu functioneaza
Site-ul s-a schimbat. Urmeaza pasii din sectiunea **Inregistrare Manuala cu Playwright** de mai jos.
```ini
TIMEOUT_2FA_SECONDS=300 # mareste daca aprobi greu pe telefon
```
### Notificări Email nu funcționează
- Pentru Gmail: folosește App Password, nu parola normală
- Verifică port: 587 (TLS) sau 465 (SSL)
- Testare: `python test_telegram.py`
Verifica si ca **notificarile push** ale aplicatiei George sunt active pe telefon.
### Notificări Telegram nu funcționează
- Verifică `TELEGRAM_ENABLED=true`
- Rulează `python test_telegram.py`
- Chat ID pentru grupuri trebuie să fie **negativ** (ex: `-1001234567890`)
- Asigură-te că botul este în grup
### Bot nu raspunde la `/scrape`
## Inregistrare Manuala cu Playwright (Codegen)
1. Verifica serviciul: `Get-Service BTGOTelegramBot`
2. `deployment\windows\scripts\view_logs.ps1` → optiunea 4 (tail stderr)
3. Verifica ca user-ul tau e in `TELEGRAM_ALLOWED_USER_IDS`
4. Pentru grupuri: `TELEGRAM_CHAT_ID` trebuie **negativ** (ex: `-1001234567890`)
Cand site-ul BT George isi schimba interfata, trebuie sa reinregistrezi fluxul manual.
### Notificari Email nu pleaca
### 1. Porneste Playwright Codegen
- Pentru Gmail: **App Password**, nu parola normala
- Port `587` (TLS) sau `465` (SSL)
- Test rapid: `python test_telegram.py` (verifica si SMTP daca esti la el)
### Selectorii s-au schimbat (UI BT actualizat)
Cand BT modifica HTML-ul, selectorii in `btgo_scraper.py` trebuie refacuti:
```powershell
# Activeaza venv-ul
.venv\Scripts\Activate.ps1
# Porneste codegen
playwright codegen https://go.bancatransilvania.ro --target python
```
Se deschid 2 ferestre:
- **Browser** - aici faci actiunile manual
- **Playwright Inspector** - aici vezi codul Python generat
Faci manual fluxul (login → 2FA → conturi → download CSV), copiezi selectorii noi generati si actualizezi sectiunile relevante:
### 2. Inregistreaza Fluxul
- Cookies: `_dismiss_gdpr_cookies` (~ liniile 150-200)
- Login: `login()` (~ liniile 449-530)
- Solduri: `read_accounts()` (~ liniile 242-310)
- Tranzactii: `download_transactions()` si `_download_*_account()` (~ liniile 529-732)
1. Accept cookies ("Accept toate")
2. Click pe "Login" - se deschide popup
3. Completeaza username si parola
4. Click "Autentifica-te"
5. Asteapta 2FA pe telefon
6. Dupa login, click pe "Conturi"
7. **Pentru primul cont:**
- Expand card (click pe sageata)
- Click pe butonul "Tranzactii" (iconita cu grafic)
- Click pe "CSV" pentru format
- Click pe "Genereaza"
- Click pe documentul generat pentru download
8. **Pentru conturile urmatoare:**
- Click pe `#selectAccountBtn` (dropdown conturi)
- Selecteaza contul din lista
- Click pe "Genereaza"
- Download fisierul
CLAUDE.md contine lista actualizata de selectori critici.
### 3. Salveaza si Analizeaza Scriptul
- In Inspector: **Copy** sau **File > Save**
- Compara cu `btgo_scraper.py` si actualizeaza selectorii modificati
- Selectori cheie de verificat:
- Cookie consent: `get_by_role("button", name="...")`
- Username field: `get_by_placeholder("...")`
- Submit button: `get_by_role("button", name="...")`
- Account selector: `#selectAccountBtn`
- Download item: `fba-document-item`
## Testare Manuala a Scraperului
### Testare Pas cu Pas
## Testare doar solduri (fara descarcare tranzactii)
```powershell
# 1. Activeaza venv
.venv\Scripts\Activate.ps1
# 2. Ruleaza scraper-ul
python btgo_scraper.py
```
### Verificare Output
Dupa rulare, verifica:
```powershell
# Fisiere generate
dir data\
# Trebuie sa vezi:
# - solduri_*.csv (solduri toate conturile)
# - solduri_*.json (metadata + solduri)
# - tranzactii_*.csv (cate un fisier per cont)
# - dashboard_*.png (screenshot final)
# Verifica log-ul pentru erori
type logs\scraper_*.log | Select-String -Pattern "EROARE|ERROR|Exception"
```
### Testare Doar Solduri (fara download tranzactii)
```powershell
# Seteaza variabila temporar
$env:BALANCES_ONLY = "true"
python btgo_scraper.py
```
### Debug - Screenshot-uri
Util cand vrei doar verificare rapida ca login + 2FA + citire conturi mai functioneaza.
Daca ceva nu merge, verifica screenshot-urile din `data/`:
- `debug_login_popup_*.png` - starea paginii de login
- `debug_dropdown_*.png` - dropdown-ul de selectare conturi (daca esueaza)
- `error_*.png` - screenshot la eroare
## Exit codes
### Testare Notificari (fara scraping)
```powershell
# Test Telegram
python test_telegram.py
# Trimite ultimele fisiere manual
python send_notifications.py
```
- `0` Success
- `1` Eroare generala
- `4` Config invalid (`.env`)
- `99` Eroare neasteptata
## Securitate
**IMPORTANT:**
- NU comite `.env` in git (deja in `.gitignore`)
- NU partaja screenshots/logs - contin date sensibile
- Sterge fisierele vechi periodic:
- `.env` e in `.gitignore` — **nu** comite credentialele
- `data/` si `logs/` contin date bancare — nu partaja
- Restrictioneaza bot-ul: seteaza `TELEGRAM_ALLOWED_USER_IDS` (lista goala = oricine poate trigeri scraper-ul cu credentialele tale)
```bash
# Windows
del /q data\*.csv data\*.json data\*.png
## Disclaimer
# Linux/Mac
rm data/*.{csv,json,png}
```
## Exit Codes
- `0` - Success
- `1` - Eroare generală
- `4` - Eroare configurare (.env invalid)
- `99` - Eroare neașteptată
## Licență
MIT License
## Disclaimer Legal
Acest tool accesează informații personale bancare. Utilizatorul este singurul responsabil pentru conformarea cu termenii Băncii Transilvania și legislația aplicabilă.
Tool autorizat pentru automatizare personala. Utilizatorul e responsabil pentru conformarea cu T&C-ul Bancii Transilvania.