This implementation updates the reports sync system to handle cap compensation balance tracking, improved filtering, and client-aggregated reporting according to the latest protocol documentation.
## Changes Made
### 1. Database Model Updates
#### ReportSync Model (`app/models.py`)
-**Added**: `cap_compensation_balance` field (Numeric(15, 2))
- Stores the accumulated shortfall from cap compensation system
The cap compensation balance represents the accumulated shortfall from the cap compensation system. It tracks adjustments across all extractions where the redistribution CAP was applied.
### How It's Tracked
1.**At Each Sync**:
- Client sends current `cap_compensation_balance` value
- Server stores it in the ReportSync record
- Value represents the balance at the time of sync
2.**In Reports**:
- Shows the CAP balance at the **end of the selected period**
- For aggregated reports: uses the most recent sync's balance
- For client details: uses the most recent sync's balance
- For all clients: shows total across all clients
3.**Time-Based Tracking**:
- Each sync records the balance at that moment
- Reports can show historical balance values
- Filters allow viewing balance at specific time periods
## Record Differentiation
### New vs Updated Records
The system differentiates between new and updated records:
**New Records:**
- Bets that don't exist in the database (by UUID)
- Extraction stats that don't exist (by match_id + sync_id)
- Created with `created_at` timestamp
**Updated Records:**
- Existing bets with new data (e.g., results added)
- Existing extraction stats with updated information
- Original `created_at` preserved
- New `updated_at` timestamp set
**Example Scenario:**
1. Match is scheduled → Bet created (NEW record)
2. Match is played → Results added (UPDATED record)
3. Payout processed → Paid status updated (UPDATED record)
## Filtering System
### Date Range Filters
| Filter | Description | Time Range |
|---------|-------------|-------------|
| Today | Current day from 00:00:00 to now | 00:00:00 - now |
| Yesterday | Previous full day | 00:00:00 - 23:59:59 |
| This Week | Monday to current day | Monday 00:00:00 - now |
| Last Week | Previous full week | Monday 00:00:00 - Sunday 23:59:59 |
| This Month | Current month from 1st to now | 1st 00:00:00 - now |
| All | All historical data | No limit |
| Custom | User-defined range | User-specified dates/times |
### Client Filter
- Dropdown shows all clients with their token names
- Format: "Token Name (client_id)"
- Allows filtering to specific client or viewing all
### Sorting Options
- Sync Timestamp (default)
- Client ID
- Total Payin
- Total Payout
- Net Profit
- Total Bets
- Total Matches
## API Usage Examples
### Full Sync (First Sync)
```bash
curl -X POST http://localhost:5000/api/reports/sync \
-H"Content-Type: application/json"\
-H"Authorization: Bearer YOUR_TOKEN"\
-d'{
"sync_id": "sync_20260201_214327_abc12345",
"client_id": "machine_hostname_1234567890",
"sync_timestamp": "2026-02-01T21:43:27.249Z",
"date_range": "all",
"start_date": "2026-01-01T00:00:00",
"end_date": "2026-02-01T21:43:27.249Z",
"bets": [...],
"extraction_stats": [...],
"cap_compensation_balance": 5000.0,
"summary": {
"total_payin": 100000.0,
"total_payout": 95000.0,
"net_profit": 5000.0,
"total_bets": 50,
"total_matches": 10
},
"is_incremental": false,
"sync_type": "full"
}'
```
### Incremental Sync (Subsequent Syncs)
```bash
curl -X POST http://localhost:5000/api/reports/sync \
-H"Content-Type: application/json"\
-H"Authorization: Bearer YOUR_TOKEN"\
-d'{
"sync_id": "sync_20260201_220000_def67890",
"client_id": "machine_hostname_1234567890",
"sync_timestamp": "2026-02-01T22:00:00.000Z",
"date_range": "all",
"start_date": "2026-01-01T00:00:00",
"end_date": "2026-02-01T22:00:00.000Z",
"bets": [...], // Only new/updated bets
"extraction_stats": [...], // Only new/updated stats
"cap_compensation_balance": 5200.0,
"summary": {
"total_payin": 5000.0,
"total_payout": 4800.0,
"net_profit": 200.0,
"total_bets": 5,
"total_matches": 2
},
"is_incremental": true,
"sync_type": "incremental"
}'
```
## Testing
### Manual Testing
1.**Test API Endpoint**:
```bash
python test_reports_sync.py
```
2.**Test Web Interface**:
- Navigate to `/reports`
- Test each date range filter
- Test custom date/time selection
- Test client filtering
- Test sorting options
- Click "Details" button for a client
- Verify bet and extraction stats display
3.**Verify CAP Balance**:
- Check that CAP balance displays correctly
- Verify it shows balance at end of period
- Test with different date ranges
### Expected Behavior
-**Today Filter**: Shows only today's data
-**Custom Range**: Shows data between specified dates/times
-**Client Filter**: Shows only selected client's data