جزئیات شغل

طراحی و پیاده‌سازی زیرساخت و APIهای اعلان رویدادهای مشاهده‌نشده (Unseen Events) برای شهروندان ( manager of backend )

تجربه: 3

سن: 18 الی 30

محدوده حقوق و دستمزد: قابل مذاکره

جای خالی: 1

طبیعت شغلی : پیمانی

تاریخ ارسال : 2026.11.15

آخرین تاریخ : 2027.01.20

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

هدف این تسک، توسعه زیرساخت بک‌اند برای ثبت، ذخیره‌سازی و مدیریت رویدادهای مهم شهروندان و فراهم‌سازی APIهای موردنیاز تیم فرانت‌اند (React) جهت دریافت و نمایش مرحله‌ای این رویدادها است.

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

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

الزامات تسک
۱. ثبت رویدادهای هدف در بک‌اند

در زمان وقوع هر یک از ۵ رویداد زیر، یک رکورد مستقل با وضعیت اولیه unseen برای شهروند ذی‌نفع ایجاد شود:

  • ارتقای سطح شهروندی (level_up): هنگام ارتقای شهروند به سطح جدید، برای هر سطح یک رویداد مستقل ثبت شود.

  • فروش زمین (property_sold): هنگام فروش زمینی که شهروند قبلاً قیمت‌گذاری کرده است، رویداد فروش برای شهروند مالک زمین ثبت شود.

  • تأیید پیشنهاد خرید زمین (buy_offer_accepted): هنگام پذیرش پیشنهاد خرید شهروند توسط مالک زمین، رویداد مربوط به خریدار ثبت شود.

  • عضویت عضو جدید در سلسله (dynasty_member_joined): هنگام پذیرش دعوت‌نامه و عضویت شهروند دعوت‌شده در سلسله، رویداد برای شهروند دعوت‌کننده ثبت شود.

  • تأیید ورود به سلسله (dynasty_join_accepted): هنگام تأیید درخواست یا پیشنهاد شهروند برای ورود به یک سلسله، رویداد مربوط به شهروند درخواست‌کننده ثبت شود.

هر رکورد باید حداقل شامل شناسه رویداد، شناسه شهروند، نوع رویداد، زمان وقوع و وضعیت مشاهده‌شدن باشد.

۲. افزودن فلگ وضعیت رویدادهای دیده‌نشده به API اطلاعات اولیه شهروند

در API مربوط به ورود شهروند به ایندکس داخلی، شامل Auth / Me / Init، فیلد زیر اضافه شود:

has_unseen_events

مقادیر قابل‌قبول:

  • 0: شهروند هیچ رویداد دیده‌نشده‌ای ندارد.

  • 1: حداقل یک رویداد دیده‌نشده برای شهروند ثبت شده است.

این فیلد باید بر اساس وضعیت واقعی رویدادهای شهروند در دیتابیس محاسبه شود.

۳. ایجاد API دریافت فهرست رویدادهای دیده‌نشده

یک Endpoint برای دریافت فهرست خلاصه رویدادهای دیده‌نشده شهروند ایجاد شود.

مسیر پیشنهادی:

GET /api/citizen/unseen-events

این API باید:

  • فقط رویدادهای متعلق به شهروند احراز هویت‌شده را برگرداند.

  • فقط رکوردهایی را نمایش دهد که وضعیت آن‌ها unseen است.

  • رویدادها را بر اساس زمان وقوع، از قدیمی‌ترین به جدیدترین (FIFO) مرتب کند.

  • اطلاعات خلاصه هر رویداد شامل شناسه، نوع و عنوان باشد.

  • از بازگشت جزئیات سنگین رویداد در این مرحله خودداری کند.

  • صرفاً با فراخوانی این API، وضعیت رویدادها را به مشاهده‌شده تغییر ندهد.

نمونه خروجی:

{
"data": [
{
"id": 101,
"type": "level_up",
"title": "سطح ۴"
},
{
"id": 102,
"type": "level_up",
"title": "سطح ۵"
},
{
"id": 105,
"type": "property_sold",
"title": "فروش زمین"
}
]
}

۴. ایجاد API دریافت جزئیات رویداد و ثبت وضعیت مشاهده‌شدن

یک Endpoint برای دریافت جزئیات کامل هر رویداد ایجاد شود.

مسیر پیشنهادی:

GET /api/citizen/unseen-events/{event_id}

در صورت نیاز به تفکیک عملیات دریافت و تغییر وضعیت، امکان استفاده از متد POST نیز بررسی شود.

منطق اجرایی:

  • بررسی احراز هویت شهروند.

  • بررسی مالکیت رویداد و اطمینان از تعلق آن به شهروند درخواست‌دهنده.

  • واکشی اطلاعات کامل رویداد بر اساس نوع آن.

  • ارسال جزئیات اختصاصی رویداد به فرانت‌اند.

  • تغییر وضعیت رویداد به seen و ثبت زمان مشاهده در فیلد seen_at.

  • اطمینان از اجرای صحیح تغییر وضعیت در شرایط درخواست‌های هم‌زمان و جلوگیری از ثبت وضعیت نادرست.

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

۵. ارائه جزئیات اختصاصی هر نوع رویداد

API جزئیات باید بر اساس مقدار type، اطلاعات مرتبط با هر رویداد را به فرانت‌اند ارائه دهد.

رویداد ارتقای سطح شهروندی (level_up):

  • نام و شماره سطح جدید.

  • تاریخ و ساعت دقیق ارتقای سطح.

  • میزان پاداش دریافتی.

  • اطلاعات تکمیلی مرتبط با ارتقای سطح، در صورت وجود.

رویداد فروش زمین (property_sold):

  • شناسه یا کد زمین.

  • مبلغ نهایی معامله.

  • تاریخ و ساعت فروش.

  • اطلاعات خریدار، در صورت نیاز.

  • اطلاعات تکمیلی مرتبط با معامله.

رویداد تأیید پیشنهاد خرید زمین (buy_offer_accepted):

  • شناسه یا کد زمین.

  • مبلغ پیشنهاد پذیرفته‌شده.

  • تاریخ و ساعت تأیید پیشنهاد.

  • اطلاعات مالک زمین.

  • اطلاعات تکمیلی مرتبط با پیشنهاد خرید.

رویداد عضویت عضو جدید در سلسله (dynasty_member_joined):

  • اطلاعات شهروند عضو جدید.

  • اطلاعات سلسله مربوطه.

  • تاریخ و ساعت عضویت.

  • پاداش یا امتیاز احتمالی مرتبط با رویداد.

رویداد تأیید ورود به سلسله (dynasty_join_accepted):

  • اطلاعات سلسله‌ای که درخواست ورود به آن تأیید شده است.

  • اطلاعات شهروند یا مالک سلسله، در صورت نیاز.

  • تاریخ و ساعت تأیید درخواست.

  • پاداش یا امتیاز احتمالی مرتبط با رویداد.

۶. مدیریت ترتیب نمایش و انباشت رویدادها

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

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

فرانت‌اند باید بتواند رویدادها را به ترتیب دریافت کرده و پس از بسته‌شدن مدال هر رویداد، جزئیات رویداد بعدی را درخواست کند.

۷. مدیریت وضعیت در صورت خروج شهروند

در صورتی که شهروند دارای چند رویداد دیده‌نشده باشد و تنها بخشی از آن‌ها را مشاهده کند، وضعیت رویدادهای مشاهده‌نشده باقی‌مانده باید حفظ شود.

برای مثال، اگر شهروند دارای ۳ رویداد دیده‌نشده باشد و تنها جزئیات رویداد اول را دریافت کند، در ورود بعدی:

  • فلگ has_unseen_events برابر 1 باقی بماند.

  • رویداد اول از فهرست دیده‌نشده‌ها حذف شود.

  • دو رویداد باقی‌مانده به ترتیب زمان وقوع در لیست بازگردانده شوند.

۸. مستندسازی APIها

مستندات فنی APIهای توسعه‌یافته باید برای تیم فرانت‌اند (React) آماده شود و شامل موارد زیر باشد:

  • مسیر و متد هر Endpoint.

  • ساختار دقیق درخواست و پاسخ.

  • فیلدهای اجباری و اختیاری.

  • فرمت JSON خروجی برای هر یک از ۵ نوع رویداد.

  • نحوه احراز هویت و بررسی مالکیت رویداد.

  • منطق ترتیب دریافت و نمایش رویدادها.

  • نحوه تغییر وضعیت رویداد به مشاهده‌شده.

  • مدیریت خطاها و پاسخ‌های مربوط به رویدادهای نامعتبر یا غیرمجاز.

وظایف اجرایی

  1. بررسی ساختار فعلی دیتابیس و APIهای ورود و اطلاعات اولیه شهروند.

  2. طراحی و ایجاد ساختار دیتابیس برای ذخیره رویدادهای شهروندان، شامل نوع رویداد، زمان وقوع، وضعیت مشاهده‌شدن و اطلاعات مرتبط.

  3. پیاده‌سازی منطق ثبت خودکار رویدادها برای هر یک از ۵ رویداد هدف.

  4. افزودن فیلد has_unseen_events به API اطلاعات اولیه شهروند.

  5. پیاده‌سازی Endpoint دریافت فهرست رویدادهای دیده‌نشده با رعایت ترتیب FIFO.

  6. پیاده‌سازی Endpoint دریافت جزئیات رویداد بر اساس شناسه و نوع آن.

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

  8. پیاده‌سازی تغییر اتمیک وضعیت رویداد به مشاهده‌شده پس از پردازش موفق درخواست جزئیات.

  9. بررسی و مدیریت سناریوهای انباشت رویداد، خروج ناگهانی شهروند و درخواست‌های هم‌زمان.

  10. تهیه مستندات فنی و نمونه پاسخ JSON برای تمامی APIهای توسعه‌یافته.

  11. انجام تست‌های عملکردی و صحت‌سنجی منطق ثبت، دریافت، ترتیب نمایش و تغییر وضعیت رویدادها.

خروجی نهایی

  • زیرساخت بک‌اند ثبت و مدیریت رویدادهای دیده‌نشده شهروندان در متارنگ.

  • ثبت مستقل و خودکار هر یک از ۵ رویداد هدف با وضعیت اولیه unseen.

  • افزودن فلگ has_unseen_events به API اطلاعات اولیه شهروند.

  • API دریافت فهرست رویدادهای دیده‌نشده با ترتیب زمانی FIFO.

  • API دریافت جزئیات کامل رویداد و ثبت وضعیت مشاهده‌شدن آن.

  • مدیریت صحیح رویدادهای انباشته‌شده، خروج ناگهانی شهروند و جلوگیری از دسترسی غیرمجاز.

  • مستندات کامل APIها و نمونه پاسخ‌های JSON برای تحویل به تیم فرانت‌اند (React).

  • آماده‌سازی زیرساخت لازم برای نمایش مرحله‌ای رویدادهای مهم شهروند پس از ورود به ایندکس داخلی متارنگ


    جهت مطالعه کامل تسک در گیتهاب از لینک زیر اقدام نمایید
    https://github.com/iranpsc/Metaverse-Rang-Microservice/issues/208

    مشخصات کار تعریف شده

    عنوان شغلی: طراحی و پیاده‌سازی زیرساخت و APIهای اعلان رویدادهای مشاهده‌نشده (Unseen Events) برای شهروندان

    تعیین: manager of backend

    تجربه: 3

    سن: 18 الی 30

    محدوده حقوق و دستمزد: قابل مذاکره

    جای خالی: 1

    طبیعت شغلی : پیمانی

    تاریخ ارسال : 2026.11.15

    آخرین تاریخ : 2027.01.20

    اکنون درخواست دهید