arc/docs/WORKFLOW_UI_EXAMPLES.md

نمونه‌های UI برای Workflow Filters

این فایل شامل نمونه‌های بصری و کدهای مثال برای استفاده از فیلترها و سلکتورهای جدید است.

---

🎨 مثال 1: Dropdown با Emoji و Label فارسی

Backend Schema:

"priority": {
    "type": "string",
    "description": "اولویت ارسال",
    "enum": ["low", "normal", "high"],
    "default": "normal",
    "ui_config": {
        "labels": {
            "low": "🔽 کم - Low",
            "normal": "➖ عادی - Normal",
            "high": "🔼 بالا - High"
        }
    },
    "required": False
}

نمایش در UI:

┌─────────────────────────────────────┐
│ اولویت ارسال ▼                      │
├─────────────────────────────────────┤
│ 🔽 کم - Low                         │
│ ➖ عادی - Normal       ✓            │
│ 🔼 بالا - High                      │
└─────────────────────────────────────┘

---

🎨 مثال 2: Multi-Select با FilterChips

Backend Schema:

"status_filter": {
    "type": "array",
    "description": "فیلتر بر اساس وضعیت فاکتور",
    "items": {
        "type": "string",
        "enum": ["draft", "confirmed", "cancelled", "pending"]
    },
    "ui_type": "multi_select",
    "ui_config": {
        "labels": {
            "draft": "پیش‌نویس",
            "confirmed": "تایید شده",
            "cancelled": "لغو شده",
            "pending": "در انتظار"
        }
    },
    "required": False
}

نمایش در UI:

وضعیت فاکتور:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ پیش‌نویس   ✓ │ │ تایید شده  ✓ │ │ لغو شده      │ │ در انتظار    │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
    (selected)      (selected)       (not selected)   (not selected)

---

🎨 مثال 3: Currency Selector

Backend Schema:

"currency_id": {
    "type": "integer",
    "description": "شناسه ارز",
    "ui_type": "currency_selector",
    "ui_config": {
        "business_scoped": True,
        "show_default": True
    },
    "required": False
}

نمایش در UI:

┌────────────────────────────────────────┐
│ ارز ▼                                   │
├────────────────────────────────────────┤
│ ﷼ ریال (IRR)                  ✓        │
│ $ دلار آمریکا (USD)                    │
│ € یورو (EUR)                           │
│ د.إ درهم امارات (AED)                  │
└────────────────────────────────────────┘

[🔗 استفاده از نود قبلی]

---

🎨 مثال 4: Timezone Selector با پرچم

Backend Schema:

"timezone": {
    "type": "string",
    "description": "منطقه زمانی",
    "default": "Asia/Tehran",
    "enum": ["Asia/Tehran", "UTC", "Asia/Dubai", "Europe/London", "America/New_York"],
    "ui_config": {
        "labels": {
            "Asia/Tehran": "🇮🇷 تهران (ایران)",
            "UTC": "🌍 UTC (جهانی)",
            "Asia/Dubai": "🇦🇪 دبی",
            "Europe/London": "🇬🇧 لندن",
            "America/New_York": "🇺🇸 نیویورک"
        }
    },
    "required": False
}

نمایش در UI:

┌─────────────────────────────────────┐
│ منطقه زمانی ▼                       │
├─────────────────────────────────────┤
│ 🇮🇷 تهران (ایران)          ✓       │
│ 🌍 UTC (جهانی)                      │
│ 🇦🇪 دبی                             │
│ 🇬🇧 لندن                            │
│ 🇺🇸 نیویورک                         │
└─────────────────────────────────────┘

---

🎨 مثال 5: Person Selector با Reference Support

Backend Schema:

"person_id": {
    "type": "integer",
    "description": "شناسه طرف حساب",
    "ui_type": "person_selector",
    "ui_config": {
        "business_scoped": True,
        "filter_by_invoice_type": True,
        "show_reference_button": True
    },
    "required": True
}

حالت 1: ورود مستقیم

┌────────────────────────────────────────┐
│ طرف حساب                        ⭐      │
├────────────────────────────────────────┤
│ 123                    [🔗] [⭐]        │
└────────────────────────────────────────┘
💡 می‌توانید شناسه را وارد کنید یا از نود
   قبلی استفاده کنید: $node_id.person_id

[🔗 استفاده از نود قبلی]

حالت 2: استفاده از Reference

┌────────────────────────────────────────┐
│ طرف حساب                        ⭐      │
├────────────────────────────────────────┤
│ 🔗 $trigger-1.person_id   [🔗] [⭐]    │
└────────────────────────────────────────┘
ℹ️ این مقدار از یک نود قبلی استفاده می‌کند

[🔗 استفاده از نود قبلی]

---

🎨 مثال 6: Invoice Type با Emoji

Backend Schema:

"invoice_type": {
    "type": "string",
    "description": "نوع فاکتور",
    "required": True,
    "enum": ["invoice_sales", "invoice_purchase", "invoice_return_sales", "invoice_return_purchase"],
    "ui_type": "select",
    "ui_config": {
        "labels": {
            "invoice_sales": "🛒 فاکتور فروش",
            "invoice_purchase": "🛍️ فاکتور خرید",
            "invoice_return_sales": "↩️ برگشت از فروش",
            "invoice_return_purchase": "↪️ برگشت از خرید"
        }
    }
}

نمایش در UI:

┌─────────────────────────────────────┐
│ نوع فاکتور ▼                ⭐      │
├─────────────────────────────────────┤
│ 🛒 فاکتور فروش             ✓       │
│ 🛍️ فاکتور خرید                     │
│ ↩️ برگشت از فروش                    │
│ ↪️ برگشت از خرید                    │
└─────────────────────────────────────┘

---

🎨 مثال 7: HTTP Method Selector

Backend Schema:

"method": {
    "type": "string",
    "description": "روش HTTP",
    "default": "POST",
    "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"],
    "ui_config": {
        "labels": {
            "GET": "GET - دریافت",
            "POST": "POST - ارسال",
            "PUT": "PUT - به‌روزرسانی کامل",
            "DELETE": "DELETE - حذف",
            "PATCH": "PATCH - به‌روزرسانی جزئی"
        }
    }
}

نمایش در UI:

┌─────────────────────────────────────────────┐
│ روش HTTP ▼                                   │
├─────────────────────────────────────────────┤
│ GET - دریافت                                │
│ POST - ارسال                        ✓       │
│ PUT - به‌روزرسانی کامل                      │
│ DELETE - حذف                                │
│ PATCH - به‌روزرسانی جزئی                    │
└─────────────────────────────────────────────┘

---

🎨 مثال 8: Parse Mode با توضیح

Backend Schema:

"parse_mode": {
    "type": "string",
    "description": "حالت پارس متن",
    "enum": ["None", "HTML", "Markdown"],
    "default": "None",
    "ui_config": {
        "labels": {
            "None": "متن ساده",
            "HTML": "HTML - با فرمت HTML",
            "Markdown": "Markdown - با فرمت مارک‌داون"
        }
    }
}

نمایش در UI:

┌─────────────────────────────────────────────┐
│ حالت پارس متن ▼                             │
├─────────────────────────────────────────────┤
│ متن ساده                            ✓       │
│ HTML - با فرمت HTML                         │
│ Markdown - با فرمت مارک‌داون                │
└─────────────────────────────────────────────┘

---

🎨 مثال 9: Person Type Filter

Backend Schema:

"person_type_filter": {
    "type": "string",
    "description": "فیلتر بر اساس نوع شخص",
    "enum": ["customer", "supplier", "employee", "other"],
    "ui_config": {
        "labels": {
            "customer": "مشتری",
            "supplier": "تامین‌کننده",
            "employee": "کارمند",
            "other": "سایر"
        }
    }
}

نمایش در UI:

┌─────────────────────────────────────┐
│ نوع شخص ▼                           │
├─────────────────────────────────────┤
│ مشتری                               │
│ تامین‌کننده                 ✓       │
│ کارمند                              │
│ سایر                                │
└─────────────────────────────────────┘

---

🎯 الگوی کامل: ساخت یک Trigger با فیلترهای کامل

Schema:

class InvoiceCreatedTrigger(BaseTrigger):
    def get_metadata(self) -> Dict[str, Any]:
        return {
            "name": "ایجاد فاکتور",
            "description": "زمانی که یک فاکتور فروش یا خرید ایجاد می‌شود",
            "config_schema": {
                "enabled": {
                    "type": "boolean",
                    "description": "فعال/غیرفعال کردن trigger",
                    "default": True
                },
                "invoice_type": {
                    "type": "string",
                    "description": "نوع فاکتور",
                    "enum": ["invoice_sales", "invoice_purchase"],
                    "ui_config": {
                        "labels": {
                            "invoice_sales": "🛒 فاکتور فروش",
                            "invoice_purchase": "🛍️ فاکتور خرید"
                        }
                    }
                },
                "min_amount": {
                    "type": "number",
                    "description": "حداقل مبلغ فاکتور"
                },
                "max_amount": {
                    "type": "number",
                    "description": "حداکثر مبلغ فاکتور"
                },
                "status_filter": {
                    "type": "array",
                    "description": "فیلتر بر اساس وضعیت فاکتور",
                    "items": {
                        "type": "string",
                        "enum": ["draft", "confirmed", "cancelled"]
                    },
                    "ui_type": "multi_select",
                    "ui_config": {
                        "labels": {
                            "draft": "پیش‌نویس",
                            "confirmed": "تایید شده",
                            "cancelled": "لغو شده"
                        }
                    }
                },
                "currency_id": {
                    "type": "integer",
                    "description": "فیلتر بر اساس ارز",
                    "ui_type": "currency_selector"
                }
            }
        }

نمایش کامل در UI:

╔═══════════════════════════════════════════════════════════╗
║  تنظیمات Trigger: ایجاد فاکتور                           ║
╠═══════════════════════════════════════════════════════════╣
║                                                            ║
║  ☑️ فعال/غیرفعال کردن trigger                             ║
║  ───────────────────────────────────────────────────────  ║
║                                                            ║
║  نوع فاکتور:                                              ║
║  ┌────────────────────────────────────┐                   ║
║  │ 🛒 فاکتور فروش             ✓      │                   ║
║  └────────────────────────────────────┘                   ║
║                                                            ║
║  حداقل مبلغ فاکتور:                                       ║
║  ┌────────────────────────────────────┐                   ║
║  │ 1000000                     [⭐]   │                   ║
║  └────────────────────────────────────┘                   ║
║                                                            ║
║  حداکثر مبلغ فاکتور:                                      ║
║  ┌────────────────────────────────────┐                   ║
║  │ 10000000                    [⭐]   │                   ║
║  └────────────────────────────────────┘                   ║
║                                                            ║
║  وضعیت فاکتور:                                            ║
║  ┌──────────┐ ┌──────────┐ ┌──────────┐                  ║
║  │پیش‌نویس✓│ │تایید شده│ │لغو شده ✓ │                  ║
║  └──────────┘ └──────────┘ └──────────┘                  ║
║                                                            ║
║  ارز:                                                      ║
║  ┌────────────────────────────────────┐                   ║
║  │ ﷼ ریال (IRR)               ✓      │                   ║
║  └────────────────────────────────────┘                   ║
║                                                            ║
╠═══════════════════════════════════════════════════════════╣
║                           [انصراف]  [💾 ذخیره]            ║
╚═══════════════════════════════════════════════════════════╝

---

💡 نکات طراحی UI

1. استفاده از Emoji:

• ✅ استفاده کنید: برای دسته‌بندی و تمایز بصری
• ❌ زیاده‌روی نکنید: حداکثر 1-2 emoji در هر label

2. ترتیب نمایش:

Priority Order:
1. فیلدهای required (با ⭐)
2. فیلدهای پرکاربرد
3. فیلترها
4. تنظیمات پیشرفته

3. Group Sections:

📋 اطلاعات پایه
    - نوع فاکتور
    - طرف حساب
    - تاریخ

🔍 فیلترها
    - وضعیت
    - مبلغ
    - ارز

⚙️ تنظیمات پیشرفته
    - سال مالی
    - انبار
    - پرداخت

4. Color Coding:

• 🔴 خطا / حذف
• 🟢 موفقیت / تایید
• 🟡 هشدار / در انتظار
• 🔵 اطلاعات / عادی
• ⚪ خنثی / پیش‌فرض

---

📱 Responsive Design

Desktop (>768px):

┌─────────────┬─────────────┐
│ فیلد 1      │ فیلد 2      │
├─────────────┼─────────────┤
│ فیلد 3      │ فیلد 4      │
└─────────────┴─────────────┘

Mobile (<768px):

┌─────────────────────────┐
│ فیلد 1                  │
├─────────────────────────┤
│ فیلد 2                  │
├─────────────────────────┤
│ فیلد 3                  │
├─────────────────────────┤
│ فیلد 4                  │
└─────────────────────────┘

---

نکته پایانی: تمام این UI patterns به صورت خودکار از schema تولید می‌شوند. فقط کافی است schema را درست تعریف کنید!