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

```powershell
# 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

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

```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
```

**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`

```bash
# 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

```csv
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)

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

### Timeout la 2FA
- Mărește timeout: `TIMEOUT_2FA_SECONDS=180` în `.env`
- Verifică notificări activate pe telefon

### Selectors nu funcționează
Site-ul s-a schimbat. Re-generează selectors:
```bash
.venv\Scripts\activate
playwright codegen https://btgo.ro --target python
```

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

## Securitate

**⚠️ IMPORTANT:**
- NU comite `.env` în git (deja în `.gitignore`)
- NU partaja screenshots/logs - conțin date sensibile
- Șterge fișierele vechi periodic:

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