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

3.4 KiB
Raw Permalink Blame History

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)

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) :

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 :

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) :

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 :

# 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) :

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

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.).