btgo-playwright/TELEGRAM_BOT_SETUP.md

# Telegram Trigger Bot - Setup Guide

## Prezentare

Telegram Trigger Bot permite declanșarea BTGO Scraper-ului de la distanță prin comenzi Telegram. Perfect pentru VM Windows 11.

**⚠️ IMPORTANT:** VM-ul Windows 11 TREBUIE să aibă:
- Remote Desktop session activă (sau user logat)
- Browser vizibil (HEADLESS=false)
- WAF-ul BT blochează browsere headless!

## Cum Funcționează

```
Tu (Telegram) → Bot → Rulează scraper → Trimite CSV-uri înapoi
```

## Setup Pas cu Pas

### 1. Configurare Bot Telegram

**Dacă ai deja bot pentru notificări:** Poți folosi același bot!

**Dacă NU ai bot:**
1. Deschide Telegram și caută **@BotFather**
2. Trimite `/newbot`
3. Alege nume pentru bot (ex: "BTGO Scraper Bot")
4. Copiază **token-ul** primit (ex: `123456789:ABCdefGHIjklMNOpqrs`)

### 2. Obține User ID-ul Tău

Ai nevoie de User ID pentru securitate (doar tu poți rula scraper-ul).

**Opțiunea A - Folosește bot existent:**
```bash
python get_telegram_chat_id.py
```
Vei vedea: `User ID: 123456789`

**Opțiunea B - Folosește @userinfobot:**
1. Caută `@userinfobot` în Telegram
2. Trimite `/start`
3. Copiază User ID-ul

### 3. Setup pentru Grup Telegram (RECOMANDAT)

**Avantaj:** Comenzi și rezultate în același grup - mai convenabil decât mesaje directe!

#### 3.1. Adaugă Bot-ul în Grup

1. **Deschide grupul Telegram** unde vrei să trimiți comenzi
2. **Adaugă bot-ul:**
   - Click pe numele grupului → "Add Members"
   - Caută bot-ul tău (ex: "BTGO Scraper Bot")
   - Adaugă

3. **Configurare Privacy Mode (important!):**

   Bot-ul trebuie să vadă comenzile din grup. Ai 2 opțiuni:

   **Opțiunea A - Dezactivează Privacy Mode (RECOMANDAT):**
   ```
   1. Deschide @BotFather în Telegram
   2. Trimite /mybots
   3. Selectează bot-ul tău
   4. Bot Settings → Group Privacy → Turn OFF
   ```
   Acum bot-ul vede toate mesajele care încep cu `/` (comenzi)

   **Opțiunea B - Fă bot-ul Admin:**
   ```
   1. În grup: Click nume grup → Administrators
   2. Add Administrator → Selectează bot-ul
   3. Permisiuni minime: nicio permisiune specială necesară
   ```
   Admin bots văd toate mesajele automat.

#### 3.2. Obține Chat ID al Grupului

**Metoda 1 - Cu scriptul helper:**
```bash
python get_telegram_chat_id.py
```
- Trimite `/start` în grup
- Script-ul va afișa: `Chat ID: -1001234567890` (NEGATIV pentru grupuri!)

**Metoda 2 - Manual:**
1. Adaugă `@RawDataBot` în grupul tău temporar
2. Bot-ul va afișa informații despre grup
3. Copiază `chat.id` (va fi negativ, ex: `-1001234567890`)
4. Șterge `@RawDataBot` din grup

### 4. Configurare .env

Editează `.env` și adaugă:

```bash
# Bot token (același ca pentru notificări sau nou)
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrs

# User IDs autorizați (separați prin virgulă)
# DOAR acești useri pot rula /scrape din grup
TELEGRAM_ALLOWED_USER_IDS=123456789,987654321

# Chat ID GRUP pentru notificări automate + răspunsuri comenzi
# IMPORTANT: Negativ pentru grupuri! (ex: -1001234567890)
TELEGRAM_CHAT_ID=-1001234567890
```

**Securitate:**
- `TELEGRAM_ALLOWED_USER_IDS` = doar acești useri pot rula `/scrape` din grup
- Lasă gol dacă vrei ca oricine din grup să poată rula (nesigur!)
- Bot-ul verifică User ID-ul celui care trimite comanda, NU group ID-ul

### 4. Pornire Bot

**Opțiunea 1 - Manual (Test):**
```powershell
deployment\windows\scripts\run_telegram_bot_manual.ps1
```

**Opțiunea 2 - Windows Service (RECOMANDAT pentru VM):**
```powershell
# Deploy complet
deployment\windows\scripts\deploy.ps1

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

**Opțiunea 3 - Manual Python:**
```bash
.venv\Scripts\activate
python telegram_trigger_bot.py
```

**Bot-ul va afișa:**
```
Bot inițializat. Useri autorizați: [123456789]
Bot pornit. Așteaptă comenzi...
```

## Utilizare

### Comenzi Disponibile

**În grupul Telegram (sau DM către bot):**

```
/start          - Pornește bot-ul și vezi comenzile
/scrape         - ⭐ Rulează scraper-ul (2-3 minute)
/status         - Vezi status sistem (ultima rulare, fișiere)
/help           - Ajutor utilizare
```

**Securitate:** Doar userii din `TELEGRAM_ALLOWED_USER_IDS` pot rula comenzi!

### Flow Tipic în Grup

1. **Scrii în grup:** `/scrape`
2. **Bot răspunde:** "🤖 BTGO Scraper pornit... Așteaptă 2FA!"
3. **Pe VM:** Browser-ul se deschide, face login automat
4. **Pe telefon:** Aprobă notificarea George 2FA
5. **Scraper trimite fișiere:** Prin notificări automate (email + grup)
6. **Bot confirmă:** "✅ Finalizat! Fișierele au fost trimise automat."

**Notă:** Fișierele sunt trimise de **scraper** (`ENABLE_NOTIFICATIONS=true`), NU de bot. Bot-ul doar declanșează execuția și confirmă finalizarea.

### Exemplu Output în Grup

```
Tu: /scrape

Bot: 🤖 BTGO Scraper pornit...
     Așteaptă 2FA pe telefon!

[După 2 minute - mesaje de la scraper prin notificări]

Bot: 📧 BTGO Scraper - Sold conturi actualizat

     📄 solduri_2025-11-06.csv
     📄 tranzactii_Colector_01.csv
     📄 tranzactii_Antreprenor_04.csv
     ... (toate fișierele)

Bot: ✅ Scraper finalizat cu succes!
     📧 Fișierele au fost trimise automat prin notificări.
```

**Important:** Mesajele cu fișiere vin din **scraper** (prin `notifications.py`), nu din bot! Bot-ul doar declanșează și confirmă.

## Setup VM Windows 11

### Cerințe Critice

**⚠️ Browser TREBUIE să fie vizibil!** WAF-ul BT blochează headless.

### Metoda Recomandată - Windows Service

```powershell
# Deploy ca serviciu Windows (auto-start, auto-restart)
deployment\windows\scripts\deploy.ps1
```

**Avantaje:**
- ✅ Pornire automată cu Windows
- ✅ Auto-restart la crash
- ✅ Management prin Services.msc
- ✅ Logging centralizat
- ✅ Nu necesită RDP conectată

**Management:**
```powershell
# Meniu interactiv
deployment\windows\scripts\menu.ps1

# SAU comenzi directe
deployment\windows\scripts\start_service.ps1
deployment\windows\scripts\stop_service.ps1
deployment\windows\scripts\restart_service.ps1
deployment\windows\scripts\status.ps1
```

### Alternativă - Task Scheduler

**Doar dacă nu vrei Windows Service:**

1. Deschide Task Scheduler
2. Create Task
3. **General:**
   - Name: "BTGO Telegram Bot"
   - Run only when user is logged on: ✅
4. **Triggers:**
   - At log on (Specific user)
5. **Actions:**
   - Action: Start a program
   - Program: `C:\path\to\btgo-playwright\deployment\windows\scripts\run_telegram_bot_manual.ps1`
   - Start in: `C:\path\to\btgo-playwright`
6. **Conditions:**
   - Dezactivează "Start task only if computer is on AC power"

### Verificare Funcționare

```bash
# Pe VM, verifică că bot-ul rulează
tasklist | findstr python

# Ar trebui să vezi:
# python.exe    12345 Console    1    45,678 K
```

## Troubleshooting

### Bot nu răspunde la comenzi

**Cauză:** Token greșit sau bot nestartă.

**Soluție:**
```bash
# Verifică token-ul
python telegram_trigger_bot.py

# Ar trebui să vezi:
# Bot inițializat. Useri autorizați: [123456789]
```

### "⛔ Acces interzis!"

**Cauză:** User ID-ul tău nu e în `TELEGRAM_ALLOWED_USER_IDS`.

**Soluție:**
```bash
# Verifică User ID-ul tău
python get_telegram_chat_id.py

# Adaugă-l în .env
TELEGRAM_ALLOWED_USER_IDS=123456789
```

### "Access Denied" la scraping

**Cauză:** Browser-ul rulează în headless mode sau VM nu are GUI activă.

**Soluție:**
- Conectează-te prin RDP și LASĂ sesiunea deschisă
- Verifică `.env`: `HEADLESS=false`
- Asigură-te că desktop-ul Windows este vizibil

### Scraper timeout (> 10 minute)

**Cauză:** Probabil blocat la 2FA sau browser nu răspunde.

**Soluție:**
- Verifică logs pe VM: `logs\scraper_*.log`
- Mărește timeout în bot: `timeout=900` (15 min)
- Asigură-te că aprobați 2FA în < 2 minute

### Bot se oprește singur

**Cauză:** Sesiune RDP deconectată sau VM suspended.

**Soluție:**
- Folosește Task Scheduler pentru restart automat
- Configurează VM să nu intre în sleep/hibernate
- Verifică că desktop-ul rămâne activ

## Securitate

**⚠️ ATENȚIE:**
- Bot-ul are acces la credentials din `.env`
- `TELEGRAM_ALLOWED_USER_IDS` TREBUIE configurat!
- Nu partaja token-ul botului
- VM-ul trebuie securizat (firewall, VPN)

**Best Practices:**
```bash
# ✅ Bun - doar tu și admin
TELEGRAM_ALLOWED_USER_IDS=123456789,987654321

# ❌ Rău - oricine cu acces la bot
TELEGRAM_ALLOWED_USER_IDS=

# ✅ Bun - notificări separate de trigger
TELEGRAM_BOT_TOKEN=bot_trigger_token
TELEGRAM_CHAT_ID=group_chat_id
```

## Logs și Monitoring

**Logs bot:**
```
[2025-11-06 17:30:00] [INFO] Bot inițializat. Useri autorizați: [123456789]
[2025-11-06 17:30:05] [INFO] Mesaj de la username (ID: 123456789): /scrape
[2025-11-06 17:30:05] [INFO] Comandă /scrape primită
[2025-11-06 17:30:05] [INFO] Pornire scraper...
[2025-11-06 17:32:45] [INFO] Scraper finalizat cu succes
[2025-11-06 17:32:50] [INFO] Trimit: solduri_2025-11-06.csv
```

**Logs scraper:**
```
logs\scraper_2025-11-06.log
```

## Alternative Trigger Methods

### 1. HTTP API (simplă)
```python
from flask import Flask, request
app = Flask(__name__)

@app.route('/scrape', methods=['POST'])
def trigger_scrape():
    # Verifică token secret
    subprocess.run(['python', 'btgo_scraper.py'])
```

### 2. Cron Job (periodicitate fixă)
```
Task Scheduler → Daily la 9:00 AM
```

### 3. File Watcher
```python
# Detectează fișier "trigger.txt"
# Rulează scraper automat
```

## Performance

**Timpi tipici:**
- Bot startup: < 5 secunde
- Scraper execution: 2-3 minute
- File upload: 5-10 secunde
- **Total:** ~3-4 minute de la `/scrape` la fișiere primite

**Resource usage (VM):**
- RAM: 500MB (bot) + 800MB (browser)
- CPU: 5-10% idle, 30-40% during scrape
- Network: ~5MB download (CSV-uri)