arc/docs/WORKFLOW_FIX_SUMMARY.md

# ✅ خلاصه رفع مشکلات ورک‌فلو

## 🎯 مشکلات شناسایی شده و حل شده

### 1️⃣ مشکل UI - Reference Selector (حل شد ✅)

**مشکل:**
- زمانی که کاربر می‌خواست از خروجی نود قبلی استفاده کند، فقط `$node_id` ذخیره می‌شد
- این باعث می‌شد کل object نود برگردانده شود، نه یک فیلد خاص

**راه‌حل اعمال شده:**
- Reference Selector را به یک dialog **دو مرحله‌ای** تبدیل کردیم
- **مرحله 1**: کاربر نود مورد نظر را انتخاب می‌کند
- **مرحله 2**: کاربر فیلد خاص را از آن نود انتخاب می‌کند
- حالا reference به صورت `$node_id.field_name` ذخیره می‌شود

**فایل تغییر یافته:**
- `hesabixUI/hesabix_ui/lib/widgets/workflow/workflow_node_config_dialog.dart`

**ویژگی‌های جدید:**
- ✅ انتخاب نود از لیست
- ✅ نمایش فیلدهای پیشنهادی بر اساس نوع نود
- ✅ امکان استفاده از کل نود (اگر نیاز باشد)
- ✅ آیکون‌های مناسب برای انواع داده (عدد، متن، تاریخ)
- ✅ UI زیبا و کاربرپسند

---

### 2️⃣ مشکل داده‌های ورک‌فلو در دیتابیس (حل شد ✅)

**مشکل:**
- ورک‌فلو شماره 3 دارای کانفیگ نادرست بود
- فیلد `message` به جای متن، reference نادرست `$node_id` داشت
- پیامی به تلگرام ارسال نمی‌شد

**راه‌حل اعمال شده:**
- داده‌های ورک‌فلو در دیتابیس اصلاح شد
- فیلد `message` به یک متن معنادار با reference های صحیح تغییر کرد

**قبل از اصلاح:**
```json
{
  "message": "$6a6f62bf-1680-4a50-9735-a1acc293d0d0"
}
```

**بعد از اصلاح:**
```json
{
  "message": "🔔 فاکتور جدیدی ایجاد شد!\n\n📋 کد فاکتور: $6a6f62bf-1680-4a50-9735-a1acc293d0d0.invoice_code\n💰 مبلغ کل: $6a6f62bf-1680-4a50-9735-a1acc293d0d0.total_amount\n👤 مشتری: $6a6f62bf-1680-4a50-9735-a1acc293d0d0.customer_name"
}
```

---

## 📋 فیلدهای پیشنهادی برای انواع نودها

Reference Selector حالا بر اساس نوع نود، فیلدهای مناسب را پیشنهاد می‌دهد:

### فاکتورها (invoice):
- `invoice_id` - شناسه فاکتور
- `invoice_code` - کد فاکتور
- `invoice_number` - شماره فاکتور
- `total_amount` - مبلغ کل
- `customer_name` - نام مشتری
- `status` - وضعیت
- و موارد دیگر...

### پرداخت‌ها (payment):
- `payment_id` - شناسه پرداخت
- `amount` - مبلغ
- `payment_method` - روش پرداخت
- `reference_code` - کد پیگیری
- و موارد دیگر...

### مشتریان (person/customer):
- `person_id` - شناسه
- `name` - نام
- `email` - ایمیل
- `phone` - تلفن
- و موارد دیگر...

---

## 🚀 نحوه استفاده از Reference Selector جدید

### مرحله 1: کلیک روی دکمه "انتخاب از نودهای قبلی"

<img src="docs/workflow_reference_step1.png" alt="مرحله 1" />

### مرحله 2: انتخاب نود مورد نظر

لیست تمام نودهای قبلی نمایش داده می‌شود. نود مورد نظر را انتخاب کنید.

### مرحله 3: انتخاب فیلد خاص

دو گزینه دارید:
1. **استفاده از کل خروجی نود** (برای موارد خاص)
2. **انتخاب یک فیلد خاص** از لیست فیلدهای پیشنهادی

### نتیجه:

Reference به صورت `$node_id.field_name` در فیلد ذخیره می‌شود.

---

## ✅ تست و بررسی

### چک‌لیست تست:

- ✅ UI دیزاینر: Reference Selector دو مرحله‌ای کار می‌کند
- ✅ لیست نودهای قبلی نمایش داده می‌شود
- ✅ لیست فیلدهای پیشنهادی بر اساس نوع نود نمایش داده می‌شود
- ✅ Reference به صورت صحیح ذخیره می‌شود
- ✅ داده‌های ورک‌فلو موجود در دیتابیس اصلاح شده است
- ✅ هیچ لینتر ارور وجود ندارد

---

## 📝 توصیه‌ها برای استفاده

### 1. برای ارسال پیام تلگرام:

```
🔔 فاکتور جدیدی ایجاد شد!

📋 کد: $trigger_node.invoice_code
💰 مبلغ: $trigger_node.total_amount ریال
👤 مشتری: $trigger_node.customer_name
📅 تاریخ: $trigger_node.invoice_date
```

### 2. برای ارسال ایمیل:

```
موضوع: فاکتور شماره $trigger_node.invoice_code

متن:
سلام $trigger_node.customer_name عزیز،
فاکتور شماره $trigger_node.invoice_code به مبلغ $trigger_node.total_amount ریال برای شما صادر شد.
```

### 3. برای شرط‌ها:

```
$trigger_node.total_amount > 1000000
$trigger_node.status == "paid"
```

---

## 🎉 نتیجه نهایی

✅ **مشکل UI حل شد** - Reference Selector حالا به درستی کار می‌کند
✅ **داده‌های ورک‌فلو اصلاح شد** - پیام‌ها به تلگرام ارسال می‌شوند
✅ **تست شد** - همه چیز کار می‌کند
✅ **مستندسازی شد** - گزارش‌ها و راهنماها آماده است

---

**تاریخ:** 2025-12-04
**نسخه:** 1.0
**وضعیت:** ✅ تکمیل شده