arc/extraScripts/shabake-tamin/README.md

افزونهٔ وردپرس «شبکه تأمین»

نمایش کاتالوگ عمومی محصولات Hesabix روی سایت وردپرس از طریق پراکسی REST داخلی (بدون مشکل CORS و بدون بارگذاری اسکریپت از CDN).

آیا نصب‌کننده می‌تواند برای بازدیدکنندگان «همهٔ تأمین‌کنندگان» را فعال کند؟

بله. اگر در تنظیمات → شبکه تأمین مقدار شناسهٔ کسب‌وکار پیش‌فرض را ۰ بگذارید و در شورت‌کد یا بلوک هم business_id / فیلد کسب‌وکار را خالی بگذارید، درخواست لیست بدون پارامتر business_id به API Hesabix ارسال می‌شود. در آن حالت بازدیدکننده:

• کالاهای همهٔ کسب‌وکارهایی که در Hesabix کالایشان برای کاتالوگ عمومی علامت خورده است را می‌بیند؛
• روی هر کارت نام تأمین‌کننده (supplier.business_name) را می‌بیند؛
• با جستجو (متن نام/توضیح/برند/مشخصات) و در صورت تنظیم در شورت‌کد/بلوک، با دسته، استان، شهر و برند/مدل نتایج را محدود می‌کند؛
• با دکمهٔ تماس (در صورت فعال بودن تماس در Hesabix و کپچا) پیام می‌فرستد.

محدودیت‌ها طبق سیاست Hesabix است (فقط کالای is_public_catalog، نرخ‌سنجی سرور، و غیره).

نیازمندی‌ها

• وردپرس 5.8+
• PHP 7.4+
• سرور Hesabix با API عمومی کاتالوگ فعال (مستندات: docs/PUBLIC_PRODUCT_CATALOG.md در مخزن اصلی)

نصب

1. پوشهٔ shabake-tamin را در wp-content/plugins/ کپی کنید.
2. از پنل وردپرس افزونه را فعال کنید.
3. به تنظیمات → شبکه تأمین بروید و آدرس پایهٔ API را وارد کنید (مثلاً https://api.example.com بدون اسلش آخر).
4. (اختیاری) صفحهٔ عمومی کاتالوگ را از همان صفحه فعال کنید؛ آدرس شبیه https://example.com/tamin/ خواهد بود (اسلاگ را می‌توانید عوض کنید). پس از اولین فعال‌سازی یا تغییر اسلاگ، در صورت ۴۰۴ یک‌بار تنظیمات → پیوندهای یکتا → ذخیره بزنید.

شورت‌کد

[shabake_tamin]

پارامترها:

پارامتر	پیش‌فرض	توضیح
business_id	خالی (یا مقدار تنظیمات «شناسهٔ کسب‌وکار پیش‌فرض»)	اگر خالی و پیش‌فرض ۰ باشد → همهٔ کسب‌وکارها
category_id	خالی	فیلتر شناسهٔ دسته در Hesabix (اختیاری)
province	خالی	فیلتر متن استان (اختیاری)
city	خالی	فیلتر متن شهر (اختیاری)
brand	خالی	فیلتر متن برند یا مدل (اختیاری)
columns	4	تعداد ستون گرید (۲ تا ۶)
search	1	نمایش نوار جستجو (0 برای مخفی)
take	20	تعداد در هر درخواست (۱ تا ۱۰۰)
location_filters	0	اگر 1 باشد، فیلدهای استان/شهر برای بازدیدکننده و دکمهٔ «اعمال فیلتر مکان» نمایش داده می‌شود
brand_filters	0	اگر 1 باشد، فیلد برند/مدل برای بازدیدکننده و دکمهٔ «اعمال فیلتر» نمایش داده می‌شود
province_suggest	1	همراه با location_filters=1: پیشنهاد ۳۱ استان ایران در فیلد استان (datalist، دادهٔ لوکال PHP)؛ با 0 غیرفعال
show_details	1	دکمهٔ جزئیات روی کارت و مودال با GET .../product/{uuid} (پراکسی REST)؛ با 0 فقط تماس
page	0	با 1 چیدمان تمام‌عرض (نوار خلاصهٔ نتایج + استایل صفحه) داخل همان برگه — برای تجربهٔ نزدیک‌تر به «ویترین» بدون rewrite

[shabake_tamin business_id="12" columns="3" search="1"]
[shabake_tamin category_id="5" province="تهران" take="30"]
[shabake_tamin location_filters="1" brand_filters="1" search="1"]
[shabake_tamin brand="سامسونگ" take="30"]

ابزارک (سایدبار)

در ظاهر → ابزارک‌ها (یا نمایش → ابزارک‌ها در قالب‌های کلاسیک) ابزارک «کاتالوگ شبکه تأمین» را به ناحیهٔ ابزارک اضافه کنید؛ فیلترها همان منطق شورت‌کد را دارند و می‌توانید با فیلتر PHP shabake_tamin_widget_catalog_config آن را تغییر دهید (بخش «Override قالب»).

بلوک گوتنبرگ

در ویرایشگر بلوک، در دستهٔ ابزارک‌ها بلوک «کاتالوگ شبکه تأمین» (shabake-tamin/catalog) را اضافه کنید. اسکریپت ادیتور فقط از بسته‌های هستهٔ وردپرس (wp-blocks, wp-element, …) استفاده می‌کند؛ فایل آن در assets/js/block-editor.js است.

جزئیات کالا

با show_details="1" (پیش‌فرض) روی هر کارت دکمهٔ جزئیات نمایش داده می‌شود؛ مودال شامل خلاصه، توضیحات، بررسی تخصصی، جدول مشخصات فنی، برند/مدل، کشور سازنده، لینک ویدیو، حداقل سفارش و زمان تحویل است (GET .../product/{uuid} پراکسی REST). اگر کالا برند یا مدل داشته باشد، روی کارت لیست هم نمایش داده می‌شود.

ترجمه

فایل الگو: languages/shabake-tamin.pot. برای به‌روزرسانی کامل رشته‌ها در محیطی که WP-CLI نصب است:

wp i18n make-pot . languages/shabake-tamin.pot --slug=shabake-tamin --domain=shabake-tamin

(از داخل پوشهٔ افزونه اجرا شود.)

کتابخانه‌های خارجی

هیچ وابستگی به CDN وجود ندارد. اسکریپت و استایل از مسیر خود افزونه (assets/js و assets/css) با wp_enqueue بارگذاری می‌شوند.

Override قالب

برای تغییر HTML کاتالوگ، فایل را در قالب خود کپی کنید:

• مسیر در قالب فرزند/والد: wp-content/themes/<your-theme>/shabake-tamin/catalog-wrapper.php
• صفحهٔ عمومی (rewrite): .../shabake-tamin/catalog-public-page.php
• نقطهٔ شروع پیش‌فرض: templates/catalog-wrapper.php و templates/catalog-public-page.php داخل افزونه

فیلترهای PHP:

• shabake_tamin_locate_template — مسیر نهایی فایل قالب
• shabake_tamin_shortcode_config — پیکربندی پس از پارس شورت‌کد
• shabake_tamin_catalog_config — پیکربندی نهایی قبل از رندر (شورت‌کد، بلوک، ابزارک یا فراخوانی دستی)
• shabake_tamin_public_catalog_config — فقط برای صفحهٔ عمومی rewrite؛ پیش از shabake_tamin_catalog_config
• shabake_tamin_widget_catalog_config — فقط برای ابزارک، پیش از shabake_tamin_catalog_config
• shabake_tamin_iran_provinces — آرایهٔ نام استان‌ها برای datalist (قبل از رندر قالب)

REST وردپرس

مسیر پایه: /wp-json/shabake-tamin/v1/

• GET catalog — پراکسی لیست (search, business_id, category_id, province, city, skip, take)
• GET product/{uuid} — جزئیات یک کالا
• POST captcha — دریافت کپچا برای فرم تماس
• POST contact — ارسال پیام تماس (بدنه مشابه POST /api/v1/public/catalog/contact-messages در Hesabix)

کش Transient روی پاسخ‌های catalog و product طبق مقدار «مدت کش پراکسی» در تنظیمات اعمال می‌شود (۰ = بدون کش).

امنیت

• پارامترهای پراکسی در PHP سانیتایز می‌شوند.
• محدودیت نرخ ساده بر اساس IP روی routeهای پراکسی اعمال شده است.

مجوز

GPL v2 یا بالاتر (هم‌تراز افزونه‌های نمونهٔ Hesabix در این مخزن).