feat: add chapter 10-external-services specs

2026-09-05 22:26:08 +08:00
parent 5b26a487c1
commit 8059df0781
8 changed files with 900 additions and 0 deletions
--- a/chapters/10-external-services/06-lesson-payment-gateway-zarinpal-sandbox/spec.md
+++ b/chapters/10-external-services/06-lesson-payment-gateway-zarinpal-sandbox/spec.md
@@ -0,0 +1,118 @@
+# مشخصات درس‌نامه: اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال در حالت سندباکس (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) با تدابیر امنیتی جلوگیری از تقلب پیاده شود.
+- [ ] سناریوی رزرو مشاوره پورتفولیو به صورت یکپارچه با پیامک و دیتابیس ارائه گردد.