101 lines
9 KiB
Markdown
101 lines
9 KiB
Markdown
# 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)
|
||
- ثبت و کسر تراکنشها با دقت ۱۰۰٪ ریالی بدون امکان ایجاد مانده منفی.
|
||
- بلوکه شدن آنی وجه پس از ثبت درخواست برداشت توسط کاربر.
|
||
- ارسال پیامک خودکار بلافاصله پس از فشردن دکمه «برگردانده شد» در ادمین.
|
||
- تغییر آنی وضعیت تراکنش در پنل کاربر و ادمین بدون نیاز به رفرش سخت.
|