hamedandClaude Opus 5
4049daf071
Every one of the fourteen named events now has an emit point. The four that
were missing all sat on paths owned by earlier tasks:
- AppointmentCompleted fires from both status-change routes, after the row is
saved. A rejected transition or a version conflict leaves no event; otherwise
the completed count runs ahead of the appointments themselves.
- AppointmentRescheduled is a third event, not a replacement. A rebook is a
confirm plus a cancel, and a consumer that only hears the cancel messages a
patient who still has an appointment.
- ResourceBlocked / ResourceReleased are a pair. Capacity coming back has to be
as audible as capacity going away, or the resource reads as permanently taken.
Publishing is now on the scheduler rather than an unregistered command: the
logic moved out of PublishDomainEventsCommand into OutboxPublisher so the
recurring message and the manual command share it, and the existing
worker-scheduler container consumes it. The scheduler message carries no data
on purpose — what to publish is read from the table, so an event recorded
between two ticks is not skipped. DomainEventMessage routes to async, since a
slow consumer was otherwise slowing the drain itself and its failure marked a
row failed that had in fact been delivered.
Panel work that these paths made reachable:
- Cancelling from the appointment page now goes through the policy-aware
endpoint and shows the penalty preview before the confirm, so the operator
does not discover the patient's penalty after the fact. The cancellation
service writes the timeline entry itself and accepts a reason, which that
path previously dropped on the floor.
- Rescheduling reuses the booking page under ?rebook=<uuid> — the search and
hold steps are identical and only the final step differs. The doctor picker
is hidden there: a reschedule is not an invitation to change doctors.
- A new GET /appointment/{uuid}/segments exposes the recorded plan. An empty
list is not an error, it means the appointment is slot-based, and that is
exactly what gates the resource-mode reschedule button.
AppointmentInvoiceCard no longer crashes the whole detail page when an older
invoice has no discount breakdown.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
135 lines
7.9 KiB
Markdown
135 lines
7.9 KiB
Markdown
# رویدادهای دامنه
|
||
|
||
سیستم وقتی چیزی اتفاق میافتد یک **رویداد** ثبت میکند تا بقیه (پیامک، حسابداری، گزارش)
|
||
واکنش نشان بدهند — بدون اینکه دامنهٔ نوبتدهی از وجودشان خبر داشته باشد.
|
||
|
||
مرجع: بند ۱۶ مستند طراحی. اندپوینت عیبیابی: [../api/reports.md](../api/reports.md)
|
||
|
||
---
|
||
|
||
## سه قاعدهٔ غیرقابلمذاکره
|
||
|
||
۱. **payload فقط uuid و اسکالر است.** هیچ entity ای در رویداد نیست؛ مصرفکننده خودش
|
||
واکشی میکند. entity در پیام async یعنی سریالسازی، detach شدن، و دادهٔ کهنه.
|
||
`DomainEventLog` مقادیر غیراسکالر را **حذف** میکند، نه اینکه سریالشان کند.
|
||
۲. **انتشار بعد از commit.** ردیف رویداد در همان تراکنشی نوشته میشود که تغییر را
|
||
انجام میدهد؛ انتشار جداست.
|
||
۳. **هر رویداد محیط دارد.** بدون `entity_type`/`entity_id`، پیامک کلینیک الف به شمارهٔ
|
||
کلینیک ب میرود.
|
||
|
||
---
|
||
|
||
## چرا صندوق خروجی (outbox)
|
||
|
||
بدون آن دو حالت شکست ممکن است:
|
||
|
||
| حالت | نتیجه |
|
||
|---|---|
|
||
| انتشار پیش از commit، بعد rollback | پیامک رفته، نوبتی وجود ندارد |
|
||
| commit موفق، انتشار شکست خورد (Redis down) | نوبت هست، هیچکس مطلع نشد |
|
||
|
||
با outbox ردیف رویداد **در همان تراکنش** ثبت میشود و بعداً منتشر میشود. حداکثر **تأخیر**
|
||
داریم، هرگز گمشدن.
|
||
|
||
### چه چیزی آن را در تولید اجرا میکند
|
||
|
||
انتشار روی زمانبند نشسته است، نه cron جدا: `PublishDomainEventsMessage` هر دقیقه در
|
||
`src/Schedule.php` صادر میشود و `worker-scheduler` همان کانتینر همیشگی مصرفش میکند.
|
||
سرویس تازهای لازم نیست.
|
||
|
||
| لایه | چه میکند |
|
||
|---|---|
|
||
| `OutboxPublisher::publish()` | منطق واقعی؛ ردیفهای منتشرنشده را از جدول میخواند |
|
||
| `PublishDomainEventsHandler` | هر تیک زمانبند صدایش میزند |
|
||
| `app:events:publish --limit=100` | اجرای دستی، برای وقتی که صف عقب افتاده |
|
||
|
||
پیامِ زمانبند عمداً **بیداده** است: «چه چیزی منتشر شود» از جدول خوانده میشود نه از پیام،
|
||
وگرنه رویدادی که بین دو تیک ثبت شده جا میماند. و چون `Schedule` روی `stateful` است، تیکِ
|
||
ازدسترفته بعد از ریاستارت جبران میشود — یک اجرا کافی است تا همهٔ عقبماندگی برود.
|
||
|
||
`DomainEventMessage` به `async` میرود، نه `sync`: یک مصرفکنندهٔ کند وگرنه خودِ تخلیهٔ صندوق
|
||
را کند میکرد، و شکستش ردیفی را «ناموفق» علامت میزد که در واقع تحویل شده بود.
|
||
|
||
پاکسازی (`app:events:prune`) روی زمانبند **نیست** و باید cron جدا باشد؛ حذف داده تصمیمی است
|
||
که باید صریح و با پنجرهٔ نگهداریِ انتخابشده اجرا شود، نه اثر جانبیِ یک worker همیشهروشن.
|
||
|
||
`DomainEventPublisher::record()` عمداً flush نمیکند — همان چیزی که تضمین میکند رویداد
|
||
با تراکنشِ برگشته از بین برود. جایی که فراخوان تراکنش باز ندارد، `recordAndFlush()` هست.
|
||
|
||
### ردیف مرده
|
||
|
||
بعد از پنج تلاش ناموفق، ردیف با `last_error` **باقی میماند** و دیگر برداشته نمیشود.
|
||
حذف خاموش یعنی رویداد گمشدهٔ بیرد؛ ادمین باید بتواند ببیند چه چیزی منتشر نشد و چرا.
|
||
|
||
---
|
||
|
||
## `AppointmentEvent` یا `DomainEventLog`؟
|
||
|
||
هر دو ماندند و کارشان یکی نیست:
|
||
|
||
| | `AppointmentEvent` | `DomainEventLog` |
|
||
|---|---|---|
|
||
| چیست | تاریخچهٔ تغییر وضعیت **یک نوبت** | اعلان تغییر به بیرونِ دامنه |
|
||
| مخاطب | خودِ صفحهٔ نوبت | پیامک، حسابداری، گزارش |
|
||
| دامنه | فقط نوبت | همهٔ دامنهها |
|
||
| مصرف | خوانده میشود | منتشر میشود |
|
||
|
||
ادغامشان یعنی تاریخچهٔ نوبت به صف پیام تبدیل شود، یا صف پیام پر از جزئیاتی که فقط یک
|
||
صفحه لازم دارد.
|
||
|
||
---
|
||
|
||
## فهرست رویدادها
|
||
|
||
```
|
||
HoldCreated AppointmentBooked
|
||
AppointmentCancelled AppointmentRescheduled
|
||
PatientNoShow AppointmentCompleted
|
||
ResourceBlocked ResourceReleased
|
||
CourseStarted CourseSessionCompleted
|
||
CourseCompleted PackagePurchased
|
||
CreditConsumed CreditRefunded
|
||
```
|
||
|
||
فهرست **بسته** است (`DomainEvents::ALL`) و نام ناشناخته استثنا میدهد: مصرفکننده روی
|
||
رشته شرط میگذارد، و تایپوی یک حرفی یعنی رویدادی که هیچکس نمیشنود و هیچ خطایی هم
|
||
نمیدهد.
|
||
|
||
### وضعیت فعلی انتشار
|
||
|
||
| رویداد | کجا ثبت میشود |
|
||
|---|---|
|
||
| `HoldCreated` | `HoldService::hold()` — بعد از گرفتن همهٔ منابع |
|
||
| `AppointmentBooked` | `BookingService::confirm()` |
|
||
| `AppointmentCancelled` | `BookingService::cancel()` |
|
||
| `PatientNoShow` | `NoShowService::record()` |
|
||
| `CourseStarted` | `CourseStarter::start()` |
|
||
| `CourseSessionCompleted` · `CourseCompleted` | `CourseSessionLinker::complete()` |
|
||
| `PackagePurchased` | `PackageSalesService::sell()` |
|
||
| `CreditConsumed` · `CreditRefunded` | `CreditLedgerService` |
|
||
| `AppointmentRescheduled` | `BookingController::rebook()` |
|
||
| `AppointmentCompleted` | `AppointmentController` — هر دو مسیر تغییر وضعیت |
|
||
| `ResourceBlocked` · `ResourceReleased` | `ResourceBlockController` |
|
||
|
||
هر چهارده رویداد نقطهٔ ثبت دارند.
|
||
|
||
دو نکته که موقع خواندن این جدول بهدرد میخورند:
|
||
|
||
- **`AppointmentRescheduled` سومین رویداد است، نه جایگزین.** جابهجایی از درون یک `confirm`
|
||
و یک `cancel` است و هر کدام رویداد خودشان را میگذارند. مصرفکنندهای که فقط
|
||
`AppointmentCancelled` را بشنود، برای بیماری که هنوز نوبت دارد پیام لغو میفرستد؛ این
|
||
رویداد همان چیزی است که آن دو را به هم وصل میکند.
|
||
- **`AppointmentCompleted` بعد از ذخیرهٔ موفق ثبت میشود، نه هنگام درخواست.** انتقالی که
|
||
`canTransitionTo` رد میکند یا `saveWithLock` روی تداخل نسخه میشکند، هیچ رویدادی
|
||
نمیگذارد — وگرنه شمارِ «انجامشده» از خودِ نوبتها جلو میزند.
|
||
|
||
---
|
||
|
||
## مصرفکنندهٔ تازه
|
||
|
||
`DomainEventHandler` فقط لاگ میکند و **نباید بیشتر بکند**؛ درزِ اتصال است. مصرفکنندهٔ
|
||
تازه کنارش ثبت میشود و باید **idempotent** باشد: messenger ممکن است پیام را دوباره
|
||
تحویل بدهد، و `DomainEventMessage::$uuid` همان شناسهای است که با آن تکراری را میشناسد.
|
||
|
||
تکرار مسئلهٔ مصرفکننده است، نه رویداد: تضمین «دقیقاً یک بار» در صف توزیعشده وجود ندارد.
|