همه‌ی پروژه‌ها
Backend API در حال توسعه

Event Planet

یک پلتفرم مدیریت رویداد API-first که با Django REST Framework توسعه داده شده است؛ شامل رویدادهای چندمرحله‌ای، چرخه حیات وضعیت اعتبارسنجی‌شده و ویژگی‌های پویای Type-safe (مبتنی بر الگو EAV).

نقش من
توسعه‌دهنده
نوع
پروژه شخصی
لینک‌ها

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

این پروژه به‌صورت کاملاً API-first پیاده‌سازی شده و تمام ارتباطات از طریق اندپوینت‌های نسخه‌بندی‌شده (/api/v1/ و /api/v2/) انجام می‌گیرد که به کمک ابزارهایی مثل OpenAPI، Swagger، Redoc و کالکشن رسمی Postman مستند شده‌اند.

کارهایی که انجام دادم

  • پیاده‌سازی چرخه حیات رویداد مبتنی بر State Machine با انتقال‌های وضعیت کنترل‌شده که هم در ادمین جنگو و هم در لایه API اعمال می‌شوند.
  • طراحی مدل داده انعطاف‌پذیر EAV: تعریف سراسری Attribute به‌همراه ستون‌های اختصاصی برای مقادیر هر رویداد، جهت حفظ نوع‌داده‌ها (Type-safe).
  • پشتیبانی هم‌زمان از احراز هویت JWT (شامل دسترسی، رفرش و بلک‌لیست هنگام خروج) و ورودSession-based برای کار راحت‌تر با Browsable API و Swagger.
  • طراحی سطح دسترسی‌های نقش‌محور برای برگزارکنندگان و شرکت‌کنندگان، که هم در سطح Permission Class و هم در لایه اعتبارسنجی Serializer بررسی می‌شوند.
  • اعتبارسنجی دقیق بازه زمانی و عدم هم‌پوشانی مراحل رویداد؛ مراحل هر رویداد صرفاً در زمان وضعیت پیش‌نویس (Draft) قابل ویرایش هستند.
  • مدیریت ثبت‌نام در سطح کل رویداد همراه با کنترل ظرفیت، محدودسازی ارسال بازخورد تنها به رویدادهای خاتمه‌یافته (و مختص شرکت‌کنندگان ثبت‌نام‌شده)، و انتشار نتایج توسط برگزارکننده.
  • قابلیت فیلتر بر اساس وضعیت، جست‌وجوی متنی در عنوان و توضیحات، نسخه‌بندی URL و ارائه مستندات تعاملی با drf-spectacular.
  • راه‌اندازی پروژه با Docker Compose شامل بررسی سلامت (Healthcheck) دیتابیس PostgreSQL، اسکریپت Entrypoint برای اجرای خودکار مهاجرت‌ها و تفکیک تنظیمات محیط‌های توسعه (SQLite) و پروداکشن (PostgreSQL).

تصمیم‌های طراحی

ثبت‌نام در سطح رویداد

عملیات ثبت‌نام و بررسی ظرفیت به جای مراحل (Stages)، روی کل رویداد مدیریت می‌شود. در سناریوهای رایج مانند وبینارهای چندبخشی یا کارگاه‌های چندجلسه‌ای، کاربر یک‌بار ثبت‌نام می‌کند و در تمام مراحل حضور دارد؛ بنابراین ثبت‌نام مجزا برای هر مرحله تنها پیچیدگی غیرضروری ایجاد می‌کرد و EventStage صرفاً یک واحد زمان‌بندی است.

پیاده‌سازی EAV بدون JSONField

مدل Attribute ساختار داده مشترک (متن، عدد صحیح، بولین) را تعریف می‌کند و EventAttributeValue مقادیر را در یکی از ستون‌های تایپ‌دار خود نگه می‌دارد. اعمال قانون پر شدن تنها یکی از ستون‌ها، هم در متد clean() ادمین و هم در سریالایزر بررسی می‌شود.

منبع واحد برای انتقال وضعیت‌ها

قوانین انتقال وضعیت در متغیر ALLOWED_TRANSITIONS روی مدل تعریف شده‌اند. از آنجا که DRF به‌صورت پیش‌فرض متد clean() مدل را صدا نمی‌زند، این قوانین برای ادمین از طریق Event.clean() و برای API از طریق EventSerializer.validate() اعمال می‌شوند.

پشتیبانی از JWT در کنار Session

کتابخانه SimpleJWT روش اصلی احراز هویت است، اما لاگین Session نیز در کنار آن فعال شده تا استفاده از Browsable API و دکمه «Authorize» در محیط Swagger به ساده‌ترین شکل ممکن انجام شود.

چرخه‌ی حیات وضعیت رویداد

  • DRAFT → PUBLISHED, CANCELLED
  • PUBLISHED → ONGOING, CLOSED, CANCELLED
  • ONGOING → FINISHED, CANCELLED
  • CLOSED → FINISHED, CANCELLED
  • FINISHED → وضعیت نهایی (Terminal)
  • CANCELLED → وضعیت نهایی (Terminal)

گروه‌های API

  • عمومی (Public) — فهرست و جزئیات رویدادهای منتشرشده، مراحل و نتایج نهایی (بدون نیاز به احراز هویت)
  • شرکت‌کننده (Participant) — ثبت‌نام در رویدادها، مشاهده وضعیت ثبت‌نام‌های شخصی، ثبت و مدیریت بازخوردها
  • برگزارکننده (Organizer) — ایجاد رویداد و مرحله، مدیریت ویژگی‌های پویا، مشاهده شرکت‌کنندگان، بررسی بازخوردها و انتشار نتایج
  • احراز هویت (Auth) — ثبت‌نام کاربران، دریافت، تمدید و ابطال (Blacklist) توکن‌های JWT، به همراه ورود و خروج با Session

تست‌نویسی

مجموعه تست‌های پروژه با Pytest و Factory Boy توسعه یافته و شامل پوشش کامل کنترل دسترسی، مجوزها، عملیات CRUD، تغییر وضعیت‌ها، مدیریت مراحل، اعتبارسنجی EAV، ثبت‌نام‌ها، بازخوردها و احراز هویت است. همچنین یک دستور مدیریتی (Management Command) مبتنی بر factory_boy و Faker برای تولید داده‌های نمایشی واقع‌گرایانه پیاده‌سازی شده است.

قدم‌های بعدی

  • پیاده‌سازی Throttling روی اندپوینت‌های حساس مثل احراز هویت و ثبت‌نام
  • افزودن سیستم Caching برای اندپوینت‌های عمومی و پربازدید
  • یکپارچه‌سازی مکانیزم Pagination در تمام اندپوینت‌های لیستی
  • راه‌اندازی CI با کمک GitHub Actions برای اجرای خودکار تست‌ها و بررسی کیفیت کد

تکنولوژی‌ها

  • Python
  • Django
  • Django REST Framework
  • SimpleJWT
  • django-filter
  • drf-spectacular
  • PostgreSQL
  • Docker
  • Docker Compose
  • Pytest
  • Factory Boy

پروژه‌های دیگر