Add transaction mix reporting endpoint for product, transaction type, operator, and status breakdowns #561

Summary

Implement a reporting endpoint in EstateReportingAPI for transaction mix breakdowns used by the mobile reporting screen.

This is the backend work behind TransactionProcessorACL issue #703: TransactionProcessing/TransactionProcessorACL#703

Current repo context

The existing transaction reporting endpoints live under api/transactions in:

• EstateReportingAPI/Endpoints/TransactionEndpoints.cs
• EstateReportingAPI/Handlers/TransactionHandler.cs
• EstateReportingAPI.BusinessLogic/Queries/TransactionQueries.cs
• EstateReportingAPI.BusinessLogic/ReportingManager.cs

This issue should follow the same request/response and integration test patterns already used for transaction detail, merchant summary, operator summary, and product performance reporting.

Proposed endpoint

Recommended route:
POST /api/transactions/transactionmixsummary

If the mobile contract requires /api/reporting, add a thin alias only if needed. Keep the implementation consistent with the existing API structure where possible.

Functional scope

Support transaction mix reporting by:

• product
• transaction type
• operator
• status
• date range

Support both:

• count view
• value view

Expected behaviour

• Accept a merchant-scoped request so results are limited to the authenticated merchant context.
• Accept startDate and endDate filters.
• Return grouped breakdown data suitable for mobile drill-down UX.
• Return top-N summary rows, with top 5 products/operators supported.
• Return empty collections when no data exists.
• Return validation errors for invalid date ranges or unsupported filter combinations.
• Return standard error responses for unexpected failures.

Suggested request shape

{
  "merchantReportingId": 12345,
  "startDate": "2026-07-01T00:00:00Z",
  "endDate": "2026-07-03T23:59:59Z",
  "breakdown": "Product",
  "measure": "Count",
  "topN": 5
}

Suggested response shape

Include:

• fromDate
• toDate
• selected breakdown
• selected measure
• aggregate totals for count and value
• grouped breakdown items
• drill-down transaction rows for the selected grouping

Implementation notes

• Add endpoint wiring in EstateReportingAPI/Endpoints/TransactionEndpoints.cs.
• Add request handling in EstateReportingAPI/Handlers/TransactionHandler.cs.
• Add query definitions in EstateReportingAPI.BusinessLogic/Queries/TransactionQueries.cs.
• Extend reporting logic in EstateReportingAPI.BusinessLogic/ReportingManager.cs.
• Add request/response DTOs in both Models and DataTrasferObjects to match the existing repo pattern.
• Keep the response shape aligned with the existing transaction reporting endpoints where possible.

Acceptance criteria

• A merchant can request transaction mix reports from the API.
• The API filters correctly by date range.
• The API can group by product, transaction type, operator, and status.
• The API can return both count and value summaries.
• The API can return top-N rows, including top 5 products/operators.
• The API returns data in a shape that supports tap-to-drill UX on mobile.
• Empty and error cases are handled cleanly.
• Integration tests cover successful and invalid request cases.

Test coverage

Add or extend tests in EstateReportingAPI.IntegrationTests/TransactionsEndpointTests.cs to verify:

• product breakdown
• operator breakdown
• transaction type breakdown
• status breakdown
• count and value measures
• top-N limiting
• empty result behaviour
• invalid date range behaviour