119 lines
13 KiB
Markdown
119 lines
13 KiB
Markdown
# مشخصات درس‌نامه: اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال در حالت سندباکس (ZarinPal Sandbox)
|
||
- **شناسه در سیلابس:** `L10.7`
|
||
- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
|
||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||
- **زمان تقریبی مطالعه:** ۲۰ دقیقه
|
||
- **پیش‌نیازهای مستقیم:** `L10.6` (ارائه‌دهندگان احراز هویت خارجی)
|
||
|
||
---
|
||
|
||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||
- [ ] **درک کند (Understand):** چرخه استاندارد ۲ مرحله‌ای پرداخت آنلاین شاپرک (درخواست پرداخت $\rightarrow$ هدایت به درگاه $\rightarrow$ تایید نهایی تراکنش Verification) را به زبان ساده شرح دهد.
|
||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ارزش فوق‌العاده محیط شبیه‌ساز (Sandbox) زرین‌پال را در تست تراکنش‌های مالی بدون نیاز به اینماد، کارت بانکی واقعی یا ریسک کسر وجه درک کند.
|
||
- [ ] **به‌کار ببندد (Apply):** قابلیت «رزرو جلسه مشاوره تخصصی ۱ ساعته» را در پورتفولیو با وب‌سرویس زرین‌پال پیاده‌سازی کرده و وضعیت پرداخت را در دیتابیس Supabase ذخیره نماید.
|
||
- [ ] **ایجاد کند (Create):** یک روت اعتبارسنجی (Verify Route Handler) امن بسازد که در برابر حمله پرداخت جعلی (Fake Query Attack) و پرداخت تکراری مقاوم باشد.
|
||
|
||
---
|
||
|
||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||
|
||
### آنچه باید پوشش داده شود (In-Scope):
|
||
1. **لحظه بلوغ تجاری محصول: تبدیل بازدیدکننده به خریدار:**
|
||
* چرا توانایی دریافت وجه آنلاین، مهم‌ترین وجه تمایز یک پروژه جدی تجاری از یک تمرین دانشجویی است.
|
||
2. **کالبدشکافی چرخه ۲ مرحله‌ای پرداخت آنلاین در ایران (شاپرک):**
|
||
* مرحله ۱ (Payment Request): ارسال مبلغ، توضیحات، ایمیل، موبایل و آدرس بازگشت به زرین‌پال $\rightarrow$ دریافت کد رهگیری اختصاصی (`Authority`).
|
||
* مرحله ۲ (Redirect): هدایت مرورگر کاربر به صفحه امن درگاه پرداخت زرین‌پال با شناسه Authority.
|
||
* مرحله ۳ (Callback): بازگشت کاربر از بانک به آدرس سایت شما با پارامترهای `Authority` و `Status=OK/NOK`.
|
||
* مرحله ۴ (Payment Verification): ارسال مجدد Authority و مبلغ از سمت سرور به زرین‌پال برای استعلام قطعی و دریافت شماره پیگیری (`RefID`).
|
||
3. **محیط سندباکس (ZarinPal Sandbox)؛ آزمایشگاه امن توسعه‌دهندگان:**
|
||
* استفاده از مرچنت کد تستی بدون نیاز به احراز هویت بانکی، سفته، یا نماد اعتماد الکترونیکی (اینماد).
|
||
* امکان شبیه‌سازی هر دو حالت «تراکنش موفق» و «تراکنش ناموفق/انصراف کاربر».
|
||
4. **پیاده‌سازی ماژول پرداخت در پورتفولیوی شخصی:**
|
||
* فیچر: «رزرو وقت مشاوره آنلاین» در صفحه پورتفولیو.
|
||
* کاربر مشخصات و زمان را انتخاب می‌کند $\rightarrow$ دکمه «پرداخت و ثبت نهایی» را می‌زند $\rightarrow$ به درگاه منتقل می‌شود $\rightarrow$ پس از پرداخت موفق، رکورد رزرو در Supabase وضعیت `paid` می‌گیرد $\rightarrow$ پیامک و ایمیل تایید ارسال می‌شود.
|
||
5. **دستورات چندسکویی برای متغیرهای محیطی زرین‌پال:**
|
||
* تنظیم `ZARINPAL_MERCHANT_ID` و `NEXT_PUBLIC_APP_URL` در سه سیستم‌عامل.
|
||
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||
* کال‌اوت بنفش (`<details class="violet">`): مفهوم تکرارناپذیری (Idempotency) و خطر کلاهبرداری بازگشت جعلی؛ هرگز بدون متد Verify به کاربر خدمات ندهید!
|
||
* کال‌اوت سبز (`<details class="green">`): شبیه‌سازی کارت بانکی تستی در سندباکس بدون کسر حتی یک ریال از حساب شما.
|
||
* کال‌اوت قرمز (`<details class="red">`): تله اشتباه گرفتن ریال و تومان؛ درگاه‌های شاپرک مبالغ را بر حسب ریال یا تومان با دقت بالا می‌خواهند.
|
||
|
||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||
- مراحل قانونی دریافت اینماد و کد مالیاتی (در فصل ۱۲ و چک‌لیست حقوقی بررسی می‌شود).
|
||
- پرداخت‌های بین‌المللی با ارز دیجیتال یا کارت‌های اعتباری ویزا/مستر.
|
||
|
||
---
|
||
|
||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||
|
||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||
| :--- | :--- | :--- |
|
||
| Payment Gateway (IPG) | درگاه پرداخت اینترنتی | واسط نرم‌افزاری امن بانکی که امکان کسر وجه از حساب خریدار و واریز به حساب فروشنده را فراهم می‌کند |
|
||
| Merchant ID | شناسه پذیرنده | کد شناسایی ۳۶ کاراکتری یکتای شما نزد شرکت پرداخت برای تفکیک تراکنش‌های کسب‌وکار |
|
||
| Authority | شناسه تراکنش شاپرک | رشته کد ۳۶ کاراکتری که برای هر درخواست پرداخت تولید شده و مبنای پیگیری تراکنش است |
|
||
| Payment Verification | تایید نهایی پرداخت | استعلام قطعی و رمزنگاری‌شده از درگاه برای اثبات واریز واقعی پول قبل از تحویل کالا یا خدمات |
|
||
| RefID | شماره پیگیری بانکی | شماره ارجاع یکتای رسمی شبکه بانکی که روی رسید تراکنش چاپ می‌شود |
|
||
| Double Spending | پرداخت تکراری یا جعلی | تلاش خرابکارانه برای تحویل چندباره خدمات با استفاده از یک شناسه تایید شده قدیمی |
|
||
|
||
---
|
||
|
||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||
|
||
1. **تصویر کاور درس:** `images/cover.png`
|
||
* **موضوع:** کارت بانکی نئونی با آیکون تایید سبز در حال لمس درگاه پرداخت دیجیتال زرین‌پال روی لپ‌تاپ پورتفولیو.
|
||
2. **چرخه ۴ مرحله‌ای پرداخت شاپرک با زرین‌پال:** `images/zarinpal-payment-flow.png`
|
||
* **موضوع:** دیاگرام معماری: ۱) درخواست پرداخت سروری $\rightarrow$ ۲) انتقال به درگاه سندباکس $\rightarrow$ ۳) بازگشت کاربر $\rightarrow$ ۴) تایید سروری (Verify) $\rightarrow$ صدور فاکتور نهایی.
|
||
3. **صفحه شبیه‌ساز پرداخت سندباکس زرین‌پال:** `images/zarinpal-sandbox-mock-screen.png`
|
||
* **موضوع:** اسکرین‌شات از محیط سندباکس زرین‌پال با دکمه‌های «پرداخت موفق» و «انصراف از پرداخت» برای تست.
|
||
4. **رسید تراکنش موفق در پورتفولیو:** `images/payment-success-receipt-card.png`
|
||
* **موضوع:** کارت رسید مدرن در سایت با کد پیگیری RefID، مبلغ، تاریخ، و دکمه دانلود جزئیات جلسه مشاوره.
|
||
|
||
---
|
||
|
||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||
|
||
1. **تیتر اصلی:** `# اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال در حالت سندباکس (ZarinPal Sandbox)`
|
||
2. **مقدمه:** هیجان‌انگیزترین لحظه برای یک خالق محصول: وقتی اولین پیامک «حساب شما شارژ شد» از راه می‌رسد!
|
||
3. **جدول کاور درس**
|
||
4. **استعاره صندوقدار فروشگاه و دستگاه پوز:**
|
||
* شما فاکتور صادر می‌کنید، مشتری کارت می‌کشد، دستگاه بوق تایید می‌زند، و سپس شما کالا را تحویل می‌دهید.
|
||
5. **معماری پرداخت در وب مدرن ایران (پروتکل دوگانه Request و Verify):**
|
||
* چرا نمی‌توان تنها به بازگشت کاربر به آدرس سایت اعتماد کرد؟
|
||
6. **فعال‌سازی آزمایشگاه سندباکس زرین‌پال (بدون نیاز به اینماد):**
|
||
* استفاده از مرچنت تستی ۳۶ کاراکتری و آدرس اندپوینت سندباکس:
|
||
`https://sandbox.zarinpal.com/pg/v4/payment/request.json`
|
||
7. **کدنویسی ماژول پرداخت `services/payment.ts` در Next.js:**
|
||
* تابع ایجاد درخواست پرداخت (`createPaymentRequest`).
|
||
* تابع اعتبارسنجی نهایی پرداخت (`verifyPayment`).
|
||
8. **جعبه پرامپت طلایی: ساخت صفحه پرداخت و رزرو مشاوره با ایجنت:**
|
||
* پرامپت دقیق:
|
||
> «من ماژول پرداخت `services/payment.ts` را برای زرین‌پال دارم. لطفاً یک بخش جدید در صفحه پورتفولیو با عنوان "رزرو جلسه مشاوره تخصصی" اضافه کن. کاربر با انتخاب تاریخ و زدن دکمه پرداخت، به سرور اکشن متصل شود، به درگاه زرین‌پال سندباکس هدایت گردد، و پس از بازگشت به صفحه `/payment/callback`، در صورت تایید موفقیت، رسید پرداخت با شماره پیگیری RefID نمایش داده شده و وضعیت رزرو در دیتابیس به paid تغییر کند.»
|
||
9. **دستورات چندسکویی برای تنظیم متغیرهای محیطی پرداخت:**
|
||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||
- Windows (PowerShell):
|
||
```powershell
|
||
Add-Content .env.local "`nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000`nNEXT_PUBLIC_APP_URL=http://localhost:3000"
|
||
```
|
||
- macOS (Terminal):
|
||
```bash
|
||
echo -e "\nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000\nNEXT_PUBLIC_APP_URL=http://localhost:3000" >> .env.local
|
||
```
|
||
- Linux (Bash):
|
||
```bash
|
||
echo -e "\nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000\nNEXT_PUBLIC_APP_URL=http://localhost:3000" >> .env.local
|
||
```
|
||
10. **باکس نکته امنیتی Quera (`<details class="violet">`):** تله جعل پارامتر URL؛ اگر کسی آدرس را دستی به `Status=OK` تغییر دهد، تابع `verifyPayment` متوجه شده و تراکنش فاقد اعتبار تلقی می‌شود.
|
||
11. **باکس هشدار Quera (`<details class="red">`):** واحد پول! مبالغ زرین‌پال به تومان است، اما همیشه مستندات رسمی را چک کنید تا مشتری ده برابر مبلغ واقعی پرداخت نکند!
|
||
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** کلیک روی دکمه پرداخت سندباکس و مشاهده صفحه تراکنش موفق بدون نیاز به کارت واقعی.
|
||
13. **جمع‌بندی درس‌نامه:** تسلط بر دریافت پول آنلاین؛ ورود به بخش هیجان‌انگیز و پایانی فصل: تزریق هوش مصنوعی به پورتفولیو با API در درس بعدی.
|
||
|
||
---
|
||
|
||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||
- [ ] چرخه ۴ مرحله‌ای پرداخت اینترنتی شاپرک با نمودار و زبان شفاف تبیین گردد.
|
||
- [ ] نحوه اتصال به سندباکس زرین‌پال با مرچنت تستی به صورت کاربردی آموزش داده شود.
|
||
- [ ] روت تایید پرداخت (Payment Verification) با تدابیر امنیتی جلوگیری از تقلب پیاده شود.
|
||
- [ ] سناریوی رزرو مشاوره پورتفولیو به صورت یکپارچه با پیامک و دیتابیس ارائه گردد.
|