Loomix
ДокументацияРуководство РазработчикаЛокальные Платежи и Региональные Функции

🇮🇷 Руководство по региональным и локальным модулям (Iran Features)

Проект Next-Strapi-Medusa включает встроенную поддержку локальной коммерческой инфраструктуры корпоративного уровня. При установке переменной ENABLE_IRAN_FEATURES=true активируются вход по номеру телефона с SMS OTP, шлюзы онлайн-банкинга (Zarinpal), расчет тарифов доставки и конвертация цен без изменения ядра Medusa.

Нативная поддержка без вмешательства в ядро Medusa
Все региональные модули (платежные шлюзы, SMS OTP и почтовые службы) спроектированы в виде изолированных плагинов по стандартам Medusa v2, гарантируя чистые обновления платформы.

1. Глобальный флаг ENABLE_IRAN_FEATURES

Для активации региональных возможностей во всем стеке (бэкенд Medusa, Strapi CMS и витрина Next.js) задайте следующие переменные в файлах .env и docker-compose.yml:

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

2. Вход по номеру телефона и SMS OTP (Phone Auth & OTP)

Модуль телефонной аутентификации реализован в store-admin/src/modules/auth/providers/otp. Он нормализует телефонные номера, генерирует безопасные одноразовые коды и защищает от частого вызова.

  • Поддержка форматов: Автоматически принимает как 0912xxxxxxx, так и +98912xxxxxxx.
  • Таймер и ограничение запросов: Защита от повторной отправки SMS с интервалом в 120 секунд.
  • Автоматическая регистрация: Автоматическое создание учетной записи для новых подтвержденных номеров.
store-admin/medusa-config.ts (раздел phone-auth)
typescript
{
  resolve: "./src/modules/auth/providers/otp",
  id: "phone-auth",
  options: {
    jwtSecret: process.env.JWT_SECRET,
  },
}

3. SMS-шлюзы (Kavenegar & SMS.ir)

Сервис отправки SMS поддерживает шаблоны с доставкой кодов менее чем за 5 секунд:

.env (Конфигурация SMS-шлюза)
env
# Провайдер: sms-ir или kavenegar
SMS_PROVIDER=sms-ir
SMS_API_KEY=your_sms_api_key
SMS_OTP_TEMPLATE_ID=100000 # ID шаблона кода подтверждения
SMS_ORDER_PLACED_TEMPLATE_ID=200000 # ID шаблона подтверждения заказа

4. Платежный онлайн-шлюз Zarinpal

Модуль Zarinpal интегрирован в систему платежных сессий Medusa, обеспечивая безопасные банковские транзакции с поддержкой тестового режима (Sandbox):

.env (Настройки Zarinpal)
env
ZARINPAL_MERCHANT_ID=your-merchant-id-xxxx-xxxx
ZARINPAL_SANDBOX=false # Установите true для тестирования

5. Расчет стоимости доставки в реальном времени (Fulfillment)

Плагин medusa-fulfillment-iran-post рассчитывает тарифы стандартной и экспресс-доставки при оформлении заказа на основе пункта отправления, назначения и веса посылки, поддерживая 24-значные трек-номера.

store-admin/medusa-config.ts (раздел модуля доставки)
typescript
{
  resolve: "./src/modules/fulfillment/providers/iran-post",
  id: "iran-post",
  options: {
    originProvince: "تهران",
    originCity: "تهران",
    defaultPackagingWeight: 150, // گرم
  },
}

6. Интеллектуальная конвертация валюты (convertToToman)

Цены сохраняются в минимальных единицах в базе данных. В Strapi при включении опции 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);
}