Seating
سلام سلام صد تا سلام
سیستم صندلی به این شکل ترسیم شده که بچه های ایوندی یه سری سالن طراحی می کنن و به عنوان قالب نیازه ذخیره شه. در نهایت برای ساخت سالن برای هر رویداد، با استفاده قالب‌های ذخیره شده امکان ساخت سالن درخواستی فراهم می شه. که انتخاب و قالب سالن به انتخاب خود برگزار کننده می تونه انجام بپذیره.
قالب سالن
ساختار دیتای مربوط به قالب سالن ها کاملا توسط فرانت طراحی می شه و به عنوان JSON در اختیار api قرار داده می شه که ذخیره شه. یه اسمی هم روش گذاشته می شه. و API نظری روی ساختار دیتای قالب ها نداره و نخواهد داشت.
قالب ها قابلیت انتشار دارند که در صورتی که قالبی ذخیره بشه و ناقص باشه، توسط برگزار کننده گان مشاهده نشه و تنها زمانی توسط برگزار کننده ها قابل رویت و استفاده باشن که قالب ها منتشر شده باشن.
ساخت قالب
برای ساخت قالب به این شکل عمل می کنیم:
که بجای ANY_VALID_JSON اطلاعات مربوط به قالب سالن در ساختار JSON ارسال و ذخیره می شه.
در صورت نیاز به انتشار قالب می تونید مقداری published رو که boolean قبول می کنه رو true و یا برای لغو انتشار هم false ارسال نمایید.
کل قالب ها (منتشر شده یا نشده)
یه ریسورس ای برای دریافت کل قالب ها، چه منتشر شده و یا نشده داریم که مخصوص مدیران ایوندی هست و برای آنها قابل استفاده می باشد.
هدف از این ریسورس اینه که بشه لیستی از قالب ها رو حتی اگه منتشر نشده باشه هم در دسترس داشته باشیم که بتونن بهش رجوع کنن و بعد از اتمام طراحی سالن بتونن منتشر کنن که برای برگزار کننده‌گان هم قابل رویت باشه.
برای دریافت لیست قالب ها به این نحو عمل می کنیم:
نکته ای که وجود داره اینه که در لیستی از قالب ها که گرفته می شه، دیتای خود قالب قرار داده نشده که هنگام مشاهده لیست، مجبور که دانلود حجم بالای دیتا نباشیم. زیرا که دیتای قالب ها می تونه حجیم باشه.
قالب های منتشر شده
ریسورس دیگری برای دریافت لیستی از قالب های منتشر شده مثل ریسورس فوق داریم، با این تفاوت که برای کل کاربران در دسترس هست. علاوه بر اون فقط قالب های منتشر شده لیست می شن.
برای دریافت لیست قالب ها به این نحو عمل می کنیم:
ویرایش قالب
در صورت نیاز به ویرایش قالب ای یا ویرایش اسم قالب و یا برای منتشر کردن یا برای لغو انتشار، می شه از این ریسورس زیر استفاده کرد.
سیستم صندلی به این شکل ترسیم شده که بچه های ایوندی یه سری سالن طراحی می کنن و به عنوان قالب نیازه ذخیره شه. در نهایت برای ساخت سالن برای هر رویداد، با استفاده قالب‌های ذخیره شده امکان ساخت سالن درخواستی فراهم می شه. که انتخاب و قالب سالن به انتخاب خود برگزار کننده می تونه انجام بپذیره.
قالب سالن
ساختار دیتای مربوط به قالب سالن ها کاملا توسط فرانت طراحی می شه و به عنوان JSON در اختیار api قرار داده می شه که ذخیره شه. یه اسمی هم روش گذاشته می شه. و API نظری روی ساختار دیتای قالب ها نداره و نخواهد داشت.
قالب ها قابلیت انتشار دارند که در صورتی که قالبی ذخیره بشه و ناقص باشه، توسط برگزار کننده گان مشاهده نشه و تنها زمانی توسط برگزار کننده ها قابل رویت و استفاده باشن که قالب ها منتشر شده باشن.
ساخت قالب
برای ساخت قالب به این شکل عمل می کنیم:
POST https://api.evand.com/seating/templates
{
"title" : "this is a title",
"data" : {
ANY_VALID_JSON
},
“published” : “false”
}
که بجای ANY_VALID_JSON اطلاعات مربوط به قالب سالن در ساختار JSON ارسال و ذخیره می شه.
در صورت نیاز به انتشار قالب می تونید مقداری published رو که boolean قبول می کنه رو true و یا برای لغو انتشار هم false ارسال نمایید.
کل قالب ها (منتشر شده یا نشده)
یه ریسورس ای برای دریافت کل قالب ها، چه منتشر شده و یا نشده داریم که مخصوص مدیران ایوندی هست و برای آنها قابل استفاده می باشد.
هدف از این ریسورس اینه که بشه لیستی از قالب ها رو حتی اگه منتشر نشده باشه هم در دسترس داشته باشیم که بتونن بهش رجوع کنن و بعد از اتمام طراحی سالن بتونن منتشر کنن که برای برگزار کننده‌گان هم قابل رویت باشه.
برای دریافت لیست قالب ها به این نحو عمل می کنیم:
GET https://api.evand.com/seating/templates/all
{
"data": [
{
"id": 6,
"title": "this is a title",
"published": false,
"_links": {
"self": {
"href": "/seating/templates/6"
}
}
},
{
"id": 5,
"title": "this is a title1",
"published": true,
"_links": {
"self": {
"href": "/seating/templates/5"
}
}
},
...
],
"meta": {
"pagination": {
"total": 6,
"count": 6,
"per_page": 10,
"current_page": 1,
"total_pages": 1,
"links": []
}
}
}
نکته ای که وجود داره اینه که در لیستی از قالب ها که گرفته می شه، دیتای خود قالب قرار داده نشده که هنگام مشاهده لیست، مجبور که دانلود حجم بالای دیتا نباشیم. زیرا که دیتای قالب ها می تونه حجیم باشه.
قالب های منتشر شده
ریسورس دیگری برای دریافت لیستی از قالب های منتشر شده مثل ریسورس فوق داریم، با این تفاوت که برای کل کاربران در دسترس هست. علاوه بر اون فقط قالب های منتشر شده لیست می شن.
برای دریافت لیست قالب ها به این نحو عمل می کنیم:
GET https://api.evand.com/seating/templates
{
"data": [
{
"id": 5,
"title": "this is a title1",
"published": true,
"_links": {
"self": {
"href": "/seating/templates/5"
}
}
},
...
],
"meta": {
"pagination": {
"total": 6,
"count": 6,
"per_page": 10,
"current_page": 1,
"total_pages": 1,
"links": []
}
}
}
ویرایش قالب
در صورت نیاز به ویرایش قالب ای یا ویرایش اسم قالب و یا برای منتشر کردن یا برای لغو انتشار، می شه از این ریسورس زیر استفاده کرد.
PUT https://api.evand.com/seating/templates/5
{
"title" : "برج میلاد",
"data" : {
"abc": "دارای هزارن هزار صندلی خوشگل"
},
"published": true
}
سالن
سالن دارای بخش های متنوع، و بخش ها دارای صندلی های رنگ و بارنگ و جذابی می باشند که هر کدام label مربوط به خود را دارا می باشند که با در دست داشتن بلیط، به سالن تشریف برده تا پذیرایی جانانه ای ازمون بشه.
یکی از اولین مراحل ساخت و پاخت سیستم صندلی برای رویداد، ایجاد سالن می باشد.
توجه کنید که برای ریسورس های زیر نیازه توکن اهراز هویت خود را در هدر ارسال نمایید. در صورتی که نیاز به راهنمایی در مورد نحوه ارسال توکن از هدر دارید، لطفا سر خود را محکم به نزدیکترین دیوار بکوبید.
ساخت سالن
برای ایجاد سالن به این شکل عمل می کنیم:
POST https://api.evand.com/seating/halls
{
"name" : "test",
"meta" : "{}",
"event_id" : "1610",
"enabled": false << OPTIONAL
}
فیلدهای ارسالی به این شرح می باشد:
- Name اسم سالن
- Meta اطلاعات جانبی که بک بهش نیازی نداره و مورد استفاده فرانت واقع می شه. این فیلد هر اطلاعاتی می تونه باشه.
- event_id که جهت فعالسازی سالن برای رویداد مورد نظر هست.
- enabled که در صورت فعالسازی، سیستم صندلی آماده استفاده توسط شرکت کننده گان خواهد بود و می تونن خریدهای خود را انجام دهند. توجه کنید که در صورتی که سالن فعال کنید، امکان غیرفعال کردنش نخواهد بود. تنها راه انصراف از فروش، کنسل کردن رویداد می تونه باشه.
نکته: بنظر فعلا meta توسط فرانت استفاده نشده. در صورتی که نیاز به استفاده شه، می تونین اطلاعات بدین که نوع این فیلد رو به json تغییر بدیم، بجای string. تا نیاز به تبدیل json به متن و بالعکس توسط فرانت نباشه.
سالن متصل به رویداد
در صورت نیاز به دریافت سالن متصل به رویداد، درخواستی به ریسورس خود رویداد می زنیم:
GET http://api.evand.abc/events/testasli?links=seatingHall
{
"data": {
"id": 1610,
"name": "تست",
"slug": "testasli",
….
"_links": {
….
"seating_hall": {
"uri": "/seating/halls/1"
}
}
}
}
همانطور که می بینید لینکی به ریسورس سالن ساخته شده برای رویداد مورد نظر، داده شده است که به استفاده از آن می شه به اطلاعات سالن رویداد دست یافت.
نکته: بنظر بهتر بود لینک ها پیش فرض در اطلاعات برگشتی لحاظ می شد، بدون اینکه نیاز باشه در url ریسورس پارامتری لحاظ بشه.
دریافت سالن
برای دریافت اطلاعات سالن، یه درخواست GET می زنیم:
GET https://api.evand.com/seating/halls/1
{
"name" : "test",
"meta" : "{}",
"event_id" : "1610",
"enabled": false
}
همین.
فعالسازی و ویرایش سالن
بعد از اتمام کارهای سالن و بخش هاش و صندلی و اتصال بلیت ها وقت فعال سازی سالن فرار می رسه. برای فعال سازی در اصل سالن رو ویرایش می کنیم:
PUT https://api.evand.com/seating/halls/1
{
"enabled": true
}
توجه کنین که بعد از فعالسازی سالن، امکان غیرفعال سازیش نخواهد بود. دلیل این امر هم اینه که ممکنه سالن فروش داشته باشه و نمی خواهیم مشکلی پیش بیاد.
در صورت نیاز به توقف فروش رویداد، می شه از قابلیت لغو رویداد استفاده کرد.
برای ویرایش اسم سالن، و متای مورد استفاده فرانت، هم می شه از این ریسورس استفاده کرد. بجای enabled می شه فیلدهای دیگه رو ارسال کرد یا همه رو با هم ارسال کرد.
ساخت، ویرایش، حذف بخش های مختلف سالن
متاسفانه از پیچیده ترین ریسورس ها مون هستن که همه کار رو با هم انجام می دن. هم ساخت هم ویرایش و هم حذف! تصمیم درستی نبوده از این لحاظ که همه با هم انجام بشه ولی جدا می کردیم هم تعداد ریکوئست ها می رفت بالا و هم پیچیدگی زیاد می شد. از آنجایی هم که ممکنه برخی درخواست ها ناموفق بشه و برخی موفق، می تونست مشکلاتی ایجاد کنه.
البته شاید بیشتر روش وقت نزاشتیم که بتونیم حداقل برخی مفاهیم رو جدا کنیم که ریسورس های خودشون رو داشته باشن.
نمی دونم!
ساخت بخش
نکته ای که وجود داره اینه که هنگام ساخت سالن، صندلی ها هم ساخته می شن. یعنی نیازه اطلاعات صندلی ها هم ارسال بشن.
نکته مهمی که وجود داره اینه که اگه از قبل بخش هایی ایجاد شده باشه، و بخواهید بخش جدید هم ایجاد کنید، نیاز است دیتاهای بخش قدیمی، به همراه بخش هایی که می خواهید ساخته شده رو با هم بفرستید، در غیر اینصورت، در صورتی که بخش های موجود رو نفرستید، باعث حذفشان خواهد شد!
برای ایجاد بخش به این نحوه عمل می کنیم:
POST https://api.evand.com/seating/halls/1/sections
از آنجایی که این ریسورس پیچیده هست، سعی می کنم همان دیتایی که ارسال می کنیم رو با هم، تیکه تیکه بررسی کنیم:
{
"id": null,
"title" : "this is a title",
"meta": {"test" : "test"},
"seats": [
{
"id": null,
"ticket_id": null,
"hold": false,
"meta": {"test" : "test"},
"label": "A3"
},
{
"id": null,
"ticket_id": 5424,
"hold": true,
"label": "A2"
}
]
}
برای ایجاد چه بخش جدید، چه صندلی جدید، نیازه id رو null بفرستیم. یعنی اگه بخش جدید می سازیم باید آی دی رو نول بدیم که بخش جدید ایجاد شود. برای صندلی ها هم همچنین. فقط توجه کنید که در صورتی که آی دی بخش نول باشه، نباید آی دی صندلی ها رو تعیین کنید، و در غیراینصورت با خطا مواجه خواهید شد.
دلیل این امر هم اینه که وقتی بخش ایجاد نشده، نمی شه صندلی توش رو تغییر داد و بهش رجوع کرد.
بریم رو باقی تکه کد فوق:
{
"id": null,
"title" : "this is a title",
"meta": {"test" : "test"},
"seats": [
{
"id": null,
"ticket_id": null,
"hold": false,
"meta": {"test" : "test"},
"label": "A3"
},
{
"id": null,
"ticket_id": 5424,
"hold": true,
"label": "A2"
}
]
}
دو فیلد دیگه داریم به اسم title و meta.
فیلد title برای تعیین اسم بخش هست و می تونه متن ساده ای باشه.
فیلد meta هم json خواهد بود که صرفا برای استفاده کلاینت (فرانت) هست و بک باهاش کاری نداره و صرفا ذخیره و بر می گردونه.
در اصل قرار بود در این فیلد اطلاعاتی در رابطه با چینش صندلی ها و بخش ها در سالن که در فرانت هندل می شه قرار بگیره. در نتیجه کاربردی برای بک نداره.
بریم رو تیکه کد بعدی:
{
"id": null,
"title" : "this is a title",
"meta": {"test" : "test"},
"seats": [
{
"id": null,
"ticket_id": null,
"hold": false,
"meta": {"test" : "test"},
"label": "A3"
},
{
"id": null,
"ticket_id": 5424,
"hold": true,
"label": "A2"
}
]
}
یه فیلد دیگه به اسم seats داریم که صندلی های بخش ها درش تعیین می شه.
فیلد seats آرایه ای از آبجکت صندلی ها هست که اطلاعات مروبط به صندلی درش تعیین می شه.
فیلد های مربوط به هر صندلی به این نحو است:
فیلد id داریم که همونطور که توضیح داده شد، در صورتی که آی دی صندلی null باشه، باعث ساخته شدن صندلی خواهد بود.
فیلد ticket_id می تونه هنگام ساخت null باشه و یا اینکه به بلیت ای وصل شه.
فیلد hold داریم که برگزار کننده می تونه تعیین کنه، صندلی رو می خواد بفروشه و یا نگه داره و قابل فروش نباشه.
فیلد meta هم باز مخصوص فرانت هست.
فیلد label داریم که نیاز اصلی بهش این بود که بفهمیم فلان صندلی که خریداری می شه، label اش چی هست که بتونیم در بلیت چاپ کنیم. از آنجایی که بک از چینش صندلی ها اطلاع نداره و فقط توسط فرانت هندل می شه برای همین نیاز بود این فیلد هم توسط فرانت به بک ارسال شه. (که دست گل شون درد نکنه)
حذف، ویرایش، و نکاتی در مورد بخش‌ها
نحوه کارکرد ریسورس صندلی به این شکله که برای اینکه تغییری در دیتاها رخ نده، باید هر چی از قبل ثبت شده رو دوباره بفرستید.
مثلا وقتی می خواهید بخش جدید اضافه کنید، بخش های قبلی + بخش جدید رو در درخواست جدید باید بفرستید تا باعث نگه‌داشته شدن بخش های قبلی بشه و علاوه بر اون باعث ایجاد بخش جدید شه.
با این حال، برای حذف بخشی، در صورتی که درخواستی بخش ها رو می فرستید، اگر بخشی رو نفرستید، باعث حذف شان خواهد شد.
دلیل اینکه به این شکل زده شده، راحتی برای فرانت بود. که بتونه کل دیتاها رو یجا بفرسته و ایطوری اگه بخشی حذف شده، حذف شه، اگه آپدیت شده، آپدیت شه، و اگر هم اضافه شده که اضافه می شه. دیگه نیاز نداشته باشن برای حذف درخواست جداگانه ای بفرستن، یا برای ویرایش هم همچنین و … .
البته مشکلی که این مدل داره، اینه که حجم دیتاها خیلی زیاد می تونه بشه، در نتیجه اگر سالن بزرگ ای رو قرار باشه مدیریت کنیم، حجم دیتاها خیلی می تونه زیاد بشه، و برای افرادی که سرعت اینترنت مناسبی ندارن می تونه مشکل ساز شه و نیاز می شه کلی دیتا به سرور بفرستن.
مشکل دیگه هم اینکه به راحتی مشخص آپدیت و ایجاد و حذف کجاست و در صورت اشتباه کوچیکی باعث از بین رفتن دیتا می شه. مثلا برای اضافه کردن، اگه فراموش کنیم دیتاهای قبلی رو هم بفرستیم، باعث پاک شدنشان خواهد بود!
امیدارم، در آینده، با تجربه ای که از کار با سیستم صندلی بدست می یاریم، بتونیم راه های بهتری برای این مسائل پیدا و پیاده کنیم که هم دغدغه فرانت برای هندل حجم عظیم دیتا و هم مدیریت راحتر بخش ها حل شه و هم مسائلی دیگری که مطرح شد درباره طراحی این ریسورس بخش‌ها هم حل شن.
دریافت بخش‌ها
برای دریافت بخش های ساخته شده به این نحو عمل می کنیم:
GET https://api.evand.com/seating/halls/1/sections
{
"data": [
{
"id": 16,
"title": "this is a title",
"sold": false,
"meta": {
"test": "test"
},
"seats": [
{
"id": 23,
"ticket_id": null,
"hold": false,
"sold": true,
"reserved": false,
"meta": {
"test": "test"
},
"label": "A3"
},
{
"id": 24,
"ticket_id": 5424,
"hold": false,
"sold": false,
"reserved": false,
"meta": null,
"label": "A2"
}
]
}
],
"meta": {
"pagination": {
"total": 1,
"count": 1,
"per_page": 10,
"current_page": 1,
"total_pages": 1,
"links": []
}
}
}
در اطلاعات برگشتی برای بخش ها چند فیلد اضافه شدن که توضیحشون به شرح زیر هست:
فیلد sold برای هر بخش: در صورتی که بخشی ای دیگری قابل خرید نباشه، مقداری این فیلد true خواهد بود که بشه فهمید بخش مربوطه به فروش رفته.
برای صندلی هم دو فیلد reserved و sold داریم که همانطوری که از معنی شون مشخص هست برای تعیین اینکه صندلی رزرو شده یا به فروش رفته.
خرید صندلی
و برای بروبچ فرانت:
هنگام ثبت سفارش مثلا ۲ تا بلیت رو انتحاب می کنه و اینا و درخواست ثبت سفارش می دید.
که تعداد بلیت برای بک می فرستید.
اینجا باید تعدادی صندلی بجای بلیت بفرستید. و بلیت های ارسالی از طرف شما نادیده
گرفته می شن.
اینطوری باید دیتا بفرستید:
{
...
"discount_code": "husen_bala_shahdana",
"affiliate_code" : 73,
"seats": [{"id" : 4, "price" : 100}, {"id" : 3, "price": 1000}]
}
فیلد های discount_code و affiliate_code که مثل قبل هست و اجباری نیست.
فیلد seats هم آرایه است که آبجکت می گیره.
آی دی صندلی مربوطه. و اون price هم صرفا برای بلیت های نوع donation استفاده داره مثل چیزی که الان داریم و کاربرد دیگه ای نداره. اگه بلیته donation نیست نمی خواد بفرستیدش در غیراینصورت مورد نیاز هست.
وضعیت های موجود صندلی
لیستی از وضعیت های هر صندلی به شرح زیر است:
- available یعنی قابل فروش هست.
- hold وقتی توسط برگزار کننده غیرقابل فروش تعیین می شه و نمی خوام صندلی مربوطه به فروش بره.
- sold وقتی صندلی جان به فروش رفته و دیگه کاریش نمی شه کرد.
- reserved وقتی صندلی رزرو می شود.
نحوه Hold و Unhold کردن صندلی ها
انجام این عمل در هر شرایطی، مثل قبل از فعال سازی فروش و یا بعدش ممکن خواهد بود.
فقط صندلی های موجود و hold شده رو می شه تغییر وضعیت داد. در نتیجه اگه به سرتون زد صندلی فروش رفته و یا رزرو شده رو تغییر وضعیت دهید با خطای ۴۲۲ مواجه خواهید شد.
برای Hold کردن صندلی مربوطه بدین شکل عمل می کنیم:
POST https://api.evand.com/seating/seats/SEAT_ID/hold
Headers:
- Authorization: Bearer ACCESS_TOKEN
برای در آوردن از Hold بدین سان عمل می کنیم:
DELETE https://api.evand.com/seating/seats/SEAT_ID/hold
Headers:
- Authorization: Bearer ACCESS_TOKEN
صزفا نیاز به دانستن آی دی صندلی مربوطه هست که در URI ریسورس های فوق قرار دهید.
در صورت موفقیت بآمیز ودن عملیات، از کد وضعیت زیبای ۲۰۰ با شما پذیرایی خواهد شد.
نظرات