مستنداتبخش برنامه نویسانماژول‌های اختصاصی، رویدادها و لایه پروکسی (proxy.ts)

ماژول‌ها، رویدادهای چرخه سفارشات و پروکسی روتینگ (proxy.ts)

علاوه بر قابلیت‌های استاندارد e-commerce، این سورس‌کد دارای ماژول‌های اختصاصی نظرات، پرسش و پاسخ، لیست علاقه‌مندی‌ها، ارسال پستی، شنوندگان رویدادهای چرخه سفارشات و لایه پروکسی درخواست‌ها (proxy.ts) در Next.js 16 است.

۱. ماژول نظرات و امتیازدهی محصولات (Product Reviews)

این ماژول در مسیر store-admin/src/modules/product-review/ پیاده‌سازی شده و امکان ثبت امتیاز (۱ تا ۵ ستاره)، دیدگاه و واکنش به نظرات (Like/Dislike) را فراهم می‌کند.

فراخوانی ثبت نظر از فرانت‌اند

typescript

const res = await fetch("/api/store/reviews", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    product_id: "prod_123",
    rating: 5,
    title: "کیفیت فوق‌العاده",
    comment: "پارچه بسیار باکیفیت و دوخت تمیز.",
  }),
});

۲. ماژول پرسش و پاسخ (Product Questions & Answers)

ماژول product-question به کاربران اجازه می‌دهد پیش از خرید درباره محصول سوال بپرسند. پاسخ‌ها توسط ادمین از پنل یا سایر کاربران ثبت می‌شوند.

۳. ماژول لیست علاقه‌مندی‌ها (Wishlist System)

ماژول wishlist به مشتریان لاگین‌شده اجازه می‌دهد محصولات محبوب خود را ذخیره کرده و در پروفایل شخصی مدیریت کنند.

۴. پلاگین ارسال پست ایران (Iran Post Shipping Plugin)

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

۵. همگام‌سازی دوطرفه محصولات با Strapi (2-Way Product Sync)

با استفاده از Medusa Workflows (مانند create-product-in-strapi و update-product-in-strapi)، هرگونه تغییر در محصولات مدوسا به دیتابیس Strapi منتقل شده و متقابلاً با ارسال Webhook از Strapi، اطلاعات در هر دو دیتابیس سینک باقی می‌مانند.

۶. چرخه زندگی سفارشات و رویدادها (Subscribers & Order Lifecycle)

در پوشه store-admin/src/subscribers/ شنوندگان رویدادهای تمام مراحل سفارش تعبیه شده‌اند:

order-placed.ts: ارسال پیامک و ایمیل تأیید سفارش به خریدار بلافاصله پس از پرداخت.
order-shipment-created.ts: ارسال کد رهگیری پستی به شماره همراه مشتری.
return-requested.ts و return-received.ts: مدیریت مرجوعی کالا.
order-canceled.ts و refund-created.ts: لغو سفارش و عودت وجه.

۷. لایه پروکسی درخواست‌ها و نگاشت خودکار منطقه و ارز (`proxy.ts`)

در **Next.js 16** معماری سنتی میدل‌ور جای خود را به فایل مدرن store/src/proxy.ts با تابع proxy(request) داده است. این پروکسی در ورودی درخواست‌ها، کد کشور کاربر را از مسیر URL یا هدر آی‌پی استخراج کرده، منطقه (Region) و واحد پولی متناظر در Medusa را تشخیص داده و کوکی‌های سشن و کش را به‌طور خودکار تنظیم و هدایت می‌کند.