# دعوت دوستان و پاداش‌ها

## محل استفاده

- مارکت‌پلیس: `/account/referrals`، از منوی پروفایل ← دعوت از دوستان.
- مدیریت: `/?section=referrals` در برنامه مستقل `planck-admin` ← دعوت و پاداش‌ها.
- مقادیر اولیه: پاداش دعوت **۵۰٬۰۰۰ تومان** و سهم دعوت‌کننده **۲۰٪ از کارمزد دریافت‌شده معامله**.
- مالک پنل با ورود دومرحله‌ای می‌تواند مبلغ، درصد و فعال بودن طرح را تغییر دهد. دیگر مدیران فقط گزارش و تنظیمات را می‌بینند.

## مسیر دعوت

هر کاربر یک کد اصلی تصادفی، مانند `plk234mf`، دارد و می‌تواند تا سقف ۲۰ کد، کدهای دیگری با عنوان دلخواه بسازد. جدول کدها عنوان، تعداد دعوت و وضعیت را نمایش می‌دهد. کدها با منبع تصادفی سرور ساخته می‌شوند و دیتابیس یکتا بودن آن‌ها را تضمین می‌کند.

لینک دعوت به شکل `/?ref=plk234mf&auth=register` است. اولین کد معتبر از نظر قالب، تا ۳۰ روز روی همان مرورگر نگهداری می‌شود و فرم ثبت‌نام را پر می‌کند. کاربر می‌تواند پیش از ثبت‌نام آن را تغییر دهد یا حذف کند. سرور اعتبار کد و تأیید شماره/ایمیل دعوت‌کننده را بررسی می‌کند. ارتباط دعوت فقط هنگام ساخت حساب جدید ثبت می‌شود؛ ویرایش اطلاعات حساب یا ورود دوباره آن را عوض نمی‌کند. کد ذخیره‌شده مرورگر پس از ورود پاک می‌شود.

دکمه‌های کپی، ایمیل و واتس‌اپ متن و لینک را آماده می‌کنند. ارسال نهایی توسط خود کاربر در برنامه مقصد انجام می‌شود؛ هیچ دعوتی به‌صورت خودکار ارسال نمی‌شود.

## قواعد پاداش و اتصال به تسویه

پاداش ثابت پس از تأیید شماره/ایمیل، احراز هویت و اولین معامله واقعیِ تسویه‌شده دوست ثبت می‌شود. سهم معاملات از `fee_rial`، کارمزد دریافت‌شده، محاسبه می‌شود. سهم درصدی در دیتابیس با واحد یک‌صدم درصد نگهداری می‌شود و نتیجه به ریال صحیح رو به پایین گرد می‌شود؛ نمایش تومان دقت یک ریال را حفظ می‌کند.

سرویس معتبر معاملات باید سفارش را در `marketplace_private.orders` با وضعیت `filled` و کارمزد نهایی غیرتهی ثبت یا به‌روزرسانی کند. تریگر `marketplace_referral_order_settled` به‌صورت اتمی پاداش را محاسبه می‌کند. سفارش پروژه‌های `is_demo=true` پاداش ندارد. کاربران مرورگر هیچ دسترسی نوشتن سفارش، کارمزد یا پاداش ندارند.

RPC `marketplace_referral_settle(p_order)` نیز فقط برای `service_role` مجاز است. برای بازیابی یا تکرار امن رویداد قابل استفاده است و پاداش را دو بار ثبت نمی‌کند. تغییر کارمزد سفارشی که قبلاً محاسبه شده، با خطا متوقف می‌شود. تراکنش ناموفق باید از طرف سرویس تسویه برگشت داده شود؛ از ویرایش مستقیم رویدادهای پاداش برای اصلاح مالی استفاده نشود.

نسخه تنظیمات و نرخ هر پاداش حفظ می‌شود. تغییرات مدیر فقط روی تسویه‌های بعدی اعمال می‌شوند. معاملات زمان توقف طرح یا پیش از واجد شرایط شدن، بعداً به‌صورت خودکار پاداش نمی‌گیرند. اجرای این مهاجرت سفارش‌های تاریخی را محاسبه نمی‌کند.

**معاملات واقعی و پرداخت خودکار پول در نسخه فعلی مارکت‌پلیس فعال نیستند.** این بخش آماده اتصال به سرویس تسویه است. پروژه‌های نمونه درآمد قابل برداشت ایجاد نمی‌کنند.

## پرداخت و گزارش

پاداش‌های محاسبه‌شده با وضعیت `accrued` جدا از پاداش‌های پرداخت‌شده نمایش داده می‌شوند. هیچ تغییری در موجودی کیف پول صرفاً با محاسبه پاداش انجام نمی‌شود.

پس از ثبت واقعی پرداخت توسط سرویس مالی، RPC `marketplace_referral_mark_paid(p_reward, p_transaction)` فقط با دسترسی `service_role` فراخوانی می‌شود. این تابع وجود تراکنش تأییدشده از نوع `reward` با صاحب حساب یکسان، نماد `TMN` و مبلغ دقیق را بررسی می‌کند. هر تراکنش پرداخت فقط به یک پاداش متصل می‌شود. وظیفه ثبت موجودی و اجرای انتقال واقعی بر عهده سرویس مالی است؛ این تابع انتقال وجه انجام نمی‌دهد.

گزارش کاربر شامل تعداد دعوت‌ها، واجدان شرایط، پاداش دعوت، سهم معاملات، در انتظار پرداخت، پرداخت‌شده و آخرین ۱۰۰ دعوت/پاداش است. جمع‌ها همه سوابق را در بر می‌گیرند. مشخصات تماس و شناسه کامل دوست برای دعوت‌کننده نمایش داده نمی‌شود.

## دیتابیس و دسترسی

مهاجرت: `supabase/migrations/202609080007_referral_program.sql`.

جداول موجود `referral_codes` و `referrals` توسعه یافته‌اند. جداول جدید:

- `referral_program`: تنظیمات فعال و شماره نسخه.
- `referral_program_history`: سابقه نرخ‌ها و مدیر تغییر‌دهنده.
- `referral_settlements`: رویدادهای محاسبه‌شده یکتا برای هر سفارش.
- `referral_rewards`: دفتر پاداش‌ها و ارتباط پرداخت تأییدشده.

همه در `marketplace_private` و دارای RLS هستند. مرورگر به این جداول دسترسی مستقیم ندارد. توابع داشبورد، صاحب اطلاعات را از `auth.uid()` می‌گیرند. تابع بررسی کد عمومی فقط پاسخ بله/خیر می‌دهد. تغییر تنظیمات به مالک با `aal2` محدود و در تاریخچه مدیریت ثبت می‌شود. ویرایش هم‌زمان با شماره نسخه کنترل می‌شود تا تنظیمات جدید ناخواسته بازنویسی نشوند.

## بررسی انجام‌شده

تست‌های دیتابیس، مهاجرت تکرارشونده، مالکیت داده، کدهای تصادفی، سقف ۲۰ کد، عدم تغییر نسبت دعوت پس از ثبت‌نام، احراز هویت، معاملات نمونه/تسویه‌نشده، محاسبه خودکار، جلوگیری از پاداش تکراری، تغییر نرخ آینده، توقف طرح و اثبات پرداخت را پوشش می‌دهند. تست‌های API، ثبت‌نام، لینک‌های اشتراک‌گذاری و محدودیت مدیر نیز اضافه شده‌اند.

هیچ پیام دعوت، پیامک آزمایشی، حساب آزمایشی یا انتقال پولی برای آزمایش این قابلیت روی دیتابیس اصلی ایجاد نشده است.