games_app/docs/REFERRAL-COMMISSION-BACKFILL.md
2026-10-26 14:18:55 +02:00

110 lines
3.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Régularisation des commissions prédiction manquées
Quand le **pool bonus** est à 0, le settle win/loss tente bien de payer le parrain, mais **aucune ligne** n’est créée dans `referral_commission_payouts` (seul un log / audit). Après avoir rechargé le pool, il faut **identifier** puis **rejouer** ces paris.
## Interface admin (recommandé)
Page **Options → Régularisation des commissions** (`/admin/referral/regularization`) :
- liste des bénéficiaires avec montants dus + total + solde pool + déficit ;
- régularisation **une personne** / **sélection** / **tout** ;
- refus si solde insuffisant, ou **partiel FIFO** (plus ancien d’abord, jamais de montant réduit) ;
- idempotent (pas de double paiement).
APIs : `GET /api/v1/admin/referral/regularization`, `POST /api/v1/admin/referral/regularization/apply`.
## 1. Lister les paris sans commission (SQL)
```sql
SELECT b.id AS bet_id,
b.created_at,
b.user_id AS referred_user_id,
u.referred_by_user_id AS referrer_user_id,
b.status,
b.stake_account_kind,
b.stake_raw,
b.wallet_type_id
FROM candle_predict_bets b
JOIN users u ON u.id = b.user_id
CROSS JOIN referral_program_settings s
WHERE s.id = 1
AND b.status IN ('won', 'lost')
AND COALESCE(b.stake_account_kind, 'main') <> 'test'
AND b.stake_raw > 0
AND u.referred_by_user_id IS NOT NULL
AND b.wallet_type_id = s.commission_wallet_type_id
AND NOT EXISTS (
SELECT 1 FROM referral_commission_payouts p
WHERE p.candle_predict_bet_id = b.id
AND p.commission_source = 'prediction'
)
ORDER BY b.created_at ASC;
```
Exclus volontairement : mises `test`, settle neutral/refund, utilisateurs sans parrain, wallet ≠ wallet de commission.
Audits futurs (après déploiement des logs) :
```sql
SELECT * FROM audit_logs
WHERE action = 'referral_commission_pool_insufficient'
ORDER BY created_at DESC
LIMIT 100;
```
## 2. Vérifier / alimenter le pool
Admin → **Referrals** → **Fund pool**, puis :
```sql
SELECT available_balance
FROM platform_bonus_pools
WHERE wallet_type_id = (
SELECT commission_wallet_type_id FROM referral_program_settings WHERE id = 1
);
```
## 3. Script dry-run puis apply (VPS)
Dry-run (liste seulement) :
```bash
cd ~/projects_repository/games-project
sudo npm run phase-b:backfill-missed-prediction-referral-commissions
# équivalent :
# sudo docker compose run --rm --no-deps --build backend \
# node dist/scripts/backfillMissedPredictionReferralCommissions.js
```
Options :
```bash
# Depuis une date (ISO)
... backfillMissedPredictionReferralCommissions.js --since=2026-10-01
# Limiter le lot
... backfillMissedPredictionReferralCommissions.js --limit=200
```
Appliquer (crée / paie les commissions manquantes ; idempotent grâce à `ON CONFLICT`) :
```bash
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/backfillMissedPredictionReferralCommissions.js --apply
```
Le script refuse `--apply` si le pool est à 0.
## 4. Contrôle après apply
```sql
SELECT id, status, beneficiary_user_id, referred_user_id, level_number,
commission_amount, candle_predict_bet_id, created_at
FROM referral_commission_payouts
WHERE commission_source = 'prediction'
ORDER BY created_at DESC
LIMIT 50;
```
Relancer le dry-run : la liste des « missed » doit être vide (ou ne contenir que des cas encore bloqués : pool insuffisant pour le reste, sybil, cap, etc.).