سیستم نوبت‌دهی آنلاین؛ مدل داده و API یک اپ رزرو

سیستم نوبت‌دهی آنلاین از بیرون ساده به نظر می‌رسد — یک تقویم و یک دکمه‌ی «رزرو» — ولی چیزی که واقعاً می‌سازیدش یک مدل داده‌ی چهارتایی است: خدمت، کارشناس، بازه‌ی کاری، و نوبت. اگر این چهارتا و رابطه‌هایشان را درست بچینید، بقیه‌ی کار رابط کاربری است. این راهنما همان مدل را نشان می‌دهد، می‌گوید کدام بخشش را باید عمومی و کدام را خصوصی بگذارید، و یک تله‌ی زمانی را باز می‌کند که تقریباً همه‌ی پیاده‌سازی‌های اول به آن می‌خورند.

سه راهی که پیش پایتان است

قبل از مدل داده، تصمیم دسته‌بندی را بگیرید:

• سرویس نوبت‌دهی آماده. ثبت‌نام می‌کنید و پنل و صفحه‌ی رزرو را تحویل می‌گیرید. سریع‌ترین راه اگر کسب‌وکارتان دقیقاً همان چیزی است که آن‌ها فرض کرده‌اند؛ ولی جریان کار و ظاهر مال آن‌هاست و اپ اختصاصی از آن درنمی‌آید.
• سفارش ساخت به آژانس. هر چیزی که بخواهید ساخته می‌شود، با هزینه و زمان خودش — و نگه‌داری‌اش بعداً سؤال بعدی است.
• خودتان بسازید، روی بک‌اند آماده. رابط کاربری و تجربه‌ی رزرو مال شماست و لایه‌ی داده و احراز هویت را نمی‌نویسید. این مقاله درباره‌ی همین راه است.

مدل داده‌ی یک سیستم نوبت‌دهی

چهار موجودیت کافی است و پنجمی معمولاً اشتباه است:

• خدمت (service) — چه کاری رزرو می‌شود: ویزیت، کوتاهی مو، جلسه‌ی مشاوره. نام، توضیح، مدت‌زمان، قیمت.
• کارشناس (staff) — چه کسی انجامش می‌دهد. یک کارشناس می‌تواند چند خدمت بدهد.
• بازه‌ی کاری (availability) — چه ساعت‌هایی باز است. روز هفته و ساعت شروع و پایان.
• نوبت (booking) — چه کسی، چه خدمتی، از چه کارشناسی، چه زمانی.

موجودیت پنجمِ اشتباه: «مشتری». وسوسه می‌شوید یک جدول مشتری بسازید، ولی کسی که نوبت می‌گیرد همان کسی است که وارد اپ شده — یعنی کاربر نهایی پروژه. جدول مشتریِ جدا یک دفترچه‌ی تلفن موازی می‌شود که به احراز هویت وصل نیست و از روز دوم با واقعیت اختلاف پیدا می‌کند.

کدام بخش عمومی و کدام خصوصی

این تصمیم امنیتی‌ترین بخش کار است و ساده‌تر از چیزی است که به نظر می‌رسد:

سه ردیف اول با کلید عمومی و بدون ورود خوانده می‌شوند، پس صفحه‌ی اول اپ برای مهمان هم پر است. ردیف چهارم دسترسی سطح رکورد می‌خواهد: کاربر واردشده فقط نوبت‌های خودش را می‌بیند و نوبت دیگری برایش وجود ندارد — نه اینکه ببیند و اجازه‌ی ویرایش نداشته باشد. این تفاوت را احراز هویت کاربران با JWT باز کرده است.

تله‌ی زمان: تداخل نوبت‌ها

اینجا جایی است که پیاده‌سازی اول تقریباً همیشه می‌شکند. فرض طبیعی این است که سرور خودش بفهمد نوبت جدید با نوبت موجود تداخل دارد یا نه. ولی در فیکارو موتور قوانین ریاضیِ تاریخ ندارد: نمی‌تواند «ساعت پایان = ساعت شروع + مدت خدمت» را حساب کند و نمی‌تواند چند رکورد را هم‌زمان ببیند تا تداخل را تشخیص دهد.

چک کردن بازه یک درخواست ساده است:

curl "https://api.fikaro.ir/my-clinic/v1/booking?filter[staff_id]=<id>&filter[start_time][gte]=2026-09-01T08:00:00Z&filter[start_time][lt]=2026-09-01T20:00:00Z&sort=start_time" \
  -H "Authorization: Bearer apck_..."

نتیجه، نوبت‌های آن روزِ آن کارشناس است و ساعت‌های آزاد را از رویش می‌سازید. این الگو — خواندن بازه، ساختن ساعت‌های آزاد در کلاینت، ثبت نوبت — همان کاری است که سرویس‌های آماده هم پشت پرده می‌کنند.

بقیه‌ی کارها که آماده‌اند

آنچه بعد از مدل داده لازم دارید و نوشتنش با شما نیست:

• ثبت‌نام و ورود مراجع با شماره موبایل و کد پیامکی، که برای این نوع کسب‌وکار طبیعی‌ترین شکل ورود است — راهنمای ورود OTP.
• اطلاع‌رسانی بعد از ثبت نوبت با وبهوک: رویداد ساخته‌شدن نوبت به سرویس پیامکی یا هر سامانه‌ی دیگری وصل می‌شود.
• اعتبارسنجی بدون کد با موتور قوانین: مثلاً نوبت در گذشته ثبت نشود، یا وضعیت فقط بین مقادیر مجاز عوض شود.
• پنل دیدن و ویرایش نوبت‌ها برای خودتان، از همان روز اول.

سریع‌ترین شروع: از روی قالب

لازم نیست این چهار موجودیت را دستی بسازید. قالب «رزرو و نوبت‌دهی» همین مدل را با فیلدها، رابطه‌ها و سطوح دسترسی بالا از قبل دارد؛ پروژه را از رویش می‌سازید و بعد به شکل کسب‌وکار خودتان تغییرش می‌دهید. فهرست قالب‌ها و شروع سریع مسیرش را نشان می‌دهند، و اگر می‌خواهید از توصیف فارسی کسب‌وکارتان شروع کنید، ساخت بک‌اند با هوش مصنوعی همان راه است.

اپ موبایلش را هم با فلاتر یا ری‌اکت‌نیتیو می‌سازید — کد اتصال در بک‌اند فلاتر و ری‌اکت‌نیتیو آمده است.

سوالات متداول

برای سیستم نوبت‌دهی حتماً باید برنامه‌نویس بک‌اند داشته باشم؟

نه. چیزی که واقعاً لازم دارید یک مدل داده‌ی درست و یک رابط کاربری است. لایه‌ی داده، احراز هویت مراجع و دسترسی سطح رکورد را بک‌اند آماده می‌دهد و شما فقط اپ یا سایت را می‌سازید.

جلوگیری از رزرو تکراری روی یک ساعت چطور انجام می‌شود؟

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

می‌شود بعد از ثبت نوبت پیامک تأیید فرستاد؟

بله. رویداد ساخته‌شدن نوبت از راه وبهوک به سرویس پیامکی یا هر سامانه‌ی دیگری وصل می‌شود، بدون اینکه کد سمت سرور بنویسید.

مراجع‌ها باید ثبت‌نام کنند یا مهمان هم می‌تواند نوبت بگیرد؟

خدمت‌ها، کارشناس‌ها و ساعت‌های کاری عمومی‌اند و بدون ورود دیده می‌شوند، ولی خودِ نوبت به کاربر گره می‌خورد تا هر کسی فقط نوبت خودش را ببیند. برای همین ثبت نوبت نیاز به ورود دارد و ساده‌ترین شکلش کد یکبار مصرف پیامکی است.