feat(refer) : Implement referral system with UI components and API integration

Referral-doc.md

@@ -0,0 +1,108 @@
+# Referral System
+
+## Overview
+
+Referral rewards are paid to the referrer based on real successful payments from referred users.
+
+- Reward rate: `20%` of payment (`2000` basis points)
+- Referred user reward: none
+- Behavior flag: `RECURRING_REFERRAL_REWARD`
+  - `true`: reward every successful eligible payment
+  - `false`: reward only once per referral
+
+## Main Rules
+
+- Each user has one unique referral code.
+- A user can apply a code only before their first confirmed payment.
+- Self-referral is blocked (user id + identity fields).
+- Rewarding is idempotent:
+  - same payment cannot reward twice
+  - non-recurring mode allows only one reward for that referral
+
+## Data Model
+
+### `ReferralCode` (`referralcodes`)
+
+- `userId` (unique)
+- `referralCode` (unique)
+
+### `Referral` (`referrals`)
+
+- `referrerId`
+- `referredUserId` (unique)
+- `referralCode`
+- `status`: `pending | converted`
+- `sourceIp`, `deviceFingerprint`, `convertedAt`
+
+### `ReferralTransaction` (`referraltransactions`)
+
+- `referralId`, `referrerId`, `referredUserId`
+- `sourcePaymentId`, `sourcePaymentGateway`, `sourcePaymentObjectId`
+- `paymentAmountUsd`, `rewardAmountUsd`, `rewardRate` (Decimal128)
+- `creditTransactionId`
+- `idempotencyKey` (unique)
+
+## Migration
+
+Migration file: `src/migrations/1744200000000-referral-system.ts`
+
+What it does:
+
+- creates indexes for referral collections
+- backfills missing referral codes for existing users
+- backfills `Referral` records from legacy `user.referral.invitedBy`
+- supports `users` and `tgusers` collections
+
+### Run migration (non-interactive)
+
+```bash
+npx ts-migrate-mongoose up -f src/migrate.ts -a true
+```
+
+### Check migration status
+
+```bash
+npm run migrate:list
+```
+
+### Roll back referral migration (if needed)
+
+```bash
+npm run migrate:down
+```
+
+## Core Services
+
+- `src/services/referral/referralCodeService.ts`
+  - ensures and fetches user referral codes
+- `src/services/referral/referralService.ts`
+  - apply code, enforce eligibility, return referral stats
+- `src/services/referral/referralRewardService.ts`
+  - compute reward in cents, award credits, upsert audit transaction, mark referral converted
+
+## API
+
+- `GET /referral/stats`
+  - returns code, referral link, totals, and referral rows
+- `POST /referral/apply`
+  - request: `{ "code": "ABCD1234", "deviceFingerprint": "optional" }`
+  - supports `x-device-fingerprint` header
+
+## Payment Integration
+
+Reward processing is triggered on successful payment flows in:
+
+- `src/controllers/payment/coinbase/webhook.ts`
+- `src/controllers/payment/stripe/handleWebhook.ts`
+
+## Config
+
+`RECURRING_REFERRAL_REWARD` is read via `nconf`. Truthy values: `true`, `1`, `yes`.
+
+## Tests
+
+Key test: `src/services/referral/__tests__/referralRewardService.test.ts`
+
+- non-recurring behavior
+- recurring behavior
+- payment idempotency