پرش به محتویات

استاندارد تدوین User Flow در تریپیلون

۱. هدف

User Flow نشان می‌دهد یک کاربر مشخص برای رسیدن به یک هدف مشخص، از چه گام‌ها و تصمیم‌هایی عبور می‌کند و سیستم در هر مرحله چه واکنشی دارد.

این سند مرجع تدوین User Flow برای تمام ماژول‌های تریپیلون است.

۲. پیش‌نیاز شروع

پیش از تدوین User Flow باید این موارد تا حد قابل قبول مشخص باشند:

  • هدف ماژول
  • محدوده و موارد خارج از محدوده
  • بازیگران و نقش‌ها
  • سناریوهای اصلی
  • قواعد کسب‌وکار مؤثر
  • وضعیت‌ها و موجودیت‌های کلیدی، در صورت وجود

اگر یکی از این موارد نامشخص باشد، Flow با «فرض موقت» ساخته و ابهام آن جداگانه ثبت می‌شود؛ فرض موقت نباید به‌عنوان تصمیم قطعی ارائه شود.

۳. مرزبندی با خروجی‌های دیگر

Domain Model

تعریف می‌کند چه موجودیت‌ها، روابط و وضعیت‌هایی در دامنه وجود دارند.

Workflow

هماهنگی فرایند میان چند نقش، تیم، سیستم یا بازه زمانی را نشان می‌دهد.

User Flow

مسیر یک بازیگر را برای دستیابی به یک هدف مشخص نشان می‌دهد.

Information Architecture

محل قرارگیری اطلاعات و قابلیت‌ها و ساختار دسترسی به آن‌ها را تعریف می‌کند.

Wireframe

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

در User Flow نباید درباره جای دکمه، شکل صفحه، رنگ، اندازه یا چیدمان تصمیم‌گیری شود.

۴. واحد استاندارد Flow

هر User Flow باید:

  • فقط یک بازیگر اصلی داشته باشد.
  • فقط یک هدف قابل سنجش را پوشش دهد.
  • نقطه شروع و پایان روشن داشته باشد.
  • به حداقل یک سناریوی تأییدشده متصل باشد.
  • مسیر اصلی، جایگزین و خطا را از هم جدا کند.

اگر بازیگر یا هدف عوض شود، معمولاً باید Flow مستقل ساخته شود.

۵. شناسنامه استاندارد

برای هر Flow ابتدا این شناسنامه تکمیل می‌شود:

فیلد توضیح
شناسه کد یکتا، مانند MEM-UF-01
عنوان فعل + موضوع + نتیجه مورد انتظار
ماژول نام ماژول
سناریوی مرجع شناسه یا عنوان سناریوی تأییدشده
بازیگر اصلی کاربری که هدف Flow متعلق به اوست
بازیگران فرعی نقش‌هایی که در مسیر اثر می‌گذارند
هدف کاربر نتیجه‌ای که کاربر می‌خواهد به آن برسد
نقطه شروع رویداد یا وضعیت آغازکننده
پیش‌شرط‌ها شرایط لازم پیش از شروع
محرک اقدامی که Flow را فعال می‌کند
نتیجه موفق وضعیت قابل مشاهده پس از موفقیت
نتیجه ناموفق وضعیت پایدار پس از توقف یا شکست
قواعد مرتبط قواعد کسب‌وکار مؤثر بر مسیر
فرضیات موارد تأییدنشده‌ای که Flow بر آن‌ها تکیه دارد
خارج از محدوده موارد نزدیک ولی خارج از این Flow

۶. ساختار مسیر

۶.۱ مسیر اصلی

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

  1. کاربر اقدام می‌کند.
  2. سیستم اعتبارسنجی یا پردازش می‌کند.
  3. در صورت نیاز، کاربر تصمیم بعدی را می‌گیرد.
  4. سیستم نتیجه و وضعیت جدید را اعلام می‌کند.

۶.۲ نقاط تصمیم

هر تصمیم باید:

  • به شکل یک پرسش روشن نوشته شود.
  • پاسخ‌های محدود و قابل تفکیک داشته باشد.
  • برای هر پاسخ، ادامه مسیر مشخص کند.
  • به یک قاعده کسب‌وکار یا انتخاب کاربر متصل باشد.

نمونه: «آیا شماره همراه قبلاً عضو این ساختمان است؟»

۶.۳ مسیرهای جایگزین

مسیر معتبر دیگری که همچنان می‌تواند کاربر را به همان هدف یا یک پایان قابل قبول برساند.

۶.۴ مسیرهای خطا

شرایطی که مانع ادامه مسیر می‌شوند. برای هر خطا باید مشخص شود:

  • علت خطا چیست؟
  • سیستم چه چیزی را به کاربر اعلام می‌کند؟
  • آیا خطا قابل بازیابی است؟
  • کاربر از کدام گام می‌تواند ادامه دهد؟
  • وضعیت داده‌ها پس از خطا چیست؟

۶.۵ لغو، خروج و وقفه

در Flowهای چندمرحله‌ای باید رفتار این حالت‌ها مشخص شود:

  • خروج عمدی کاربر
  • قطع ارتباط یا بسته‌شدن برنامه
  • انقضای زمان
  • ادامه‌دادن در مراجعه بعدی
  • لغو توسط نقش دیگر

۷. الگوی نوشتن گام‌ها

هر گام باید یک کنش یا واکنش مشخص داشته باشد:

شماره گام — بازیگر/سیستم — اقدام — نتیجه یا وضعیت

نمونه:

03 — سیستم — شماره همراه را با اعضای فعال ساختمان تطبیق می‌دهد — نتیجه تطبیق مشخص می‌شود.

قواعد نگارشی

  • از فعل فعال و دقیق استفاده شود.
  • هر گام فقط یک اقدام اصلی داشته باشد.
  • رفتار قابل مشاهده نوشته شود، نه جزئیات فنی پیاده‌سازی.
  • از نام‌گذاری ثابت نقش‌ها و وضعیت‌ها استفاده شود.
  • عبارت‌هایی مانند «سیستم بررسی می‌کند» بدون ذکر موضوع و خروجی بررسی کافی نیست.
  • متن پیام رابط کاربری فقط در صورت وجود الزام حقوقی یا کسب‌وکاری ثبت شود.

۸. قالب استاندارد خروجی

هر سند User Flow در سطح ماژول، پیش از Flowهای تفصیلی باید این اجزا را داشته باشد:

  1. وضعیت سند و مبنای استخراج Flowها
  2. هدف و مرزبندی سند
  3. راهنمای خواندن نمودارها
  4. ماتریس پوشش سناریوها
  5. نمای کلان ارتباط Flowها، در صورت وجود بیش از سه Flow
  6. Flowهای تفصیلی
  7. تصمیم‌های باز و Flowهای وابسته
  8. معیار پذیرش مجموعه Flowها

ماتریس پوشش سناریوها

شناسه Flow هدف کاربر بازیگر اصلی سناریوهای مرجع
[MOD]-UF-01 ... ... SCN-01، SCN-02

هر سناریوی تأییدشده باید حداقل در یک Flow پوشش داده شود. اگر یک سناریو به چند Flow مربوط است، ارتباط آن با همه Flowها ثبت می‌شود.

قالب Flow تفصیلی

# [شناسه] — [عنوان Flow]

## شناسنامه

- ماژول:
- سناریوی مرجع:
- بازیگر اصلی:
- بازیگران فرعی:
- هدف کاربر:
- نقطه شروع:
- پیش‌شرط‌ها:
- محرک:
- نتیجه موفق:
- نتیجه ناموفق:
- قواعد مرتبط:
- فرضیات:
- خارج از محدوده:

## مسیر اصلی

1. ...
2. ...
3. ...

## نقاط تصمیم

### D1 — [پرسش تصمیم]

- اگر ... → گام ...
- اگر ... → مسیر جایگزین A1

## مسیرهای جایگزین

### A1 — [عنوان]

1. ...
2. ...

## مسیرهای خطا

### E1 — [عنوان خطا]

- علت:
- واکنش سیستم:
- راه بازیابی:
- وضعیت نهایی داده:
- ادامه مسیر:

## لغو و وقفه

- ...

## رویدادها و اعلان‌های مهم

- رویداد:
- دریافت‌کننده:
- زمان ارسال:
- هدف:

## ابهام‌ها و تصمیم‌های باز

- ...

## معیارهای پذیرش Flow

- ...

۹. قواعد ترسیم نمودار

۹.۱. انتخاب نوع و سطح نمودار

  • برای User Flow از flowchart در Mermaid استفاده شود.
  • نمای کلان ماژول فقط ارتباط Flowها را نشان می‌دهد و جایگزین Flow تفصیلی نیست.
  • هر نمودار تفصیلی یک بازیگر اصلی و یک هدف اصلی دارد.
  • اگر بازیگر اصلی یا هدف تغییر کند، Flow مستقل ساخته شود.
  • اگر یک سناریو ذاتاً میان چند نقش، تیم یا بازه زمانی جابه‌جا می‌شود، بخش چندنقشی آن Workflow است؛ در User Flow فقط تجربه قابل مشاهده بازیگر اصلی نمایش داده شود.
  • State Machine، وضعیت‌های داخلی Ticket، Payment یا سایر موجودیت‌ها در سند Workflow تعریف شوند.

۹.۲. جهت و اندازه

  • جهت پیش‌فرض نمودارهای تفصیلی TD است تا شاخه‌ها تقاطع کمتری داشته باشند و نمودار در موبایل خواناتر باشد.
  • جهت LR فقط برای نمای کلان کوتاه و ارتباط چند Flow استفاده شود.
  • اگر نمودار بیش از حدود ۲۵ تا ۳۰ Node، بیش از ۷ Decision یا بیش از ۳ مسیر خطای مستقل دارد، شکستن آن به Flowهای کوچک‌تر بررسی شود.
  • مسیر اصلی باید در نگاه اول قابل دنبال‌کردن باشد.
  • در Flow پیچیده، نمای کلان، مسیر اصلی و استثناهای پرجزئیات در نمودارهای جدا ارائه شوند.

۹.۳. شناسه و متن Node

  • شناسه Node باید انگلیسی، کوتاه، معنادار و در همان نمودار یکتا باشد؛ مانند PAYMENT_RESULT.
  • متن قابل مشاهده Node باید فارسی و داخل کوتیشن قرار گیرد.
  • از شناسه‌های مبهم مانند A1 و B2 جز برای مثال‌های کوتاه استفاده نشود.
  • شناسه Node با تغییر جزئی متن نمایشی تغییر نکند تا Diff سند قابل پیگیری بماند.
  • هر Node فقط یک اقدام، واکنش، تصمیم یا پایان مشخص را نمایش دهد.
  • متن Node کوتاه باشد؛ جزئیات و قواعد تکمیلی زیر نمودار نوشته شوند.
  • از واژه end با حروف کوچک به‌عنوان شناسه Node استفاده نشود؛ این واژه می‌تواند Parser را دچار خطا کند.

نمونه:

flowchart TD accTitle: نمونه ورود کاربر accDescr: کاربر شماره موبایل را وارد می‌کند و پس از تأیید رمز یک‌بارمصرف وارد می‌شود START(["شروع"]) ENTER_MOBILE["واردکردن شماره موبایل"] OTP_VALID{"رمز یک‌بارمصرف معتبر است؟"} DONE(["ورود موفق"]) START --> ENTER_MOBILE --> OTP_VALID OTP_VALID -->|"بله"| DONE

۹.۴. معنا و شکل Nodeها

نوع شکل پیشنهادی کاربرد
شروع یا پایان (["متن"]) آغاز و نتیجه پایدار Flow
اقدام کاربر ["متن"] کنش بازیگر اصلی
واکنش سامانه ["متن"] اعتبارسنجی، پردازش یا پاسخ قابل مشاهده
تصمیم {"پرسش؟"} انشعاب بر اساس قاعده یا انتخاب
بازیگر یا سامانه بیرونی ["متن"] با Class مستقل درگاه، سرویس پیامک یا پشتیبانی
خطای قابل بازیابی ["متن"] با Class خطا توقفی که مسیر بازگشت دارد

شکل و متن باید معنا را منتقل کنند؛ رنگ به‌تنهایی نباید حامل معنا باشد.

۹.۵. تصمیم‌ها و اتصال‌ها

  • شروع و پایان با نام وضعیت مشخص شوند.
  • اقدام کاربر و واکنش سیستم از نظر بصری قابل تفکیک باشند.
  • هر لوزی فقط یک پرسش تصمیم داشته باشد.
  • تمام خروجی‌های Decision برچسب روشن مانند «بله/خیر»، «موفق/ناموفق» یا نام وضعیت داشته باشند.
  • مسیر اصلی خواناترین و کوتاه‌ترین مسیر باشد.
  • مسیرهای خطا بن‌بست مبهم نداشته باشند.
  • خط پیوسته برای مسیر اصلی یا جایگزین و خط‌چین برای Retry، بازگشت یا ادامه در مراجعه بعدی استفاده شود.
  • اتصال چند Node در یک خط فقط زمانی استفاده شود که خوانایی کد Mermaid را کاهش ندهد.
  • از اتصال‌های متقاطع زیاد و دست‌کاری افراطی چیدمان با Linkهای نامرئی خودداری شود.
  • جزئیات صفحه و کنترل‌های UI وارد نمودار نشوند.

۹.۶. پایان‌ها، خطا و Retry

  • پایان موفق، ناموفق و قابل ادامه باید از هم قابل تشخیص باشند.
  • «نمایش خطا» بدون مسیر بازیابی کافی نیست.
  • Retry باید به آخرین نقطه امن بازگردد، نه لزوماً به شروع Flow.
  • مشخص شود داده‌های ثبت‌شده پس از خطا حفظ می‌شوند یا خیر.
  • عملیات مالی یا ایجاد رکورد باید در برابر درخواست تکراری مسیر امن داشته باشد.
  • خطای موقت، نتیجه ناموفق قطعی و وضعیت «در حال بررسی» با هم ادغام نشوند.

۹.۷. رنگ و راهنمای خواندن

یک الگوی پیشنهادی برای همه ماژول‌ها:

Class معنا رنگ پیشنهادی
user اقدام بازیگر اصلی آبی
system واکنش سامانه خاکستری
decision تصمیم زرد
external بازیگر یا سامانه بیرونی بنفش
success پایان موفق یا قابل قبول سبز
error خطا یا توقف قابل بازیابی قرمز

اگر سند بیش از یک نمودار دارد، Legend یک‌بار در ابتدای سند نوشته و همین معنا در تمام نمودارها حفظ شود. مقدار دقیق رنگ‌ها می‌تواند با Design System مستندات هماهنگ شود.

نمونه Classها:

flowchart TD accTitle: نمونه رنگ و شکل در User Flow accDescr: نمونه‌ای از تفکیک اقدام کاربر، واکنش سامانه، تصمیم، خطا و پایان موفق START(["شروع"]):::start ACTION["اقدام کاربر"]:::user CHECK{"نتیجه معتبر است؟"}:::decision RESPONSE["واکنش سامانه"]:::system FAILURE["نمایش خطا"]:::error DONE(["پایان موفق"]):::success START --> ACTION --> CHECK CHECK -->|"بله"| RESPONSE --> DONE CHECK -->|"خیر"| FAILURE FAILURE -.->|"تلاش مجدد"| ACTION classDef start fill:#DBEAFE,stroke:#2563EB,color:#172554,stroke-width:2px; classDef user fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E; classDef system fill:#F3F4F6,stroke:#6B7280,color:#111827; classDef decision fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px; classDef external fill:#F3E8FF,stroke:#9333EA,color:#581C87; classDef success fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px; classDef error fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D;

۹.۸. دسترس‌پذیری

هر نمودار باید بلافاصله پس از تعریف نوع نمودار دارای این دو مقدار باشد:

  • accTitle: عنوان کوتاه و یکتای نمودار
  • accDescr: توضیح یک‌خطی درباره بازیگر، هدف و نتیجه مسیر

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

flowchart TD accTitle: ورود کاربر accDescr: کاربر شماره موبایل را وارد می‌کند و پس از تأیید رمز یک‌بارمصرف وارد سامانه می‌شود START(["شروع"]) --> MOBILE["ورود شماره موبایل"]

۹.۹. قواعد سازگاری Mermaid

  • متن فارسی، پرانتز، دونقطه و سایر نویسه‌های خاص داخل کوتیشن قرار گیرند.
  • شناسه Nodeها فقط با حروف انگلیسی، عدد و Underscore نوشته شوند.
  • از قابلیت‌های Beta برای سند مرجع محصول استفاده نشود، مگر سازگاری Renderer پروژه بررسی شده باشد.
  • از Markdown String، HTML Label یا Shapeهای جدید فقط در صورت نیاز واقعی و پس از بررسی خروجی استفاده شود.
  • Source نمودار باید خوانا باقی بماند؛ فشرده‌سازی چند اتصال در یک خط نباید نگهداری آن را دشوار کند.
  • هر نمودار پس از تغییر باید در Renderer واقعی مستندات بازبینی شود.

۱۰. کنترل کیفیت

پیش از تأیید هر User Flow بررسی شود:

  • Flow به یک هدف و سناریوی مشخص متصل است.
  • بازیگر اصلی فقط یک نقش است.
  • نقطه شروع و پایان روشن‌اند.
  • پیش‌شرط با اولین گام اشتباه نشده است.
  • مسیر اصلی بدون پرش منطقی کامل است.
  • تمام نقاط تصمیم شاخه خروجی دارند.
  • تمام شاخه‌های تصمیم برچسب صریح دارند.
  • مسیرهای جایگزین و خطا مشخص‌اند.
  • امکان بازیابی از خطا، در صورت وجود، تعریف شده است.
  • Retry به آخرین نقطه امن بازمی‌گردد.
  • خطای قطعی، وضعیت موقت و حالت «در حال بررسی» از هم جدا هستند.
  • وضعیت نهایی داده و عضویت/درخواست روشن است.
  • قواعد دسترسی و اختیار نقش‌ها رعایت شده‌اند.
  • اعلان‌های مؤثر بر ادامه فرایند ثبت شده‌اند.
  • فرضیات و تصمیم‌های باز از تصمیم‌های قطعی جدا هستند.
  • هیچ تصمیم مربوط به چیدمان Wireframe وارد Flow نشده است.
  • اصطلاحات با Domain Model و سایر Flowها سازگارند.
  • ماتریس پوشش، تمام سناریوهای تأییدشده را پوشش می‌دهد.
  • Diagram تفصیلی بیش از اندازه پیچیده نشده است.
  • شناسه Nodeها پایدار، انگلیسی و معنادار هستند.
  • متن قابل مشاهده Nodeها فارسی و داخل کوتیشن است.
  • Legend و معنای رنگ‌ها در همه نمودارهای سند ثابت است.
  • accTitle و accDescr برای هر نمودار تعریف شده‌اند.
  • نمودار بدون اتکا به رنگ قابل فهم است.
  • Syntax و Render نمودار در محیط واقعی مستندات بررسی شده‌اند.

۱۱. نام‌گذاری و نسخه‌بندی

الگوی شناسه:

[کد ماژول]-UF-[شماره دو رقمی]

نمونه برای ماژول راه‌اندازی و عضویت:

  • OBM-UF-01 — راه‌اندازی ساختمان توسط مدیر
  • OBM-UF-02 — پذیرش دعوت عضویت توسط ساکن
  • OBM-UF-03 — درخواست عضویت بدون دعوت

تغییر محتوای Flow با تاریخ و خلاصه تصمیم ثبت می‌شود. اگر هدف یا بازیگر اصلی تغییر کند، به‌جای بازنویسی Flow قبلی باید ایجاد Flow جدید بررسی شود.

۱۲. روش اجرای استاندارد برای هر ماژول

  1. فهرست سناریوهای تأییدشده استخراج می‌شود.
  2. سناریوها بر اساس «بازیگر + هدف» گروه‌بندی می‌شوند.
  3. ماتریس پوشش سناریو به Flow ساخته می‌شود.
  4. اگر بیش از سه Flow وجود دارد، نمای کلان ارتباط آن‌ها تهیه می‌شود.
  5. Flowهای اصلی و پرتکرار اولویت‌بندی می‌شوند.
  6. شناسنامه هر Flow تکمیل می‌شود.
  7. مسیر اصلی به‌صورت متنی نوشته می‌شود.
  8. نقاط تصمیم، مسیرهای جایگزین، خطا، لغو و وقفه افزوده می‌شوند.
  9. قواعد کسب‌وکار و وضعیت‌های دامنه کنترل می‌شوند.
  10. خطاهای قطعی، وضعیت‌های موقت و Retryهای امن از هم جدا می‌شوند.
  11. ابهام‌ها و Flowهای وابسته برای تصمیم‌گیری محصول جدا می‌شوند.
  12. پس از تأیید منطق، نمودار با استاندارد Mermaid این راهنما تهیه می‌شود.
  13. Syntax، دسترس‌پذیری و Render نمودار بررسی می‌شوند.
  14. ماتریس پوشش و معیار پذیرش مجموعه Flowها نهایی می‌شوند.
  15. در مرحله بعد، IA و Wireframe با اتکا به Flow تأییدشده ساخته می‌شوند.

۱۳. منابع مرجع Mermaid