مستنداتبخش برنامه نویسانمدیریت استورفرانت و همگام‌سازی کامپوننت‌ها

مدیریت استورفرانت، همگام‌سازی Loomix و GitHub CI/CD

این پروژه مجهز به یک پنل اختصاصی Storefront Management در پنل ادمین Strapi همراه با فرایند بیلد و استقرار خودکار GitHub Actions (CI/CD) است. بدین ترتیب نیازی به ابزارهای دستی نبوده و می‌توانید استایل‌های جدید را مستقیماً از Loomix Registry دریافت کرده، در صف قرار دهید و به سادگی روی پروداکشن دیپلوی کنید.

همگام‌سازی ابری خودکار و توسعه محلی

تمامی فرایندهای همگام‌سازی کامپوننت‌های استورفرانت و دیپلوی در پروداکشن، به صورت یکپارچه از طریق داشبورد Storefront Management در پنل استراپی و فرایند بیلد و استقرار خودکار GitHub Actions مدیریت می‌شوند.

منوی Storefront Management در پنل Strapi

در داشبورد Strapi Admin به منوی Storefront Management بروید. از این بخش می‌توانید:

انتخاب کامپوننت: انتخاب از میان گروه‌های آماده (Home, Layout, Account, Cart & Checkout, Common, Pages).
تعیین استایل یا همگام‌سازی کامل: نام استایل مورد نظر (مانند style-4) را وارد کنید یا تیک Sync all styles را برای دریافت تمام پوشه کامپوننت بزنید.
دیپلوی فوری: با فعال‌سازی تیک Deploy to server immediately، بلافاصله پس از سینک، فرایند بیلد و دیپلوی تریگر می‌شود.
افزودن یا حذف استایل: روی Add / Sync Style جهت دریافت یا Remove Style جهت حذف استایل‌های بلااستفاده کلیک کنید.
ویجت وضعیت زنده استقرار (Live Status Widget): یک نشانگر هوشمند در بالای صفحه وضعیت لحظه‌ای بیلد را نمایش می‌دهد (🟡 در حال ساخت، 🟢 استقرار موفق و زنده، 🔴 ناموفق) و پس از اتمام خودکار به‌روزرسانی می‌شود.

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

bash

# دسترسی از داشبورد استراپی:
http://admin.local/admin
 
# یا فراخوانی مستقیم API:
POST /api/storefront/sync-component

صف تغییرات (Pending Updates) و بیلد دسته‌ای

برای جلوگیری از بیلد‌های مکرر و سنگین، تغییرات استایل‌ها ابتدا در فایل محلی .sync-history.json ذخیره می‌شوند:

مشاهده صف: تمامی درخواست‌های افزودن یا حذف کامپوننت‌ها را قبل از بیلد نهایی مشاهده کنید.
قابلیت Undo: امکان لغو هر تغییر به سادگی با زدن دکمه Undo قبل از شروع فرآیند بیلد.
دکمه Update Storefront: پس از اطمینان، با زدن دکمه Update Storefront تمام تغییرات به‌صورت یکجا برای GitHub Actions ارسال و بیلد پروداکشن آغاز می‌شود.

۳. فرایند بیلد و استقرار خودکار GitHub Actions (محیط پروداکشن)

در حالت پروداکشن (NODE_ENV=production)، فرایند همگام‌سازی و انتشار به شرح زیر است:

۱. فراخوانی (Dispatch): فشردن Update Storefront رویداد repository_dispatch را در گیت‌هاب تریگر می‌کند.

۲. دریافت و کامیت: ورک‌فلو deploy-storefront.yml فایل‌های کامپوننت را از رجیستری دانلود کرده و در برنچ main کامیت می‌کند.

۳. ساخت ایمیج: ورک‌فلو build-storefront.yml فراخوانی شده، ایمیج پروداکشن Next.js را ساخته و در GitHub Packages (ghcr.io) قرار می‌دهد.

۴. دیپلوی با Self-Hosted Runner: رانر سلف‌هاستد روی سرور VPS شما ایمیج جدید را Pull کرده و کانتینر را بدون قطعی ری‌استارت می‌کند.

۵. اعلان و وضعیت زنده در استراپی: هیچ نیازی به باز ماندن صفحه گیت‌هاب نیست. داشبورد Storefront Management در استراپی وضعیت بیلد را به صورت لحظه‌ای پیگیری کرده و به محض اتمام، اعلان موفقیت (🎉) و سبز شدن وضعیت را نمایش می‌دهد.

۴. معماری همگام‌سازی خودکار کامپوننت‌ها

هنگامی که در پنل استراپی دکمه Update Storefront را می‌زنید، بک‌اند استراپی یک رویداد repository_dispatch به گیت‌هاب ارسال می‌کند. پایپ‌لاین GitHub Actions در فضای ابری فایل‌ها را از رجیستری دریافت کرده، در store/src/modules/ کامیت می‌کند و از طریق Self-Hosted Runner روی سرور دیپلوی می‌نماید.

مرحله خودکار در GitHub Actions

bash

# اجرای خودکار در GitHub Actions:
node scripts/sync-loom-component.js "$ACTION" "$COMPONENT"
git add store/src/modules
git commit -m "chore(storefront): sync components from Loomix registry [skip ci]"
git push

۵. اکوسیستم رجیستری باز و ساخت رجیستری اختصاصی

موتور همگام‌سازی کامپوننت‌ها فایل‌های استایل را به صورت باز و مستقیم از ریپازیتوری گیت‌هاب دریافت می‌کند. شما در انتخاب منبع رجیستری کاملاً آزاد هستید؛ می‌توانید از رجیستری عمومی Loomix Blocks استفاده کنید یا یک رجیستری اختصاصی برای تیم خود بسازید.

گزینه‌های منبع رجیستری:

روش اول: استفاده از رجیستری عمومی Loomix Blocks (رایگان و بدون نیاز به توکن)

دسترسی آزاد، فوری و ۱۰۰٪ رایگان به تمامی استایل‌ها و به‌روزرسانی‌های جدید. نیاز به هیچ توکن گیت‌هاب یا لایسنسی نیست و همچنین هر توسعه‌دهنده‌ای می‌تواند با ارسال Pull Request استایل‌های جدیدی به آن اضافه کند.

روش دوم: ساخت ریپازیتوری رجیستری اختصاصی توسط خود برنامه‌نویس/آژانس

شما می‌توانید یک ریپازیتوری (عمومی یا خصوصی) روی گیت‌هاب خود بسازید و دیزاین سیستم و استایل‌های اختصاصی مشتریان خود را در آن مدیریت کنید.

ساختار پوشه‌بندی استاندارد رجیستری (Folder Structure):

موتور همگام‌سازی انتظار دارد ساختار فایل‌ها در ریپازیتوری رجیستری دقیقاً منطبق بر پوشه src/modules/ استورفرانت باشد:

ساختار درختی ریپازیتوری رجیستری

text

my-loomix-registry/
└── src/
    └── modules/
        ├── home/
        │   └── components/
        │       ├── FeaturesBlock/
        │       │   ├── style-1.tsx
        │       │   ├── style-2.tsx
        │       │   ├── style-3.tsx
        │       │   └── style-4.tsx
        │       ├── ProductShowcase/
        │       │   ├── style-1.tsx
        │       │   ├── style-2.tsx
        │       │   └── style-3.tsx
        │       ├── Blog/
        │       ├── CategoryCollection/
        │       └── SplitBanner/
        ├── layout/
        │   └── components/
        │       ├── Header/
        │       └── Footer/
        └── account/ | cart/ | checkout/ | common/

مراحل ساخت و اتصال رجیستری اختصاصی خودتان:

۱. ساخت ریپازیتوری در گیت‌هاب: یک ریپازیتوری جدید (عمومی یا خصوصی) با نام دلخواه (مثلاً my-agency/loomix-styles-registry) ایجاد کنید.
۲. ایجاد ساختار پوشه‌ها: پوشه ریشه src/modules/ را بسازید و زیرپوشه‌های کامپوننت‌ها را مطابق ساختار بالا نام‌گذاری نمایید.
۳. تنظیم دسترسی (در صورت خصوصی بودن): اگر ریپازیتوری را خصوصی ساختید، یک Personal Access Token (classic) با دسترسی repo در گیت‌هاب بسازید.
۴. تنظیم در .env پروژه: متغیر REGISTRY_URL را با آدرس خام گیت‌هاب خود مقداردهی کنید.

پیکربندی متغیرهای محیطی رجیستری (.env)

env

# حالت ۱: استفاده از رجیستری عمومی Loomix Blocks (پیش‌فرض و بدون توکن)
REGISTRY_URL=https://raw.githubusercontent.com/landa33/loom-blocks-registry/main/src/modules
 
# حالت ۲: استفاده از ریپازیتوری اختصاصی خودتان
# REGISTRY_URL=https://raw.githubusercontent.com/your-org/your-custom-registry/main/src/modules
# GITHUB_PAT=ghp_your_personal_access_token # (فقط در صورت خصوصی بودن)