btgo-playwright/README.md

BTGO Scraper - Automatizare Citire Solduri

Prezentare

Automatizare Playwright pentru extragerea soldurilor și tranzacțiilor din George (btgo.ro).

Arhitectură

BTGO Scraper (btgo_scraper.py)

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

# Clonare proiect
git clone https://gitea.romfast.ro/romfast/btgo-playwright.git
cd btgo-playwright

# Setup automat (instaleaza Python venv + dependente + Playwright browsers)
deployment\windows\scripts\setup_dev.ps1

# Configurare credentiale in .env
# Editează .env și adaugă:
# BTGO_USERNAME=your_username
# BTGO_PASSWORD=your_password
# HEADLESS=false

# Rulare scraper
deployment\windows\scripts\run_scraper.ps1

Actualizare după Modificări

# 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 (recomandat)
deployment\windows\scripts\setup_dev.ps1

# SAU meniu interactiv complet
deployment\windows\scripts\menu.ps1

Rulare Manuală

# 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

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/

Configurare .env

# Obligatorii
BTGO_USERNAME=your_username
BTGO_PASSWORD=your_password
HEADLESS=false  # OBLIGATORIU false!

# Opționale
DOWNLOAD_TRANSACTIONS=true
TIMEOUT_2FA_SECONDS=120

Structură 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

logs/
└── scraper_2025-11-06.log                       # Log zilnic

Format CSV Solduri

timestamp,nume_cont,iban,sold,moneda,tip_cont
2025-11-06 14:30:45,Colector 01,RO32BTRLRONCRT0637236701,7223.26,RON,colector

Notificări (Email & Telegram)

Email (SMTP)

# .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:

   python get_telegram_chat_id.py
   

3. Configurare .env:

   ENABLE_NOTIFICATIONS=true
   TELEGRAM_ENABLED=true
   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrs
   TELEGRAM_CHAT_ID=-1001234567890  # Negativ pentru grupuri
   

Trimitere Manuală Notificări

python send_notifications.py

Telegram Trigger Bot - Declanșare Remote

Setup Rapid (Manual Mode)

1. Configurare .env:

   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrs
   TELEGRAM_ALLOWED_USER_IDS=your_user_id
   TELEGRAM_CHAT_ID=-1001234567890  # Pentru grup (negativ!)
   

2. Pornire bot:

   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)

# 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.

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.

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

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

Inregistrare Manuala cu Playwright (Codegen)

Cand site-ul BT George isi schimba interfata, trebuie sa reinregistrezi fluxul manual.

1. Porneste Playwright Codegen

# 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

2. Inregistreaza Fluxul

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

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

# 1. Activeaza venv
.venv\Scripts\Activate.ps1

# 2. Ruleaza scraper-ul
python btgo_scraper.py

Verificare Output

Dupa rulare, verifica:

# 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)

# Seteaza variabila temporar
$env:BALANCES_ONLY = "true"
python btgo_scraper.py

Debug - Screenshot-uri

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

Testare Notificari (fara scraping)

# Test Telegram
python test_telegram.py

# Trimite ultimele fisiere manual
python send_notifications.py

Securitate

IMPORTANT:

• NU comite .env in git (deja in .gitignore)
• NU partaja screenshots/logs - contin date sensibile
• Sterge fisierele vechi periodic:

# Windows
del /q data\*.csv data\*.json data\*.png

# 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ă.