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

Feature: Telegram Unified Treasury Button

Overview

Replace the two separate "Trezorerie Casa" and "Trezorerie Banca" buttons in the Telegram bot main menu with a single unified "Trezorerie" button that displays comprehensive treasury information in one message. This consolidation improves UX by reducing button clutter and providing a complete treasury overview at a glance.

Problem Statement

Currently, users must tap two separate buttons ("Trezorerie Casa" and "Trezorerie Banca") to view complete treasury information. This creates friction in the user experience and takes up valuable menu real estate. Users need a single, comprehensive treasury view that shows:

• Grand total treasury (Casa + Banca combined)
• Casa total with account breakdown
• Banca total with account breakdown

The unified view will reduce taps from 2 to 1 and free up menu space for future features.

User Stories

• As a financial manager, I want to see all treasury data (Casa + Banca) in one message so that I can quickly assess total available funds without switching between views
• As a user, I want a cleaner, more compact menu so that I can navigate more efficiently
• As a power user, I want to optionally use the legacy /trezorerie_casa and /trezorerie_banca commands so that I can access specific views if needed
• As a developer, I want consistent formatting across all treasury messages so that maintenance is easier

Functional Requirements

Core Requirements

1. Single "Trezorerie" Button: Replace [Trezorerie Casa] and [Trezorerie Banca] with a single [Trezorerie] button in main menu
2. Combined Display Format: Show unified message with:
   • Grand Total (Casa + Banca)
   • Casa section: total + all accounts
   • Banca section: total + all accounts
3. Menu Layout Compaction: Reorganize main menu to fill the freed space:
   • Row 2: [Sold Companie] [Trezorerie]
   • Row 3: [Sold Clienti] [Sold Furnizori]
   • Row 4: [Evolutie Incasari]
4. Backward Compatibility: Keep /trezorerie, /trezorerie_casa, /trezorerie_banca commands working
5. Performance Footer: Include cache hit/miss metadata in response (consistent with existing pattern)

Secondary Requirements

1. Export Support: Add "Export" button (matching other financial views)
2. Refresh Support: Add "Refresh" button (matching other financial views)
3. Error Handling: Graceful fallback if treasury data unavailable

Technical Requirements

Files to Modify

File	Changes
backend/modules/telegram/bot/menus.py	Update create_main_menu() (lines 234-247): Replace 2-button rows with unified layout
backend/modules/telegram/bot/formatters.py	Add format_treasury_combined_response() function after line 187
backend/modules/telegram/bot/handlers.py	Update button_callback() (lines 1486-1546): Add menu:trezorerie case; Keep existing casa/banca cases for legacy commands
backend/modules/telegram/bot/handlers.py	Update /trezorerie command handler (if exists) to use new unified formatter, OR create new trezorerie_unified_command()

New Files to Create

None - all changes are modifications to existing files.

Dependencies

• Existing: get_treasury_breakdown_split() from helpers.py (lines 275-354)
• Existing: format_response_with_company() from menus.py (lines 111-144)
• Existing: create_action_buttons() from menus.py (lines 278-335)
• Existing: add_performance_footer() from formatters.py

Database Changes

None - uses existing /api/reports/dashboard/treasury-breakdown endpoint.

API Changes

None - reuses existing backend API endpoints.

Design Decisions

Approach

Unified Formatter Pattern: Create a new format_treasury_combined_response() function that:

1. Takes the full treasury_data dict (containing both casa and banca keys)
2. Calculates grand total by summing casa + banca totals
3. Formats a single message with three sections: Grand Total, Casa breakdown, Banca breakdown
4. Reuses existing formatting patterns (Markdown bold, account lists, RON amounts)

Menu Reorganization: Compact the main menu layout to:

• Row 2: [Sold Companie] [Trezorerie] (unified button replaces Trezorerie Casa)
• Row 3: [Sold Clienti] [Sold Furnizori] (moves up from previous rows)
• Row 4: [Evolutie Incasari] (full width, moves up)

This creates a balanced 2-2-1 button layout that's more compact than the previous 2-2-2 layout.

Callback Naming: Use menu:trezorerie for the new unified button to maintain consistency with existing callback patterns (menu:sold, menu:clienti, etc.).

Alternatives Considered

1. Keep Both Buttons + Add Third: Rejected because it increases menu clutter instead of reducing it
2. Tabbed Interface: Rejected because Telegram inline keyboards don't support tabs; would require complex state management
3. Remove Legacy Commands: Rejected to maintain backward compatibility for power users who have muscle memory for old commands

Acceptance Criteria

Menu Changes

• Main menu has single [Trezorerie] button instead of [Trezorerie Casa] and [Trezorerie Banca]
• Menu layout shows Row 2: [Sold Companie] [Trezorerie]
• Menu layout shows Row 3: [Sold Clienti] [Sold Furnizori]
• Menu layout shows Row 4: [Evolutie Incasari] (full width)

Message Format

• Unified message shows "Sold Total Trezorerie: X,XXX RON" at top
• Unified message shows "Casa" section with total and account list
• Unified message shows "Banca" section with total and account list
• Grand total equals sum of Casa total + Banca total
• All amounts rounded to whole RON (0 decimals) with thousands separator
• Company name displayed at top of message
• Performance footer shows cache hit/miss metadata

Functionality

• Tapping [Trezorerie] button displays unified treasury message
• Message includes [Refresh] and [Menu Principal] action buttons
• Legacy /trezorerie_casa command still works (shows Casa only)
• Legacy /trezorerie_banca command still works (Banca only)
• /trezorerie command shows unified view (if exists, otherwise create it)
• Callback menu:trezorerie triggers unified view
• Error handling works if treasury data unavailable

Code Quality

• No code duplication between formatters
• Consistent Markdown formatting with existing patterns
• Proper error logging in handlers
• Comments explain new unified formatter logic

Out of Scope

• Export Functionality: While we add the Export button, implementing actual Excel/PDF export is out of scope (deferred to future feature)
• Historical Trends: No graph or historical data - current snapshot only
• Currency Conversion: RON only, no multi-currency support
• Account Filtering: Show all accounts, no user-selectable filters
• Menu Help Text: No changes to /help command text (can be updated separately)

Message Format Examples

Unified Treasury Message (New)

Five Holding SRL

Sold Total Trezorerie: 20,500 RON

Casa
Sold Total Cash: 5,000 RON

Conturi de Casa:
  - Casa Lei: 3,000 RON
  - Casa Valuta: 2,000 RON

Banca
Sold Total Banca: 15,500 RON

Conturi Bancare:
  - BCR RON: 10,000 RON
  - BRD EUR: 5,500 RON

[Cache HIT | L1 | 23ms]

Casa Only Message (Legacy /trezorerie_casa)

Five Holding SRL

Sold Total Cash: 5,000 RON

Conturi de Casa:
  - Casa Lei: 3,000 RON
  - Casa Valuta: 2,000 RON

[Cache HIT | L1 | 23ms]

Banca Only Message (Legacy /trezorerie_banca)

Five Holding SRL

Sold Total Banca: 15,500 RON

Conturi Bancare:
  - BCR RON: 10,000 RON
  - BRD EUR: 5,500 RON

[Cache HIT | L1 | 23ms]

Implementation Details

1. New Unified Formatter

Add to backend/modules/telegram/bot/formatters.py after line 187:

def format_treasury_combined_response(data: Dict[str, Any], company_name: str = None) -> str:
    """
    Format combined treasury data (Casa + Banca) for Telegram.

    Args:
        data: Dict with 'casa' and 'banca' keys from get_treasury_breakdown_split()
        company_name: Company name (kept for compatibility, not used)

    Returns:
        Formatted Markdown string with grand total and both sections

    Example:
        data = {'casa': {...}, 'banca': {...}}
        text = format_treasury_combined_response(data)
    """
    text = ""

    # Extract totals
    casa_total = round(data.get('casa', {}).get('total', 0))
    banca_total = round(data.get('banca', {}).get('total', 0))
    grand_total = casa_total + banca_total

    # Grand total
    text += f"**Sold Total Trezorerie:** {grand_total:,} RON\n\n"

    # Casa section
    text += "**Casa**\n"
    text += f"Sold Total Cash: {casa_total:,} RON\n\n"

    casa_accounts = data.get('casa', {}).get('accounts', [])
    if casa_accounts:
        text += "Conturi de Casa:\n"
        for acc in casa_accounts:
            name = acc.get('name', 'N/A')
            balance = round(acc.get('balance', 0))
            text += f"  - {name}: {balance:,} RON\n"
    else:
        text += "Nu exista conturi de casa.\n"

    text += "\n"

    # Banca section
    text += "**Banca**\n"
    text += f"Sold Total Banca: {banca_total:,} RON\n\n"

    banca_accounts = data.get('banca', {}).get('accounts', [])
    if banca_accounts:
        text += "Conturi Bancare:\n"
        for acc in banca_accounts:
            name = acc.get('name', 'N/A')
            balance = round(acc.get('balance', 0))
            text += f"  - {name}: {balance:,} RON\n"
    else:
        text += "Nu exista conturi bancare.\n"

    return text

2. Update Main Menu Layout

Update backend/modules/telegram/bot/menus.py lines 234-247:

# Rows 2-4: Financial options (compacted layout)
keyboard.extend([
    [
        InlineKeyboardButton("Sold Companie", callback_data="menu:sold"),
        InlineKeyboardButton("Trezorerie", callback_data="menu:trezorerie")
    ],
    [
        InlineKeyboardButton("Sold Clienti", callback_data="menu:clienti"),
        InlineKeyboardButton("Sold Furnizori", callback_data="menu:furnizori")
    ],
    [
        InlineKeyboardButton("Evolutie Incasari", callback_data="menu:evolutie")
    ]
])

3. Update Button Callback Handler

Update backend/modules/telegram/bot/handlers.py in button_callback() function, add new case after line 1485:

elif action == "trezorerie":
    # Unified trezorerie (Casa + Banca combined)
    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'])

    # Add performance footer if cache metadata is available
    if 'cache_hit' in treasury_data and 'response_time_ms' in treasury_data:
        cache_hit = treasury_data['cache_hit']
        response_time_ms = treasury_data['response_time_ms']
        cache_source = treasury_data.get('cache_source', None)
        response = add_performance_footer(response, cache_hit, response_time_ms, cache_source)

    keyboard = create_action_buttons("trezorerie", show_export=False, show_refresh=False)

    try:
        await query.edit_message_text(
            response,
            reply_markup=keyboard,
            parse_mode=ParseMode.MARKDOWN
        )
    except Exception as e:
        # Ignore "Message is not modified" error
        if "Message is not modified" not in str(e):
            raise

elif action == "casa":
    # Keep existing casa handler for legacy /trezorerie_casa command
    # ... existing code ...

4. Legacy Command Handlers

Keep existing handlers in backend/modules/telegram/bot/handlers.py:

• trezorerie_casa_command() (lines 884-955) - NO CHANGES
• trezorerie_banca_command() (lines 957-1028) - NO CHANGES

Update /trezorerie command (or create if missing) to use unified formatter:

async def trezorerie_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Handle /trezorerie command - shows unified treasury data (Casa + Banca).

    Displays complete treasury overview with grand total and account breakdowns.

    Args:
        update: Telegram update object
        context: Telegram context
    """
    try:
        telegram_user_id = update.effective_user.id
        logger.info(f"/trezorerie command from user {telegram_user_id}")

        # Check linked
        is_linked = await check_user_linked(telegram_user_id)
        if not is_linked:
            await update.message.reply_text(
                "**Cont neconectat**\n\nFoloseste /start",
                parse_mode=ParseMode.MARKDOWN
            )
            return

        # Get active company
        session_manager = get_session_manager()
        from backend.modules.telegram.bot.helpers import get_active_company_or_prompt
        company = await get_active_company_or_prompt(update, session_manager, telegram_user_id)

        if not company:
            return  # Prompt already sent

        # Get auth data
        auth_data = await get_user_auth_data(telegram_user_id)
        jwt_token = auth_data['jwt_token']

        # Get treasury breakdown split
        from backend.modules.telegram.bot.helpers import get_treasury_breakdown_split
        treasury_data = await get_treasury_breakdown_split(
            company_id=company['id'],
            jwt_token=jwt_token
        )

        if not treasury_data:
            await update.message.reply_text("Eroare la incarcarea trezoreriei.")
            return

        # Format unified response
        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'])

        # Add performance footer if cache metadata is available
        if 'cache_hit' in treasury_data and 'response_time_ms' in treasury_data:
            cache_hit = treasury_data['cache_hit']
            response_time_ms = treasury_data['response_time_ms']
            cache_source = treasury_data.get('cache_source', None)
            response = add_performance_footer(response, cache_hit, response_time_ms, cache_source)

        keyboard = create_action_buttons("trezorerie", show_export=True)

        await update.message.reply_text(
            response,
            reply_markup=keyboard,
            parse_mode=ParseMode.MARKDOWN
        )

    except Exception as e:
        logger.error(f"Error in trezorerie_command: {e}", exc_info=True)
        await update.message.reply_text("Eroare la incarcarea trezoreriei.")

5. Command Registration

Update backend/modules/telegram/bot_main.py - ensure trezorerie_command is registered (line 126):

application.add_handler(CommandHandler("trezorerie", trezorerie_command))

No changes needed for trezorerie_casa_command and trezorerie_banca_command (already registered at lines 127-128).

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Users confused by menu change	Medium	Low	Keep legacy commands working; users can still use old commands if preferred
Grand total calculation error	Low	Medium	Add unit tests verifying casa_total + banca_total = grand_total; Use round() consistently
Message too long for Telegram	Low	Medium	Telegram limit is 4096 chars; current format uses ~300-500 chars; Monitor in production
Cache metadata missing	Low	Low	Graceful fallback: only add footer if metadata exists (existing pattern)
Formatting inconsistencies	Low	Low	Reuse existing formatters (format_response_with_company, add_performance_footer)

Open Questions

1. Should /trezorerie show unified view or redirect to menu?

   • Decision: Show unified view (recommended for consistency)
   • Rationale: More useful for power users who type commands

2. Should we add Export button functionality now or later?

   • Decision: Add button now, implement export functionality later
   • Rationale: Maintains UI consistency with other views; export can be separate feature

3. Should we update /help command text to reflect menu changes?

   • Decision: Out of scope for this feature
   • Rationale: Can be updated in separate UX improvement task

Testing Strategy

Manual Testing Checklist

1. Menu Navigation:

   • /menu shows new compact layout
   • [Trezorerie] button exists in Row 2
   • [Trezorerie Casa] and [Trezorerie Banca] buttons removed
   • [Sold Clienti] and [Sold Furnizori] in Row 3
   • [Evolutie Incasari] in Row 4

2. Unified View:

   • Tapping [Trezorerie] shows combined message
   • Grand total = Casa total + Banca total
   • Casa section shows total + accounts
   • Banca section shows total + accounts
   • Company name at top
   • Performance footer at bottom

3. Legacy Commands:

   • /trezorerie_casa shows Casa only
   • /trezorerie_banca shows Banca only
   • /trezorerie shows unified view

4. Action Buttons:

   • [Refresh] button exists (for command, not callback)
   • [Menu Principal] button exists
   • [Menu Principal] returns to main menu

5. Edge Cases:

   • No casa accounts: Shows "Nu exista conturi de casa"
   • No banca accounts: Shows "Nu exista conturi bancare"
   • Zero balances: Shows "0 RON"
   • Large amounts: Thousands separator works (e.g., "1,234,567 RON")

Unit Testing

# Test unified formatter
def test_format_treasury_combined_response():
    data = {
        'casa': {
            'total': 5000.0,
            'accounts': [
                {'name': 'Casa Lei', 'balance': 3000.0},
                {'name': 'Casa Valuta', 'balance': 2000.0}
            ]
        },
        'banca': {
            'total': 15500.0,
            'accounts': [
                {'name': 'BCR RON', 'balance': 10000.0},
                {'name': 'BRD EUR', 'balance': 5500.0}
            ]
        }
    }

    result = format_treasury_combined_response(data)

    # Assert grand total
    assert "20,500 RON" in result

    # Assert casa section
    assert "Casa Lei: 3,000 RON" in result
    assert "Casa Valuta: 2,000 RON" in result

    # Assert banca section
    assert "BCR RON: 10,000 RON" in result
    assert "BRD EUR: 5,500 RON" in result

Estimated Complexity

Medium - This is a straightforward refactoring task with clear requirements and existing patterns to follow.

Justification:

• Low Risk: No database changes, no new API endpoints, uses existing data
• Well-Defined: Clear specification with examples and acceptance criteria
• Existing Patterns: Follows established formatter and handler patterns
• Backward Compatible: Legacy commands remain functional
• Estimated Effort: 2-3 hours (1h coding, 1h testing, 0.5h code review)

Complexity Breakdown:

• New formatter function: 30 min (straightforward string formatting)
• Menu layout update: 10 min (simple button rearrangement)
• Callback handler: 20 min (copy-paste existing pattern)
• Legacy command update: 20 min (if /trezorerie needs changes)
• Testing: 60 min (manual testing + edge cases)
• Code review fixes: 30 min (buffer for feedback)

Total Estimated Time: 2.5 hours