# 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:

```python
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:

```python
# 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:

```python
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:

```python
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):

```python
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

```python
# 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