المستنداتدليل المطورينوصفات التخصيص السريعة (Customization Recipes)

وصفات التخصيص والحلول البرمجية الجاهزة (Recipes)

دليل عملي يحتوي على حلول مجربة لتخصيص السلات، بوابات الدفع، الشحن، والكتل لتلبية متطلبات متجرك بدقة.

1. إضافة حقول مخصصة إلى عملية إتمام الطلب (Checkout)

توسيع نموذج الطلب في Medusa وStrapi
يمكنك إضافة حقول مثل الرقم الضريبي، ملاحظات التوصيل، أو تحديد وقت الاستلام المفضل.

الخطوات الأساسية لإضافة الحقل المخصص:

  • إضافة الحقل الجديد إلى واجهة المستخدم (Checkout Form) في Next.js.
  • تحديث كائن سلة التسوق وتمرير الحقل المخصص عبر خاصية metadata في Medusa.
  • عرض البيانات المخصصة في لوحة تحكم Medusa Admin وتضمينها في فاتورة العميل.
مثال: إرسال ملاحظات التوصيل عبر واجهة برمجة Medusa
typescript
// store/src/lib/strapi-client/get-option-translations.ts
export async function getOptionTranslation(optionKey: string, locale: string = "fa") {
const res = await fetch(
`${process.env.NEXT_PUBLIC_STRAPI_URL}/api/option-translations?filters[key][$eq]=${optionKey}&locale=${locale}`,
{ headers: { Authorization: `Bearer ${process.env.STRAPI_API_TOKEN_FOR_FRONT}` } }
)
const json = await res.json()
return json.data?.[0]?.translated_name || optionKey
}

2. تخصيص نمط وتخطيط صفحة المنتج (PDP Layout)

كيفية تغيير ترتيب معرض الصور، جدول المقاسات، وتقييمات العملاء في صفحة تفاصيل المنتج.

تخصيص مكون تفاصيل المنتج
typescript
// تخصيص ترتيب مكونات صفحة المنتج في Next.js
import { ProductGallery } from '@/components/product/ProductGallery'
import { ProductDetails } from '@/components/product/ProductDetails'
إضافة تبويب المواصفات الفنية
typescript
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
import { getDailyDealsWorkflow } from "../../../workflows/daily-deals";
export async function GET(req: MedusaRequest, res: MedusaResponse) {
const { result } = await getDailyDealsWorkflow(req.scope).run();
res.json({ deals: result });
}

3. ربط بوابة دفع مخصصة جديدة (Custom Payment Processor)

خطوات بناء معالج دفع مخصص في Medusa v2 وربطه بالواجهة الأمامية بسلاسة.

نظام معالجات الدفع في Medusa 2.0
يعتمد Medusa v2 على نظام AbstractPaymentProcessor المعياري الذي يسهل إضافة أي بوابة في دقائق.

المراحل التنفيذية لإضافة بوابة دفع:

  1. إنشاء ملف المعالج CustomPaymentService.ts داخل مجلد الخدمات في Medusa.
هيكل معالج الدفع في Medusa
typescript
class CustomPaymentProcessor extends AbstractPaymentProcessorService {
static identifier = 'custom-payment'
}
  1. تنفيذ الدوال الأساسية: authorizePayment، capturePayment، و refundPayment.
تسجيل المعالج في medusa-config.js
tsx
import React from "react"
import type { CountdownBlock as CountdownBlockType } from "@lib/data/homepage"
interface CountdownBlockProps {
block: CountdownBlockType
}
export default function CountdownBlock({ block }: CountdownBlockProps) {
return (
<section className="py-16 text-center">
<h2 className="text-xl font-bold mb-4">{block.title}</h2>
<p className="text-gray-500">{block.target_date}</p>
</section>
)
}
  1. تسجيل المعالج الجديد في ملف medusa-config.js.
استدعاء جلسة الدفع من الواجهة الأمامية
tsx
import CountdownBlock from "../CountdownBlock"
// Inside BlockRenderer switch(block.__component):
case "ui.countdown-block":
BlockContent = <CountdownBlock block={block} />
break
  1. إضافة خيار الدفع إلى واجهة المستخدم في Next.js وتوجيه العميل لرابط الدفع.
التحقق من توقيع Webhook البوابة
json
{
"collectionName": "components_ui_countdown_blocks",
"info": {
"displayName": "Countdown Block",
"icon": "clock",
"description": "A countdown timer block for the homepage"
},
"options": {},
"attributes": {
"title": { "type": "string" },
"target_date": { "type": "datetime", "required": true }
}
}
تأمين معالجة المدفوعات
احرص دائماً على التحقق من توقيع الـ Webhook الوارد من بوابة الدفع باستخدام المفتاح السري المشترك.

4. إضافة رسوم شحن ديناميكية بناءً على الموقع

كيفية حساب تكلفة الشحن تلقائياً بناءً على الرمز البريدي أو المدينة المختارة من قبل العميل.