# PRD سند جامع نیازمندی‌های محصول: سیستم کیف پول کاربر (Player Wallet) و تسویه مالی ادمین - **عنوان پروژه:** پیاده‌سازی زیرساخت لجر کیف پول، شارژ، پرداخت و پنل تسویه ادمین - **کد پروژه جیرا:** EKD - **نوع سند:** Product Requirement Document (PRD) - **مدیر محصول (PM):** سارا محمودزاده - **مجریان فنی:** آرمین زاهدی (معماری بک‌اند، دیتابیس و لاجیک مالی) | مرتضی صادقی (توسعه فرانت‌اند طبق فیگما) --- ## ۱. صورت مسئله و اهداف کلیدی پلتفرم اکیپا در حال حاضر در زمان کنسلی سانس یا استرداد وجه، مستقیماً وابسته به انتقال‌های دستی خارج از چرخه یا درگاه است. با پیاده‌سازی سیستم کیف پول: 1. کاربر وجه کنسلی یا جوایز/کش‌بک را فوراً در کیف پول دریافت می‌کند (کاهش خروج نقدینگی از سیستم). 2. امکان شارژ دلخواه کیف پول و پرداخت آنی (Fast Checkout) بدون نیاز به اتصال مجدد به درگاه بانکی فراهم می‌شود. 3. کاربر می‌تواند درخواست تسویه و بازگشت وجه (Cash-out) به حساب بانکی ثبت کند. 4. تیم پشتیبانی و مالی اکیپا، درخواست‌های استرداد را در پنل ادمین مشاهده، پردازش و تایید می‌کند و پیامک اطلاع‌رسانی خودکار برای کاربر ارسال می‌شود. --- ## ۲. معماری دیتابیس و اصول فنی (بک‌اند - آرمین زاهدی) با توجه به نگاه به **اسکیل بزرگ (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) 1. **شارژ مستقیم:** انتخاب مبلغ دلخواه یا ارقام پیشنهادی -> اتصال به درگاه بانکی -> پس از بازگشت موفق، ثبت لاگ لجر و افزایش آنی موجودی. 2. **پرداخت سانس:** در صفحه پرداخت، گزینه «پرداخت با کیف پول» نمایش داده می‌شود: - اگر موجودی >= مبلغ رزرو: کسر آنی از کیف پول و ثبت قطعی رزرو. - اگر موجودی < مبلغ رزرو: پرداخت ترکیبی (کسر موجودی کیف پول + پرداخت مابقی از درگاه بانکی - در صورت آماده بودن). ### ۳.۲. ثبت درخواست بازگشت وجه (Player Cash-out Request) 1. کاربر در بخش کیف پول گزینه «برداشت وجه / استرداد به حساب» را می‌زند. 2. ثبت شماره کارت و نام صاحب حساب (با اعتبارسنجی الگوریتم کارت‌های بانکی ایران). 3. بلافاصله مبلغ از موجودی قابل برداشت کاربر **بلوکه (Hold)** می‌شود تا کاربر نتواند هم‌زمان با آن رزرو ثبت کند. 4. درخواست به پنل ادمین ارسال می‌شود. ### ۳.۳. پنل مدیریت و پشتیبانی (Admin Panel Action) 1. منوی جدید در پنل ادمین: **«درخواست‌های استرداد کیف پول» (`/wallet/withdrawals`)**. 2. مشاهده جدول شامل: نام کاربر، شماره موبایل، مبلغ، شماره کارت، نام صاحب حساب، زمان درخواست و وضعیت. 3. کارشناس پشتیبانی (مثلاً الهه یا سارا) شماره کارت را کپی و واریز بانکی را انجام می‌دهد. 4. کارشناس دکمه **«برگردانده شد / تایید واریز»** را کلیک و کد رهگیری بانکی را ثبت می‌کند. 5. **ارسال خودکار پیامک وب‌سرویس:** - متن پیامک: `کاربر گرامی [نام]، مبلغ [مبلغ] تومان به شماره کارت [شماره کارت ماسک‌شده] واریز شد. کد پیگیری: [کد پیگیری]. اکیپا` 6. وضعیت در اپلیکیشن و حساب کاربر درجا به **«واریز شده»** تغییر می‌کند. --- ## ۴. تفکیک دقیق وظایف تیم فنی ### بخش آرمین زاهدی (بک‌اند و سیستم مالی) 1. پیاده‌سازی مدل لجر و مایگریشن‌های دیتابیس (`wallets` و `wallet_transactions`) با قفل ردیفی. 2. پیاده‌سازی اندپوینت‌های کاربر: - `GET /v2/wallet/balance` (دریافت موجودی و آخرین تراکنش‌ها). - `POST /v2/wallet/charge` (شارژ از طریق درگاه). - `POST /v2/wallet/withdraw-request` (ثبت درخواست برداشت). - متد پرداخت رزرو با کیف پول در سرویس رزرواسیون. 3. پیاده‌سازی اندپوینت‌های پنل ادمین: - `GET /v2/admin/wallet/withdrawals` (لیست فیلترپذیر بر اساس وضعیت، تاریخ، کاربر). - `PATCH /v2/admin/wallet/withdrawals/:id/complete` (تغییر وضعیت به پرداخت شده + ذخیره لاگ ادمین). - `PATCH /v2/admin/wallet/withdrawals/:id/reject` (رد درخواست و برگشت مبلغ بلوکه‌شده به کیف پول). 4. اتصال وب‌هوک/سرویس پیامک (کاوه نگار یا سرویس فعال اکیپا) برای ارسال آنی پیامک تایید واریز. ### بخش مرتضی صادقی (فرانت‌اند - طبق طرح فیگما) 1. **سمت کلاینت / وب‌اپلیکیشن کاربر:** - صفحه اختصاصی کیف پول کاربر (نمایش موجودی، دکمه شارژ سریع، لیست تراکنش‌ها). - فرم مودال درخواست استرداد وجه (ورود شماره کارت ۱۶ رقمی، نام صاحب حساب و اعتبارسنجی فیلدها). - اضافه کردن گزینه «پرداخت با کیف پول» در استپ نهایی تسویه‌حساب رزرو. 2. **سمت پنل ادمین (React-Admin):** - ایجاد منوی جدید «تسویه و بازگشت وجه کیف پول». - جدول با ستون‌های: کاربر، مبلغ، شماره کارت (با قابلیت کپی در کلیپ‌بورد با یک کلیک)، نام صاحب کارت، تاریخ و دکمه تغییر وضعیت. - مودال تایید واریز وجه همراه با فیلد اختیاری کد رهگیری بانکی. --- ## ۵. معیارهای پذیرش (Acceptance Criteria) - ثبت و کسر تراکنش‌ها با دقت ۱۰۰٪ ریالی بدون امکان ایجاد مانده منفی. - بلوکه شدن آنی وجه پس از ثبت درخواست برداشت توسط کاربر. - ارسال پیامک خودکار بلافاصله پس از فشردن دکمه «برگردانده شد» در ادمین. - تغییر آنی وضعیت تراکنش در پنل کاربر و ادمین بدون نیاز به رفرش سخت.