roa2web-service-auto/reports-app/telegram-bot/TELEGRAM_COMMANDS.md

Comenzi Telegram Bot ROA2WEB

Configurare comenzi în BotFather pentru @ROA2WEBDEVBot

📋 Setup Rapid în BotFather

1. Deschide @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:

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