# راهنمای ساخت Journey در Arcopet Bot

این راهنما برای همکارانی نوشته شده که می‌خواهند بدون برنامه‌نویسی مسیر مکالمه بات را بسازند، آزمایش کنند و منتشر کنند.

## ۱. Journey چیست؟

Journey یک مسیر مکالمه است. هر Journey از چند Node تشکیل می‌شود و هر Node یک کار مشخص انجام می‌دهد؛ مثلاً پیام نشان می‌دهد، سؤال می‌پرسد، پاسخ را ذخیره می‌کند یا کاربر را به مسیر دیگری می‌فرستد.

نمونه ساده:

```text
Start
  ↓
Message: سلام، چطور می‌توانیم کمک کنیم؟
  ↓
Buttons
  ├─ پیگیری سفارش → Order Tracking
  └─ انتخاب غذا → Food Finder
```

## ۲. چهار مفهوم اصلی

### Node

یک مرحله از مکالمه است؛ مانند Message، Buttons یا Condition.

### Connection

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

### Variable

اطلاعاتی است که در طول مکالمه ذخیره می‌شود؛ مانند:

```text
pet_type = cat
pet_age_group = adult
sterilised = true
```

نام Variable را انگلیسی، کوتاه و با الگوی `snake_case` بنویسید؛ مانند `pet_type` و `order_id`.

### Draft و Published

- **Draft:** نسخه قابل ویرایش که مشتری آن را نمی‌بیند.
- **Published:** نسخه‌ای که ویجت سایت برای مشتری اجرا می‌کند.

ذخیره Draft به معنی انتشار نیست.

## ۳. ساخت اولین Journey در پنج دقیقه

1. وارد بخش **Journeyها** شوید.
2. دکمه **Journey جدید** را بزنید.
3. نام فارسی، کلید انگلیسی و توضیح کوتاه را وارد کنید.
4. در Journey Builder بین Start و End، Nodeهای موردنیاز را اضافه کنید.
5. روی هر Node کلیک و تنظیماتش را از ستون سمت راست تکمیل کنید.
6. بعد از هر تغییر روی **اعمال تغییرات** بزنید.
7. روی **ذخیره Draft** بزنید.
8. با دکمه **تست** تمام شاخه‌ها را بررسی کنید.
9. اگر همه مسیرها درست بود، روی **انتشار** بزنید.

## ۴. کاربرد Nodeها

| Node | کاربرد | نکته مهم |
|---|---|---|
| Start | نقطه شروع Journey | فقط یک مسیر خروجی داشته باشد |
| Message | نمایش متن به کاربر | باید Node بعدی تعیین شود |
| Buttons | نمایش چند انتخاب | هر گزینه باید Value و مقصد داشته باشد |
| Question | دریافت متن یا عدد | پاسخ را در یک Variable ذخیره کنید |
| Condition | انتخاب مسیر براساس Variable | همیشه مسیر Else را مشخص کنید |
| Save Variable | ثبت یک مقدار بدون سؤال | برای ثبت مقادیر ثابت مناسب است |
| Go To Journey | اجرای یک Journey دیگر | مسیر ادامه بعد از بازگشت را مشخص کنید |
| WooCommerce | دریافت امن سفارش | فقط Action مجاز و دو مسیر موفق/خطا دارد |
| Product Finder | نمایش محصولات موجود از کاتالوگ زنده | سه مسیر نتیجه، خالی و خطا دارد |
| End | پایان مسیر | خروجی ندارد |

## ۵. Message

برای نمایش متن، توضیح یا نتیجه استفاده می‌شود.

نمونه:

```text
برای انتخاب غذای مناسب چند سؤال کوتاه از شما می‌پرسیم.
```

می‌توانید مقدار Variable را داخل متن نمایش دهید:

```text
انتخاب شما برای {{pet_type}} ثبت شد.
```

پس از نوشتن متن، «Node بعدی» را انتخاب کنید.

## ۶. Buttons

برای سؤال‌های چندگزینه‌ای استفاده می‌شود.

نمونه تنظیمات:

```text
متن: برای چه حیوانی غذا می‌خواهید؟
ذخیره انتخاب در متغیر: pet_type

عنوان گزینه: گربه
Value: cat
مقصد: cat_age

عنوان گزینه: سگ
Value: dog
مقصد: dog_age
```

- **عنوان** همان چیزی است که مشتری می‌بیند.
- **Value** مقدار داخلی ذخیره‌شده است و بهتر است انگلیسی باشد.
- **مقصد** Node بعدی همان گزینه است.
- دو گزینه در یک Node نباید Value یکسان داشته باشند.

## ۷. Question

برای دریافت پاسخ آزاد استفاده می‌شود.

نمونه:

```text
متن: شماره سفارش خود را وارد کنید.
نوع ورودی: عدد
ذخیره پاسخ در متغیر: order_id
Placeholder: مثلاً 145820
Node بعدی: show_tracking_message
```

اگر پاسخ عددی نیست، نوع ورودی را «متن» انتخاب کنید.

## ۸. Save Variable

وقتی می‌خواهید بدون سؤال از مشتری یک مقدار ثابت ذخیره شود، از این Node استفاده کنید.

```text
نام متغیر: source
مقدار: website_chat
```

مقادیر `true`، `false` و عدد به نوع واقعی خودشان ذخیره می‌شوند.

## ۹. Condition

Condition مقدار Variable را بررسی و مسیر مناسب را انتخاب می‌کند. Ruleها در نسخه فعلی به‌صورت JSON وارد می‌شوند.

```json
[
  {
    "if": {
      "variable": "pet_type",
      "operator": "equals",
      "value": "cat"
    },
    "next": "cat_flow"
  }
]
```

سپس در فیلد **مسیر Else** مسیر پیش‌فرض را انتخاب کنید؛ مثلاً `dog_flow`.

| Operator | معنی |
|---|---|
| `equals` | برابر است |
| `not_equals` | برابر نیست |
| `greater_than` | بزرگ‌تر است |
| `greater_or_equal` | بزرگ‌تر یا مساوی است |
| `less_than` | کوچک‌تر است |
| `less_or_equal` | کوچک‌تر یا مساوی است |
| `contains` | شامل مقدار است |
| `exists` | Variable وجود دارد |

نمونه بررسی وزن:

```json
[
  {
    "if": {
      "variable": "pet_weight",
      "operator": "greater_than",
      "value": 6
    },
    "next": "weight_control_message"
  }
]
```

هر Condition باید حداقل یک Rule و یک مسیر Else داشته باشد.

## ۱۰. Go To Journey

برای استفاده مجدد از یک مسیر مشترک است. مثلاً Journey اصلی می‌تواند Journey «ارتباط با پشتیبانی» را اجرا کند و سپس به مسیر خودش برگردد.

1. Journey مقصد را انتخاب کنید.
2. در «Node بعدی»، محل ادامه مسیر بعد از بازگشت را مشخص کنید.
3. Journey مقصد باید مسیر کامل و End داشته باشد.

## ۱۱. WooCommerce Action

این Node اطلاعات سفارش را فقط از Backend دریافت می‌کند. Secret و URL داخل Journey قرار نمی‌گیرند.

تنظیم استاندارد پیگیری سفارش:

```json
{
  "action": "woocommerce.get_order",
  "input": {
    "order_id": "{{order_id}}",
    "phone": "{{customer_phone}}"
  },
  "save_result": "order",
  "on_success": "order_found",
  "on_error": "order_not_found"
}
```

- `order_id` و `phone` باید قبلاً از کاربر دریافت شده باشند.
- در مسیر موفق می‌توانید از `{{order.summary}}`، `{{order.status_label}}` و `{{order.tracking_number}}` استفاده کنید.
- مسیر خطا نباید مشخص کند شماره سفارش وجود داشته ولی موبایل اشتباه بوده است؛ پیام عمومی نمایش دهید.
- فقط Action از پیش مجاز `woocommerce.get_order` اجرا می‌شود. JSON اجازه اجرای URL دلخواه ندارد.
- کلیدهای WooCommerce فقط در Environment Variables دو Python App ثبت می‌شوند.

## ۱۲. اتصال Nodeها

اتصال‌ها با کشیدن خط ساخته نمی‌شوند؛ مقصد را در تنظیمات Node تعیین می‌کنید و پنل خط را خودکار رسم می‌کند:

- Start، Message، Question، Save Variable و Go To Journey: فیلد **Node بعدی**
- Buttons: مقصد هر گزینه
- Condition: مقدار `next` هر Rule و فیلد **مسیر Else**
- WooCommerce: فیلدهای **مسیر موفق** و **مسیر خطا**
- End: بدون اتصال خروجی

اگر نمودار نامرتب شد، دکمه **مرتب‌سازی خودکار** را بزنید.

## ۱۳. نام‌گذاری پیشنهادی

| مورد | الگوی مناسب | نمونه |
|---|---|---|
| Journey Key | انگلیسی و `snake_case` | `cat_food_finder` |
| Node ID | انگلیسی و توصیفی | `ask_pet_age` |
| Variable | انگلیسی و `snake_case` | `health_need` |
| Button Value | انگلیسی و کوتاه | `weight_control` |
| عنوان مدیریتی | کوتاه و قابل فهم | `سؤال سن گربه` |

از نام‌های مبهم مثل `node_1` یا `value2` برای مسیرهای اصلی استفاده نکنید.

## ۱۴. تست Journey

1. روی **ذخیره Draft** بزنید.
2. دکمه **تست** را باز کنید.
3. تمام گزینه‌ها و شاخه‌ها را جداگانه اجرا کنید.
4. مقدار Session Variables را بررسی کنید.
5. متن‌ها، غلط‌های املایی و مقصد دکمه‌ها را کنترل کنید.
6. مطمئن شوید تمام مسیرها به End یا Sub-Journey معتبر می‌رسند.

Preview نسخه Draft را اجرا می‌کند؛ ویجت سایت نسخه Published را نمایش می‌دهد.

## ۱۵. انتشار و ویرایش بعدی

بعد از تأیید تست، روی **انتشار** بزنید. سیستم نسخه منتشرشده را نگه می‌دارد و یک Draft جدید برای تغییرات بعدی ایجاد می‌کند.

- ویرایش Draft، گفت‌وگوی مشتریان را تغییر نمی‌دهد.
- فقط با Publish نسخه جدید وارد ویجت می‌شود.
- قبل از هر Publish دوباره Preview را تست کنید.

## ۱۶. Import و Export JSON

### Import

1. در بخش Journeyها روی **Import JSON** بزنید.
2. فایل را انتخاب یا JSON را Paste کنید.
3. روی **بررسی JSON** بزنید.
4. خطاها و هشدارها را اصلاح کنید.
5. با **Import به‌عنوان Draft** آن را وارد کنید.

Import هیچ Journey را مستقیم Published نمی‌کند.

### Export

در Journey Builder روی **Export** بزنید. فایل خروجی را برای نسخه پشتیبان یا ویرایش بیرون از پنل نگه دارید.

اگر Journey موجود را دوباره Import کنید، پنل پیش از جایگزینی Draft تأیید می‌گیرد.

## ۱۷. خطاهای رایج

| خطا | علت معمول | راه‌حل |
|---|---|---|
| Node بدون خروجی | Node بعدی تعیین نشده | مقصد را در تنظیمات انتخاب کنید |
| Missing reference | مقصدی انتخاب شده که حذف شده است | مقصد جدید تعیین کنید |
| Duplicate Node ID | شناسه Node تکراری است | در JSON شناسه یکتا قرار دهید |
| Unreachable Node | هیچ مسیری از Start به Node نمی‌رسد | اتصال ورودی ایجاد یا Node را حذف کنید |
| Condition بدون Else | مسیر پیش‌فرض تعیین نشده | فیلد مسیر Else را تکمیل کنید |
| JSON شرط نامعتبر | ویرگول، کوتیشن یا براکت اشتباه است | ساختار JSON را اصلاح کنید |
| Action انجام نمی‌شود | کلید Read-only در هر دو App ثبت نشده است | Environment Variables و تست اتصال را بررسی کنید |
| تغییرات در سایت دیده نمی‌شود | فقط Draft ذخیره شده است | بعد از تست Publish کنید |

## ۱۸. چک‌لیست قبل از Publish

- [ ] Start به اولین Node درست متصل است.
- [ ] همه Messageها و سؤال‌ها متن واضح دارند.
- [ ] تمام گزینه‌های Buttons دارای Value و مقصد هستند.
- [ ] نام Variableها انگلیسی و مشخص است.
- [ ] تمام Conditionها Rule و Else دارند.
- [ ] Actionهای WooCommerce هم مسیر موفق و هم مسیر خطا دارند.
- [ ] Node بدون دسترسی یا اتصال شکسته وجود ندارد.
- [ ] تمام شاخه‌ها در Preview تست شده‌اند.
- [ ] مسیرها به End یا Sub-Journey معتبر می‌رسند.
- [ ] اطلاعات محرمانه، رمز یا کلید API داخل متن و JSON قرار نگرفته است.
- [ ] نسخه صحیح Publish شده است.

## ۱۹. روش ساخت Journeyهای بزرگ

ابتدا منطق را در یک متن ساده مشخص کنید:

```text
شروع → انتخاب موضوع → سؤال اول → سؤال دوم → شرط → نتیجه → پایان
```

سپس Variableها و شاخه‌ها را مشخص کنید، بخش‌های تکراری را به Sub-Journey تبدیل کنید و هر شاخه را جداگانه تست کنید.

قاعده طلایی: هر Node باید یک وظیفه روشن داشته باشد و هر مسیر باید پایان مشخص داشته باشد.

## ۲۰. Product Finder و بانک اصطلاحات

1. در «بانک محصولات» دسته، تگ و برند را همگام کنید؛ slug باید همان slug فیلتر فروشگاه باشد.
2. در Builder یک Node **Product Finder** بگذارید و فیلتر موردنیاز را انتخاب کنید.
3. Nodeهای بعدی سه شاخهٔ «نتیجه یافت شد»، «محصولی پیدا نشد» و «خطا در فروشگاه» را مشخص کنید.
4. Draft را ذخیره و با «تست» اجرا کنید؛ حداکثر چهار کارت محصول موجود نمایش داده می‌شود.
5. وقتی نتیجه درست بود Publish کنید. برای استفاده در منوی اصلی، یک Buttons و Go To Journey به مسیر محصول وصل کنید.

نمونه آماده `product_search` برای جست‌وجوی متنی به‌صورت Draft در پنل وجود دارد. برای جست‌وجو بر اساس نیاز حیوان، دسته یا تگ واقعی را با نظر متخصص انتخاب کنید؛ متن پزشکی یا تشخیص بیماری را خودکار به محصول نگاشت نکنید. راهنمای فنی بیشتر در `PHASE3_1_PRODUCT_FINDER_FA.md` داخل بسته است.
