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

استاندارد تدوین اعلان‌ها در تریپیلون

۱. هدف

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

اعلان باید اطلاعات مهم و به‌موقع را منتقل کند؛ نه اینکه جای خطای صفحه، گزارش فعالیت یا وضعیت قابل مشاهده داخل ماژول را بگیرد.

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

اعلان‌ها پس از نهایی‌شدن سناریو، User Flow، Workflow و Access Control طراحی می‌شوند.

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

۳. مرزبندی

Feedback رابط کاربری

پاسخ همان لحظه به Action کاربر است؛ مانند خطای فرم، پیام موفقیت Save یا نتیجه پرداخت. این Feedback الزاماً Notification نیست.

Notification

پیامی است که به‌دلیل Event مهم، خارج از Context فعلی یا برای مراجعه بعدی کاربر ایجاد می‌شود.

Message Center

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

Audit

رکورد اثبات می‌کند چه اتفاقی افتاده است. هر Audit Event نباید به Notification تبدیل شود.

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

حداقل یکی از این شرایط باید برقرار باشد:

  • کاربر هنگام وقوع Event در Context مربوط حضور ندارد.
  • Action یا تصمیم کاربر لازم است.
  • وضعیت مهم Async نهایی شده است.
  • تغییر امنیتی یا دسترسی مهم رخ داده است.
  • کاربر باید از تغییر رابطه، مسئولیت یا Scope خود آگاه شود.
  • عدم اطلاع می‌تواند باعث زیان، سردرگمی یا ریسک امنیتی شود.

برای Saveهای عادی، تغییرات قابل مشاهده در همان صفحه یا هر Event داخلی، اعلان جدا ساخته نمی‌شود.

۵. کانال‌ها

کانال کاربرد
Inline Feedback پاسخ همان لحظه در صفحه
In-app / Message Center منبع پایدار پیام داخل محصول
Push جلب توجه کاربر دارای اپ فعال
SMS OTP، Invitation، Event امنیتی یا Fallback محدود
Operational Alert هشدار داخلی برای تیم پلتفرم

۶. سطح اولویت

سطح نام تعریف
P0 امنیتی فوری تغییر دسترسی بحرانی یا Incident
P1 نیازمند اقدام کاربر باید برای ادامه فرایند اقدام کند
P2 مهم نتیجه مهم یا تغییر Scope بدون اقدام فوری
P3 اطلاع‌رسانی قابل مشاهده در زمان مناسب یا Digest

اولویت بالا نباید برای افزایش نرخ مشاهده سوءاستفاده شود.

۷. Event Catalog

برای هر Event این فیلدها ثبت شوند:

فیلد توضیح
شناسه مانند OBM-NOT-01
Event رخداد قطعی آغازکننده
شرط ارسال Guard ایجاد Notification
مخاطب شخص یا Role هدف
اولویت P0 تا P3
کانال اصلی In-app، Push یا SMS
Fallback کانال جایگزین و شرط آن
Action مقصد یا اقدام مرتبط
Dedup Key جلوگیری از پیام تکراری
Preference قابل خاموش‌کردن یا الزامی
داده حساس محدودیت محتوای Preview
Audit الزام ثبت

۸. Recipient Resolution

  • مخاطب در زمان ایجاد Notification از رابطه معتبر همان Event استخراج می‌شود.
  • Recipient نباید فقط از شماره، Role یا Scope قدیمی Cache‌شده تعیین شود.
  • برای Eventهای واحد، رابطه معتبر در Effective Date بررسی می‌شود.
  • برای Role Decision، گیرندگان مدیریتی بر اساس Permission فعلی تعیین می‌شوند.
  • Actor انجام‌دهنده Action فقط در صورت ارزش مستقل، Notification دریافت می‌کند.
  • اعلان نباید به Person یا Contact Point مورد اختلاف ارسال شود.

۹. Channel Policy

SMS الزامی

  • OTP
  • Invitation اولیه و Resend
  • تغییر دسترسی امنیتی بحرانی

In-app و Push

  • نتیجه Async
  • Action موردنیاز
  • تغییر Role، Scope یا Ticket

SMS Fallback

فقط زمانی استفاده شود که:

  • Account Link یا Push فعال وجود ندارد؛
  • Event نیازمند اقدام است؛
  • محتوای SMS بدون افشای اطلاعات حساس قابل ارسال است.

۱۰. Preference

نوع رفتار
امنیت و OTP غیرقابل خاموش‌کردن در کانال ضروری
Invitation SMS الزامی طبق Business Rule
نیازمند اقدام In-app الزامی؛ Push قابل مدیریت؛ SMS فقط Fallback
مهم In-app الزامی؛ Push قابل مدیریت
اطلاع‌رسانی قابل تنظیم یا Digest

Preference کاربر نباید باعث حذف رکورد لازم از Message Center شود.

۱۱. Deduplication و Grouping

  • هر Notification یک Dedup Key پایدار دارد.
  • Retry Delivery، Notification منطقی جدید ایجاد نمی‌کند.
  • تغییر وضعیت جدید می‌تواند نسخه جدید Notification بسازد.
  • Eventهای گروهی برای مدیر به Summary یا Digest تبدیل می‌شوند.
  • Pushهای جایگزین‌پذیر می‌توانند Collapse Key مشترک داشته باشند.
  • Eventهای امنیتی مستقل و غیرقابل Collapse هستند.

نمونه:

payment:{payment_id}:{final_status}
invitation:{envelope_id}:{delivery_attempt}
role-decision:{role_assignment_id}:{decision}
support-grant:{grant_id}:{status}

۱۲. Retry

In-app

ثبت Notification باید Idempotent باشد و Retry نباید رکورد تکراری بسازد.

Push

  • خطای موقت قابل Retry است.
  • Token نامعتبر غیرفعال می‌شود.
  • Push منبع نهایی حقیقت نیست؛ App پس از بازشدن داده جاری را Fetch می‌کند.

SMS

  • OTP Rate Limit مستقل دارد.
  • Invitation Resend خودکار نیست.
  • Retry Invitation فقط با Action مدیر و فاصله مجاز انجام می‌شود.
  • شکست SMS نباید Membership یا Role State را تغییر دهد.

۱۳. Privacy و محتوا

  • Push و SMS نباید اطلاعات مالی، شماره واحد، مدرک یا Permission حساس را بی‌دلیل نمایش دهند.
  • متن Preview کوتاه و حداقلی باشد.
  • Deep Link فقط مقصد را باز می‌کند و جای Authorization نیست.
  • پس از بازشدن، Permission و Scope دوباره بررسی می‌شوند.
  • محتوای نقش‌های چندگانه در SMS خلاصه می‌شود و جزئیات داخل اپ نمایش داده می‌شوند.

۱۴. ساختار Template

هر Template باید شامل این اجزا باشد:

  • template_code
  • version
  • title
  • body
  • متغیرهای مجاز
  • کانال‌های مجاز
  • Deep Link مقصد
  • سطح حساسیت
  • محدودیت طول SMS
  • Fallback Copy
  • زبان و جهت متن

متن Template نباید تصمیم Business Logic را تعیین کند.

۱۵. Lifecycle اعلان و Delivery

Notification منطقی و Delivery Attempt دو موجودیت مستقل‌اند.

Notification

  • ACTIVE
  • READ
  • ARCHIVED
  • SUPERSEDED

Delivery Attempt

  • QUEUED
  • SENT
  • DELIVERED
  • FAILED
flowchart TD accTitle: ایجاد و ارسال اعلان accDescr: Event معتبر به Notification یکتا تبدیل می‌شود و هر کانال Delivery Attempt مستقل دارد EVENT(["وقوع Event قطعی"]):::start RULE{"شرط ارسال برقرار است؟"}:::decision SUPPRESS(["عدم ایجاد اعلان"]):::muted RECIPIENT["تعیین مخاطب و Scope جاری"]:::system DEDUP{"Notification مشابه موجود است؟"}:::decision UPDATE["به‌روزرسانی یا Grouping رکورد موجود"]:::system CREATE["ایجاد Notification منطقی"]:::system CHANNEL["انتخاب کانال بر اساس Policy و Preference"]:::system ATTEMPT["ایجاد Delivery Attempt برای هر کانال"]:::system RESULT{"نتیجه Delivery چیست؟"}:::decision DELIVERED(["ثبت نتیجه موفق"]):::success RETRY["Retry خطای موقت بدون Notification تکراری"]:::error EVENT --> RULE RULE -->|"خیر"| SUPPRESS RULE -->|"بله"| RECIPIENT --> DEDUP DEDUP -->|"بله"| UPDATE --> CHANNEL DEDUP -->|"خیر"| CREATE --> CHANNEL CHANNEL --> ATTEMPT --> RESULT RESULT -->|"موفق"| DELIVERED RESULT -->|"خطای موقت"| RETRY RETRY -.-> ATTEMPT classDef start fill:#DBEAFE,stroke:#2563EB,color:#172554,stroke-width:2px; classDef system fill:#F3F4F6,stroke:#6B7280,color:#111827; classDef decision fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px; classDef success fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px; classDef error fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D; classDef muted fill:#F9FAFB,stroke:#9CA3AF,color:#4B5563;

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

  • هر اعلان به Event قطعی متصل است.
  • Feedback صفحه با Notification اشتباه نشده است.
  • مخاطب و Scope در زمان Event معتبرند.
  • Actor بی‌دلیل به خودش اعلان دریافت نمی‌کند.
  • اولویت با میزان فوریت واقعی هماهنگ است.
  • SMS فقط در موارد ضروری یا Fallback استفاده می‌شود.
  • پیام گروهی به Digest تبدیل می‌شود.
  • Dedup Key مشخص است.
  • Retry رکورد منطقی تکراری ایجاد نمی‌کند.
  • Preference و پیام‌های الزامی از هم جدا هستند.
  • Push و SMS اطلاعات حساس افشا نمی‌کنند.
  • Deep Link هنگام بازشدن دوباره Authorization می‌شود.
  • Notification از Delivery Attempt جداست.
  • متن Template نسخه‌بندی می‌شود.
  • Eventهای منسوخ‌شده Supersede یا Archive می‌شوند.
  • کانال و Delivery واقعی در محیط محصول بررسی شده‌اند.

۱۷. روش اجرای استاندارد

  1. Eventهای قطعی Workflow استخراج شوند.
  2. Feedbackهای Inline حذف شوند.
  3. Eventهای ارزشمند برای کاربر انتخاب شوند.
  4. مخاطب و Scope هر Event تعیین شوند.
  5. اولویت و کانال اصلی مشخص شوند.
  6. Fallback و Preference تعریف شوند.
  7. Dedup Key، Grouping و Retry تکمیل شوند.
  8. Privacy و Deep Link بررسی شوند.
  9. Template Contract نوشته شود.
  10. Event Catalog و Recipient Matrix نهایی شوند.
  11. تست سناریوهای Delivery، Failure و Duplicate انجام شود.

۱۸. منابع