طراحی ورک‌فلو بیلدر
UX Design & Component Inventory

۱ اصول راهنمای UX

کل طراحی Builder تحت تأثیر یک واقعیت قرار دارد: کاربر این محصول، برنامه‌نویس نیست. مدیر فروش، بازاریاب یا صاحب کسب‌وکار باید بدون آموزش بتواند جریان بسازد. پس «سادگی» اولویت اول است و «امکانات» دوم.

۲ شخصیت‌های کاربری (Personas)

۳ چیدمان کلی صفحه Builder

صفحه Builder از پنج ناحیه ثابت تشکیل شده است. ناحیه‌ها هرگز جابه‌جا نمی‌شوند تا ماهیچه حافظه کاربر شکل گیرد.

┌─────────────────────────────────────────────────────────────────────────────┐
│ ② Top Bar                                                                  │
│  [← بازگشت]  [نام جریان ▾]  [● پیش‌نویس]  [🔍 جست‌وجو]  [↶ ↷] │
│                                                [ذخیره]  [آزمایش]  [انتشار] │
├──────────┬──────────────────────────────────────────────────┬───────────────┤
│          │                                                  │               │
│ ① Left   │              ③ Canvas                             │ ④ Right      │
│ Palette  │         (مرکز، قابل بزرگنمایی)                    │ Config Panel │
│          │                                                  │               │
│ 🔍 جست‌وجو│      ┌──────┐     ┌──────┐                        │ [گره انتخاب‌شده]│
│          │      │ Trigger│────►│ HTTP │                        │ ───────────  │
│ ▸ محرک‌ها  │      └──────┘     └──────┘                        │ URL           │
│ ▸ اقدام‌ها │                                     ┌──────┐     │ [{{ }} ]      │
│ ▸ شرط‌ها  │                        ┌─────┐       │Email │     │ ───────────  │
│ ▸ داده    │                        │ IF  │──────►│      │     │ Error         │
│          │                        └─────┘       └──────┘     │ -policy       │
│          │                                                  │               │
├──────────┴──────────────────────────────────────────────────┴───────────────┤
│ ⑤ Bottom Bar                                                                 │
│  وضعیت: ذخیره شد ۲ ثانیه قبل │ ۴ گره │ آخرین اجرا: موفق ۱۲:۳۰ │ 🐞 آزمایش     │
└─────────────────────────────────────────────────────────────────────────────┘

۴ کانواس و رفتار آن

۴.۱ ناحیه‌های داخلی یک گره (Node Anatomy)

┌─────────────────────────────────┐
│ ●  ① آیکون نوع   [جداشده] ②    │ ← هدر رنگی، برچسب نوع
│─────────────────────────────────│
│  ③ عنوان کاربری                │ ← «ارسال پیامک» (قابل ویرایش دوبار کلیک)
│  ④ خلاصه مقدارها               │ ← «به ۰۹۱۲… · قالب: خوش‌آمد»
│─────────────────────────────────│
│  ⚠ ⑤ نشان خطا (در صورت وجود)  │
└─────────────────────────────────┘
      ⑥ ورودی (چپ)              ⑦ خروجی (راست)
         ◯ ........................◯
              ⑧ دسته اتصال: دایره‌ای همیشه در لبه، هیچ‌وقت وسط گره

۴.۲ رفتار کانواس

۵ پالت گره‌ها (Node Palette)

پالت، ویترین کل گره‌هاست. اگر کاربر نتواند در ۱۰ ثانیه گره درست را پیدا کند، طراحی شکست خورده است.

┌────────────────────────────┐
│ 🔍 جست‌وجوی گره...       [⌘K]│
│────────────────────────────│
│ ✦ پیشنهادی برای شما        │   ← بر اساس گره‌های موجود
│   [ارسال ایمیل] [پیامک]    │
│────────────────────────────│
│ ▸ محرک‌ها            (۸)   │   ← جمع‌شده به‌صورت پیش‌فرض
│   ▸ CRM                   │
│   ▸ فرم وب                │
│   ▸ زمان‌بندی              │
│ ▾ اقدام‌ها            (۹)   │   ← باز
│     crm.contact.create      │   ← کارت با آیکون + نام فارسی
│     crm.contact.update      │
│     crm.deal.move_stage     │
│   ▸ HTTP و داده            │
│   ▸ پیام‌رسان             │
│ ▸ شرط‌ها              (۵)   │
│ ▸ پیکربندی جریان       (۳)   │
│────────────────────────────│
│ 💡 «گره مورد نیافتید؟»    │
│     درخواست گره جدید       │
└────────────────────────────┘

۶ سیم‌کشی و گره‌های اتصال (Wiring)

۶.۱ رفتار اتصال

   (درگ از دسته خروجی)                  (هنگام رها کردن)
      ① ◯──┐                          ┌──◯ ② ◯──┐
            │  ② سیم متحرک با نوک      │  ④ خط خطا
            │     دنبال‌کننده         │    قرمز اگر نامعتبر
            ▼                          ▼
   [گره منبع]  ····◯(ghost)····►  [گره مقصد معتبر]
                                       ③ Snap به دسته ورودی با بزرگنمایی

۶.۲ منطق «می‌توان متصل کرد؟» (Valid Connection)

  قواعد اعتبارسنجی هنگام سیم‌کشی:

  ۱) نوع خروجی سازگار با نوع ورودی؟
        ├─ همه → همه          ⇒ مجاز (پیش‌فرض)
        └─ شرط دارای خروجی‌های TRUE/FALSE  ⇒ مجاز فقط به گره بعدی

  ۲) اتصال خود-به-خود؟ (self-loop)
        └─ ممنوع ❌

  ۳) اتصال متناوب (برگشت به عقب)?
        └─ ممنوع ❌ (چون گراف باید DAG باشد)

  ۴) حداکثر یک منبع روی یک ورودی؟
        └─ باشد ⇒ جایگزینی با پیام «اتصال قبلی جایگزین شد»

  ۵) شاخه شرطی بدون مقصد؟
        └─ اجازه می‌شود، اما در «بررسی اعتبار» خطای هشداری می‌دهد

۷ پنل پیکربندی پویا (Config Panel)

این پنل هیچ فرم کدنویسی‌شده‌ای ندارد. فرم کاملاً از schema همان گره (بخش ۶ از Doc 02) ساخته می‌شود. این یعنی هر ماژول جدید، فرم جدید و بدون تغییر در کد فرانت.

┌───────────────────────────────────┐
│  ← ایجاد مخاطب           [ بستن ]│   ← هدر: نام فارسی + اسلاگ
│  crm.contact.create               │
│───────────────────────────────────│
│  ① ردیف‌های اصلی فرم              │
│                                   │
│  نام [________________] *         │   ← required = ستاره قرمز
│  ایمیل[________________] 📋{{ }}  │   ← دکمه انتخاب متغیر
│  وضعیت[  بکس لیست  ▾ ]           │   ← options از سرور
│                                   │
│───────────────────────────────────│
│  ▾ بخش پیشرفته (۴)                │   ← جمع‌شده به‌صورت پیش‌فرض
│    رفتار تکراری [ در صورت تکرار ]│
│    رشته خطا   [ ]                │
│───────────────────────────────────│
│  📖 مستندات این گره  ·  🐞 آزمایش  │   ← لینک‌های کمکی
│───────────────────────────────────│
│         [ذخیره]   [آزمایش گره]     │   ← پایین‌چسب
└───────────────────────────────────┘

۷.۱ انواع فیلد و رفتار هرکدام

۷.۲ اعتبارسنجی سه‌لایه

۸ انتخاب متغیر (Variable Picker)

این کوچک‌ترین اما سخت‌ترین بخش کل Builder است. اگر کاربر نتواند «نتیجه گره قبلی» را در یک فیلد قرار دهد، کل ارزش اتوماسیون از بین می‌رود.

۸.۱ روش‌های انتخاب متغیر

۸.۲ ساختار مودال انتخاب متغیر

┌──────────────────────────────────────────────────┐
│  انتخاب متغیر                🔍 جست‌وجو...      │
│──────────────────────────────────────────────────│
│  ▾ Trigger — لیدفرم                               │
│     email         │ maryam@acme.ir       [درج]  │
│     full_name     │ مریم احمدی           [درج]  │
│     utm_source    │ instagram            [درج]  │
│  ▾ گره ۱ — ایجاد مخاطب                           │
│     contact.id    │ ctc_01J8X...         [درج]  │
│     contact.status│ new                  [درج]  │
│  ▾ گره ۲ — ارسال پیامک                            │
│     status        │ sent                 [درج]  │
│  ▾ Environment                                    │
│     tenant.name   │ آکادمی رشد           [درج]  │
│──────────────────────────────────────────────────│
│  💡 فقط متغیرهای گره‌های «قبل این نقطه» نمایش   │
│     داده می‌شوند — ترتیب بر اساس وابستگی گراف    │
└──────────────────────────────────────────────────┘

۸.۳ تصمیم کلیدی: «فقط گره‌های قبلی»

۹ اجرای آزمایشی و دیباگ زنده

پس از ساخت، کاربر باید «ببیند چه اتفاقی می‌افتد». این مهم‌ترین بخش از نظر اعتمادسازی است.

۹.۱ گردش کار آزمایش

  ۱) کلیک «آزمایش» در نوار پایین
         │
         ▼
  ۲) مودال «ورودی آزمایشی»:
        ├─ (الف) استفاده از آخرین وب‌هوک دریافتی (ذخیره‌شده)
        ├─ (ب) قالب JSON خالی
        ├─ (ج) بارگذاری Sample Payload پیشنهادی
        └─ (د) «اجرای گام‌به‌گام» (Step-by-step)
         │
         ▼
  ۳) شروع اجرا — نوار پیشرفت روی کانواس
        · گره در حال اجرا:  حاشیه آبی + پالس
        · گره انجام‌شده:    ● سبز + نمایش زمان (ms)
        · گره شکست‌خورده:   ✖ قرمز + پیام
        · گره ردشده (branch): طوسی + «Missed»
         │
         ▼
  ۴) پنل نتیجه (جایگزین پنل پیکربندی)
        ├─ جمع‌بندی: موفق/ناموفق + مدت کل
        ├─ هر گره: [ورودی] [خروجی] [خطا] با JSON مرتب
        ├─ دکمه «اجرای مجدد با همین ورودی»
        ├─ دکمه «ذخیره به‌عنوان Test Case»
        └─ دکمه «رفتن به اجراهای واقعی»
         │
         ▼
  ۵) در حالت «گام‌به‌گام» ⇒ با دکمه «قدم بعدی» هر گره
     جدا اجرا می‌شود و خروجی قبلی درون متن بعدی درج می‌شود

۱۰ نمایش خطا و لبه‌ها (Error UX)

خطا باید به‌مکان (گره خاص)، به‌زمان (کدام تلاش) و با راه‌حل نمایش داده شود. خطای بی‌مکان و بدون راه‌حل، کاربر را از محصول فراری می‌دهد.

۱۰.۱ چهار سطح خطا

۱۰.۲ آناتومی نمایش خطا روی یک گره

   ┌──────────────────────────────┐
   │ ● HTTP Request            ⚠  │  ← بج قرمز گوشه بالا
   │──────────────────────────────│
   │  ارسال به CRM                │
   │  ⛔ 401 Unauthorized          │  ← کد خطای ماشین‌خوان
   │  ⚠ توکن منقضی است            │  ← خطای انسانی (فارسی)
   │──────────────────────────────│
   │  🔄 تلاش ۲ از ۳ · ۱۲ ثانیه بعد│  ← وضعیت retry
   └──────────────────────────────┘
        │ کلیک
        ▼
   ┌──────────────────────────────┐
   │ پنل خطا (Overlay):           │
   │ · زمان دقیق وقوع             │
   │ · کد HTTP + Response کامل     │
   │ · Payload ارسالی (mask شده)   │
   │ · خلاصه خطای بک‌اند           │
   │                              │
   │ [ویرایش توکن] [تلاش مجدد]     │
   │ [دیدن مستندات]                │
   └──────────────────────────────┘

۱۰.۳ جریان تصمیم‌گیری خطا

  گره شکست می‌خورد
       │
       ├─ آیا قابل تکرار است؟ (timeout / 5xx / 429)
       │     ├─ بله ⇒ زمان‌بندی تکرار با backoff نمایی
       │     │        نمایش «تلاش ۲ از ۳» روی گره
       │     └─ خیر ⇒ خطای نهایی + متوقف شدن مسیر
       │
       ├─ آیا شاخه خطای (error branch) دارد؟
       │     └─ بله ⇒ هدایت خطا به آن شاخه + علامت زرد
       │
       └─ آیا «ادامه در صورت خطا» فعال است؟
             └─ بله ⇒ ثبت خطا + ادامه مسیر بعدی
                      با علامت زرد به جای قرمز

۱۱ ذخیره، وضعیت و بازگشت نسخه

۱۱.۱ تمایز حیاتی «ذخیره» و «انتشار»

  [ذخیره (Save)]                      [انتشار (Publish)]
       │                                      │
       ▼                                      ▼
  ثبت پیش‌نویس فعلی                     اعتبارسنجی کامل گراف
  قابل ویرایش در زمان بعدی              ساخت snapshot در workflow_versions
  اجرای واقعی تغییر نمی‌کند              افزایش version + ثبت published_at
                                        اجرای واقعی از این لحظه ← نسخه جدید
                                        نسخه قبلی دست‌نخورده باقی می‌ماند

  ══════════════════════════════════════════════════════
  خروج از صفحه با تغییرات ذخیره‌نشده:
  «تغییرات ذخیره‌نشده دارید. بدون ذخیره خارج می‌شوید؟»

۱۲ کیبورد شورتکات‌ها

کاربر پرکاربرد با کیبورد ۳ برابر موس سریع است. همه شورتکات‌ها در راهنمای شناور (?) و هنگام اولین ورود معرفی می‌شوند.

۱۳ حالت‌های خالی و بارگذاری (Empty / Loading)

۱۳.۱ حالت‌های ارتباطی (Offline / Reconnect)

۱۴ واکنش‌گرایی (Responsive)

Builder یک ابزار دسکتاپ است، اما باید در تبلت هم کار کند. موبایل فقط خواندنی است.

۱۵ دسترسی‌پذیری (Accessibility)

۱۶ فهرست کامپوننت‌ها (Component Inventory)

فهرست کامل کامپوننت‌های Vue مورد نیاز Builder با مسئولیت هرکدام. این فهرست مبنای تخمین توسعه است.

۱۶.۱ کامپوننت‌های کانواس و گراف

۱۶.۲ کامپوننت‌های پالت و پیکربندی

۱۶.۳ کامپوننت‌های متغیر، آزمایش و پیام

۱۷ معماری فنی و Pinia Store

۱۷.۱ ساختار Store

// stores/workflow/builder.ts — قلب وضعیت Builder
interface BuilderState {
    meta:      WorkflowMeta;        // نام، وضعیت، نسخه
    nodes:     BuilderNode[];       // گره‌های روی کانواس
    edges:     BuilderEdge[];       // سیم‌ها
    selection: string[];            // گره‌های انتخاب‌شده
    history:   HistoryStack;        // Undo/Redo (حداکثر ۵۰ قدم)
    dirty:     boolean;             // تغییرات ذخیره‌نشده
    saving:    boolean;             // در حال ذخیره
    runState:  RunState | null;     // وضعیت اجرای آزمایشی
}

interface BuilderActions {
    addNode(type: string, pos: XY): BuilderNode;
    removeNode(id: string): void;
    connect(src: HandleRef, dst: HandleRef): BuilderEdge | null;
    updateNodeConfig(id: string, patch: ConfigPatch): void;
    validate(): ValidationIssue[];
    testRun(payload: TestPayload): Promise<TestResult>;
    publish(): Promise<VersionInfo>;
}

۱۷.۲ جریان داده (Data Flow)

  Vue Flow (view)  ◄──►  Pinia Store (state)
          │                      │
          │  drag / connect      │  debounced autosave (2s)
          ▼                      ▼
     Layout cache (pos)   API Client (useWorkflowApi)
                                   │
                        ┌──────────┴──────────┐
                        ▼                     ▼
                 POST /draft            POST /validate
                 (ذخیره پیش‌نویس)       (بررسی اعتبار)

  قوانین:
    ✦ Store هرگز مستقیم به API وصل نیست؛ فقط از طریق composable
    ✦ تاریخچه Undo فقط در حافظه است (بین رفرش‌ها باقی نمی‌ماند)
    ✦ هر تغییر → dirty=true → autosave فعال می‌شود

۱۷.۳ الزامات فنی کانواس

۱۸ معیارهای موفقیت و تست کاربردپذیری

۱۸.۱ شاخص‌های کلیدی (KPI)

۱۸.۲ سناریوهای تست کاربردپذیری (۵ کاربر واقعی)

۱۹ نقشه پیاده‌سازی فرانت

پیاده‌سازی Builder در ۶ اسپرینت دو‌هفته‌ای موازی با توسعه بک‌اند (تیم فرانت ۱ نفر).

۲۰ جمع‌بندی و گام بعدی

۲۰.۱ سند در یک نگاه