WAGERBABE DOCS
All Stories
9-11-settlement-preview-with-cash-outsReadyEpic 9.11

Story 9.11: Settlement Preview with Cash Outs

Status: ready-for-dev

Tasks

  • **Task 1: Implement Single Customer Preview Endpoint** (AC: AC-9.11-1, AC-9.11-3, AC-9.11-5, AC-9.11-6, AC-9.11-7, AC-9.11-8)
    • 1.1: Create GET /api/v1/agent/settlements/preview/{customer_id} endpoint
    • 1.2: Add optional period_id query parameter with default to active period
    • 1.3: Verify customer ownership (customer.agent_id == agent.id)
    • 1.4: Query opening balance from previous settlement period
    • 1.5: Query all bets for period with cash_out_amount and is_auto_cash_out
    • 1.6: Calculate totals: stakes, payouts, cash_outs, losses
    • 1.7: Build cash_out_summary with count, total_amount, net_from_stake, auto_count
    • 1.8: Calculate closing balance: opening + payouts + cash_outs - stakes
    • 1.9: Determine settlement_direction based on closing balance sign
    • 1.10: Return SettlementPreviewResponse with all fields
  • **Task 2: Implement All Customers Preview Endpoint** (AC: AC-9.11-2)
    • 2.1: Create GET /api/v1/agent/settlements/preview/all endpoint
    • 2.2: Query all customers with bet activity in current period
    • 2.3: Loop through customers calling single customer preview logic
    • 2.4: Build customer_previews array with all individual previews
    • 2.5: Calculate summary totals: customers_owing, customers_owed counts
    • 2.6: Calculate total_owed_by_customers and total_owed_to_customers
    • 2.7: Calculate net_position: owed_by - owed_to
    • 2.8: Calculate total_cash_out_impact across all customers
    • 2.9: Return AllSettlementsPreviewResponse with previews and summary
  • **Task 3: Create Response Models** (AC: AC-9.11-1, AC-9.11-2, AC-9.11-7)
    • 3.1: Define SettlementPreviewResponse Pydantic model
    • 3.2: Define PeriodSummary model (id, start, end, due_date)
    • 3.3: Define ActivitySummary model with cash_outs dict
    • 3.4: Define BetDetail model with all bet fields including cash_out_amount
    • 3.5: Define AllSettlementsPreviewResponse model
    • 3.6: Define PreviewSummary model with aggregated totals
    • 3.7: Add OpenAPI documentation with examples
  • **Task 4: Implement Opening Balance Query** (AC: AC-9.11-5)
    • 4.1: Query settlement_requirements for customer's last completed period
    • 4.2: Get amount_due from period ending before current period start
    • 4.3: Default to 0 if no previous settlement exists
    • 4.4: Handle case where customer is new (no prior history)
  • **Task 5: Implement Bet Activity Query** (AC: AC-9.11-1, AC-9.11-3, AC-9.11-4, AC-9.11-7)
    • 5.1: Query bets table for period with all relevant fields
    • 5.2: Include cash_out_amount and is_auto_cash_out columns
    • 5.3: Filter by customer_id and period date range
    • 5.4: Order by created_at for chronological view
    • 5.5: Join with any needed related tables for description
  • **Task 6: Implement Cash Out Summary Calculation** (AC: AC-9.11-3, AC-9.11-4)
    • 6.1: Filter bets where status == 'cashed_out'
    • 6.2: Count total cash outs
    • 6.3: Sum total cash_out_amount
    • 6.4: Calculate net_from_stake: total_cash_outs - stakes_of_cashed_out_bets
    • 6.5: Count auto_count where is_auto_cash_out == true
    • 6.6: Build cash_out_summary dict with all metrics
  • **Task 7: Implement Settlement Calculation Logic** (AC: AC-9.11-5, AC-9.11-6)
    • 7.1: Calculate total_stakes from all bets
    • 7.2: Calculate total_payouts from won bets (stake * odds)
    • 7.3: Sum total_cash_outs from cash out summary
    • 7.4: Calculate closing_balance: opening + payouts + cash_outs - stakes
    • 7.5: Determine settlement_direction: 'customer_owes' if positive, 'agent_owes' if negative
    • 7.6: Calculate settlement_amount as abs(closing_balance)
    • 7.7: Set settlement_required flag (closing_balance != 0)
  • **Task 8: Create Frontend SettlementPreview Component** (AC: AC-9.11-1, AC-9.11-2)
    • 8.1: Create client/src/components/composite/agent/settlement-preview.tsx
    • 8.2: Accept customerId prop (optional for all vs single view)
    • 8.3: Use React Query to fetch preview data
    • 8.4: Render SingleCustomerPreview or AllCustomersPreview based on prop
    • 8.5: Add loading skeleton for data fetch
  • **Task 9: Create SingleCustomerPreview Component** (AC: AC-9.11-1, AC-9.11-3, AC-9.11-4, AC-9.11-5, AC-9.11-6, AC-9.11-7)
    • 9.1: Display period info in header (start - end dates)
    • 9.2: Show activity summary grid: total bets, stakes, payouts, cash outs
    • 9.3: Add cash out impact alert if cash outs exist
    • 9.4: Show auto count in parentheses if applicable
    • 9.5: Display net from stake for cash outs
    • 9.6: Create settlement summary card with opening → closing balance flow
    • 9.7: Use ArrowRight icon between opening and closing
    • 9.8: Color code closing balance (green for customer owes, red for agent owes)
    • 9.9: Show settlement direction with clear label
    • 9.10: Create bet details accordion with expandable list
    • 9.11: Badge bet status (won, lost, cashed_out) with color coding
    • 9.12: Show cash out amount for cashed out bets
  • **Task 10: Create AllCustomersPreview Component** (AC: AC-9.11-2)
    • 10.1: Display period info in header
    • 10.2: Show summary stats: total customers, customers owing, customers owed
    • 10.3: Display total owed by customers vs total owed to customers
    • 10.4: Show net position for agent
    • 10.5: Display total cash out impact across all customers
    • 10.6: Render table of customer previews with key metrics
    • 10.7: Add click handler to expand individual customer details
    • 10.8: Color code settlement amounts based on direction
  • **Task 11: Add Period Selection UI** (AC: AC-9.11-8)
    • 11.1: Add period selector dropdown to preview component
    • 11.2: Fetch available settlement periods from API
    • 11.3: Default to current active period
    • 11.4: Update query when period changes
    • 11.5: Show historical periods for reconciliation
  • **Task 12: Integration Testing** (AC: AC-9.11-1, AC-9.11-2, AC-9.11-3, AC-9.11-4, AC-9.11-5, AC-9.11-6, AC-9.11-7, AC-9.11-8)
    • 12.1: Test single customer preview with cash outs
    • 12.2: Test customer with no cash outs (baseline)
    • 12.3: Test customer with only auto cash outs
    • 12.4: Test customer with mixed manual and auto cash outs
    • 12.5: Test all customers preview aggregation
    • 12.6: Test opening balance carry forward from previous period
    • 12.7: Test closing balance calculation accuracy
    • 12.8: Test settlement direction determination (positive/negative)
    • 12.9: Test period selection with historical periods
    • 12.10: Test bet details include all cash out fields
    • 12.11: Verify cash out impact calculations correct
    • 12.12: Test edge case: new customer with no opening balance
  • **Task 13: Frontend State Management** (AC: AC-9.11-1, AC-9.11-2)
    • 13.1: Set up React Query for preview data caching
    • 13.2: Implement query key strategy for customer/period combinations
    • 13.3: Add optimistic updates for preview recalculation
    • 13.4: Handle loading and error states gracefully
    • 13.5: Add retry logic for failed preview fetches
  • **Task 14: Mobile Responsive Design** (AC: AC-9.11-1, AC-9.11-2)
    • 14.1: Make activity summary grid responsive (2 cols on mobile, 4 on desktop)
    • 14.2: Stack settlement summary vertically on mobile
    • 14.3: Optimize bet details accordion for touch
    • 14.4: Ensure all customers table scrolls horizontally on mobile
    • 14.5: Test on various screen sizes (320px, 768px, 1024px)
  • **Task 15: Documentation and OpenAPI** (AC: AC-9.11-1, AC-9.11-2)
    • 15.1: Add comprehensive OpenAPI documentation for both endpoints
    • 15.2: Include request/response examples with cash outs
    • 15.3: Document query parameters (period_id)
    • 15.4: Add calculation formulas to endpoint descriptions
    • 15.5: Document settlement direction logic

Progress

Tasks0/15
Acceptance Criteria0
Total Tasks15

Navigation

View Epic 9.11All Stories