تنظیمات بایروز (Buyruz Settings)

هشدار: پیش از هر تغییر، حتماً فایل CONTRIBUTING.md را با دقت کامل بخوانید و بی‌قید و شرط اجرا کنید و پس از اتمام کار تطابق را دوباره چک کنید؛ این جمله باید در تمام فایل‌ها (جدید و موجود) بدون استثنا افزوده و حفظ شود.

پنل «تنظیمات بایروز» مرکز کنترل برای همه‌ی قابلیت‌ها و تنظیمات اختصاصی بایروز است. از اینجا می‌توانید رفتار افزونه‌های بایروز را به شکل یکپارچه با نیازهای سایت هماهنگ کنید.

بدست: کُدروز
خانهٔ افزونه: https://github.com/Codruz/buyruz-plugin.git نسخه: 5.42.1

محتوا

• معرفی
• ویژگی‌ها
• پیش‌نیازها
• نصب
• نحوهٔ استفاده
• تنظیمات افزونه
• توسعه و مشارکت
• مانیفست بسته‌بندی و ساخت فایل ZIP
• به‌روزرسانی دستی
• پشتیبانی
• لایسنس
• یادداشت‌های انتشار

معرفی

تنظیمات بایروز (Buyruz Settings) یک هاب مرکزی برای مدیریت همهٔ ماژول‌ها و قابلیت‌های بایروز است. طراحی آن ماژولار است تا هر قابلیت (مثلاً FAQ یا ادغام‌های آینده) بتواند جداگانه اضافه یا حذف شود و پنل همچنان ساده و سریع باقی بماند.

ویژگی‌ها

• دسترسی سریع از منوی «تنظیمات بایروز» که درست زیر «پیشخوان» در سایدبار مدیریت قرار دارد
• رابط تنظیمات مدرن با کارت‌های بخش‌بندی شده و قابل توسعه برای ماژول‌های آینده
• معرفی کوتاه و کاربرمحور در لیست افزونه‌ها تا مدیر سایت بداند این پنل چه کار می‌کند
• بارگذاری شرطی CSS/JS بر اساس حضور FAQ یا سلکتور سفارشی برای کاهش حجم صفحه
• تب «جدول مقایسه» در ویرایش محصول با امکان افزودن/حذف سطر و ستون، ذخیرهٔ لحظه‌ای در متای محصول و پیش‌نمایش زنده بدون نیاز به نوشتن HTML
• ادغام اختیاری با Rank Math FAQ (در صورت فعال بودن ماژول و افزونه Rank Math)
• پشتیبانی کامل از لایه‌های RTL و موبایل با انیمیشن نرم و طراحی تمیز
• امکان تعیین رنگ برند، فعال یا غیرفعال کردن استایل، جاوااسکریپت، انیمیشن و حالت فشردهٔ موبایل
• حالت فقط یک سؤال باز (Single Open) برای تجربهٔ کاربری بهتر
• تشخیص FAQ به صورت خودکار از طریق بلوک‌های rank-math/faq-block, شورت‌کد rank_math_faq یا کلاس rank-math-faq
• تزریق دادهٔ سازگار با Rank Math بدون تغییر در محتوا یا ساختار HTML اصلی (تنها زمانی که Rank Math فعال است)

پیش‌نیازها

• WordPress 6.8.3 یا جدیدتر
• PHP 8.1 یا بالاتر
• Rank Math SEO تنها زمانی نیاز است که ماژول ادغام Rank Math فعال و مورد استفاده باشد.
• دسترسی مدیر (manage_options) برای پیکربندی

نصب

1. مخزن را کلون کنید یا آخرین نسخه را دانلود کرده و در پوشهٔ wp-content/plugins/buyruz-plugin قرار دهید.
2. از مدیریت وردپرس به مسیر افزونه‌ها → افزودن → بارگذاری افزونه بروید و فایل فشرده را آپلود کنید یا پوشه را به صورت دستی در سرور کپی کنید.
3. افزونه را فعال کنید.

نحوهٔ استفاده

1. در صفحات یا نوشته‌ها به کمک Rank Math یک FAQ Block یا شورت‌کد rank_math_faq ایجاد کنید.
2. به مسیر پیشخوان → تنظیمات بایروز بروید و گزینه‌های مورد نیاز را پیکربندی کنید.
3. در صورت نیاز به نمایش در صفحات خاص، حالت بارگذاری را روی «سلکتور سفارشی» گذاشته و کلاس یا شناسهٔ دلخواه را وارد کنید.

تنظیمات افزونه

گزینه	توضیح
فعال‌سازی CSS	بارگذاری استایل پیش‌فرض. در صورت غیرفعال بودن هیچ CSSی افزوده نمی‌شود.
درون‌خطی کردن CSS	استایل‌ها به صورت inline تزریق می‌شوند تا نیاز به فایل مجزا نباشد.
رنگ برند	تعیین رنگ حباب آیکون‌ها و المان‌های اصلی (#1a73e8 به صورت پیش‌فرض).
فعال‌سازی JS	بارگذاری اسکریپت آکاردئون. با غیرفعال کردن، FAQها به صورت باز/بستهٔ اولیه باقی می‌مانند.
فقط یک مورد باز	همواره فقط یک سؤال باز می‌ماند و بقیه بسته می‌شوند.
انیمیشن نرم	فعال یا غیرفعال کردن انیمیشن باز و بسته شدن.
نسخهٔ موبایل فشرده	اصلاح فاصله‌ها و اندازه‌ها برای نمایش بهتر در موبایل.
حالت بارگذاری	یکی از حالت‌های «خودکار»، «همهٔ صفحات» یا «سلکتور سفارشی».
سلکتور سفارشی	وقتی حالت بالا روی «سلکتور» است، افزونه تنها در صورت وجود این سلکتور فعال می‌شود.
فعال‌سازی دیباگ	هنگام فعال بودن، رخدادهای انتخاب‌شده به صورت لاگ در پوشهٔ افزونه ذخیره می‌شوند.
بخش‌های قابل لاگ	در صورت نیاز می‌توان بخش‌های آینده را برای لاگ‌گیری انتخاب کرد.
ماسک داده‌های حساس	در صورت فعال بودن، مقادیری مثل توکن یا هدرهای Authorization در لاگ‌ها با [masked] نمایش داده می‌شوند.
مدت نگهداری لاگ	تعیین می‌کند فایل‌های لاگ چند روز روی سرور باقی بمانند (پیش‌فرض ۷ روز، قابل تنظیم بین ۱ تا ۳۰ روز).

توسعه و مشارکت

• توسعه‌ی فعلی توسط تیم کُدروز انجام می‌شود.
• پیش از هر تغییری حتماً فایل CONTRIBUTING.md را مطالعه و چک‌لیست نسخه‌دهی اجباری را رعایت کنید.
• برای پیشنهاد یا اشکال جدید می‌توانید Pull Request ثبت کنید. پیش از ارسال، مطمئن شوید که استایل کدنویسی وردپرس رعایت شده و هیچ بستهٔ وابستگی اضافه‌ای نیاز ندارد.

مانیفست بسته‌بندی و ساخت فایل ZIP (Packaging Rules)

این مانیفست ضامن ساخت خروجی‌های بهینه، سبک و آداپتیو (Adaptive) جهت آپلود در وردپرس است. معماری بسته‌بندی افزونه بر اصل ترکیب «فهرست سفید (Allowlist)» و «محافظت دوگانه (Git-Attributes Standard)» استوار است تا در صورت افزودن ابزارها، فایل‌های تست یا وابستگی‌های جدید در آینده، هیچ ابزار توسعه یا متای اضافی به فایل زیپ سرور نفوذ نکند.

۱. اصل فهرست سفید (Allowlist Principle - ساختار مجاز برای سرور)

تنها فایل‌ها و پوشه‌های زیر در نسخه نهایی آپلود و خروجی ZIP مجاز هستند:

• buyruz-settings.php : فایل اصلی و ثبت‌کننده افزونه در وردپرس
• uninstall.php : اسکریپت پاک‌سازی متای افزونه هنگام حذف
• includes/ : کدهای منطقی، کلاس‌ها و ماژول‌های افزونه
• assets/ : استایل‌ها (CSS) و اسکریپت‌های فرانت و ادمین (JS)
• README.md : مستندات اصلی و مانیفست
• CHANGELOG.md : یادداشت‌های انتشار و تاریخچه نسخه‌ها
• LICENSE : مجوز پروژه

۲. اصل فهرست سیاه و الگوهای استثنا (Exclusion Safeguards)

پوشه‌ها و فایل‌های مربوط به توسعه محلی، تست، کنترل نسخه و ابزارهای کامپایل به هیچ عنوان نباید در سرور یا فایل ZIP قرار گیرند:

• ابزارهای تست و کش: tests/, .phpunit.cache/, .phpunit.result.cache, phpunit.xml
• وابستگی‌های توسعه محلی: vendor/ (شامل ابزارهای تست محلی PHPUnit), composer.json, composer.lock
• کنترل نسخه و CI/CD: .git/, .github/, .gitignore, .gitattributes
• اسناد و فایل‌های موقت توسعه: QA.md, .DS_Store, *.log

---

۳. روش‌های استاندارد و آینده‌نگرانه ساخت ZIP (Adaptive Build Methods)

روش اول (روش استاندارد و خودکار Git Archive - پیشنهادی):

این روش به طور کامل بر فایل .gitattributes متکی است. فایل .gitattributes پروژه تمام موارد استثنا را با export-ignore علامت‌گذاری کرده است، بنابراین حتی در صورت افزودن فایل‌ها یا ابزارهای جدید در آینده، با افزودن نام آن‌ها به .gitattributes این دستور بدون تغییر در اسکریپت‌ها همیشه خروجی ۱۰۰٪ پاک تولید می‌کند:

git archive --format=zip --prefix=buyruz-wordpress-plugin/ -o ../buyruz-wordpress-plugin.zip HEAD

روش دوم (دستور مستقیم مبتنی بر لیست سفید - White-list Zip):

در این روش تنها اقلام مجاز انتخاب می‌شوند؛ لذا در آینده حتی اگر صدها ابزار توسعه (مانند node_modules یا وابستگی‌های جدید) به پوشه اضافه شوند، خروجی زیپ ۱۰۰٪ ایمن و آداپتیو می‌ماند:

cd /Users/moh3n/Documents/Development && \
rm -f buyruz-wordpress-plugin.zip && \
zip -r buyruz-wordpress-plugin.zip buyruz-wordpress-plugin \
  -i "buyruz-wordpress-plugin/buyruz-settings.php" \
  -i "buyruz-wordpress-plugin/uninstall.php" \
  -i "buyruz-wordpress-plugin/includes/*" \
  -i "buyruz-wordpress-plugin/assets/*" \
  -i "buyruz-wordpress-plugin/README.md" \
  -i "buyruz-wordpress-plugin/CHANGELOG.md" \
  -i "buyruz-wordpress-plugin/LICENSE"

روش سوم (دستور استثنائات الگویی - Dynamic Blocklist Zip):

استفاده از الگوهای کلی برای حذف تمامی فایل‌های مخفی، تست‌ها و وابستگی‌های غیرتولیدی:

cd /Users/moh3n/Documents/Development && \
rm -f buyruz-wordpress-plugin.zip && \
zip -r buyruz-wordpress-plugin.zip buyruz-wordpress-plugin \
  -x "buyruz-wordpress-plugin/.*" \
  -x "buyruz-wordpress-plugin/.git/*" \
  -x "buyruz-wordpress-plugin/.github/*" \
  -x "buyruz-wordpress-plugin/.phpunit.cache/*" \
  -x "buyruz-wordpress-plugin/tests/*" \
  -x "buyruz-wordpress-plugin/vendor/*" \
  -x "buyruz-wordpress-plugin/*.xml" \
  -x "buyruz-wordpress-plugin/*.json" \
  -x "buyruz-wordpress-plugin/*.lock" \
  -x "buyruz-wordpress-plugin/QA.md" \
  -x "buyruz-wordpress-plugin/*/.DS_Store" \
  -x "*.DS_Store"

به‌روزرسانی دستی

• برای به‌روزرسانی، بستهٔ جدید را به صورت دستی (FTP یا «افزودن افزونه → بارگذاری») جایگزین کنید.

دیباگ و لاگ‌ها

• از کارت «دیباگ و لاگ‌ها» می‌توانید ثبت لاگ برای بخش‌هایی که در آینده اضافه می‌شود را فعال کنید.
• لاگ‌ها در مسیر wp-content/plugins/buyruz-plugin/logs/ ذخیره می‌شوند و به صورت روزانه نام‌گذاری خواهند شد.
• گزینهٔ «ماسک داده‌های حساس» به صورت پیش‌فرض فعال است تا مقادیر محرمانه در لاگ‌ها قابل خواندن نباشند.
• پاکسازی خودکار فایل‌های لاگ بر اساس تعداد روز تعیین‌شده انجام می‌شود؛ مقدار پیش‌فرض ۷ روز است تا فضا اشغال نشود.

پشتیبانی

در صورت بروز مشکل یا پیشنهاد، در صفحهٔ Issues همین مخزن موضوع باز کنید: https://github.com/Codruz/buyruz-plugin/issues

لایسنس

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

یادداشت‌های انتشار

شرح فارسی تغییرات هر نسخه در CHANGELOG.md ثبت می‌شود. پیش از نصب نسخهٔ جدید، این فایل را برای آگاهی از تغییرات و اقدامات لازم مطالعه کنید.

buyruz-plugin