vibe-coding-college-specs/chapters/10-external-services/03-lesson-sms-integration-kavenegar-smsir/spec.md

مشخصات درس‌نامه: اتصال وب‌سرویس پیامک بومی (کاوه‌نگار و SMS.ir) و ارسال الگوهای خدماتی

• شناسه در سیلابس: L10.4
• فصل: فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۱۸ دقیقه
• پیش‌نیازهای مستقیم: L10.3 (رمزگشایی از مستندات API و مدیریت کلیدها)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): تفاوت خطوط عادی تبلیغاتی با خطوط خدماتی بر پایه الگو (Verify Lookup / Pattern-based SMS) را در اپراتورهای مخابراتی ایران بشناسد و علت عبور از بلک‌لیست را درک کند.
• تحلیل/ارزیابی کند (Evaluate): معماری وب‌سرویس دو ارائه‌دهنده بومی برجسته (کاوه‌نگار و SMS.ir) را مقایسه کرده و مدل ارسال پیامک نوتیفیکیشن در وب را ارزیابی نماید.
• به‌کار ببندد (Apply): یک Next.js Server Action برای فرم تماس پورتفولیو بسازد که به محض ثبت پیام توسط کارفرما، یک پیامک هشدار فوری به شماره موبایل صاحب پورتفولیو و یک پیامک تأیید به کارفرما ارسال کند.
• ایجاد کند (Create): یک حالت شبیه‌ساز لوکال (Mock Mode) برای مواقعی که دانشجو اعتبار مالی یا کلید وب‌سرویس ندارد پیاده کند تا بدون هزینه بتواند رفتار ارسال پیامک را در ترمینال تست نماید.

---

۲. محدوده و مرزهای محتوا (Scope & Boundaries)

آنچه باید پوشش داده شود (In-Scope):

1. داستان واقعی پیامک در ایران: چالش بلک‌لیست مخابرات (لیست سیاه تبلیغات):
   • چرا پیامک‌های عادی روی گوشی بیش از ۶۰٪ کاربران به دلیل مسدودسازی تبلیغات نمی‌رسد؟
   • راهکار نجات: ارسال بر اساس الگو (Pattern/Template) از طریق خطوط خدماتی اشتراکی ارائه‌دهندگان معتبر.
2. بررسی وب‌سرویس‌های کاوه‌نگار (Kavenegar) و SMS.ir:
   • ثبت نام در پنل، دریافت API Key و تعریف الگوی پیامکی با متغیرها (مثلاً: نام %token% پیام شما دریافت شد).
   • ساختار اندپوینت ارسال اعتبارسنجی (Verify Lookup).
3. پیاده‌سازی ماژول ارسال پیامک در پورتفولیوی شخصی:
   • سناریوی کاربردی: کارفرما در فرم «تماس با من» نام و شماره خود را وارد می‌کند.
   • سرور اکشن Next.js داده را می‌گیرد \rightarrow در Supabase ذخیره می‌کند \rightarrow تابع ارسال پیامک کاوه‌نگار را فراخوانی می‌کند \rightarrow صاحب سایت در جیب خود لرزش گوشی و صدای نوتیفیکیشن پیامک را احساس می‌کند!
4. طراحی حالت شبیه‌ساز تستی (Dev Mock Logger):
   • اگر کلید پیامک تعریف نشده باشد، متن پیامک به صورت یک کادر زیبا در ترمینال چاپ شود تا توسعه و تست متوقف نشود.
5. جعبه پرامپت طلایی برای ایجنت:
   • پرامپت ساخت ماژول پیامک با تایپ‌های مشخص و مدیریت ارورهای قطعی اینترنت.
6. دستورات چندسکویی برای نصب پکیج‌ها یا استفاده از Fetch استاندارد:
   • استفاده از fetch داخلی Node.js یا پکیج‌های رسمی در ویندوز، مک و لینوکس.
7. کال‌اوت‌های آموزشی و هشدار کوئرا:
   • کال‌اوت بنفش (<details class="violet">): قانون سازمان تنظیم مقررات درباره محتوای پیامک‌های خدماتی و ممنوعیت ارسال متون تبلیغاتی با خطوط خدماتی.
   • کال‌اوت سبز (<details class="green">): شارژ هدیه رایگان ثبت نام در کاوه‌نگار برای تست‌های اولیه دانشجویان.
   • کال‌اوت قرمز (<details class="red">): خطر حملات پیامکی (SMS Flooding) و لزوم قرار دادن اعتبارسنجی اولیه روی فرم‌ها.

آنچه نباید وارد آن شویم (Out-of-Scope):

• احراز هویت پیامکی کامل و مدیریت سشن‌های OTP (در درس ۱۰.۶ بررسی می‌شود).
• تنظیمات پیچیده وب‌هوک وضعیت دلیوری (Delivery Report) پیامک.

---

۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Pattern-based SMS	پیامک بر اساس الگو	ارسال پیام با متن پیش‌تأییدشده از طریق خط خدماتی که حتی به شماره‌های مسدود تبلیغات تحویل داده می‌شود
Blacklist / DND	لیست سیاه تبلیغات	فهرست مشترکان تلفن همراه که دریافت هرگونه پیامک تجاری و تبلیغاتی را لغو کرده‌اند
Service Line	خط خدماتی	سرشماره‌های پیامکی مورد تایید مراجع قانونی برای ارسال اطلاع‌رسانی‌ها و کدهای فوری اعتبارسنجی
Verify Lookup	سرویس اعتبارسنجی سریع	وب‌سرویس بهینه‌شده شرکت‌های پیامکی که پیامک‌ها را با اولویت بالا و در کمتر از ۵ ثانیه ارسال می‌کند
Mock Mode	حالت شبیه‌ساز تستی	اجرای آزمایشی فرآیند بدون ارسال درخواست واقعی به سرور برای صرفه‌جویی در هزینه و تسهیل تست
SMS Flooding	بمباران پیامکی	ارسال حجم بالایی از پیامک‌های ناخواسته توسط ربات‌ها که موجب هدررفت اعتبار حساب می‌شود

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: گوشی موبایل در حال دریافت یک پیامک تایید شیک با لوگوی نوتیفیکیشن در کنار دکمه ارسال فرم پورتفولیو.
2. تفاوت خط تبلیغاتی و خط خدماتی الگومحور: images/service-vs-advertising-sms.png
   • موضوع: اینفوگرافیک مقایسه‌ای: خط تبلیغاتی به دیوار سد بلک‌لیست برخورد می‌کند؛ خط خدماتی الگومحور از گیت عبور کرده و به مقصد می‌رسد.
3. معماری ارسال پیامک فرم تماس در پورتفولیو: images/contact-form-sms-flow.png
   • موضوع: فلوچارت جریان: فرم تماس \rightarrow Server Action \rightarrow API کاوه‌نگار \rightarrow پیامک به صاحب سایت و کارفرما.
4. خروجی حالت شبیه‌ساز در ترمینال: images/sms-terminal-mock-output.png
   • موضوع: نمایش کادر شبیه‌سازی شده متن پیامک در ترمینال مشکی ادیتور با متغیرهای نام، شماره و متن درخواست.

---

۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)

1. تیتر اصلی: # اتصال وب‌سرویس پیامک بومی (کاوه‌نگار و SMS.ir) و ارسال الگوهای خدماتی
2. مقدمه: چرا وقتی کارفرما روی دکمه «ارسال درخواست» در پورتفولیو کلیک می‌کند، صدای پیامک روی گوشی شما باید به صدا درآید؟
3. جدول کاور درس
4. چالش بزرگ بلک‌لیست مخابرات در ایران و نسخه شفابخش «ارسال با پترن»:
   • تفاوت خطوط تبلیغاتی با خطوط خدماتی اشتراکی؛ چرا نباید از ارسال متنی ساده استفاده کنیم؟
5. گام اول: ساخت حساب در کاوه‌نگار / SMS.ir و دریافت کلید API:
   • ثبت رایگان، دریافت کلید تست، و ثبت یک الگوی ساده اعتبارسنجی در پنل.
6. معماری ارسال ایمن سمت سرور با Next.js Server Actions:
   • ساخت فایل services/sms.ts برای تفکیک منطق ارسال پیامک از صفحات کاربری.
7. کد ماژول ارسال پیامک با قابلیت خودکار شبیه‌ساز (Mock Fallback):
   • اگر کلید KAVENEGAR_API_KEY وجود نداشت، پیام را در کنسول چاپ کن؛ اگر بود، درخواست fetch واقعی بفرست.
8. جعبه پرامپت طلایی: ساخت فرم تماس مجهز به نوتیفیکیشن پیامکی با ایجنت:
   • پرامپت دقیق:

     «من یک فایل services/sms.ts برای ارسال پیامک پترن با وب‌سرویس کاوه‌نگار دارم. لطفاً فرم تماس در صفحه اصلی پورتفولیو را به یک Server Action متصل کن که پس از ثبت پیام در دیتابیس، با متغیرهای نام کارفرما و متن کوتاه، تابع ارسال پیامک را فراخوانی کند و وضعیت ارسال موفق را با انیمیشن سبز به کاربر نشان دهد.»

9. دستورات چندسکویی برای تعریف متغیرهای محیطی پیامک:
   • افزودن KAVENEGAR_API_KEY در منوی کشویی سه‌گانه ویندوز، مک و لینوکس:
     • Windows (PowerShell):

       Add-Content .env.local "`nKAVENEGAR_API_KEY=your_api_key_here"
       

     • macOS (Terminal):

       echo "KAVENEGAR_API_KEY=your_api_key_here" >> .env.local
       

     • Linux (Bash):

       echo "KAVENEGAR_API_KEY=your_api_key_here" >> .env.local
       

10. باکس نکته Quera (<details class="violet">): قوانین متغیرها در پترن‌های کاوه‌نگار (توکن‌های عددی و حروفی بدون فاصله) و اهمیت تایید سریع الگو در پنل.
11. باکس هشدار Quera (<details class="red">): هرگز اندپوینت پیامک را بدون اعتبارسنجی شماره (بررسی فرمت ۰۹xxxxxxxx) رها نکنید؛ خطر سوءاستفاده ربات‌ها.
12. باکس انرژی‌بخش Quera (<details class="green">): احساس فوق‌العاده دیدن اولین پیامک واقعی ارسالی از سایتی که خودتان ساخته‌اید روی گوشی موبایلتان.
13. جمع‌بندی درس‌نامه: تکمیل زنجیره پیامک بومی؛ ورود به دنیای ایمیل‌های تراکنشی و ارسال ایمیل با ایمیل‌سرور لیارا در درس بعدی.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• پدیده بلک‌لیست مخابرات ایران و لزوم ارسال پیامک‌های پترن‌محور تشریح شده باشد.
• ادغام وب‌سرویس‌های بومی (کاوه‌نگار / SMS.ir) با کدهای تمیز سمت سرور پیاده شود.
• مکانیزم شبیه‌ساز محلی (Mock Mode) برای تست بدون نیاز به شارژ حساب ارائه گردد.
• دستورات ترمینالی چندسکویی برای پیکربندی کلیدها در تب‌های اختصاصی گنجانده شود.