forked from hesabix/arc
121 lines
8.6 KiB
Markdown
121 lines
8.6 KiB
Markdown
# افزونهٔ وردپرس «شبکه تأمین»
|
||
|
||
نمایش **کاتالوگ عمومی** محصولات 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/` خواهد بود (اسلاگ را می‌توانید عوض کنید). پس از اولین فعال‌سازی یا تغییر اسلاگ، در صورت ۴۰۴ یک‌بار **تنظیمات → پیوندهای یکتا → ذخیره** بزنید.
|
||
|
||
## شورت‌کد
|
||
|
||
```text
|
||
[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 |
|
||
|
||
```text
|
||
[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 نصب است:
|
||
|
||
```bash
|
||
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 در این مخزن).
|