Business Summary (Daily/Weekly): High-level cashflow view for the merchant

[square-story]

Merchants need a quick, high-level overview of their business metrics and cashflow for a given period (today, this week, this month). Currently, they can only see individual transactions, not aggregated business insights. This feature should provide at-a-glance metrics to help merchants understand their business performance.

Problem

Merchants often need to quickly answer questions like:

• How much credit did I give out today?
• How much cash did I collect?
• How many customers did I interact with today?
• Who are my top customers by transaction volume?

Without a summary view, they have to manually add up transactions, which is time-consuming and error-prone.

User Input Examples

• "Today's summary"
• "Aaj ka hisab" (Today's account/summary - Hindi)
• "Show weekly report"
• "Hafta ke summary" (Weekly summary - Hindi)
• "Monthly cashflow"
• "Is week ka report" (This week's report - Hindi)
• "Yeh mahine ka summary" (This month's summary - Hindi)

Backend Logic

1. Determine Date Range: Parse the user's request to determine the time period:

   • "Today" → 00:00 to 23:59 of current day
   • "This week" → Monday 00:00 to Sunday 23:59
   • "This month" → 1st to last day of month
   • "Last 7 days" → Last 7 days from today

2. Aggregate Transactions:

   • Sum all CREDIT transactions (Udhaar Given/Sales)
   • Sum all DEBIT transactions (Cash Collected)
   • Sum all NEUTRAL transactions if applicable
   • Calculate net cashflow (Debit - Credit)

3. Count Metrics:

   • Total distinct active customers in the period
   • Number of transactions
   • Average transaction amount

4. Top Activity:

   • Fetch top 3-5 customers by transaction count or amount
   • Show customer names and their transaction details

Expected WhatsApp Output

For Daily Summary:

📊 *Business Summary (Today)*
28 Nov 2025

📉 *Total Udhaar Given:* ₹2,500
💚 *Cash Collected:* ₹1,200
💰 *Net Cashflow:* -₹1,300

👥 *Active Customers:* 5
📈 *Total Transactions:* 12

_Top Activity:_
1. Raju (-₹500)
2. Amit (+₹200)
3. Priya (-₹300)

For Weekly Summary:

📊 *Business Summary (This Week)*
25-28 Nov 2025

📉 *Total Udhaar Given:* ₹8,500
💚 *Cash Collected:* ₹5,200
💰 *Net Cashflow:* -₹3,300

👥 *Active Customers:* 18
📈 *Total Transactions:* 45

_Top Activity:_
1. Raju (-₹1,500)
2. Amit (+₹800)
3. Priya (-₹950)

Database Queries Needed

// Get transactions within date range for a user
findTransactionsByDateRange(userId, startDate, endDate)

// Sum all credit transactions
sumCreditTransactions(userId, startDate, endDate)

// Sum all debit transactions
sumDebitTransactions(userId, startDate, endDate)

// Count distinct customers in period
countActiveCustomers(userId, startDate, endDate)

// Get top customers by volume
getTopCustomersByVolume(userId, startDate, endDate, limit: 5)

Acceptance Criteria

• NLU recognizes summary request keywords in English and regional languages
• Date range is correctly parsed from user input
• All transactions within the period are correctly summed
• Credit and debit transactions are properly categorized
• Active customer count is accurate and distinct
• Top customers are correctly identified and ranked
• WhatsApp output is formatted with proper emojis and readable layout
• Summary works for daily, weekly, and monthly periods
• Performance is optimized for large transaction datasets

Implementation Tasks

• Extend NLU parser to recognize summary/report intent and time periods
• Create getSummaryReport service method with date range logic
• Implement transaction aggregation queries with proper filtering
• Add getTopCustomers method to fetch top N customers by volume
• Create WhatsApp message formatter for different summary types
• Add caching/optimization for large datasets
• Write comprehensive unit tests for all aggregation logic
• Add integration tests for different date range scenarios
• Create documentation for the summary feature