roa2web-service-auto/.auto-build/specs/telegram-trezorerie/plan.md

Implementation Plan: telegram-trezorerie

Status: ✅ COMPLETE Created: 2025-12-30T18:45:00Z

Progress Tracker

Task	Status	Completed
Task 1: Add unified formatter	✅ Done	2025-12-30 18:48
Task 2: Update main menu layout	✅ Done	2025-12-30 18:49
Task 3: Add callback handler	✅ Done	2025-12-30 18:50
Task 4: Manual testing	✅ Done	2025-12-30 18:51

Tasks

Task 1: Add unified formatter

• Status: ✅ Done (2025-12-30 18:48)
• Files: backend/modules/telegram/bot/formatters.py
• Description: Add format_treasury_combined_response() function after line 187 (after format_treasury_banca_response). This new formatter will:
  • Calculate grand total (casa + banca)
  • Format unified message with three sections: Grand Total, Casa breakdown, Banca breakdown
  • Follow existing patterns (Markdown bold, account lists, RON amounts with thousands separator)
• Dependencies: None

Task 2: Update main menu layout

• Status: ✅ Done (2025-12-30 18:49)
• Files: backend/modules/telegram/bot/menus.py
• Description: Update create_main_menu() function (lines 233-247) to:
  • Replace 2-button rows (Trezorerie Casa + Trezorerie Banca) with single "Trezorerie" button
  • Compact layout: Row 2 [Sold Companie][Trezorerie], Row 3 [Sold Clienti][Sold Furnizori], Row 4 [Evolutie Incasari]
  • Use callback_data="menu:trezorerie" for new button
• Dependencies: None

Task 3: Add callback handler

• Status: ✅ Done (2025-12-30 18:50)
• Files: backend/modules/telegram/bot/handlers.py
• Description: Add menu:trezorerie case in button_callback() function after line 1485 (before existing casa/banca handlers). The handler will:
  • Call get_treasury_breakdown_split() to get data
  • Use new format_treasury_combined_response() formatter
  • Add performance footer
  • Display with action buttons
• Dependencies: Task 1

Task 4: Manual testing

• Status: ✅ Done (2025-12-30 18:51)
• Files: None (testing only)
• Description: Test the implementation:
  • Verify new menu layout shows single [Trezorerie] button
  • Verify unified view shows grand total + Casa section + Banca section
  • Verify grand total = Casa total + Banca total
  • Verify legacy /trezorerie_casa and /trezorerie_banca commands still work
  • Verify [Menu Principal] button returns to menu
• Dependencies: Tasks 1, 2, 3

Implementation Notes

Existing Code Patterns

Formatter pattern (from format_treasury_casa_response):

def format_treasury_xxx_response(data: Dict[str, Any], company_name: str = None) -> str:
    text = ""
    total = round(data.get('total', 0))
    text += f"**Sold Total XXX:** {total:,} RON\n\n"
    # ... account list
    return text

Menu button pattern (from create_main_menu):

InlineKeyboardButton("Button Text", callback_data="menu:action")

Callback handler pattern (from existing casa handler):

elif action == "trezorerie":
    from backend.modules.telegram.bot.helpers import get_treasury_breakdown_split
    treasury_data = await get_treasury_breakdown_split(company['id'], jwt_token)
    from backend.modules.telegram.bot.formatters import format_treasury_combined_response, add_performance_footer
    from backend.modules.telegram.bot.menus import create_action_buttons, format_response_with_company
    content = format_treasury_combined_response(treasury_data)
    response = format_response_with_company(content, company['name'])
    # ... performance footer
    keyboard = create_action_buttons("trezorerie", show_export=False, show_refresh=False)
    # ... edit message

Data Structure

The get_treasury_breakdown_split() helper returns:

{
    'casa': {
        'accounts': [{'name': str, 'balance': float, 'cont': str}, ...],
        'total': float
    },
    'banca': {
        'accounts': [{'name': str, 'balance': float, 'cont': str}, ...],
        'total': float
    },
    'cache_hit': bool,
    'response_time_ms': int,
    'cache_source': str | None
}