hamedandClaude Opus 5
3c43955800
Tasks 07 through 13 each changed something the rest of the system might want to know about, with no contract for saying so. And task 05 shipped a powerful segment editor with no feedback on whether a clinic defined its segments right. Events - A closed list of names, because a consumer branches on the string and a one-letter typo would produce an event nobody hears and no error either - Payloads carry uuids and scalars only; non-scalars are dropped, not serialised, so a consumer always fetches fresh rather than reading a stale detached entity - record() deliberately does not flush: the event row commits with the change it describes, so a rolled-back transaction leaves no event behind. A test pins exactly that - app:events:publish drains the outbox; five failed attempts park a row with its error rather than deleting it, because a silently dropped event is a loss with no trace. app:events:prune only ever removes published rows Reports - Resource utilisation separates available, occupied and active minutes. The gap between occupied and active is what exposes a bad segment definition, and available is multiplied by capacity so a three-chair room does not read as permanently over 100% - A resource with no calendar reports utilization: null, not zero — dividing by zero means something different from being idle - Plan accuracy compares planned against actual duration per service and flags both directions: running short wastes capacity that could have been sold. Its row links straight to editing that service's segments, because a report with no route to a fix does not get read Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
148 lines
4.7 KiB
Markdown
148 lines
4.7 KiB
Markdown
# Reports — بهرهوری منابع و دقت برنامه
|
|
|
|
اندپوینتهای `src/Report/*`. بند ۱۷ مستند، ریسک سوم: «کلینیک بخشهای نوبت را اشتباه
|
|
تعریف کند → ظرفیت غلط حساب میشود». این دو گزارش تنها بازخوردیاند که آن اشتباه را
|
|
نشان میدهند.
|
|
|
|
---
|
|
|
|
## GET `/api/v1/reports/resource-utilization`
|
|
|
|
| Query | Type | Required | Description |
|
|
|---|---|---|---|
|
|
| `branch_uuid` | string | ✅ | |
|
|
| `from` / `to` | int | — | Unix؛ پیشفرض هفتهٔ گذشته، حداکثر ۹۰ روز |
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"from": 1784880000,
|
|
"to": 1785484800,
|
|
"rows": [
|
|
{
|
|
"resource_uuid": "…",
|
|
"resource_name": "اپراتور مریم",
|
|
"role": "operator",
|
|
"available_minutes": 2400,
|
|
"occupied_minutes": 1800,
|
|
"active_minutes": 1200,
|
|
"utilization": 0.75,
|
|
"active_ratio": 0.5,
|
|
"wasted_capacity": false
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
سه عدد، سه معنا:
|
|
|
|
| عدد | یعنی |
|
|
|---|---|
|
|
| `available_minutes` | منبع طبق تقویمش چقدر در دسترس بوده |
|
|
| `occupied_minutes` | چقدر **گرفته** شده — شامل آمادهسازی، تمیزکاری و بخشهای انتظار |
|
|
| `active_minutes` | چقدر واقعاً کار شده — فقط بخشهایی که بیمار حاضر بوده |
|
|
|
|
فاصلهٔ `occupied` و `active` همان چیزی است که تعریف غلط بخشها را لو میدهد. `active_ratio`
|
|
زیر ۰٫۳ با `wasted_capacity: true` میآید: منبعی که هشت ساعت اشغال بوده ولی دو ساعت کار
|
|
کرده یا بخشهای `passive` زیادی گرفته یا انتظارها اشتباه به او نسبت داده شده.
|
|
|
|
⚠️ منبعی بدون تقویم `available_minutes: 0` و **`utilization: null`** میدهد، نه صفر:
|
|
تقسیم بر صفر معنای متفاوتی دارد — بهرهوریاش تعریفنشده است، نه بد.
|
|
|
|
ردیفهای `released` (لغوشده) در محاسبه نمیآیند، وگرنه هر لغو بهرهوری را بالا میبرد.
|
|
|
|
---
|
|
|
|
## GET `/api/v1/reports/plan-accuracy`
|
|
|
|
| Query | Type | Required | Description |
|
|
|---|---|---|---|
|
|
| `from` / `to` | int | — | پیشفرض هفتهٔ گذشته، حداکثر ۹۰ روز |
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"from": 1784880000,
|
|
"to": 1785484800,
|
|
"rows": [
|
|
{
|
|
"service_uuid": "…",
|
|
"service_name": "لیزر فولبادی",
|
|
"sample_size": 4,
|
|
"planned_minutes": 60,
|
|
"actual_minutes": 90,
|
|
"deviation_percent": 50,
|
|
"severity": "high"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
| قدر مطلق انحراف | شدت |
|
|
|---|---|
|
|
| ≥ ۳۰٪ | `high` |
|
|
| ≥ ۱۵٪ | `medium` |
|
|
| ≥ ۵٪ | `low` |
|
|
| کمتر | `none` |
|
|
|
|
شدت از **قدر مطلق** میآید: سرویسی که نصف زمان پیشبینیشده طول میکشد هم غلط تعریف
|
|
شده — ظرفیتی که میشد فروخت، خالی مانده.
|
|
|
|
فقط نوبتهای `completed` شمرده میشوند (لغوشده چیزی دربارهٔ مدت واقعی نمیگوید) و
|
|
سرویس با کمتر از **سه** نمونه اصلاً نمیآید — میانگین دو نوبت، میانگین نیست.
|
|
|
|
مبنای «واقعی» فاصلهٔ ثبتشدهٔ اسلات است، نه ساعت ورود و خروج بیمار؛ آن دومی جایی ثبت
|
|
نمیشود و حدس زدنش بدتر از نداشتنش است.
|
|
|
|
---
|
|
|
|
## GET `/api/v1/domain-events`
|
|
|
|
**Permission:** `ROLE_ADMIN` (بقیه `403`)
|
|
|
|
| Query | Type | Description |
|
|
|---|---|---|
|
|
| `name` | string | فیلتر نام رویداد |
|
|
| `limit` | int | پیشفرض ۱۰۰، سقف ۵۰۰ |
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"uuid": "…",
|
|
"name": "AppointmentBooked",
|
|
"payload": { "appointment_uuid": "…", "hold_uuid": "…" },
|
|
"occurred_at": 1785484800,
|
|
"published_at": 1785484802,
|
|
"attempts": 0,
|
|
"last_error": null
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`published_at: null` یعنی هنوز در صندوق خروجی است. جزئیات:
|
|
[../architecture/domain-events.md](../architecture/domain-events.md)
|
|
|
|
---
|
|
|
|
## خطاها
|
|
|
|
| Code | HTTP | Description |
|
|
|---|---|---|
|
|
| `ERR_VALIDATION_001` | 422 | بازهٔ وارونه یا بزرگتر از ۹۰ روز |
|
|
| `ERR_VALIDATION_002` | 422 | `branch_uuid` غایب |
|
|
|
|
## تستها
|
|
|
|
```bash
|
|
ddev exec php bin/phpunit tests/Report # ۱۶ تست
|
|
```
|