# پیاده‌سازی بخش مالی و کیف پول در پنل ادمین

## انجام شده

### ۱. لیست پرداخت‌ها (مدیریت مالی ادمین)
- **فیلتر پروژه:** انتخاب پروژه (رابطه با `project_id`)
- **فیلتر بازه زمانی:** از تاریخ / تا تاریخ (روی `created_at`)
- **فیلتر شماره کارت:** جستجو در `card_number`
- **فیلتر شماره همراه:** جستجو در `cellphone`
- **فیلتر ایمیل:** جستجو در `email`
- **فیلتر حساب کاربری:** انتخاب کاربر با جستجو (نام، کدملی، موبایل، ایمیل)
- **فیلتر کد پیگیری:** جستجو در `ref_id`
- **فیلتر شناسه تراکنش:** جستجو در `transaction_id`
- **فیلتر وضعیت:** انتخاب وضعیت (از `Status` enum)
- **مشاهده اطلاعات کامل پرداخت:** دکمه «مشاهده» با **slide-over** (بدون صفحه جدید)
- **خروجی اکسل/CSV:** دکمه «خروجی اکسل/CSV» با استفاده از `ExportAction` و `PaymentExporter` (بر اساس فیلترهای اعمال‌شده)

**مایگریشن:** `2026_02_20_120000_add_project_and_meta_to_payments_table.php`  
ستون‌های اضافه‌شده به `payments`: `project_id`, `card_number`, `cellphone`, `email`.  
در رویداد `creating` مدل `Payment`، در صورت وجود `user` و `Order`، فیلدهای `cellphone`, `email`, `project_id` از روی کاربر و سفارش پر می‌شوند.

**فرم پرداخت:** فیلدهای «پروژه»، «شماره کارت»، «شماره همراه»، «ایمیل» به فرم اضافه شده است.

---

### ۲. درخواست‌های برداشت
- **لیست برداشت‌ها:** ریسورس `WithdrawalRequestResource` در گروه «مالی»
- **ستون‌ها:** درخواست‌کننده، شماره همراه، کد ملی، مبلغ، شماره شبا، به نام، موجودی کیف پول، وضعیت، شناسه واریز، یادداشت ادمین، تاریخ/زمان
- **فیلترها:** بازه زمانی، وضعیت (در انتظار / تایید شده / رد شده)، کاربر (جستجو با نام، موبایل، کدملی، ایمیل)
- **مشاهده جزئیات:** دکمه «مشاهده» با slide-over و فرم فقط خواندنی
- **تایید درخواست برداشت:** اکشن «تایید» با فرم (شناسه واریز اجباری، یادداشت اختیاری) و به‌روزرسانی وضعیت و `processed_by` / `processed_at`
- **رد درخواست برداشت:** اکشن «رد» با فرم (دلیل رد اجباری)
- **نمایش تعداد در انتظار:** بج کنار منوی «درخواست‌های برداشت» برای تعداد درخواست‌های در انتظار

**مدل و مایگریشن:**  
`WithdrawalRequest` با فیلدهای `user_id`, `amount`, `shaba`, `account_holder_name`, `wallet_balance_at_request`, `status`, `admin_note`, `transfer_ref`, `processed_by`, `processed_at`.

---

### ۳. گردش مالی (تراکنش‌های کیف پول)
- **لیست گردش مالی:** ریسورس `WalletTransactionResource` در گروه «مالی»
- **ستون‌ها:** کاربر، نوع (واریز/برداشت/سود/کارمزد/شارژ/خرید/فروش)، مبلغ، موجودی پس، کد پیگیری، وضعیت، پروژه، شرح، تاریخ/زمان
- **فیلترها:** بازه زمانی، کاربر (جستجو)، کد پیگیری، وضعیت، پروژه

**مدل و مایگریشن:**  
`WalletTransaction` و جدول `wallet_transactions` با فیلدهای `user_id`, `type`, `amount`, `balance_after`, `description`, `tracking_code`, `status`, `payment_id`, `project_id`, `invoice_id`, `meta`.

---

### ۴. فاکتورها
- **لیست فاکتورها:** ریسورس `InvoiceResource` در گروه «مالی»
- **ستون‌ها:** شماره فاکتور، پروژه، کد پروژه، کاربر، نوع (درآمد/هزینه)، وضعیت، جمع کل، تاریخ صدور، سررسید، تاریخ ایجاد
- **فیلترها:** بازه زمانی، وضعیت (پرداخت شده/نشده/تایید/رد/ویرایش/پیش‌نویس)، نوع تراکنش (درآمد/هزینه)، پروژه

**مدل و مایگریشن:**  
`Invoice`, `InvoiceItem` و جداول `invoices`, `invoice_items`.  
فاکتور دارای `number`, `project_id`, `user_id`, `type`, `status`, `total`, `issued_at`, `due_at`.  
آیتم فاکتور دارای `name`, `category`, `subcategory`, `quantity`, `unit`, `unit_price`, `total`, `description`, `attachments`.

---

## مواردی که در این مرحله پیاده نشده‌اند (پیشنهاد مراحل بعد)

- **خروجی PDF:** فقط خروجی CSV/Excel برای پرداخت‌ها اضافه شده؛ برای PDF می‌توان از یک پکیج مثل `barryvdh/laravel-dompdf` و یک اکشن سفارشی استفاده کرد.
- **اعلان پاپ‌آپ درخواست برداشت برای ادمین:** می‌توان با Filament Notifications یا یک ویجت در داشبورد که تعداد درخواست‌های در انتظار را نشان می‌دهد و لینک به لیست برداشت می‌دهد اضافه شود.
- **افزودن فاکتور جدید توسط ادمین:** فرم ایجاد فاکتور با آیتم‌ها، دسته/زیردسته، مبلغ، تاریخ، دریافت‌کنندگان و غیره هنوز اضافه نشده؛ فقط لیست و فیلترها پیاده شده است.
- **جریمه دیرکرد، پیامک عدم پرداخت، انتخاب پروژه پیشرفته برای فاکتور:** نیاز به منطق کسب‌وکار و احتمالاً صف job و سرویس پیامک دارد.
- **فاکتور دریافتی از تولیدکننده، وضعیت تایید/رد/نیاز به ویرایش:** نیاز به اکشن‌ها و احتمالاً رابطه با مدل تولیدکننده/پروژه دارد.
- **تراکنش جدید برای تولیدکننده، لیست تراکنش‌ها با فیلترها و دکمه‌های ویرایش/مشاهده/دانلود:** بیشتر مربوط به پنل تولیدکننده (یا API) است.
- **مالی کارفرما (نمودار، زبانه‌ها، لیست تراکنش‌ها):** معمولاً در فرانت/داشبورد کارفرما پیاده می‌شود.
- **RFP و شارژ/برداشت کیف پول، پرداخت هزینه نگهداری، کمیسیون، محاسبات دقیق دام و غیره:** نیاز به تعریف دقیق قوانین و یکپارچه‌سازی با درگاه و کیف پول است.
- **بخش واریزها (لیست واریزی‌ها با فیلترها):** می‌توان از همان لیست «گردش مالی» با فیلتر نوع «واریز» استفاده کرد یا یک ریسورس جدا برای واریزها تعریف کرد.
- **تغییر کارمزد برای کاربر، سود و هزینه نگهداری توسط ادمین:** نیاز به تنظیمات سیستمی (جدول settings یا مدل Commission) و فرم در پنل ادمین دارد.

---

## اجرای مایگریشن‌ها

```bash
php artisan migrate
```

مایگریشن‌های جدید:
- `2026_02_20_120000_add_project_and_meta_to_payments_table`
- `2026_02_20_130000_create_withdrawal_requests_table`
- `2026_02_20_140000_create_wallet_transactions_table`
- `2026_02_20_141000_create_invoices_table`

---

## نکته برای Export (پرداخت‌ها)

برای استفاده از خروجی اکسل/CSV در Filament لازم است مایگریشن‌های صف و اعلان Filament اجرا شده باشند:

```bash
php artisan make:queue-batches-table
php artisan make:notifications-table
php artisan vendor:publish --tag=filament-actions-migrations
php artisan migrate
```

اگر این مایگریشن‌ها را اجرا نکنید، دکمه Export ممکن است خطا بدهد؛ در آن صورت می‌توان موقتاً آن را از `headerActions` جدول پرداخت‌ها حذف کرد.