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

استاندارد تدوین خطاها و موارد خاص در تریپیلون

۱. هدف

این راهنما روش استاندارد ثبت خطاها، وضعیت‌های غیرعادی، حالت‌های مرزی و مسیر بازیابی را برای همه ماژول‌های تریپیلون تعریف می‌کند.

هدف فقط نوشتن متن خطا نیست؛ باید مشخص شود:

  • چه اتفاقی افتاده است؟
  • آیا ادامه فرایند ممکن است؟
  • چه داده‌ای حفظ شده است؟
  • کاربر یا سامانه چه اقدام بعدی دارد؟
  • Retry امن است یا خیر؟
  • چه چیزی باید Log، Audit یا Escalate شود؟

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

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

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

۳. مرزبندی مفاهیم

Validation Error

ورودی کاربر با قواعد معتبر منطبق نیست.

Business Block

ورودی ممکن است معتبر باشد، اما Business Rule اجازه ادامه نمی‌دهد.

Conflict

داده یا وضعیت از زمان نمایش به کاربر تغییر کرده یا با رکورد جاری تعارض دارد.

Transient Failure

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

Pending State

نتیجه هنوز قطعی نیست. Pending خطای قطعی نیست و نباید با ظاهر شکست نمایش داده شود.

Partial Failure

بخشی از عملیات موفق و بخشی ناموفق است. موفقیت‌های معتبر حفظ می‌شوند، مگر عملیات ذاتاً اتمیک باشد.

Security / Authorization Failure

هویت، Permission، Scope یا Guard معتبر نیست. پاسخ نباید اطلاعات حساس افشا کند.

Empty State

نبود داده مورد انتظار است و خطا محسوب نمی‌شود.

۴. طبقه‌بندی استاندارد

کد دسته نمونه
VAL اعتبارسنجی مقدار منفی یا فیلد خالی
BUS مانع کسب‌وکاری کمتر از دو واحد
CON تعارض تغییر قیمت یا تداخل رابطه
TRN خطای موقت درگاه در دسترس نیست
PND نتیجه نامشخص پرداخت در حال بررسی
PAR شکست بخشی بخشی از SMSها ناموفق
SEC امنیت و دسترسی Scope نامعتبر
SUP نیازمند بررسی پشتیبانی مغایرت مبلغ

۵. شدت

سطح تعریف نمونه
SEV-1 خطر مالی، امنیتی یا ناسازگاری جدی مغایرت مبلغ یا شکست Switch مدیر
SEV-2 مسیر اصلی مسدود، داده حفظ شده و بازیابی ممکن خطای پرداخت یا Provisioning
SEV-3 Action جاری مسدود و با اصلاح کاربر حل می‌شود خطای فیلد یا Guard
SEV-4 Warning غیرمسدودکننده موبایل خالی در Import

شدت فنی با میزان برجستگی UI یکسان نیست.

۶. قرارداد استاندارد Error

فیلد توضیح
شناسه محصول مانند ERR-SET-07
دسته VAL، BUS و...
شدت SEV-1 تا SEV-4
Trigger شرط دقیق وقوع
رفتار سیستم تغییر یا عدم تغییر State
اثر روی داده حفظ، Rollback یا ثبت بخشی
نمایش Field، Summary، Banner، Page State، Modal یا Report
پیام کاربر مفهوم قابل فهم بدون جزئیات فنی
اقدام اصلی Action بازیابی
اقدام ثانویه در صورت نیاز
Retry دستی، خودکار، ممنوع یا زمان‌دار
Idempotency کلید یا رفتار ضدتکرار
Log / Audit سطح ثبت
Escalation شرط ارجاع به پشتیبانی

۷. الگوی پیام

پیام باید سه پرسش را پاسخ دهد:

  1. چه چیزی انجام نشد؟
  2. کاربر چه کاری می‌تواند انجام دهد؟
  3. داده قبلی حفظ شده است یا خیر، اگر اهمیت دارد؟

قواعد نگارشی

  • کوتاه، مستقیم و بدون سرزنش کاربر؛
  • استفاده از نام فیلد یا Action واقعی؛
  • پرهیز از «خطای ناشناخته» بدون مسیر بازیابی؛
  • پرهیز از نمایش Stack Trace، نام سرویس، Database یا کد داخلی؛
  • یکسان‌بودن متن Error Summary و خطای کنار فیلد؛
  • نمایش Reference ID فقط برای پیگیری پشتیبانی؛
  • کد داخلی محصول در UI عمومی نمایش داده نشود.

۸. الگوی نمایش

موقعیت نمایش پیشنهادی
یک فیلد خطای Inline کنار فیلد
چند فیلد Error Summary + لینک به فیلدها
Guard کسب‌وکاری Banner یا توضیح در Context
نتیجه نامشخص Page State مستقل
شکست کل صفحه Full-page State با Retry
Action مخرب یا حساس Confirmation Modal پیش از Action
Import چندردیفی Summary + گزارش ردیف‌ها
شکست بخشی Batch نتیجه تجمیعی و Retry موارد ناموفق

Toast نباید تنها محل نمایش خطای مسدودکننده یا غیرقابل بازیابی باشد.

۹. بازیابی استاندارد

Recovery Code معنا
FIX_INPUT اصلاح ورودی
REVIEW_CONFIRM مشاهده اثر و تأیید
RETRY تلاش مجدد امن
WAIT_RETRY انتظار تا پایان محدودیت
RELOAD دریافت وضعیت جاری
REAUTH تأیید دوباره هویت
USE_EXISTING استفاده از رکورد موجود
REUPLOAD اصلاح و بارگذاری فایل جدید
RESOLVE_DEPENDENCY تکمیل پیش‌نیاز
CONTACT_SUPPORT بررسی انسانی
NO_ACTION فقط اطلاع از وضعیت پایدار

۱۰. حفظ داده

  • Validation نباید ورودی‌های معتبر دیگر را پاک کند.
  • خطای شبکه نباید Draft یا درخواست معتبر را حذف کند.
  • شکست پرداخت نباید ساختمان ایجاد کند.
  • نتیجه نامشخص پرداخت نباید موفق یا ناموفق حدس زده شود.
  • Provisioning ناموفق نباید پرداخت را از بین ببرد.
  • Import اتمیک نباید داده ناقص ثبت کند.
  • شکست بخشی Batch نباید موفقیت‌های معتبر را Rollback کند.
  • عملیات جایگزینی باید اتمیک یا قابل Rollback باشد.

۱۱. Retry و Idempotency

  • Retry فقط از آخرین نقطه امن انجام می‌شود.
  • Action مالی یا ایجاد رکورد، Retry خودکار بدون Idempotency ندارد.
  • Double-click یا درخواست تکراری نباید رکورد جدید بسازد.
  • Retry Delivery پیام، State دامنه را تغییر نمی‌دهد.
  • Retry نامحدود ممنوع است و باید Backoff، Limit یا Escalation داشته باشد.

۱۲. امنیت و Privacy

  • خطای Authentication نباید وجود یا عدم وجود Account را بیش از نیاز افشا کند.
  • خطای Authorization نباید Resource نامرتبط را تأیید کند.
  • پاسخ خطای غیرمنتظره عمومی است و جزئیات فقط Server-side ثبت می‌شوند.
  • Token، OTP، اطلاعات بانکی، مدرک و Permission حساس در Log خام ثبت نمی‌شوند.
  • Error Reference قابل حدس و حاوی شناسه داخلی حساس نباشد.

۱۳. Logging، Audit و Monitoring

Log فنی

  • Error Type و Stack داخلی؛
  • Correlation ID؛
  • Service و Operation؛
  • Retry Count؛
  • نتیجه Provider؛
  • داده حساس Mask‌شده.

Audit

برای شکست یا رد Actionهای حساس:

  • Actor؛
  • Resource و Scope؛
  • وضعیت قبل و بعد؛
  • دلیل کسب‌وکاری؛
  • نتیجه نهایی.

Monitoring

خطاهای SEV-1 و افزایش غیرعادی SEV-2 باید Alert عملیاتی داشته باشند.

۱۴. تصمیم‌گیری نمایش خطا

flowchart TD accTitle: انتخاب رفتار مناسب برای خطا accDescr: سامانه نوع مشکل، اثر داده و امکان بازیابی را بررسی و نمایش مناسب را انتخاب می‌کند START(["وقوع وضعیت غیرعادی"]):::start PENDING{"نتیجه هنوز نامشخص است؟"}:::decision PENDING_STATE(["نمایش وضعیت در حال بررسی"]):::pending INPUT{"با اصلاح ورودی حل می‌شود؟"}:::decision FIELD["نمایش خطای Field یا Summary"]:::user PARTIAL{"بخشی از عملیات موفق شده است؟"}:::decision PARTIAL_RESULT["حفظ موفق‌ها و نمایش Retry ناموفق‌ها"]:::system TRANSIENT{"خطا موقت و Retry امن است؟"}:::decision RETRY["حفظ داده و نمایش یا اجرای Retry امن"]:::system SENSITIVE{"مالی، امنیتی یا ناسازگاری جدی است؟"}:::decision SUPPORT["توقف امن، ثبت Reference و Escalation"]:::error STABLE["نمایش وضعیت پایدار و اقدام بعدی"]:::system START --> PENDING PENDING -->|"بله"| PENDING_STATE PENDING -->|"خیر"| INPUT INPUT -->|"بله"| FIELD INPUT -->|"خیر"| PARTIAL PARTIAL -->|"بله"| PARTIAL_RESULT PARTIAL -->|"خیر"| TRANSIENT TRANSIENT -->|"بله"| RETRY TRANSIENT -->|"خیر"| SENSITIVE SENSITIVE -->|"بله"| SUPPORT SENSITIVE -->|"خیر"| STABLE 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 pending fill:#F3E8FF,stroke:#9333EA,color:#581C87; classDef error fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D;

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

  • خطا از Pending، Empty State و Warning جدا شده است.
  • دسته و شدت مشخص‌اند.
  • اثر روی State و داده ثبت شده است.
  • مسیر بازیابی روشن است.
  • Retry از نقطه امن انجام می‌شود.
  • Idempotency برای Action حساس مشخص است.
  • خطای Field و Summary متن یکسان دارند.
  • خطای مسدودکننده فقط Toast نیست.
  • اطلاعات فنی یا حساس در UI افشا نمی‌شوند.
  • Log و Audit از پیام کاربر جدا هستند.
  • Correlation ID برای خطای غیرمنتظره وجود دارد.
  • خطای SEV-1 Escalation دارد.
  • حالت Offline، Refresh، Double-submit و Concurrency بررسی شده‌اند.
  • تغییر Permission یا Scope در میانه Action بررسی شده است.
  • سناریوی بازگشت کاربر پس از وقفه تعریف شده است.

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

  1. Errorهای سناریو و شاخه‌های User Flow استخراج شوند.
  2. Pending، Empty State و Warning از Error جدا شوند.
  3. Errorها دسته‌بندی و Severityگذاری شوند.
  4. اثر State و داده مشخص شود.
  5. Recovery Code و Retry تعیین شود.
  6. UI Pattern مناسب انتخاب شود.
  7. Idempotency و Concurrency بررسی شوند.
  8. Security، Logging و Audit تکمیل شوند.
  9. Edge Caseهای سراسری افزوده شوند.
  10. Error Catalog با Workflow و Notification تطبیق داده شود.
  11. متن نهایی در Content Design بازبینی شود.

۱۷. منابع