WAGERBABE DOCS
All Stories
9-5-3-promotion-limits-liabilityReadyEpic 9.5

Story 9.5.3: Promotion Limits & Liability

Status: ready-for-dev

Tasks

  • **Task 1: Implement PromotionLiabilityService** (AC: 1, 2, 3)
    • 1.1 Create `server/app/services/promotions/promotion_liability_service.py`
    • 1.2 Implement `validate_and_record_use()` method with all eligibility checks
    • 1.3 Implement `_calculate_liability()` for different promotion types
    • 1.4 Implement `_calculate_boosted_odds()` for American odds calculation
    • 1.5 Add per-user usage limit validation
    • 1.6 Add total usage limit validation
  • **Task 2: Implement Auto-Pause Logic** (AC: 2, 6)
    • 2.1 Add total usage count check in `validate_and_record_use()`
    • 2.2 Auto-pause promotion when max_total_uses reached
    • 2.3 Return appropriate error message when promotion paused
    • 2.4 Update promotion status to 'paused' in database
  • **Task 3: Implement Alert System** (AC: 5)
    • 3.1 Create `send_agent_alert()` helper function
    • 3.2 Calculate usage percentage in `validate_and_record_use()`
    • 3.3 Send alert when usage >= 80% of max_total_uses
    • 3.4 Prevent duplicate alerts for same promotion
    • 3.5 Log alert delivery to `promotion_alerts` table
  • **Task 4: Implement Liability Dashboard Endpoint** (AC: 4)
    • 4.1 Create GET `/api/v1/agent/promotions/liability` endpoint
    • 4.2 Query promotion_uses with JOIN to bets and promotions
    • 4.3 Calculate total_liability (potential cost if all bets win)
    • 4.4 Calculate realized_cost (actual cost from won bets)
    • 4.5 Support date_from and date_to query parameters
    • 4.6 Return per-promotion breakdown with aggregates
  • **Task 5: Record Promotion Usage** (AC: 1, 2, 3)
    • 5.1 Insert into `promotion_uses` table on successful validation
    • 5.2 Store original_odds and boosted_odds
    • 5.3 Store calculated liability cost
    • 5.4 Link to bet_id, user_id, and promotion_id
    • 5.5 Add created_at timestamp
  • **Task 6: Testing** (AC: all)
    • 6.1 Add pytest test for `validate_and_record_use()` with per-user limit
    • 6.2 Add pytest test for total usage limit enforcement
    • 6.3 Add pytest test for liability calculation (odds_boost)
    • 6.4 Add pytest test for liability calculation (profit_boost)
    • 6.5 Add pytest test for liability calculation (risk_free)
    • 6.6 Add pytest test for 80% alert trigger
    • 6.7 Add pytest test for auto-pause at max uses
    • 6.8 Add integration test for liability dashboard endpoint

Progress

Tasks0/6
Acceptance Criteria0
Total Tasks6

Navigation

View Epic 9.5All Stories