9 KiB
9 KiB
PRD سند جامع نیازمندیهای محصول: سیستم کیف پول کاربر (Player Wallet) و تسویه مالی ادمین
- عنوان پروژه: پیادهسازی زیرساخت لجر کیف پول، شارژ، پرداخت و پنل تسویه ادمین
- کد پروژه جیرا: EKD
- نوع سند: Product Requirement Document (PRD)
- مدیر محصول (PM): سارا محمودزاده
- مجریان فنی: آرمین زاهدی (معماری بکاند، دیتابیس و لاجیک مالی) | مرتضی صادقی (توسعه فرانتاند طبق فیگما)
۱. صورت مسئله و اهداف کلیدی
پلتفرم اکیپا در حال حاضر در زمان کنسلی سانس یا استرداد وجه، مستقیماً وابسته به انتقالهای دستی خارج از چرخه یا درگاه است. با پیادهسازی سیستم کیف پول:
- کاربر وجه کنسلی یا جوایز/کشبک را فوراً در کیف پول دریافت میکند (کاهش خروج نقدینگی از سیستم).
- امکان شارژ دلخواه کیف پول و پرداخت آنی (Fast Checkout) بدون نیاز به اتصال مجدد به درگاه بانکی فراهم میشود.
- کاربر میتواند درخواست تسویه و بازگشت وجه (Cash-out) به حساب بانکی ثبت کند.
- تیم پشتیبانی و مالی اکیپا، درخواستهای استرداد را در پنل ادمین مشاهده، پردازش و تایید میکند و پیامک اطلاعرسانی خودکار برای کاربر ارسال میشود.
۲. معماری دیتابیس و اصول فنی (بکاند - آرمین زاهدی)
با توجه به نگاه به اسکیل بزرگ (High Scale & Financial Audit)، رعایت نکات زیر در طراحی دیتابیس الزامی است:
۲.۱. معماری لجر دوطرفه (Double-Entry Bookkeeping Ledger)
- کیف پول هرگز نباید صرفاً یک فیلد ساده
balanceباشد که باUPDATEتغییر کند. - مدل داده باید بر اساس تراکنشهای ثبتشده (Immutable Transactions) باشد:
- جدول
wallets: شناسه کاربر، موجودی فعلی، ارز، وضعیت (فعال/مسدود). - جدول
wallet_transactions: شناسه تراکنش، شناسه کیف پول، نوع (DEPOSIT,WITHDRAW,RESERVE_PAYMENT,REFUND_CHARGE,SETTLEMENT_PAYOUT)، مبلغ، مانده پس از تراکنش، شناسه مرجع (reference_idمانند شماره رزرو)، توضیحات و زمان. - تراکنشهای اتمیک با Database Row Locking (
SELECT FOR UPDATE) برای جلوگیری از Race Condition و موجودی منفی.
- جدول
۲.۲. جدول درخواستهای بازگشت وجه (Settlement / Cash-out Requests)
- جدول
wallet_withdrawal_requests:id: شناسه یکتاuser_id: شناسه کاربرamount: مبلغ درخواستیcard_number: شماره کارت ۱۶ رقمیshaba_number: شماره شبا (اختیاری یا اجباری)account_owner_name: نام و نام خانوادگی صاحب حسابstatus: وضعیت (PENDINGدر انتظار،PROCESSINGدر حال واریز،PAIDواریز شده/برگردانده شده،REJECTEDرد شده)admin_id: کارشناس پشتیبانی/مالی اقدامکنندهadmin_note: یادداشت پشتیبان یا کد پیگیری واریز بانکیcreated_at,updated_at,paid_at
۳. جریانهای عملیاتی سیستم (Business Workflows)
۳.۱. شارژ و پرداخت با کیف پول (Player Side)
- شارژ مستقیم: انتخاب مبلغ دلخواه یا ارقام پیشنهادی -> اتصال به درگاه بانکی -> پس از بازگشت موفق، ثبت لاگ لجر و افزایش آنی موجودی.
- پرداخت سانس: در صفحه پرداخت، گزینه «پرداخت با کیف پول» نمایش داده میشود:
- اگر موجودی >= مبلغ رزرو: کسر آنی از کیف پول و ثبت قطعی رزرو.
- اگر موجودی < مبلغ رزرو: پرداخت ترکیبی (کسر موجودی کیف پول + پرداخت مابقی از درگاه بانکی - در صورت آماده بودن).
۳.۲. ثبت درخواست بازگشت وجه (Player Cash-out Request)
- کاربر در بخش کیف پول گزینه «برداشت وجه / استرداد به حساب» را میزند.
- ثبت شماره کارت و نام صاحب حساب (با اعتبارسنجی الگوریتم کارتهای بانکی ایران).
- بلافاصله مبلغ از موجودی قابل برداشت کاربر بلوکه (Hold) میشود تا کاربر نتواند همزمان با آن رزرو ثبت کند.
- درخواست به پنل ادمین ارسال میشود.
۳.۳. پنل مدیریت و پشتیبانی (Admin Panel Action)
- منوی جدید در پنل ادمین: «درخواستهای استرداد کیف پول» (
/wallet/withdrawals). - مشاهده جدول شامل: نام کاربر، شماره موبایل، مبلغ، شماره کارت، نام صاحب حساب، زمان درخواست و وضعیت.
- کارشناس پشتیبانی (مثلاً الهه یا سارا) شماره کارت را کپی و واریز بانکی را انجام میدهد.
- کارشناس دکمه «برگردانده شد / تایید واریز» را کلیک و کد رهگیری بانکی را ثبت میکند.
- ارسال خودکار پیامک وبسرویس:
- متن پیامک:
کاربر گرامی [نام]، مبلغ [مبلغ] تومان به شماره کارت [شماره کارت ماسکشده] واریز شد. کد پیگیری: [کد پیگیری]. اکیپا
- متن پیامک:
- وضعیت در اپلیکیشن و حساب کاربر درجا به «واریز شده» تغییر میکند.
۴. تفکیک دقیق وظایف تیم فنی
بخش آرمین زاهدی (بکاند و سیستم مالی)
- پیادهسازی مدل لجر و مایگریشنهای دیتابیس (
walletsوwallet_transactions) با قفل ردیفی. - پیادهسازی اندپوینتهای کاربر:
GET /v2/wallet/balance(دریافت موجودی و آخرین تراکنشها).POST /v2/wallet/charge(شارژ از طریق درگاه).POST /v2/wallet/withdraw-request(ثبت درخواست برداشت).- متد پرداخت رزرو با کیف پول در سرویس رزرواسیون.
- پیادهسازی اندپوینتهای پنل ادمین:
GET /v2/admin/wallet/withdrawals(لیست فیلترپذیر بر اساس وضعیت، تاریخ، کاربر).PATCH /v2/admin/wallet/withdrawals/:id/complete(تغییر وضعیت به پرداخت شده + ذخیره لاگ ادمین).PATCH /v2/admin/wallet/withdrawals/:id/reject(رد درخواست و برگشت مبلغ بلوکهشده به کیف پول).
- اتصال وبهوک/سرویس پیامک (کاوه نگار یا سرویس فعال اکیپا) برای ارسال آنی پیامک تایید واریز.
بخش مرتضی صادقی (فرانتاند - طبق طرح فیگما)
- سمت کلاینت / وباپلیکیشن کاربر:
- صفحه اختصاصی کیف پول کاربر (نمایش موجودی، دکمه شارژ سریع، لیست تراکنشها).
- فرم مودال درخواست استرداد وجه (ورود شماره کارت ۱۶ رقمی، نام صاحب حساب و اعتبارسنجی فیلدها).
- اضافه کردن گزینه «پرداخت با کیف پول» در استپ نهایی تسویهحساب رزرو.
- سمت پنل ادمین (React-Admin):
- ایجاد منوی جدید «تسویه و بازگشت وجه کیف پول».
- جدول با ستونهای: کاربر، مبلغ، شماره کارت (با قابلیت کپی در کلیپبورد با یک کلیک)، نام صاحب کارت، تاریخ و دکمه تغییر وضعیت.
- مودال تایید واریز وجه همراه با فیلد اختیاری کد رهگیری بانکی.
۵. معیارهای پذیرش (Acceptance Criteria)
- ثبت و کسر تراکنشها با دقت ۱۰۰٪ ریالی بدون امکان ایجاد مانده منفی.
- بلوکه شدن آنی وجه پس از ثبت درخواست برداشت توسط کاربر.
- ارسال پیامک خودکار بلافاصله پس از فشردن دکمه «برگردانده شد» در ادمین.
- تغییر آنی وضعیت تراکنش در پنل کاربر و ادمین بدون نیاز به رفرش سخت.