# Comenzi Telegram Bot ROA2WEB

Configurare comenzi în BotFather pentru @ROA2WEBDEVBot

## 📋 Setup Rapid în BotFather

1. Deschide [@BotFather](https://t.me/BotFather) în Telegram
2. Trimite comanda `/mybots`
3. Selectează `@ROA2WEBDEVBot` (sau bot-ul tău)
4. Alege `Edit Bot` → `Edit Commands`
5. Copiază și lipește lista de comenzi de mai jos:

```
start - Link cont sau pornire bot
help - Informații și ajutor
companies - Vezi companiile tale
selectcompany - Selectează/caută companie activă
dashboard - Dashboard financiar
sold - Vezi sold și situație financiară
facturi - Listă facturi (opțional: status)
trezorerie - Date trezorerie și cash flow
export - Export rapoarte (Excel/PDF/CSV)
clear - Șterge conversație
unlink - Deconectează contul
```

## 📖 Comenzi Detaliate

### `/start`
**Descriere:** Link cont ROA2WEB cu Telegram

**Utilizare:**
- Dacă nu ești linkuit: Generează cod de 8 caractere din aplicația web și trimite-l aici
- Dacă ești deja linkuit: Afișează mesaj de bun venit cu comenzile disponibile

**Exemplu:**
```
/start
→ Cont deja linkuit pentru utilizatorul: john.doe
```

---

### `/help`
**Descriere:** Informații și ajutor despre utilizarea bot-ului

**Utilizare:**
- Afișează toate comenzile disponibile cu explicații
- Ghid rapid de utilizare
- Link către documentație

---

### `/companies`
**Descriere:** Vezi toate companiile tale accesibile

**Utilizare:**
- Afișează listă cu toate companiile tale din sistem
- Include CUI și detalii companie
- Buton de selecție rapidă pentru fiecare companie

**Exemplu output:**
```
📋 Companiile tale (3):

1. ACME SOLUTIONS SRL
   CUI: RO12345678
   [Selectează]

2. BETA CONSULTING SRL
   CUI: RO87654321
   [Selectează]
```

---

### `/selectcompany [search]`
**Descriere:** Selectează compania activă pentru toate comenzile ulterioare

**Utilizare:**
- `/selectcompany` - Arată toate companiile cu butoane de selecție
- `/selectcompany ACME` - Caută companii care conțin "ACME" în nume
- Search este case-insensitive și funcționează cu match parțial

**Exemplu:**
```
/selectcompany ACME
→ Rezultate pentru 'ACME' (2):
   • ACME SOLUTIONS SRL (RO12345678) [Selectează]
   • ACME TRADE SRL (RO11223344) [Selectează]
```

**Notă:** După selecție, toate comenzile (`/dashboard`, `/facturi`, `/trezorerie`) vor folosi această companie.

---

### `/dashboard` sau `/sold`
**Descriere:** Dashboard financiar pentru compania activă

**Necesită:** Companie activă selectată (vezi `/selectcompany`)

**Date afișate:**
- 💰 Sold total în RON
- 📄 Statistici facturi (emise/plătite/neplătite)
- 💵 Cash flow (încasări/plăți/net)

**Exemplu output:**
```
📊 Dashboard Financiar

💰 Sold Total: 145,678.50 RON

📄 Facturi:
  • Emise: 45
  • Plătite: 32
  • Neplătite: 13

💵 Cash Flow:
  • Încasări: 234,567.00 RON
  • Plăți: 156,789.50 RON
  • Net: 77,777.50 RON

━━━━━━━━━━━━━━
📊 ACME SOLUTIONS SRL | /selectcompany
```

---

### `/facturi [filtru]`
**Descriere:** Listă facturi pentru compania activă

**Necesită:** Companie activă selectată

**Utilizare:**
- `/facturi` - Toate facturile (primele 10)
- `/facturi neplatite` - Doar facturi neplătite
- `/facturi platite` - Doar facturi plătite

**Exemplu output:**
```
📄 Facturi (13 total)

1. ✅ FV2024001
   CLIENT ABC SRL - 15,450.00 RON
   Status: platit

2. ⏳ FV2024002
   CLIENT XYZ SRL - 8,900.00 RON
   Status: neplatit

━━━━━━━━━━━━━━
📊 ACME SOLUTIONS SRL | /selectcompany
```

---

### `/trezorerie`
**Descriere:** Date trezorerie și cash flow pentru compania activă

**Necesită:** Companie activă selectată

**Date afișate:**
- 💵 Sold cash curent
- 🏦 Conturi bancare și solduri
- 📊 Plăți programate (de încasat/de plătit)

**Exemplu output:**
```
💰 Trezorerie

💵 Sold Cash: 45,678.90 RON

🏦 Conturi Bancare: 3
  • BCR: 123,456.78 RON
  • BRD: 67,890.12 RON
  • ING: 34,567.89 RON

📊 Plăți Programate:
  • De încasat: 89,000.00 RON
  • De plătit: 45,600.00 RON

━━━━━━━━━━━━━━
📊 ACME SOLUTIONS SRL | /selectcompany
```

---

### `/export [tip]`
**Descriere:** Export rapoarte în Excel/PDF/CSV

**Necesită:** Companie activă selectată

**Utilizare:**
- `/export dashboard` - Export dashboard în Excel
- `/export facturi` - Export listă facturi în Excel
- `/export trezorerie` - Export date trezorerie în Excel

**Exemplu:**
```
/export dashboard
→ 📊 Generating report...
→ ✅ Dashboard_ACME_2025-10-22.xlsx
   [Download]
```

---

### `/clear`
**Descriere:** Șterge istoricul conversației cu Claude

**Utilizare:**
- Șterge tot istoricul de mesaje din sesiunea curentă
- Util când vrei să începi o conversație nouă
- NU afectează compania activă selectată

---

### `/unlink`
**Descriere:** Deconectează contul Telegram de contul ROA2WEB

**Utilizare:**
- Șterge legătura între Telegram și Oracle
- Șterge toate datele salvate (sesiuni, istoric)
- Necesită re-linking cu `/start` pentru a folosi din nou bot-ul

**Confirmare:** Da/Nu

---

## 🤖 Setup Automat (via API)

Poți seta comenzile programatic folosind scriptul `setup_bot_commands.py`:

```bash
cd /mnt/e/proiecte/roa2web/roa2web/reports-app/telegram-bot
source venv/bin/activate
python setup_bot_commands.py
```

Scriptul va configura automat toate comenzile în Telegram Bot API.

---

## 🔄 Actualizare Comenzi

Când adaugi comenzi noi:

1. Actualizează această documentație
2. Actualizează lista în BotFather (manual) SAU
3. Rulează `setup_bot_commands.py` (automat)
4. Testează că comenzile apar în UI-ul Telegram (apasă `/`)

---

## ✅ Checklist Testare

După configurare, verifică:

- [ ] Comenzile apar când apeși `/` în chat
- [ ] Descrierile sunt afișate corect
- [ ] Ordinea comenzilor are sens logic
- [ ] Comenzile funcționează conform așteptărilor
- [ ] Help text este actualizat cu noile comenzi

---

**Ultima actualizare:** 2025-10-22
**Bot:** @ROA2WEBDEVBot
**Status:** ✅ Comenzi configurate