Event-driven Design و Idempotent Receipt

این درس فقط یک مسئله محدود را مالک است: یک event consumer چگونه redelivery را تحمل کند بدون اینکه side effect تحت مالکیت خودش دوباره اجرا شود و در عین حال محدودیت ordering را صریح نگه دارد؟ خروجی شواهدی درس Idempotent Event Receipt Record v1 است. این خروجی اثبات exactly-once سراسری، total ordering یا تضمین خاص یک broker نیست.

1. Outcome محدود درس

در Lab یک inventory projection رویداد ReservationAccepted را مصرف می‌کند. باید event producer، event channel، event consumer، business entity، stable receipt key، version، side effect، duplicate rule، ordering rule و residual risk کاملاً قابل مشاهده باشند.

2. مرز Event-driven قبل از پیاده‌سازی

در event-driven architecture، producer و consumer از طریق event channel از هم جدا می‌شوند. این decoupling مفید است، اما مسئله delivery، retry، ordering و eventual consistency را حذف نمی‌کند؛ فقط آن‌ها را به reliability design منتقل می‌کند.

زنجیره محدود این درس چنین است:

producer fact -> event channel -> delivery -> stable receipt key -> atomic receipt + owned effect -> duplicate/out-of-order decision -> acknowledgement -> evidence

3. Stable receipt key

receipt key باید واحد منطقی کار را شناسایی کند و در redelivery ثابت بماند. در fixture، delivery_id در تلاش‌های مختلف تغییر می‌کند اما event key همان inventory:sku-42:reservation:R-1001 می‌ماند. بنابراین هویت deduplication همان event key پایدار است، نه شناسه موقتی delivery.

4. Idempotent effect

بعد از اولین رویداد پذیرفته‌شده، stock از 100 به 97 می‌رسد. redelivery با همان stable receipt key ولی delivery ID متفاوت باید DUPLICATE_SUPPRESSED شود، stock روی 97 بماند و receipt منطقی دوباره ساخته نشود.

این فقط idempotency محدود برای side effect همین consumer است و درباره downstream system ادعایی نمی‌کند.

5. Atomic receipt و effect

در طراحی امن محلی، ثبت receipt و تغییر state تحت مالکیت consumer در یک atomic boundary قرار می‌گیرند. fixture مصنوعی ما مسیر اتمیک را به‌صورت «هر دو یا هیچ‌کدام» مدل می‌کند.

در variant عمداً خراب، stock کم می‌شود ولی قبل از ثبت receipt crash رخ می‌دهد. redelivery چون receipt نمی‌بیند، دوباره side effect را اجرا می‌کند. classification مورد انتظار NON_ATOMIC_DUPLICATE_RISK است.

6. Deduplication با Ordering یکی نیست

ممکن است consumer هیچ duplicateای را دوباره اعمال نکند اما همچنان event قدیمی را بپذیرد. پس از version 10، یک event مستقل با version 9 duplicate نیست؛ stale است. نتیجه محدود صحیح STALE_EVENT_REJECTED است.

در این projection، mutation فقط وقتی مجاز است که entity version جدید از version پذیرفته‌شده فعلی بزرگ‌تر باشد.

7. Baseline probe

در baseline_first_delivery از event key ثابت، delivery-A، version 10 و delta برابر -3 استفاده می‌شود. classification مورد انتظار RECEIPT_COMMITTED_EFFECT_APPLIED است.

8. Redelivery probe

در duplicate_redelivery_new_transport_id همان event key و version با delivery-B دوباره می‌آید. classification باید DUPLICATE_SUPPRESSED باشد و state بعد از اولین effect تغییر نکند.

9. Crash-window probe

در non_atomic_crash_window عمداً effect قبل از receipt قابل مشاهده می‌شود. تلاش اول بعد از کاهش stock crash می‌کند؛ redelivery receipt ندارد و دوباره stock را کاهش می‌دهد. classification مورد انتظار NON_ATOMIC_DUPLICATE_RISK است. این negative evidence باید حفظ شود.

10. Stale-version probe

در stale_lower_version یک event key جدید با version 9 بعد از پذیرفته‌شدن version 10 می‌آید. classification مورد انتظار STALE_EVENT_REJECTED است. این probe نشان می‌دهد deduplication به‌تنهایی stale یا out-of-order event را حل نمی‌کند.

11. Evidence completeness probe

در probe پنجم، فیلد Residual Risk از record حذف می‌شود. classification مورد انتظار EVIDENCE_INCOMPLETE است. اجرای موفق کد بدون evidence کامل برای تصمیم نهایی کافی نیست.

12. ساختار Idempotent Event Receipt Record v1

برای هر case این فیلدها را ثبت کن:

• Event Key
• Business Entity
• Version
• Delivery Attempt
• Receipt State
• Side Effect
• Duplicate Decision
• Ordering Decision
• Evidence
• Residual Risk

FACT رسمی، observation محلی و inference مهندسی را از هم جدا نگه دار.

13. مرز سه منبع رسمی

سه صفحه رسمی Microsoft Learn منبع این درس هستند. راهنمای event-driven architecture برای producer/channel/consumer و challengeهای delivery، ordering و eventual consistency استفاده می‌شود. الگوی Idempotent Consumer برای stable identifier و durable processed-message record تحت duplicate delivery استفاده می‌شود. Retry pattern فقط رابطه retry و idempotency را محدود می‌کند.

این سه صفحه تضمین exactly-once برای fixture یا total ordering یک broker خاص را ثابت نمی‌کنند.

14. Non-goalها

از این درس نتیجه نگیر که:

• event-driven architecture ordering یا exactly-once side effect را تضمین می‌کند؛
• broker-level duplicate suppression نیاز به idempotent consumer را حذف می‌کند؛
• transport delivery ID همیشه business idempotency key درست است؛
• deduplication به‌تنهایی stale یا out-of-order event را حل می‌کند؛
• green local run معادل production reliability است.

15. Transfer: webhook retry

در changed context، یک webhook consumer retryهایی با request_id=req-4401 ثابت ولی delivery IDهای مختلف می‌گیرد. receipt key و stale-update rule را مستقل انتخاب کن. باید توضیح بدهی چرا business request ID در redelivery پایدار می‌ماند و چرا resource version پایین‌تر حتی با request ID جدید نباید state تازه‌تر را overwrite کند.

16. Assessment boundary

پاس‌شدن نیازمند positive evidence، negative evidence و transfer است. happy path به‌تنهایی کافی نیست. learner باید تصمیم محدود را در برابر این shortcut دفاع کند که broker deduplication یا retry configuration به‌تنهایی مسئله side effect consumer را حل می‌کند.

17. Freshness

مرز منبع شامل سه صفحه رسمی Microsoft Learn است. same-locator recheck در 2026-09-16 material drift در claimهای مورد استفاده پیدا نکرد. review trigger طبق Bible همان 2026-12-31 باقی می‌ماند.

18. تصمیم محدود نهایی

fixture محلی می‌تواند نشان دهد stable receipt key یک redelivery را suppress می‌کند، variant غیراتمیک duplicate-risk می‌سازد و stale version به rule مستقلی از deduplication نیاز دارد. این fixture نمی‌تواند exactly-once سراسری broker، total ordering، production safety یا downstream idempotency را اثبات کند. تصمیم residual risk با learner است.