# مشخصات درس‌نامه: اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال در حالت سندباکس (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) با تدابیر امنیتی جلوگیری از تقلب پیاده شود.
- [ ] سناریوی رزرو مشاوره پورتفولیو به صورت یکپارچه با پیامک و دیتابیس ارائه گردد.