افزونه ارسال پست ایران برای مدوسا (Medusa Fulfillment Iran Post)

این افزونه یک Fulfillment Provider اختصاصی برای سیستم فروشگاه‌ساز Medusa v2 است که امکان محاسبه هزینه ارسال مرسولات پستی را بر اساس قوانین پست ایران (وزن، مسافت، استان همجوار و غیرهمجوار) فراهم می‌کند.

ویژگی‌ها

• پشتیبانی از روش‌های ارسال پستی ایران:
  • پست پیشتاز
  • پست عادی (سفارشی)
  • پست اکسپرس
  • پست ویژه
• محاسبه هوشمند هزینه ارسال بر اساس فاصله: (استان مبدا، استان‌های همسایه و استان‌های دور)
• تنظیم آسان استان مبدا فروشگاه

نصب

ابتدا پکیج افزونه را در پروژه اصلی مدوسای خود نصب کنید:

npm install medusa-fulfillment-iran-post
# یا
yarn add medusa-fulfillment-iran-post

پیکربندی (تنظیمات افزونه)

برای فعال‌سازی افزونه، فایل medusa-config.ts پروژه مدوسا خود را باز کرده و آن را در بخش ماژول‌های fulfillment ثبت کنید.

در بخش options حتماً ویژگی originProvince را روی نام استان مبدأ فروشگاه خود (به صورت پینگلیش) تنظیم کنید (مثل tehran, isfahan, fars, khorasan-razavi و...). در صورتی که این مقدار را وارد نکنید، به صورت پیش‌فرض اصفهان (isfahan) در نظر گرفته می‌شود.

// medusa-config.ts
import { loadEnv, defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  projectConfig: {
    // ... سایر تنظیمات شما
  },
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          {
            resolve: "medusa-fulfillment-iran-post",
            id: "iran-post",
            options: {
              // استان مبدا مرسولات فروشگاه خود را اینجا مشخص کنید
              originProvince: "tehran", 
            },
          },
        ],
      },
    },
  ],
})

نحوه استفاده در پنل ادمین

1. بعد از انجام تنظیمات بالا، پروژه را یک‌بار متوقف کرده و مجدداً راه‌اندازی کنید (npm run dev).
2. وارد پنل ادمین مدوسا شوید.
3. به مسیر Settings -> Regions بروید و منطقه (Region) مورد نظر (مثلاً ایران) را انتخاب کنید.
4. در بخش Providers، ارائه‌دهنده iran-post را فعال کنید.
5. حالا در منوی Shipping Profiles می‌توانید گزینه‌های ارسال جدیدی اضافه کنید و ارائه‌دهنده سرویس (Fulfillment Provider) آن‌ها را روی گزینه‌هایی مثل "پست پیشتاز" یا "پست عادی" که توسط این افزونه ساخته شده‌اند، تنظیم کنید. نوع محاسبه قیمت (Price Type) را روی Calculated قرار دهید تا افزونه هزینه را به شکل پویا محاسبه کند.

توسعه و تغییر الگوریتم

این پروژه با TypeScript توسعه یافته است. در صورتی که تمایل دارید الگوریتم محاسبه قیمت‌ها را بر اساس سیاست‌های جدید پست ایران تغییر دهید، می‌توانید کدهای مربوطه را در فایل‌های موجود در پوشه src/calculators شخصی‌سازی کنید.