۱. هدف و دامنه کاربرد سند (Scope & Purpose)

این سند به عنوان مرجع الزام‌آور فنی جهت پیاده‌سازی و نهایی‌سازی «روش سوم ورود به ملک» میان سه لایه اصلی اکوسیستم متارنگ تدوین شده است:

فرانت‌اند و لایه کلاینت (React.js / WebGL Modal)

بک‌اند میکروسرویس و مدیریت کسب‌وکار (Go Microservice & API Gateway)

سرور اختصاصی بازی و کلاینت موتور سه‌بعدی (Unity Dedicated Game Server & WebGL Build)

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

۲. نمودار جریان اجرای ورود (End-to-End Sequence Flow)

۳. تکالیف فنی و قرارداد لایه میکروسرویس (تیم آقای آجرلو)

۳.۱. به‌روزرسانی Endpoint ورود به ملک

اندپوینت ثبت ورود باید علاوه بر منطق حسابداری و دسترسی، اطلاعات اجرای بازی را بازگرداند:

متد و مسیر: POST /api/features/{featureId}/building/enter

احراز هویت: اجباری (Bearer Token)

پیش‌شرط‌های اعتبارسنجی (Execution Pre-conditions):

بررسی باز بودن قفل امنیت حساب (Account Security Lock)؛ در صورت قفل بودن 410 Gone بازگردانده شود.

بررسی اتمام ساخت بنا (construction_end_date سپری شده باشد)؛ در غیر این صورت خطای 412 صادر گردد.

فعال بودن ورود (is_active: true) و تطابق سطح کاربری (level_scope_type).

بررسی حضور کاربر داخل ملک؛ در صورت وجود سشن فعال بازگشت خطای 412 user already inside this building.محاسبه تخفیف کوپن، کسر موجودی PSC و ریال و فعال‌سازی پنجره ۲۴ ساعته.

درخواست (Request Body):

{

  "coupon_code": "OPENING-10" // اختیاری

}

پاسخ موفق جدید (Response 200 OK):

{

  "message": "entry successful",

  "data": {

    "feature_id": 44,

    "feature_properties_id": "TO111",

    "ticket_id": "b8f278d6-52c1-4b11-9a74-dcfbb193a101",

    "launch_url": "https://play.metarang.com/vod/TO111",

    "expires_in_seconds": 60

  }

}

۳.۲. پروتکل فراخوانی ماشین‌به‌ماشین (gRPC Client به سرور بازی)

بلافاصله پس از تسویه مالی، میکروسرویس Go با کلاینت gRPC متد CreateEntryTicket را بر روی سرور گیم‌پلی فراخوانی می‌کند:

message CreateEntryTicketRequest {

  uint64 user_id = 1;

  string feature_properties_id = 2;

  uint32 ttl_seconds = 3; // مقدار پیش‌فرض: 60 ثانیه

  string request_id = 4;

}

message CreateEntryTicketResponse {

  bool accepted = 1;

  string ticket_id = 2;

  string launch_url = 3;

  string error_message = 4;

}

۳.۳. هندلینگ پیام‌های خروج و لغو دسترسی (Kick / Revoke)

اندپوینت خروج POST /api/features/{featureId}/building/exit پس از ثبت اتمام ویزیت در دیتابیس، فراخوانی Unary RPC با عنوان KickUser را با دلیل user_exit به سمت گیم‌پلی ارسال می‌نماید.

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

۴. تکالیف فنی و قرارداد سرور و کلاینت یونیتی (تیم آقای سعادت‌پور)

۴.۱. سرور گیم‌پلی (Unity Dedicated Server / Node Coordinator)

میزبانی gRPC Service: سرور بازی پورت gRPC محافظت‌شده با mTLS/Token را جهت دریافت درخواست‌های میکروسرویس باز نگه می‌دارد.

بررسی تیکت در حافظه رم (Zero-Network-Call Verification): تیکت دریافتی به همراه ticket_id، user_id، feature_properties_id و زمان انقضای ۶۰ ثانیه‌ای در کش سریع حافظه (Redis یا In-Memory) ذخیره شده و پس از اولین Handshake کلاینت WebGL باطل می‌شود (Anti-Replay).

تفکیک Room و لود محیط سه‌بعدی: شناسه feature_properties_id به صورت مستقیم مبنای واکشی Prefab و Room محیط قرار می‌گیرد و از لود مجدد کل دیتای سنگین جلوگیری می‌شود.

پروتکل ارتباطی کلاینت: از آنجا که نسخه WebGL در مرورگر محدود به WebSocket است، اتصال زنده کلاینت به سرور بازی از طریق مسیر امن WSS پشت Nginx/Envoy با آدرس تعیین‌شده برقرار می‌گردد.

۴.۲. ارتباطات داده‌ای دوطرفه در طول بازی (gRPC Unary)

استعلام سکه و امتیاز (Station Queries): هنگامی که آواتار داخل ملک با یک دستگاه تعامل می‌کند، کلاینت بازی درخواست را به گیم‌سرور داده و سرور بازی مستقیماً با فراخوانی gRPC Unary از میکروسرویس Go استعلام می‌گیرد:

rpc GetCitizenBalance(CitizenBalanceRequest) returns (CitizenBalanceResponse);

rpc GetCitizenPoints(CitizenPointsRequest) returns (CitizenPointsResponse);

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

۵. تکالیف فنی لایه فرانت‌اند (React.js WebGL Wrapper)

۵.۱. جریان باز شدن و نمایش Modal

1. کاربر بر روی دکمه «ورود به ملک» کلیک می‌کند.

فرانت‌اند درخواست POST /api/features/{featureId}/building/enter را با توکن کاربر ارسال می‌کند.

در صورت دریافت پاسخ ۲۰۰، فرانت‌اند پنجره Modal تمام‌صفحه را باز کرده و تگ iframe را به صورت زیر مقداردهی می‌کند:

<iframe 

src={`${launch_url}?ticket=${ticket_id}&feature=${feature_properties_id}`}

  allow="autoplay; fullscreen; microphone"

  className="vod-webgl-frame"

/>

مدیریت فوکوس و ورودی‌ها: در زمان باز بودن Modal، Pointer Lock و Focus کیبورد منحصراً به iframe اختصاص می‌یابد تا کلیدهای حرکتی بازی (WASD / Space) موجب اسکرول صفحه وب نشوند.

بستن Modal و خروج: با کلیک کاربر روی دکمه خروج یا بستن پنجره، فرانت‌اند اندپوینت POST /api/features/{featureId}/building/exit را صدا زده و سورس iframe را خالی (src="") می‌کند تا منابع گرافیکی و وب‌سوکت آزاد شوند.

۵.۲. الزامات زیرساخت وب‌سرور و پروکسی (Nginx / Envoy)

هدرهای مجاز فریمینگ: در سرور ارائه‌دهنده بیلد WebGL، هدر زیر باید تنظیم شود تا مرورگر اجازه لود در دامنه اصلی متارنگ را بدهد:

Content-Security-Policy: frame-ancestors 'self' https://metarang.com https://*.metarang.com;

مجوزهای امنیتی ایزولاسیون: تنظیم هدرهای Cross-Origin-Opener-Policy: same-origin و Cross-Origin-Embedder-Policy: require-corp در صورت نیاز WebGL به مالتی‌تردینگ و WebAssembly پیشرفته.

۶. پروتکل خطاها و واکنش‌های سیستمی (Error Handling Matrix)

۷. تعهدات اجرایی و جدول زمان‌بندی (Action Items & Sign-off)

تیم میکروسرویس (جناب آقای آجرلو):

پیاده‌سازی منطق فراخوانی gRPC به سرور گیم‌پلی درون مسیر POST /building/enter و تغییر آبجکت بازگشتی به ساختار حاوی ticket_id و launch_url تا پایان هفته جاری.

اتصال رویداد خروج POST /building/exit به متد KickUser در سرور گیم‌پلی.

تیم یونیتی و گیم‌پلی (جناب آقای سعادت‌پور):

پیاده‌سازی رسیور gRPC متد CreateEntryTicket و ذخیره‌سازی تیکت موقت ۶۰ ثانیه‌ای.

تکمیل هندشیک وب‌سوکت WebGL بر مبنای ticket_id و متصل کردن آواتار به Room معادل feature_properties_id.

پیاده‌سازی فراخوانی Unary RPC برای ایستگاه‌های سکه و امتیاز در صحنه سه‌بعدی.

تیم فرانت‌اند:

بازطراحی کامپوننت مودال ورود به ملک در React جهت باز کردن امن بیلد WebGL از طریق iframe با پارامترهای دریافتی از API.