# فاز ۳.۱: بانک اصطلاحات و Product Finder

## نصب روی دو اپ cPanel

همان ZIP را در مسیر **Admin** و **Widget** جایگزین کنید. پوشه/فایل SQLite مشترک تنظیم‌شده با `ARCO_BOT_DB` را حذف یا جایگزین نکنید. هر دو Python App را Restart کنید. نسخه `/api/health` باید `3.1.0` باشد. برای بارگذاری کد جدید کارت‌ها، آدرس فایل JS در WordPress را با `?v=3.1.0` تازه کنید و کش مرورگر/آروان را پاک کنید. هیچ کلید یا URL محرمانه‌ای در Journey وارد نکنید.

## استفاده از بانک

1. در پنل Admin از سایدبار **بانک محصولات** را باز کنید.
2. «دسته‌ها» را انتخاب و «همگام‌سازی از فروشگاه» را بزنید؛ همین کار را برای «تگ‌ها» و «برندها» انجام دهید. هر صفحه حداکثر ۱۰۰ مورد می‌خواند، و درخواست‌ها پشت سر هم و کوتاه هستند.
3. روی هر عنوان کلیک کنید تا عنوان فارسی و مترادف‌ها را ویرایش کنید. slug فقط با حذف و افزودن دوباره تغییر می‌کند. نام و مترادف‌ها در همگام‌سازی بعدی حفظ می‌شوند.
4. اگر Endpoint برندهای WooCommerce در فروشگاه وجود نداشت، برندها را با **اصطلاح جدید** یا «واردکردن گروهی از JSON» با همان slug فیلتر فعلی سایت اضافه کنید. پلاگین فیلتر موجود دست‌نخورده است.
5. «تست کاتالوگ» را بزنید؛ این دکمه حداکثر ۴ محصول موجود از API فروشگاه می‌خواند. برای نگهداری خروجی بانک، «دریافت JSON» را بزنید. همان خروجی JSON برای بازگرداندن بانک با دکمه «واردکردن اصطلاحات» قابل استفاده است؛ اصطلاح هم‌نام را به‌روزرسانی می‌کند.

بانک، موجودی یا قیمت محصول را ذخیره نمی‌کند؛ فقط `taxonomy`، `slug`، `name_fa` و `aliases` را نگه می‌دارد. عنوان‌های فارسی و مترادف‌ها برای تبدیل عبارت مشتری به slug درست در Journey و در آینده AI به کار می‌آیند.

## Product Finder در Journey Builder

Node **Product Finder** را اضافه کنید، حداقل یک فیلتر دسته/تگ/برند را از بانک انتخاب کنید یا برای جست‌وجوی متنی `q` را تنظیم کنید. سه مسیر `نتیجه یافت شد`، `محصولی پیدا نشد` و `خطا در فروشگاه` را به Nodeهای بعدی وصل کنید. متن بالای کارت‌ها اختیاری است. نتیجه در متغیری مانند `products` ذخیره می‌شود؛ `{{products.count}}` تعداد کارت‌های برگشتی را نشان می‌دهد.

فیلترهای مجاز: `category`, `tag`, `brand`, `q`, `taste`, `weight`, `price_min`, `price_max`, `orderby`, `order`. برای فیلترهای غیر از دسته/تگ/برند در کادر «سایر فیلترها» JSON وارد کنید؛ برای مثال:

```json
{"q": "{{product_query}}", "orderby": "popularity"}
```

نمونه Draft با نام **جست‌وجوی محصول در فروشگاه** (`product_search`) خودکار ساخته می‌شود. ابتدا «تست» را اجرا کنید، بعد آن را Publish کنید و برای در دسترس شدن در ویجت، از Journey منوی اصلی یک دکمه با مقصد `Go To Journey: product_search` بسازید و منوی اصلی را نیز Publish کنید. Journeyهای Published قبلی هنگام نصب تغییر نمی‌کنند.

درخواست محصول فقط از Backend به `/wp-json/arcopet/v1/products/compact` با `instock=1&per_page=4` ارسال می‌شود. URL و کلید API از JSON Journey گرفته نمی‌شوند. خروجی ویجت حداکثر چهار کارت با عنوان، قیمت دریافتی از کاتالوگ و لینک HTTPS همان فروشگاه است. خرید در صفحه محصول انجام می‌شود؛ این مرحله پیشنهاد پزشکی یا انتخاب خودکار محصول بر اساس بیماری نیست.

### نمونه JSON قابل Import

نمونه کامل در `examples/05-product-search.json` است. برای محدود کردن نتیجه به یک دسته، پس از همگام‌سازی بانک، این فیلتر را در Node `lookup` بگذارید:

```json
"filters": {"category": "SLUG_FROM_CATALOG", "q": "{{product_query}}"}
```

اگر «تست کاتالوگ» کار می‌کند اما Node نتیجه‌ای نمی‌دهد، slug دسته/تگ/برند را با مقدار فیلتر فروشگاه مقایسه کنید. برای دسته یا برند ناموجود در بانک، خروجی Node به شاخه خطا می‌رود.
