games_app/.cursor/rules/platform-setup-referral.mdc

31 lines
1.6 KiB
Plaintext

---
description: Referral network bootstrap during initial platform setup (super admin root)
globs: backend/src/services/setupService.ts,backend/src/services/referralService.ts,backend/src/services/authService.ts,prediqo_web/src/features/auth/SetupPage.tsx
alwaysApply: false
---
# Platform setup — referral root
When the first Super Administrator is created during initial deployment (`setupService.createFirstAdmin` or `promoteExistingUserToAdmin`):
1. **Assign a unique referral code** to that account (same generator as standard users: `referralRepository.ensureUserReferralCode`).
2. **Set `referral_program_settings.default_referrer_user_id`** to the super admin's user id (`referralService.bootstrapReferralRootAtPlatformSetup`).
The super admin is the **root of the referral network**.
## Registration behaviour (`authService.register`)
- User provides a **valid** referral code → that referrer is used (`referralService.resolveReferrerId`).
- User provides **no** code (or empty) → `default_referrer_user_id` (super admin) is used.
- Invalid codes fall back to the default referrer (existing behaviour).
## Eligibility
The default referrer (platform root) may act as referrer **without** a completed deposit, even when `referrer_must_have_deposited` is enabled (`assertReferrerEligible` exemption).
## Do not break
- Do not skip referral bootstrap on first-admin setup paths.
- Do not clear `default_referrer_user_id` when promoting later admins (only the **first** setup sets the root).
- Setup API responses should include `referralCode` for operator visibility.