در زمان عدم حضور شهروند در متارنگ، ممکن است رویدادهای مهمی در حساب کاربری او رخ دهد که نیازمند اطلاعرسانی پس از ورود مجدد به سامانه هستند.
هدف این تسک، توسعه زیرساخت بکاند برای ثبت، ذخیرهسازی و مدیریت رویدادهای مهم شهروندان و فراهمسازی APIهای موردنیاز تیم فرانتاند (React) جهت دریافت و نمایش مرحلهای این رویدادها است.
سیستم باید رویدادهای مرتبط با شهروند را در زمان وقوع ثبت کرده و پس از ورود مجدد او به ایندکس داخلی، امکان دریافت فهرست رویدادهای دیدهنشده و واکشی جزئیات هر رویداد را بهصورت ترتیبی فراهم کند.
هر رویداد باید بهصورت مستقل ذخیره شود و پس از دریافت جزئیات آن توسط فرانتاند، وضعیت مشاهدهشدن آن در بکاند ثبت گردد تا از نمایش مجدد رویداد در ورودهای بعدی جلوگیری شود.
الزامات تسک
۱. ثبت رویدادهای هدف در بکاند
در زمان وقوع هر یک از ۵ رویداد زیر، یک رکورد مستقل با وضعیت اولیه unseen برای شهروند ذینفع ایجاد شود:
ارتقای سطح شهروندی (level_up): هنگام ارتقای شهروند به سطح جدید، برای هر سطح یک رویداد مستقل ثبت شود.
فروش زمین (property_sold): هنگام فروش زمینی که شهروند قبلاً قیمتگذاری کرده است، رویداد فروش برای شهروند مالک زمین ثبت شود.
تأیید پیشنهاد خرید زمین (buy_offer_accepted): هنگام پذیرش پیشنهاد خرید شهروند توسط مالک زمین، رویداد مربوط به خریدار ثبت شود.
عضویت عضو جدید در سلسله (dynasty_member_joined): هنگام پذیرش دعوتنامه و عضویت شهروند دعوتشده در سلسله، رویداد برای شهروند دعوتکننده ثبت شود.
تأیید ورود به سلسله (dynasty_join_accepted): هنگام تأیید درخواست یا پیشنهاد شهروند برای ورود به یک سلسله، رویداد مربوط به شهروند درخواستکننده ثبت شود.
هر رکورد باید حداقل شامل شناسه رویداد، شناسه شهروند، نوع رویداد، زمان وقوع و وضعیت مشاهدهشدن باشد.
۲. افزودن فلگ وضعیت رویدادهای دیدهنشده به API اطلاعات اولیه شهروند
در API مربوط به ورود شهروند به ایندکس داخلی، شامل Auth / Me / Init، فیلد زیر اضافه شود:
has_unseen_events
مقادیر قابلقبول:
این فیلد باید بر اساس وضعیت واقعی رویدادهای شهروند در دیتابیس محاسبه شود.
۳. ایجاد 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 خروجی برای هر یک از ۵ نوع رویداد.
نحوه احراز هویت و بررسی مالکیت رویداد.
منطق ترتیب دریافت و نمایش رویدادها.
نحوه تغییر وضعیت رویداد به مشاهدهشده.
مدیریت خطاها و پاسخهای مربوط به رویدادهای نامعتبر یا غیرمجاز.
وظایف اجرایی
بررسی ساختار فعلی دیتابیس و APIهای ورود و اطلاعات اولیه شهروند.
طراحی و ایجاد ساختار دیتابیس برای ذخیره رویدادهای شهروندان، شامل نوع رویداد، زمان وقوع، وضعیت مشاهدهشدن و اطلاعات مرتبط.
پیادهسازی منطق ثبت خودکار رویدادها برای هر یک از ۵ رویداد هدف.
افزودن فیلد has_unseen_events به API اطلاعات اولیه شهروند.
پیادهسازی Endpoint دریافت فهرست رویدادهای دیدهنشده با رعایت ترتیب FIFO.
پیادهسازی Endpoint دریافت جزئیات رویداد بر اساس شناسه و نوع آن.
پیادهسازی منطق بررسی مالکیت رویداد و جلوگیری از دسترسی شهروند به رویدادهای سایر کاربران.
پیادهسازی تغییر اتمیک وضعیت رویداد به مشاهدهشده پس از پردازش موفق درخواست جزئیات.
بررسی و مدیریت سناریوهای انباشت رویداد، خروج ناگهانی شهروند و درخواستهای همزمان.
تهیه مستندات فنی و نمونه پاسخ JSON برای تمامی APIهای توسعهیافته.
انجام تستهای عملکردی و صحتسنجی منطق ثبت، دریافت، ترتیب نمایش و تغییر وضعیت رویدادها.
خروجی نهایی
زیرساخت بکاند ثبت و مدیریت رویدادهای دیدهنشده شهروندان در متارنگ.
ثبت مستقل و خودکار هر یک از ۵ رویداد هدف با وضعیت اولیه unseen.
افزودن فلگ has_unseen_events به API اطلاعات اولیه شهروند.
API دریافت فهرست رویدادهای دیدهنشده با ترتیب زمانی FIFO.
API دریافت جزئیات کامل رویداد و ثبت وضعیت مشاهدهشدن آن.
مدیریت صحیح رویدادهای انباشتهشده، خروج ناگهانی شهروند و جلوگیری از دسترسی غیرمجاز.
مستندات کامل APIها و نمونه پاسخهای JSON برای تحویل به تیم فرانتاند (React).
آمادهسازی زیرساخت لازم برای نمایش مرحلهای رویدادهای مهم شهروند پس از ورود به ایندکس داخلی متارنگ
جهت مطالعه کامل تسک در گیتهاب از لینک زیر اقدام نمایید
https://github.com/iranpsc/Metaverse-Rang-Microservice/issues/208