به محتوای اصلی

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

سیستم نوبت‌دهی از چهار موجودیت ساخته می‌شود: خدمت، کارشناس، بازه و نوبت. مدل داده، سطح دسترسی هرکدام، و تله‌ی تداخل نوبت که پیاده‌سازی اول را می‌شکند.

عاطفه امیری۶ دقیقه مطالعهبه‌روزرسانی
در این مطلب

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

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

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

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

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

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

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

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

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

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

موجودیتسطح دسترسیچرا
خدمتعمومیویترین است؛ بازدیدکننده قبل از ثبت‌نام باید ببیند
کارشناسعمومیبخشی از همان ویترین
بازه‌ی کاریعمومیساعت‌های باز باید بدون ورود دیده شود
نوبتفقط خودشنوبت هر کسی فقط مال خودش است

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

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

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

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

قالب رزرو این کار را آماده دارد. پروژه‌ای که از قالب می‌سازید از روز اول فانکشنی به نام book دارد و نوبت فقط از همین راه ثبت می‌شود. اپ به‌جای POST /v1/booking آن را با توکن مراجع صدا می‌زند:

curl -X POST "https://api.fikaro.ir/my-clinic/v1/fn/book" \
  -H "Authorization: Bearer <توکن مراجع>" \
  -H "Content-Type: application/json" \
  -d '{"service_id": "<id>", "staff_id": "<id>", "start_time": "2026-12-01T13:00"}'

book این‌ها را سمت سرور انجام می‌دهد:

  • فقط مراجع واردشده نوبت می‌گیرد، و نوبت به نام خود صداکننده ساخته می‌شود. با کلید API جواب 403 login_required است، چون کلید مراجعی ندارد که نوبت به نامش باشد.
  • زمان را به وقت تهران می‌خواند اگر start_time منطقه‌ی زمانی نداشته باشد. زمان گذشته رد می‌شود.
  • زمان پایان را از مدت خود خدمت و مبلغ را از قیمت خود خدمت حساب می‌کند و یک کد نوبت NB-… می‌گذارد. اپ این‌ها را نمی‌فرستد، پس نمی‌تواند دستکاری‌شان کند.
  • نوبت‌های زنده‌ی همه‌ی مراجع همان کارشناس را با ctx.db.admin.list می‌خواند و چیزی از آن‌ها به اپ برنمی‌گرداند. ساعت پر با 409 و کد slot_taken رد می‌شود.
  • بعد از نوشتن یک بار دیگر نگاه می‌کند. اگر دو مراجع در یک لحظه همان ساعت را بخواهند، نوبتی که بعد از ثبت نوبت دیگری را روی بازه‌اش ببیند خودش را حذف می‌کند و 409 می‌دهد. دومی همیشه اولی را می‌بیند، پس دو نوبت روی یک ساعت نمی‌مانند.

هسته‌ی این بررسی چند خط است:

function overlapping(limit) {
  return ctx.db.admin.list("booking", {
    filter: {
      staff_id: staff.id,
      "start_time[lt]": to,
      "end_time[gt]": from,
      "status[in]": ["pending", "confirmed"],
    },
    limit: limit,
  });
}

if (overlapping(1).length > 0) fail(409, "slot_taken", TAKEN);
const created = ctx.db.admin.create("booking", row);
for (const other of overlapping(2)) {
  if (other.id !== created.id) {
    ctx.db.admin.delete("booking", created.id);
    fail(409, "slot_taken", TAKEN);
  }
}

کد کامل را در صفحه‌ی فانکشن‌های همان پروژه می‌بینید و توضیحش در راهنمای «گرفتن نوبت، با بررسی تداخل» قالب آمده است. book ساعت کاری کارشناس در آن روز و خدمت‌هایی را که ارائه می‌دهد هم چک می‌کند، پس نوبت بیرون از شیفت یا برای خدمتی که کارشناس ندارد با 409 و پیام فارسی رد می‌شود. پشتوانه‌ی این در خود جدول است: کارشناس، خدمت، زمان شروع و پایان، مبلغ و وضعیت نوبت فیلدهای فقط‌ادمین‌اند. پس POST مستقیم به /v1/booking با توکن مراجع 403 field_admin_only می‌گیرد، و مراجع نوبتش را با PATCH به ساعت یا کارشناس دیگری نمی‌برد یا خودش «تأییدشده» نمی‌کند. لغو هم از راه فانکشن دوم قالب است، cancel_booking، که فقط نوبت آینده‌ی خود مراجع را لغو می‌کند؛ نوبت لغوشده دوباره فعال نمی‌شود، چون ممکن است آن ساعت را کس دیگری گرفته باشد.

ساعت‌های خالی را هم اپ به همین دلیل خودش نمی‌تواند بسازد. تابع free_slots در نوبت دهی با هوش مصنوعی همین را حساب می‌کند و فقط ساعت‌ها را برمی‌گرداند. اگر سطح دسترسی‌اش را «کلید API + کاربران واردشده» بگذارید، اپ هم با توکن مراجع صدایش می‌زند.

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

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

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

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

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

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

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

برای سیستم نوبت‌دهی حتماً باید برنامه‌نویس بک‌اند داشته باشم؟
نه. چیزی که واقعاً لازم دارید یک مدل داده‌ی درست و یک رابط کاربری است. لایه‌ی داده، احراز هویت مراجع و دسترسی سطح رکورد را بک‌اند آماده می‌دهد و شما فقط اپ یا سایت را می‌سازید.
جلوگیری از رزرو تکراری روی یک ساعت چطور انجام می‌شود؟
با فانکشن book که قالب رزرو آماده دارد: درست پیش از ساختن نوبت، نوبت‌های همه‌ی مراجع همان کارشناس را در همان بازه می‌خواند و ساعت پر را با ۴۰۹ رد می‌کند، و بعد از ثبت هم یک بار دیگر نگاه می‌کند تا دو درخواست هم‌زمان هر دو نمانند. موتور قوانین عمداً چند رکورد را هم‌زمان نمی‌بیند، و اپ با توکن مراجع فقط نوبت‌های خود او را می‌بیند، پس جای این بررسی فانکشن است، نه قانون و نه خود اپ.
می‌شود بعد از ثبت نوبت پیامک تأیید فرستاد؟
بله. رویداد ساخته‌شدن نوبت از راه وبهوک به سرویس پیامکی یا هر سامانه‌ی دیگری وصل می‌شود، بدون اینکه کد سمت سرور بنویسید.
مراجع‌ها باید ثبت‌نام کنند یا مهمان هم می‌تواند نوبت بگیرد؟
خدمت‌ها، کارشناس‌ها و ساعت‌های کاری عمومی‌اند و بدون ورود دیده می‌شوند، ولی خودِ نوبت به کاربر گره می‌خورد تا هر کسی فقط نوبت خودش را ببیند. برای همین ثبت نوبت نیاز به ورود دارد و ساده‌ترین شکلش کد یکبار مصرف پیامکی است.

مطالب مرتبط