sara-dashboards/PRD_کیف_پول_کاربر_و_تسویه_ادمین.md

101 lines
9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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