مستنداتبخش برنامه نویسانویژگی‌های بومی ایران

🇮🇷 راهنمای جامع قابلیت‌های بومی ایران (Iran Features)

پروژه Next-Strapi-Medusa دارای پشتیبانی توکار و سطح بالا از زیرساخت‌های بومی تجارت الکترونیک ایران است. با فعال‌سازی فلگ ENABLE_IRAN_FEATURES=true، امکانات ورود با شماره موبایل و پیامک OTP، درگاه‌های بانکی شتاب/شاپرک (زرین‌پال)، محاسبه تعرفه زنده پست پیشتاز، و نمایش قیمت‌ها به تومان بدون هیچ دستکاری در هسته مدوسا فعال می‌شوند.

پشتیبانی بومی بدون تغییر در هسته Medusa

تمامی ماژول‌های ایرانی (درگاه پرداخت، پیامک OTP و پست) به صورت ماژول‌های تفکیک‌شده طبق استانداردهای Medusa v2 طراحی شده‌اند و هنگام آپدیت نسخه‌های مدوسا دچار شکست و باگ نمی‌شوند.

۱. فلگ سراسری ENABLE_IRAN_FEATURES

برای فعال‌سازی تمامی قابلیت‌های اختصاصی ایران در کل استک (بک‌اند مدوسا، پنل استراپی و استورفرانت نکست)، کافیست متغیر زیر را در فایل .env و docker-compose.yml تنظیم کنید:

.env

env

ENABLE_IRAN_FEATURES=true
NEXT_PUBLIC_ENABLE_IRAN_FEATURES=true
DEFAULT_REGION=IR
DEFAULT_LOCALE=fa-IR

۲. ورود و ثبت‌نام با پیامک و شماره موبایل (Phone Auth & OTP)

ماژول اختصاصی احراز هویت با شماره موبایل در مسیر store-admin/src/modules/auth/providers/otp پیاده‌سازی شده است. این سیستم شماره‌های ایران را به صورت استاندارد فرمت‌بندی کرده و با ایجاد کدهای موقت ۴ تا ۶ رقمی، ارسال پیامک را با استراتژی Rate Limiting ایمن انجام می‌دهد.

پشتیبانی از فرمت‌های مختلف: پذیرش خودکار 0912xxxxxxx و +98912xxxxxxx.
تایمر شمارش معکوس و Rate Limiting: جلوگیری از درخواست‌های مکرر پیامک (Cooldown ۱۲۰ ثانیه‌ای).
ثبت‌نام خودکار (Auto Register): در صورت جدید بودن شماره، حساب مشتری به صورت خودکار ساخته می‌شود.

store-admin/medusa-config.ts (بخش phone-auth)

typescript

{
  resolve: "./src/modules/auth/providers/otp",
  id: "phone-auth",
  options: {
    jwtSecret: process.env.JWT_SECRET,
  },
}

۳. سرویس‌های پیامک ایرانی (Kavenegar & SMS.ir)

سیستم ارسال پیامک از الگوهای وب‌سرویس سریع (Fast Pattern / خط خدماتی) پشتیبانی می‌کند تا پیامک تایید حتی به شماره‌های بلک‌لیست تبلیغاتی نیز در کمتر از ۵ ثانیه ارسال شود:

.env (تنظیمات پنل پیامک)

env

# نوع ارائه‌دهنده: sms-ir یا kavenegar
SMS_PROVIDER=sms-ir
SMS_API_KEY=your_sms_ir_api_key
SMS_OTP_TEMPLATE_ID=100000 # شناسه قالب کد تایید (Pattern ID)
SMS_ORDER_PLACED_TEMPLATE_ID=200000 # شناسه قالب ثبت سفارش

۴. درگاه پرداخت اینترنتی زرین‌پال (Zarinpal Gateway)

ماژول اختصاصی درگاه زرین‌پال مستقیماً به سیستم Payment Sessions مدوسا متصل است. این ماژول امکان خرید با کارت‌های بانکی عضو شتاب را فراهم ساخته و از حالت تست (Sandbox) نیز پشتیبانی می‌کند:

.env (تنظیمات زرین‌پال)

env

ZARINPAL_MERCHANT_ID=your-merchant-id-xxxx-xxxx
ZARINPAL_SANDBOX=false # در محیط توسعه true بگذارید

۵. محاسبه زنده کرایه پست ایران (Iran Post Fulfillment)

پلاگین medusa-fulfillment-iran-post در مرحله Checkout تسویه‌حساب، هزینه پست پیشتاز و سفارشی را براساس مبدأ، استان مقصد و وزن مرسوله بر اساس آخرین تعرفه پستی محاسبه می‌کند و امکان درج کد رهگیری ۲۴ رقمی پست را در پنل سفارشات دارد.

store-admin/medusa-config.ts (بخش ماژول ارسال پست)

typescript

{
  resolve: "./src/modules/fulfillment/providers/iran-post",
  id: "iran-post",
  options: {
    originProvince: "تهران",
    originCity: "تهران",
    defaultPackagingWeight: 150, // گرم
  },
}

۶. تبدیل هوشمند واحد پول به تومان (convertToToman)

در دیتابیس مدوسا مبالغ به ریال ذخیره می‌شوند (جهت سازگاری با سیستم‌های شاپرک)، اما در پنل استراپی با روشن کردن گزینه convertToToman در تنظیمات Storefront Settings، فرانت‌اند یک صفر از ارقام را برداشته و قیمت‌ها را با جداکننده هزارگان به تومان به کاربران نمایش می‌دهد.

نحوه تبدیل قیمت در فرانت‌اند (store/src/lib/util/prices.ts)

typescript

export function formatPrice(amount: number, currencyCode: string, convertToToman = false) {
  if (currencyCode.toLowerCase() === 'irr' && convertToToman) {
    const tomanAmount = Math.round(amount / 10);
    return `${new Intl.NumberFormat('fa-IR').format(tomanAmount)} تومان`;
  }
  return new Intl.NumberFormat('fa-IR', { style: 'currency', currency: currencyCode }).format(amount);
}