97 lines
11 KiB
Markdown
97 lines
11 KiB
Markdown
# مشخصات درس‌نامه: سرویس Third-Party چیست و چرا نباید چرخ را از نو بسازیم؟
|
||
- **شناسه در سیلابس:** `L10.2`
|
||
- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
|
||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
|
||
- **پیش‌نیازهای مستقیم:** `L10.1` (اهداف فصل دهم)
|
||
|
||
---
|
||
|
||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||
- [ ] **درک کند (Understand):** مفهوم سرویس‌های شخص ثالث (Third-Party Services) و فلسفه استفاده از قطعات آماده نرم‌افزاری (Lego-Bricks Architecture) را در توسعه پرسرعت محصول شرح دهد.
|
||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** دوراهی ساختن در برابر خریدن/استفاده از سرویس آماده (Build vs Buy) را از منظر هزینه مالی، زمان عرضه به بازار (Time to Market) و الزامات قانونی مقایسه کند.
|
||
- [ ] **درک کند (Understand):** چرا درخواست به سرویس‌های حساس شخص ثالث (پیامک، پرداخت، مدل‌های زبانی) حتماً باید از طریق سرور (Next.js Server Actions / Route Handlers) انجام شود تا کلیدهای محرمانه فاش نشوند.
|
||
- [ ] **به‌کار ببندد (Apply):** معماری کلی ارتباط پروژه پورتفولیو با سرویس‌های ارتباطی، مالی و هوش مصنوعی را روی نمودار جریان سیستم رسم و پیاده نماید.
|
||
|
||
---
|
||
|
||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||
|
||
### آنچه باید پوشش داده شود (In-Scope):
|
||
1. **استعاره کارخانه لگو در برابر ساخت پلاستیک از نفت خام:**
|
||
* توسعه‌دهنده مدرن کارخانه‌دار نیست؛ یک معمار زبردست است که قطعات باکیفیت و تخصصی را کنار هم می‌چیند.
|
||
2. **کالبدشکافی دوراهی استراتژیک ساخت یا خرید (Build vs Buy):**
|
||
* برای ارسال پیامک: بستن قرارداد با اپراتورها، راه‌اندازی دکل، مجوزهای مخابراتی (چند ماه و صدها میلیون تومان) در برابر ثبت‌نام ۲ دقیقه‌ای در کاوه‌نگار یا SMS.ir.
|
||
* برای پرداخت: راه‌اندازی سرور اختصاصی، دریافت نماد اعتماد و پروتکل‌های شاپرک در برابر اتصال سندباکس زرین‌پال در چند خط کد.
|
||
3. **دسته‌بندی اصلی سرویس‌های ابری در دنیای وب مدرن:**
|
||
* سرویس‌های ارتباطی و نوتیفیکیشن (Communication: SMS & Email).
|
||
* سرویس‌های مالی و درگاه‌های پرداخت (Fintech: Payment Gateways).
|
||
* سرویس‌های هویتی و دسترسی (Identity & OAuth: Google, GitHub).
|
||
* سرویس‌های ابری داده و فایل (BaaS: Supabase Database & Storage).
|
||
* سرویس‌های هوش مصنوعی زاینده (AI Model APIs: OpenAI, OpenRouter, AvalAI).
|
||
4. **جریان فنی تبادل داده با سرویس‌های بیرونی:**
|
||
* مرورگر کاربر دکمه را می‌زند $\rightarrow$ درخواست امن به سرور پروژه شما می‌رسد $\rightarrow$ سرور شما کلید اختصاصی را الصاق کرده و به سرور سرویس ثالث می‌فرستد $\rightarrow$ پاسخ JSON دریافت و وضعیت کاربر آپدیت می‌شود.
|
||
5. **معماری امنیت: سرور امن در برابر مرورگر ناامن:**
|
||
* چرا نباید کلیدهای پرداخت یا پیامک مستقیماً در کدهای کلاینت جاوااسکریپت قرار گیرند.
|
||
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||
* کال‌اوت بنفش (`<details class="violet">`): مفهوم وب‌هوک (Webhook)؛ وقتی سرویس خارجی به سرور شما اطلاع‌رسانی معکوس می‌کند.
|
||
* کال‌اوت سبز (`<details class="green">`): محیط‌های رایگان و اعتبارهای هدیه آغازین سرویس‌های بومی و بین‌المللی برای تست.
|
||
* کال‌اوت قرمز (`<details class="red">`): وابستگی انحصاری (Vendor Lock-in) و اهمیت جداسازی کد از سرویس با لایه واسط (Adapter Pattern).
|
||
|
||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||
- نوشتن کدهای تفصیلی ارسال پیامک یا پرداخت (درس‌های ۱۰.۴ و ۱۰.۷).
|
||
- معماری مایکروسرویس‌های توزیع‌شده سازمانی (فصل ۱۶).
|
||
|
||
---
|
||
|
||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||
|
||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||
| :--- | :--- | :--- |
|
||
| Third-Party Integration | یکپارچه‌سازی با سرویس ثالث | اتصال و هماهنگ‌سازی نرم‌افزار با یک پلتفرم خارجی از طریق پروتکل‌های استاندارد وب |
|
||
| Build vs Buy | دوراهی ساخت یا خرید | تصمیم استراتژیک مهندسی درباره توسعه داخلی یک ماژول یا استفاده از سرویس‌های آماده موجود |
|
||
| Webhook | وب‌هوک / قلاب وب | سازوکار اعلان خودکار از طرف سرویس خارجی به آدرس سرور شما هنگام رخ دادن یک رویداد |
|
||
| Adapter Pattern | الگوی آداپتور یا لایه واسط | شیوه طراحی کد به نحوی که تعویض یک سرویس‌دهنده (مثلاً کاوه‌نگار با SMS.ir) به کمترین تغییر در کل پروژه منجر شود |
|
||
| Server-Side Proxy | پروکسی سمت سرور | ارسال درخواست‌ها از طریق سرور خودی به منظور مخفی‌سازی کلیدهای اختصاصی از دید کاربران |
|
||
|
||
---
|
||
|
||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||
|
||
1. **تصویر کاور درس:** `images/cover.png`
|
||
* **موضوع:** تقابل ساخت دستی یک قطعه مکانیکی پیچیده و پرزحمت با استفاده از قطعات لگوی دیجیتال مدرن و براق.
|
||
2. **دیاگرام معماری پورتفولیو و قطعات متصل:** `images/portfolio-integrations-architecture.png`
|
||
* **موضوع:** معماری سیستم پورتفولیو در مرکز با فلش‌های متصل به کاوه‌نگار (پیامک)، لیارا (ایمیل)، زرین‌پال (پرداخت)، سوپابیس (دیتابیس/Auth) و OpenRouter (هوش مصنوعی).
|
||
3. **تفاوت درخواست امن سروری با درخواست ناامن کلاینتی:** `images/secure-server-vs-client-flow.png`
|
||
* **موضوع:** اینفوگرافیک مقایسه‌ای: مسیر قرمز (مرورگر کلید را مستقیماً می‌فرستد و هک می‌شود) در برابر مسیر سبز (مرورگر به Next.js Server Action پیام می‌دهد و سرور کلید را محرمانه ارسال می‌کند).
|
||
|
||
---
|
||
|
||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||
|
||
1. **تیتر اصلی:** `# سرویس Third-Party چیست و چرا نباید چرخ را از نو بسازیم؟`
|
||
2. **مقدمه:** اگر برای سفر با هواپیما مجبور بودید خودتان کارخانه هواپیماسازی راه بیندازید، هیچ‌کس هرگز مسافرت نمی‌رفت!
|
||
3. **جدول کاور درس**
|
||
4. **استعاره جعبه ابزار و قطعات پیش‌ساخته در مهندسی:**
|
||
* چرا ارزش شما در اتصال هوشمندانه قطعات برای حل مسئله کاربر است، نه در بازنویسی پروتکل‌های مخابراتی و بانکی.
|
||
5. **جدول مقایسه‌ای Build vs Buy در ۵ بُعد کلیدی:**
|
||
* مقایسه هزینه، زمان تا راه‌اندازی، امنیت، نگهداری و مقیاس‌پذیری.
|
||
6. **نقشه اکوسیستم سرویس‌های شخص ثالث در پورتفولیوی شخصی:**
|
||
* نقش پیامک، ایمیل، درگاه پرداخت و هوش مصنوعی در ساخت یک تجربه کاربری فوق‌العاده.
|
||
7. **باکس نکته Quera (`<details class="violet">`):** وب‌هوک‌ها چگونه کار می‌کنند؟ تفاوت این که ما مدام استعلام بگیریم (Polling) یا اینکه سرویس خودش زنگ بزند (Webhook).
|
||
8. **اصل ایمنی حیاتی: کلیدهای محرمانه هرگز به مرورگر کاربر نمی‌روند!**
|
||
* توضیح ساده نحوه میانجی‌گری Next.js Server Actions برای محافظت از سرمایه و اعتبار شما.
|
||
9. **باکس هشدار Quera (`<details class="red">`):** خطر قفل شدن به یک شرکت خاص (Vendor Lock-in) و توصیه به تمیز نوشتن کد با توابع واسط.
|
||
10. **باکس انرژی‌بخش Quera (`<details class="green">`):** خوشبختانه تقریباً تمام سرویس‌های مدرن دارای پنل‌های آزمایشی و سهمیه تست رایگان هستند.
|
||
11. **جمع‌بندی درس‌نامه:** تسلط مفهومی بر سرویس‌های شخص ثالث و ورود به دنیای خواندن مستندات فنی API و مدیریت امن متغیرها در درس بعدی.
|
||
|
||
---
|
||
|
||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||
- [ ] استعاره قطعات لگو و دوراهی Build vs Buy به صورت شفاف و قانع‌کننده تحلیل شود.
|
||
- [ ] پنج دسته اصلی سرویس‌های ابری با مثال‌های متناسب با نیاز ایران معرفی گردند.
|
||
- [ ] چرخه درخواست امن سمت سرور برای حفظ کلیدهای اختصاصی به صورت گرافیکی و متنی تبیین شود.
|
||
- [ ] مفهوم وب‌هوک (Webhook) به زبان ساده آموزش داده شود.
|