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

استاندارد تدوین گردش‌کار و وضعیت‌ها در تریپیلون

۱. هدف

Workflow مشخص می‌کند یک فرایند یا موجودیت در طول زمان چگونه تغییر می‌کند، چه رویدادی تغییر را آغاز می‌کند، چه Actor یا سیستمی مسئول آن است و در شکست، تکرار یا وقفه چه اتفاقی می‌افتد.

این راهنما مرجع تدوین Workflow و State Machine برای همه ماژول‌های تریپیلون است.

۲. جایگاه در فرایند طراحی ماژول

ترتیب استاندارد:

  1. هدف، محدوده و سناریوها
  2. User Flow
  3. Workflow و وضعیت‌ها
  4. دسترسی‌ها
  5. اعلان‌ها
  6. خطاها و موارد خاص
  7. Information Architecture و Wireframe

Workflow باید بر تصمیم‌های تأییدشده مراحل قبل تکیه کند و نباید برای پرکردن خلأ سناریو، Business Rule جدید را پنهانی قطعی کند.

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

Domain Model

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

User Flow

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

Workflow

هماهنگی رویدادها، وضعیت‌ها، نقش‌ها و سامانه‌ها را در طول زمان نشان می‌دهد.

State Machine

چرخه عمر یک موجودیت مشخص و Transitionهای مجاز آن را تعریف می‌کند.

Sequence Diagram

ترتیب تعامل میان Actorها و سامانه‌ها را برای یک اجرای مشخص نشان می‌دهد.

Wireframe

چیدمان صفحه و کنترل‌های رابط کاربری را تعریف می‌کند.

Workflow نباید محل تصمیم‌گیری درباره جای دکمه، ساختار منو یا جزئیات فنی API باشد.

۴. چه زمانی Workflow لازم است؟

Workflow زمانی لازم است که حداقل یکی از شرایط زیر وجود داشته باشد:

  • موجودیت در طول زمان چند وضعیت دارد.
  • چند Actor یا سامانه مسئول بخش‌های مختلف فرایند هستند.
  • فرایند Async است یا نتیجه آن بلافاصله مشخص نمی‌شود.
  • Retry، Timeout، Callback یا درخواست تکراری وجود دارد.
  • تغییر باید اتمیک یا قابل Rollback باشد.
  • تأیید، رد، لغو، تعلیق یا انقضا وجود دارد.
  • اعلان یا اقدام بعدی به تغییر وضعیت وابسته است.
  • Audit و اثبات Actor اقدام اهمیت دارد.

برای یک مسیر ساده و هم‌زمان که فقط اقدام کاربر و پاسخ سامانه را نشان می‌دهد، User Flow کافی است.

۵. واحد استاندارد Workflow

هر State Machine باید فقط چرخه عمر یک موجودیت یا یک بُعد وضعیت را پوشش دهد.

نمونه‌های درست:

  • Payment Status
  • Invitation Envelope Status
  • SMS Delivery Attempt Status
  • Role Acceptance Status
  • Support Ticket Status

نمونه نادرست:

  • یک State Machine مشترک برای Delivery پیامک، پذیرش Role و Membership

اگر دو وضعیت می‌توانند مستقل از هم تغییر کنند، باید در دو State Machine جدا باشند.

۶. پیش‌نیازهای شروع

  • سناریوهای تأییدشده
  • User Flowهای مرتبط
  • Business Ruleهای مؤثر
  • موجودیت یا فرایند صاحب وضعیت
  • Actorهای مجاز
  • رویدادهای آغازکننده
  • نتیجه‌های موفق، ناموفق و موقت
  • الزامات Audit، اعلان و بازیابی

ابهام باید با برچسب «تصمیم باز» ثبت شود و نباید به‌عنوان وضعیت قطعی وارد پیاده‌سازی شود.

۷. خروجی استاندارد سند

هر سند Workflow در سطح ماژول باید شامل این اجزا باشد:

  1. هدف و مرزبندی
  2. فهرست Workflowها
  3. واژه‌نامه وضعیت‌ها
  4. State Machine هر موجودیت
  5. Transition Table
  6. Workflowهای چندنقشی یا چندسیستمی
  7. قواعد Retry، Idempotency و Rollback
  8. اعلان‌ها و Auditهای وابسته
  9. Transitionهای ممنوع
  10. تصمیم‌های باز
  11. معیارهای پذیرش

۸. شناسنامه استاندارد Workflow

فیلد توضیح
شناسه مانند OBM-WF-01
عنوان چرخه عمر یا نتیجه فرایند
نوع State Machine، Sequence یا Orchestration
موجودیت اصلی صاحب وضعیت
سناریوهای مرجع سناریوهای تأییدشده
User Flowهای مرجع Flowهای قابل مشاهده مرتبط
Actorها نقش‌ها و سامانه‌های اثرگذار
رویداد شروع Trigger آغاز
وضعیت شروع Initial State
وضعیت‌های پایانی Terminal States
قواعد مرتبط Business Ruleها
حساسیت مالی، دسترسی، حقوقی یا عادی
تصمیم‌های باز موارد تأییدنشده

۹. واژه‌نامه وضعیت‌ها

برای هر وضعیت این موارد ثبت شود:

فیلد توضیح
کد انگلیسی، پایدار و UPPER_SNAKE_CASE
عنوان فارسی نام قابل فهم برای تیم محصول
تعریف شرط دقیق حضور موجودیت در وضعیت
نوع موقت، پایدار، پایانی، خطا یا تعلیق
ورود مجاز Eventها و وضعیت‌های مبدأ
خروج مجاز Eventها و وضعیت‌های مقصد
قابل نمایش به کاربر بله، خیر یا با عنوان متفاوت
محدودیت اقدام اقدام‌های مجاز و غیرمجاز

نام وضعیت باید درباره «وضعیت موجودیت» باشد، نه نام اقدام. برای نمونه PAID وضعیت است و PAY اقدام.

۱۰. Transition Table

قالب استاندارد:

از وضعیت Event Actor Guard Action / Side Effect به وضعیت خطای جایگزین Audit
DRAFT تأیید مدیر مدیر مجاز داده کامل است ثبت زمان تأیید APPROVED حفظ DRAFT الزامی

قواعد Transition

  • هر Transition یک Event مشخص دارد.
  • Actor یا System مسئول Event مشخص است.
  • Guard باید قابل ارزیابی و بدون ابهام باشد.
  • Side Effect با تغییر وضعیت اشتباه گرفته نشود.
  • اگر Action شکست بخورد، وضعیت پایدار بعدی مشخص باشد.
  • Transition حساس باید Audit شود.
  • Transition تکراری باید نتیجه قبلی را برگرداند یا امن رد شود.

۱۱. انواع وضعیت

وضعیت موقت

پردازش در جریان است و نباید پایان موفق یا ناموفق فرض شود؛ مانند UNDER_REVIEW.

وضعیت پایدار

موجودیت می‌تواند بدون پردازش فعال در آن باقی بماند؛ مانند DRAFT.

وضعیت پایانی

چرخه جاری از آن خارج نمی‌شود؛ مانند COMPLETED یا CANCELED، مگر Business Rule صریح برای بازگشایی وجود داشته باشد.

وضعیت خطا

پردازش شکست خورده است و مسیر Retry یا اقدام انسانی دارد.

وضعیت تعلیق

عملکرد موجودیت موقتاً متوقف است، اما پایان چرخه نیست؛ مانند SUSPENDED.

۱۲. Event، Command و Side Effect

  • Command: درخواست انجام کار؛ ممکن است پذیرفته یا رد شود.
  • Event: رخداد ثبت‌شده‌ای که اتفاق افتاده است.
  • State: وضعیت پایدار پس از Event.
  • Side Effect: نتیجه جانبی مانند ارسال SMS، ایجاد Audit یا اعلان.

نمونه:

  • Command: «ارسال دعوت»
  • Event: INVITATION_SEND_REQUESTED
  • State: Envelope همچنان ACTIVE
  • Side Effect: ایجاد Delivery Attempt

ارسال SMS نباید به‌تنهایی وضعیت پذیرش Role را تغییر دهد.

۱۳. Retry، Idempotency و درخواست تکراری

برای عملیات حساس مشخص شود:

  • کلید Idempotency چیست؟
  • Retry خودکار است یا دستی؟
  • حداکثر تعداد و فاصله Retry چقدر است؟
  • کدام Side Effect نباید تکرار شود؟
  • درخواست تکراری نتیجه قبلی را برمی‌گرداند یا رد می‌شود؟
  • در شکست جزئی، چه داده‌ای حفظ می‌شود؟

در پرداخت، ایجاد ساختمان، Import، دعوت گروهی و جابه‌جایی Role باید رفتار درخواست تکراری صریح باشد.

۱۴. عملیات اتمیک و Rollback

اگر موفقیت به چند تغییر وابسته است:

  1. مرز تراکنش مشخص شود.
  2. ترتیب تغییرها ثبت شود.
  3. شکست هر گام و وضعیت باقی‌مانده مشخص شود.
  4. Rollback یا Compensating Action تعریف شود.
  5. Retry نباید رکورد تکراری ایجاد کند.

نمونه: در تغییر مدیر، سلب Role قبلی و فعال‌سازی Role جدید باید یک نتیجه واحد داشته باشند؛ نباید ساختمان بدون مدیر یا دارای دو مدیر راه‌اندازی ناخواسته باقی بماند.

۱۵. Transitionهای ممنوع

فقط Transitionهای مجاز کافی نیستند. تغییرهای پرریسک ممنوع نیز ثبت شوند.

نمونه:

  • FAILED مستقیم به SUCCEEDED بدون اعتبارسنجی دوباره پرداخت
  • PENDING_ACCEPTANCE به ACTIVE بدون پذیرش شخص
  • CANCELED به ACTIVE بدون ایجاد درخواست جدید
  • حذف Person برای پایان Membership

۱۶. انتخاب نمودار Mermaid

نیاز نمودار
چرخه عمر یک موجودیت stateDiagram-v2
تعامل زمانی میان Actorها و سامانه‌ها sequenceDiagram
Orchestration کسب‌وکاری با تصمیم‌ها flowchart

یک نمودار نباید هم‌زمان جای State Machine و Sequence Diagram را بگیرد.

قواعد مشترک

  • هر نمودار accTitle و accDescr داشته باشد.
  • شناسه‌ها انگلیسی و پایدار باشند.
  • عنوان‌ها و توضیح‌های قابل مشاهده فارسی باشند.
  • نمودار پیچیده به چند نمودار کوچک‌تر شکسته شود.
  • قابلیت‌های Beta فقط پس از بررسی Renderer پروژه استفاده شوند.
  • نمودار در محیط واقعی مستندات Render و بازبینی شود.

۱۷. استاندارد State Diagram

  • از stateDiagram-v2 استفاده شود.
  • شروع و پایان با [*] مشخص شوند.
  • وضعیت با شناسه انگلیسی و عنوان فارسی تعریف شود.
  • Transition با Event یا شرط روشن برچسب بخورد.
  • از Composite State فقط زمانی استفاده شود که حالت‌های داخلی واقعاً یک چرخه مستقل دارند.
  • Stateهای موازی فقط برای ابعاد واقعاً مستقل استفاده شوند؛ در اغلب اسناد محصول، نمودارهای جدا خواناترند.
stateDiagram-v2 accTitle: نمونه چرخه عمر درخواست accDescr: درخواست از پیش‌نویس به بررسی و سپس تأیید یا رد می‌رود state "پیش‌نویس" as DRAFT state "در حال بررسی" as UNDER_REVIEW state "تأییدشده" as APPROVED state "ردشده" as REJECTED [*] --> DRAFT DRAFT --> UNDER_REVIEW: ارسال درخواست UNDER_REVIEW --> APPROVED: تأیید UNDER_REVIEW --> REJECTED: رد APPROVED --> [*] REJECTED --> [*]

۱۸. استاندارد Sequence Diagram

  • Participantها از ابتدا و با ترتیب خواندن تعریف شوند.
  • برای بازیگر انسانی از actor و برای سامانه از participant استفاده شود.
  • autonumber برای فرایندهای بیش از پنج پیام فعال شود.
  • alt برای مسیرهای جایگزین، opt برای اقدام اختیاری و critical برای عملیات اتمیک استفاده شود.
  • پاسخ Sync و Async از نظر نوع پیکان قابل تشخیص باشد.
  • جزئیات Endpoint، Payload و Protocol وارد سند محصول نشوند.
sequenceDiagram accTitle: نمونه اعتبارسنجی پرداخت accDescr: سامانه نتیجه پرداخت را از سرویس پرداخت بررسی و نتیجه معتبر را ثبت می‌کند autonumber actor User as کاربر participant App as تریپیلون participant PSP as سرویس پرداخت User->>App: بازگشت از درگاه App->>PSP: درخواست اعتبارسنجی نتیجه PSP-->>App: نتیجه معتبر alt پرداخت موفق App-->>User: نمایش موفقیت else نتیجه نامشخص App-->>User: نمایش «در حال بررسی» end

۱۹. Audit و اعلان

برای هر Transition مهم مشخص شود:

  • چه کسی اقدام را آغاز کرده است؟
  • زمان و وضعیت قبل و بعد چیست؟
  • دلیل یا مدرک لازم است؟
  • چه گیرنده‌ای باید مطلع شود؟
  • اعلان بخشی از موفقیت Transition است یا Side Effect قابل Retry؟

شکست اعلان معمولاً نباید Transition اصلی را Rollback کند، مگر Business Rule صریح خلاف آن را تعیین کرده باشد.

۲۰. معیارهای پذیرش Workflow

  • موجودیت یا فرایند صاحب Workflow روشن است.
  • ابعاد وضعیت مستقل از هم جدا شده‌اند.
  • Initial State و Terminal Stateها مشخص‌اند.
  • همه Stateها تعریف دقیق دارند.
  • تمام Transitionها Event، Actor و Guard دارند.
  • Side Effect از تغییر State جدا شده است.
  • مسیر خطا، Retry و بازیابی مشخص است.
  • عملیات تکراری رفتار امن دارند.
  • عملیات چندمرحله‌ای مرز اتمیک یا Rollback دارند.
  • Transitionهای ممنوع ثبت شده‌اند.
  • اعلان و Audit وابسته مشخص‌اند.
  • تصمیم‌های حقوقی یا محصولی باز علامت‌گذاری شده‌اند.
  • Workflow با Business Ruleها و User Flowها تناقض ندارد.
  • جزئیات UI، IA و API وارد سند نشده‌اند.
  • نمودارهای Mermaid دارای accTitle و accDescr هستند.
  • نمودارها در Renderer واقعی مستندات بررسی شده‌اند.

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

  1. سناریوها و User Flowهای تأییدشده استخراج شوند.
  2. موجودیت‌ها و فرایندهای دارای چرخه عمر شناسایی شوند.
  3. ابعاد وضعیت مستقل از هم جدا شوند.
  4. فهرست Workflowها و ماتریس پوشش ساخته شود.
  5. واژه‌نامه Stateها تدوین شود.
  6. Transition Table نوشته شود.
  7. Guard، Side Effect، Retry و Audit تکمیل شوند.
  8. Transitionهای ممنوع و تصمیم‌های باز ثبت شوند.
  9. State Diagramها ترسیم شوند.
  10. برای تعامل‌های حساس، Sequence Diagram تهیه شود.
  11. تناقض با Business Rule و User Flow کنترل شود.
  12. نمودارها Render و بازبینی شوند.
  13. پس از تأیید Workflow، اسناد دسترسی، اعلان و خطا تکمیل شوند.

۲۲. منابع مرجع Mermaid