المستنداتدليل المطورينالتكامل العميق مع MedusaJS 2.0

التكامل مع محرك التجارة Medusa 2.0 والـ Workflows

محرك Medusa 2.0 هو النواة التجارية المتقدمة لمنظومة Loomix، والمسؤول عن إدارة سلة التسوق، المخزون، الطلبات، والمدفوعات المتعددة.

ملاحظة هامة حول إصدار Medusa 2.0
تعتمد المنظومة على الإصدار الحديث Medusa v2 كلياً، والذي يتميز بنظام Workflows القوي وأداء مضاعف مقارنة بالإصدارات السابقة.

1. البنية المعيارية لـ Medusa v2 والمزامنة الفورية

تتواصل واجهة Next.js مع Medusa عبر حزمة SDK الرسمية مع مصادقة بواسطة الـ Publishable API Key المولد تلقائياً أثناء التثبيت.

product-strapi.tsإدارة المنتجات، المتغيرات، خيارات الألوان والمقاسات بدقة متناهية.
review-product.tsمعالجة سلة التسوق وتطبيق أكواد الخصم الترويجية في الوقت الفعلي.
wishlist-customer.tsإدارة الشحن، العناوين، وحساب الضرائب والتوصيل بدقة.
question-product.tsتتبع حالات الطلبات وتحديث المخزون تلقائياً بعد إتمام الدفع.
store-admin/src/links/review-product.ts
typescript
import { defineLink } from "@medusajs/framework/modules-sdk"
import ProductModule from "@medusajs/medusa/product"
import ProductReviewModule from "../modules/product-review"
export default defineLink(
ProductModule.linkable.product,
ProductReviewModule.linkable.productReview
)

2. إعداد مفاتيح الاتصال في واجهة المتجر (.env)

المتغيرات البيئية الإلزامية لربط واجهة المتجر بمحرك Medusa بنجاح:

متغيرات ربط Medusa في ملف .env
bash
npm run seed
تهيئة عميل Medusa JS Client
bash
npx medusa exec ./src/scripts/seed-30-products.ts
مثال على استعلام جلب المنتجات
bash
npx medusa exec ./src/scripts/sync-meilisearch.ts
مثال على إضافة منتج إلى سلة التسوق
bash
npx medusa exec ./src/scripts/delete-all-products.ts

3. سير عمل الطلبات والـ Workflows المدمجة

src/lib/data/products.ts
typescript
import { sdk } from "@lib/config"
import { HttpTypes } from "@medusajs/types"
import { getAuthHeaders, getCacheOptions } from "./cookies"
import { getLocaleHeader } from "@lib/util/get-locale-header"
import { getRegion, retrieveRegion } from "./regions"
import { isNetworkFetchError, warnMedusaUnreachable } from "@lib/util/medusa-fetch"
export const listProducts = async ({
pageParam = 1,
queryParams,
countryCode,
regionId,
disableAuth = false,
}: {
pageParam?: number
queryParams?: HttpTypes.FindParams & HttpTypes.StoreProductListParams
countryCode?: string
regionId?: string
disableAuth?: boolean
}): Promise<{
response: { products: HttpTypes.StoreProduct[]; count: number }
nextPage: number | null
queryParams?: HttpTypes.FindParams & HttpTypes.StoreProductListParams
}> => {
if (!countryCode && !regionId) {
throw new Error("Country code or region ID is required")
}
const limit = queryParams?.limit || 12
const _pageParam = Math.max(pageParam, 1)
const offset = _pageParam === 1 ? 0 : (_pageParam - 1) * limit
let region: HttpTypes.StoreRegion | undefined | null
if (countryCode) {
region = await getRegion(countryCode, disableAuth)
} else {
region = await retrieveRegion(regionId!, disableAuth)
}
if (!region) {
return { response: { products: [], count: 0 }, nextPage: null }
}
const headers = {
...(disableAuth ? {} : await getAuthHeaders()),
...(await getLocaleHeader(disableAuth)),
} as Record<string, string>
const next = {
...(disableAuth
? { tags: ["store-products"] }
: await getCacheOptions("store-products")),
revalidate: 3600,
}
try {
return await sdk.client
.fetch<{ products: HttpTypes.StoreProduct[]; count: number }>(
`/store/products`,
{
method: "GET",
query: {
limit,
offset,
region_id: region?.id,
fields:
"*variants.calculated_price,+variants.inventory_quantity,*variants.images,*options,*options.values,*variants.options,+metadata,+tags",
...queryParams,
},
headers,
next,
cache: "force-cache",
}
)
.then(({ products, count }) => {
const nextPage = count > offset + limit ? pageParam + 1 : null
return {
response: { products, count },
nextPage,
queryParams,
}
})
} catch (error) {
if (isNetworkFetchError(error)) {
warnMedusaUnreachable("listProducts")
return {
response: { products: [], count: 0 },
nextPage: null,
queryParams,
}
}
throw error
}
}

4. نصائح إدارة المنتجات والتخزين المؤقت للأسعار

يتم تخزين بيانات الكتالوج مؤقتاً في Next.js مع وسوم كاش محددة (مثل medusa-products) يعاد تحديثها تلقائياً عند تغيير الأسعار في لوحة التحكم.

إعادة التحقق من كاش منتجات Medusa
env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM_ADDRESS=noreply@yourdomain.com
CONTACT_FORM_RECIPIENT=info@yourdomain.com
SENDPULSE_API_ID=your_sendpulse_id
SENDPULSE_API_SECRET=your_sendpulse_secret