# جریان کاربری — تسک ۰۶

## الف) بیمار وقت انتخاب می‌کند (سایت عمومی)

```
[از تسک ۰۵] برنامهٔ نوبت ساخته شد: ۶۸ دقیقه، ۵ بخش
    │
    ▼
GET /api/v1/appointment-availability/month?…&month=1405-05
    → { "1405-05-03": true, "1405-05-04": false, … }
    تقویم شمسی: روزهای بدون ظرفیت خاکستری
    │
    ▼
بیمار روز ۳ مرداد را می‌زند
    │
    ▼
POST /api/v1/appointment-availability
{
  "doctor_uuid": "…", "branch_uuid": "…",
  "service_item_uuid": "…", "option_uuids": ["…","…"],
  "from": "1405-05-03", "to": "1405-05-03", "limit": 50
}
    ▼
{
  "data": {
    "total_minutes": 68,
    "patient_facing_minutes": 63,
    "slots": [
      { "start": 1754…, "start_time": "09:00", "end_time": "10:08",
        "assignment": { "room": "اتاق ۲", "operator": "مریم …", "device": "کندلا ۱" } },
      { "start": 1754…, "start_time": "10:15", … }
    ]
  }
}
```

**بیمار `assignment` را نمی‌بیند.** فقط ساعت. تخصیص برای پنل و برای مرحلهٔ رزرو موقت است.
(استثنا: اگر کلینیک «انتخاب پزشک/اپراتور توسط بیمار» را فعال کرده باشد — خارج از دامنهٔ
این تسک.)

```
    ▼
بیمار ۰۹:۰۰ را می‌زند  →  تسک ۰۷ (رزرو موقت)
```

---

## ب) هیچ وقتی نیست — سه پیام متفاوت

```
POST /appointment-availability → data.slots = []
                                 data.reason = ?
```

| `reason` | پیام فارسی | دکمهٔ پیشنهادی |
|---|---|---|
| `no_resource` | «برای این خدمت، منبع لازم در این شعبه تعریف نشده است» | (پنل) «افزودن منبع» |
| `no_calendar` | «برای منابع این خدمت ساعت کاری تعریف نشده است» | (پنل) «تنظیم تقویم» |
| `fully_booked` | «در بازهٔ انتخابی وقت خالی نیست» | «جستجو در ۳۰ روز آینده» |
| `outside_window` | «رزرو آنلاین فقط تا ۳ ماه آینده ممکن است» | — |

پیام واحد «وقتی موجود نیست» بدترین حالت است: بیمار فکر می‌کند کلینیک پر است در حالی که
کلینیک اصلاً تقویم تعریف نکرده.

---

## ج) منشی از پنل — با انتخاب دستی منبع

```
پنل › نوبت جدید
    │
    ├─ بیمار (جستجو یا ثبت جدید)
    ├─ شعبه · سرویس · آیتم‌ها
    │     └─ اعتبارسنجی زنده (تسک ۰۴)
    ▼
POST /appointment-availability  با forManagement=true
    │  (بازهٔ رزرو آنلاین و خاموش‌بودن نوبت‌دهی اعمال نمی‌شود — رفتار امروزی)
    ▼
جدول وقت‌ها با ستون «منابع پیشنهادی»

  ساعت    مدت    اتاق      اپراتور    دستگاه
  ─────────────────────────────────────────────
  ۰۹:۰۰   ۶۸'    اتاق ۲ ▾   مریم ▾    کندلا ۱ ▾
  ۱۰:۱۵   ۶۸'    اتاق ۱ ▾   سارا ▾    کندلا ۲ ▾

هر ▾ یک SearchableSelect است با فقط منابع آزادِ همان بازه.
عوض کردن یکی → درخواست دوباره برای اعتبارسنجی همان زمان (نه کل لیست).
    ▼
«ثبت نوبت» → تسک ۰۷
```

---

## د) کلینیک به حالت چندمنبعی ارتقا می‌دهد

```
پنل › تنظیمات نوبت‌دهی
    │
    وضعیت فعلی: «نوبت‌دهی سرویسی» (قفل‌شده)
    │
    ├─ بنر: «ارتقا به نوبت‌دهی چندمنبعی»
    │     ✓ ۵ منبع فعال دارید
    │     ✓ ۳ سرویس با مدت معتبر
    │     ✗ ۲ نوبت فعال در آینده دارید — ابتدا تعیین تکلیف کنید
    │       [مشاهدهٔ نوبت‌ها]
    │
    ▼ (بعد از رفع همهٔ شرط‌ها)
    ├─ ☑ می‌دانم این تغییر برگشت‌ناپذیر است
    └─ [ارتقا]
    ▼
POST /api/v1/appointment-settings/upgrade-booking-mode
    ▼
حالا تنظیمات جدید فعال می‌شوند:
    گام زمانی: ۱۵ دقیقه ▾
    استراتژی انتخاب منبع: کمترین شکاف ▾
```

چک‌لیست پیش از ارتقا اجباری است. بدون آن، کلینیک ارتقا می‌دهد، نوبت‌های قدیمی‌اش
نمایش نادرست می‌گیرند و هیچ راه بازگشتی نیست.

---

## ه) چه چیزی در این جریان **تغییر نمی‌کند**

```
پزشک در حالت slot     → GET /api/v1/appointment-slots            بدون تغییر
پزشک در حالت service  → GET /api/v1/appointment-service-slots    بدون تغییر
تقویم ماهانهٔ قدیمی    → GET /api/v1/appointment-settings/month-availability/{uuid}  بدون تغییر
```

سایت عمومی و اپ دسکتاپ تا وقتی کلینیک ارتقا نداده، هیچ کد جدیدی لازم ندارند.
پس از ارتقا، `GET /appointment-booking-services` مقدار `booking_mode: "resource"` می‌دهد و
کلاینت باید مسیر جدید را صدا بزند — **این تنها نقطه‌ای است که کلاینت‌ها باید به‌روز شوند**
و باید در `docs/api/appointment.md` برجسته نوشته شود.