# سیستم پرداخت و تمدید آنلاین — راهنمای نصب و استفاده

## این چیست؟

افزوده‌ای به license-server که به مشتریان اجازه می‌دهد **مستقیماً** (بدون
دخالت دستی شما) لایسنس خودشان را تمدید کنند — با زرین‌پال، PayPal، یا واریز
بانکی همراه با آپلود فیش. بعد از پرداخت موفق، لایسنس **خودکار** تمدید
می‌شود، بدون تغییر هیچ کدی در سمت مشتری.

## فایل‌های جدید

```
license-server/
├── sql/payment-migration.sql        ← جداول جدید (باید اجرا کنید)
├── renew.html                       ← صفحه‌ی عمومی که مشتری باز می‌کند
├── api/
│   ├── license-public-status.php    ← استعلام عمومی وضعیت (بدون توکن)
│   ├── plans-public.php             ← لیست پلن‌های یک محصول (عمومی)
│   └── payments/
│       ├── zarinpal.php             ← کلاس اتصال به زرین‌پال
│       ├── paypal.php               ← کلاس اتصال به PayPal
│       ├── renewal-helpers.php      ← توابع مشترک تمدید
│       ├── renew-start.php          ← شروع فرایند پرداخت
│       ├── zarinpal-callback.php    ← بازگشت از زرین‌پال
│       ├── paypal-callback.php      ← بازگشت از PayPal
│       └── upload-receipt.php       ← آپلود فیش بانکی
```

پنل `admin/index.html` هم یک تب جدید «پرداخت‌ها» گرفته: تنظیم درگاه‌ها،
مدیریت حساب‌های بانکی، و تایید/رد فیش‌های در انتظار.

## نصب

### ۱. اجرای migration جدید
محتوای `sql/payment-migration.sql` را در phpMyAdmin (تب SQL، بعد از انتخاب
همان دیتابیس قبلی) اجرا کنید.

### ۲. آپلود فایل‌های جدید
تمام فایل‌های بالا را در همان ساختار (پوشه‌ی `api/payments/` باید جدید
ساخته شود) روی هاست آپلود کنید.

### ۳. ساخت پوشه‌ی آپلود فیش با دسترسی نوشتن
```
license-server/uploads/receipts/
```
این پوشه باید مجوز نوشتن (۷۵۵ یا ۷۷۷) داشته باشد؛ کد خودش هم تلاش می‌کند
بسازدش، اما بهتر است از قبل با مجوز درست وجود داشته باشد.

### ۴. تنظیم درگاه‌ها از پنل مدیر
وارد پنل شوید → تب «پرداخت‌ها»:
- **زرین‌پال:** Merchant ID را از پنل زرین‌پال خودتان کپی کنید
- **PayPal:** Client ID و Client Secret را از [developer.paypal.com](https://developer.paypal.com) بگیرید
- هرکدام را که می‌خواهید فعال کنید، تیک «فعال» را بزنید و ذخیره کنید

### ۵. افزودن حساب‌های بانکی
در همان تب، بخش «حساب‌های بانکی» — نام بانک، شماره کارت، شبا (اختیاری)،
نام صاحب حساب را وارد و «افزودن» بزنید. می‌توانید چند حساب اضافه کنید و
هرکدام را فعال/غیرفعال کنید.

## چگونه مشتری از آن استفاده می‌کند

مشتری این آدرس را باز می‌کند:
```
https://s.mahdavifar.ir/license-server/renew.html?license_key=XXXXX-XXXXX
```
(پارامتر `license_key` اختیاری است - اگر ندهید، مشتری خودش وارد می‌کند)

مراحل: کلید لایسنس → انتخاب پلن → انتخاب روش پرداخت → پرداخت یا آپلود فیش
→ تمدید خودکار (برای زرین‌پال/PayPal) یا در انتظار تایید شما (برای واریز بانکی).

## نکات امنیتی و فنی مهم

⚠️ **PayPal و قیمت دلاری:** فعلاً کد فرض می‌کند `plans.price` همان مبلغی
است که برای PayPal هم استفاده می‌شود، که اشتباه است (چون price معمولاً
تومان است). اگر PayPal را فعال می‌کنید، باید یک ستون `price_usd` به جدول
`plans` اضافه کنید:
```sql
ALTER TABLE plans ADD COLUMN price_usd DECIMAL(10,2) DEFAULT NULL;
```
و از پنل مدیر، مقدار دلاری هر پلن را جداگانه تنظیم کنید (فعلاً این فیلد
در فرم ساخت پلن نیست - باید دستی در دیتابیس یا با ویرایش کوچک فرم اضافه شود).

⚠️ **HTTPS اجباری:** برای پرداخت آنلاین (چه زرین‌پال چه PayPal)، سایت
باید حتماً SSL فعال داشته باشد — درگاه‌ها بدون HTTPS کار نمی‌کنند.

⚠️ **کریپتو هنوز غیرفعال است:** جدول و ردیف پیش‌فرض `payment_gateways`
برایش آماده است، اما منطق واقعی هنوز نوشته نشده - وقتی سیستم پرداخت
کریپتوی خودتان آماده شد، برگردید تا وصلش کنیم.

⚠️ **امنیت فیش بانکی:** فایل‌های آپلودی در `uploads/receipts/` با نام
تصادفی (نه نام اصلی فایل) ذخیره می‌شوند، اما این پوشه از طریق وب قابل
دسترسی است (چون در همان ساختار وب‌سرور است). اگر می‌خواهید مطمئن‌تر باشید،
می‌توانید یک `.htaccess` در آن پوشه بگذارید که فقط با یک لینک مستقیم
(نه لیست پوشه) قابل مشاهده باشد - فعلاً `Options -Indexes` در پوشه‌ی
اصلی همین کار را تا حدی می‌کند.

## تست کامل قبل از استفاده‌ی واقعی

۱. یک لایسنس تستی بسازید
۲. `renew.html?license_key=...` را باز کنید
۳. با حالت Sandbox زرین‌پال (`sandbox: true` در تنظیمات) یک پرداخت تستی
   انجام دهید - زرین‌پال کارت تستی رایگان می‌دهد
۴. با حالت Sandbox PayPal هم همینطور - یک حساب تستی بسازید
   ([developer.paypal.com](https://developer.paypal.com) → Sandbox Accounts)
۵. برای واریز بانکی، یک تصویر تستی آپلود کنید و از پنل مدیر تایید کنید
۶. بعد از هرکدام، چک کنید که `expires_at` لایسنس واقعاً در دیتابیس
   به‌روزرسانی شده (از تب «لایسنس‌ها» در پنل قابل مشاهده است)

فقط بعد از تست موفق همه‌ی مسیرها، `sandbox` را در تنظیمات درگاه‌ها خاموش
کنید تا پرداخت واقعی فعال شود.