پس از تلاش‌‌های فراوان معین بالاخره به سرزمین رویا‌هایش ایران‌سرور (IranServer) رسید! از آن‌جایی که ایران‌سرور قصد دارد به زودی سرویس‌های ابری جدیدی را به کاربرانش ارائه دهد، معین قرار است همراه با سایر ایران‌سروریون به توسعه پنل کاربری جدیدی با عنوان "ایران‌گیت" مشغول شود که بر پایه لاراول ۱۲ است که به تازگی معرفی شده است!

از آن‌جایی که ایران‌گیت به زودی قرار است به کاربران معرفی شود، در این سوال شما نیز قرار است تا به کمک معین و ایران‌سروریون بروید تا با استفاده از لاراول ۱۲ و استارتر کیت Jetstream بخش‌هایی از پنل کاربری ایران‌گیت را پیاده‌سازی کنید.

جزئیات پروژه

پروژه‌ی اولیه را از این لینک دانلود کنید.

irangate
├── app
│   ├── Http
│   │   ├── Middleware
│   │   │   └── CheckFeatureAccess.php
│   ├── Jobs
│   │   ├── DowngradePendingInvoicesJob.php
│   │   └── ExpireSubscriptionsJob.php
│   ├── Models
│   │   ├── Coupon.php
│   │   ├── Feature.php
│   │   ├── Invoice.php
│   │   ├── Log.php
│   │   ├── Plan.php
│   │   ├── Referral.php
│   │   ├── Subscription.php
│   │   ├── SubscriptionLog.php
│   │   └── User.php
│   ├── Observers
│   │   └── SubscriptionObserver.php
│   ├── Policies
│   │   ├── FeaturePolicy.php
│   │   └── SubscriptionPolicy.php
│   ├── Providers
│   │   ├── AppServiceProvider.php
│   │   └── AuthServiceProvider.php
├── bootstrap
│   ├── app.php
│   └── providers.php
├── database
│   ├── factories
│   │   ├── CouponFactory.php
│   │   ├── FeatureFactory.php
│   │   ├── InvoiceFactory.php
│   │   ├── LogFactory.php
│   │   ├── PlanFactory.php
│   │   ├── ReferralFactory.php
│   │   ├── SubscriptionFactory.php
│   │   ├── SubscriptionLogFactory.php
│   │   └── UserFactory.php
│   ├── migrations
│   │   ├── 2025_02_26_164235_create_plans_table.php
│   │   ├── 2025_02_26_164344_create_features_table.php
│   │   ├── 2025_02_26_164408_create_subscriptions_table.php
│   │   ├── 2025_02_26_164432_create_subscription_logs_table.php
│   │   ├── 2025_02_26_164501_create_referrals_table.php
│   │   ├── 2025_02_26_164538_create_coupons_table.php
│   │   ├── 2025_02_26_164610_create_invoices_table.php
│   │   ├── 2025_02_26_164639_create_logs_table.php
│   │   └── 2025_02_26_173343_create_plan_feature_table.php
│   ├── seeders
│   │   ├── CouponSeeder.php
│   │   ├── DatabaseSeeder.php
│   │   ├── FeatureSeeder.php
│   │   ├── InvoiceSeeder.php
│   │   ├── LogSeeder.php
│   │   ├── PlanSeeder.php
│   │   ├── ReferralSeeder.php
│   │   ├── SubscriptionLogSeeder.php
│   │   ├── SubscriptionSeeder.php
│   │   └── UserSeeder.php
├── routes
│   └── console.php
├── tests
├── README.md
├── artisan
├── composer.json
├── composer.lock
├── package.json
├── phpunit.xml
├── server.php
└── webpack.mix.js

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

معرفی کلی پروژه ایران‌گیت (IranGate) و موارد پیاده‌سازی شده

در این بخش به معرفی پروژه ایران‌گیت (IranGate) خواهیم پرداخت. بخش‌هایی از ایران‌گیت در این پروژه اولیه این سوال از قبل پیاده‌سازی شده‌اند و نیازی به پیاده‌سازی دوباره ندارند. پایه ایران‌گیت همانطور که پیش‌تر گفته شد بر اساس استارتر کیت Jetstream می‌باشد و امکانات پیشفرضی که این استارتر کیت در اختیار توسعه‌دهندگان قرار می‌دهد را شامل می‌شود. موارد پیاده‌سازی شده در پروژه به شکل زیر هستند:

<?php

use App\Http\Controllers\FeatureController;
use App\Http\Controllers\InvoiceController;
use App\Http\Controllers\PlanController;
use App\Http\Controllers\SubscriptionLogController;
use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('welcome');
});

Route::middleware([
    'auth:sanctum',
    config('jetstream.auth_session'),
    'verified',
])->group(function () {
    Route::get('/dashboard', function () {
        return view('dashboard');
    })->name('dashboard');
});

<?php

namespace App\Http\Controllers;

class FeatureController extends Controller
{
    public function access($featureSlug)
    {
        return response('Access granted to feature: ' . $featureSlug, 200);
    }
}

<?php

use App\Http\Controllers\FeatureController;
use App\Http\Controllers\InvoiceController;
use App\Http\Controllers\PlanController;
use App\Http\Controllers\SubscriptionLogController;
use Illuminate\Support\Facades\Route;

Route::get('/feature/{featureSlug}', [FeatureController::class, 'access'])->middleware('feature.access')->name('feature');

<?php

namespace App\Http\Controllers;

class InvoiceController extends Controller
{
    public function index()
    {
        $invoices = auth()->user()->invoices()->latest()->get();

        return view('invoices.index', compact('invoices'));
    }
}

<?php

namespace App\Http\Controllers;

use App\Models\Plan;
use Illuminate\Support\Facades\Auth;

class PlanController extends Controller
{
    public function index()
    {
        $plans = Plan::all();
        return view('profile.plans', compact('plans'));
    }

    public function switch(Plan $plan)
    {
        $user = Auth::user();

        $subscription = $user->subscription;

        if (!$subscription) {
            $subscription = $user->subscription()->create([
                'plan_id' => $plan->id,
                'expires_at' => now()->addDays($plan->duration),
            ]);
        } else {
            $subscription->plan_id = $plan->id;
            $subscription->expires_at = now()->addDays($plan->duration);
        }

        if ($plan->price > 0) {
            $invoice = $user->invoices()->create([
                'plan_id' => $plan->id,
                'amount' => $plan->price,
                'status' => 'pending',
            ]);

            $subscription->expires_at = now()->addDays($plan->duration);
            $subscription->save();

            return redirect()->route('plans.index')->with('success', 'اشتراک کاربری شما با موفقیت بروزرسانی شد. لطفا نسبت به پرداخت صورت حساب آن اقدام کنید.');
        } else {
            $subscription->save();
            return redirect()->route('plans.index')->with('success', 'اشتراک کاربری شما با موفقیت بروزرسانی شد.');
        }
    }
}

<?php

namespace App\Http\Controllers;

class SubscriptionLogController extends Controller
{
    public function index()
    {
        $subscriptionLogs = auth()->user()->subscriptionLogs()->latest()->get();

        return view('subscription-logs.index', compact('subscriptionLogs'));
    }
}

پیاده‌سازی جداول و نوشتن مایگریشن‌ها (Migrations)

در این بخش، مایگریشن‌های مربوط به ایجاد جداول users، plans، subscriptions، invoices، logs، coupons، features و سایر جداول مرتبط باید پیاده‌سازی شوند. این جداول برای مدیریت کاربران، اشتراک‌ها، پرداخت‌ها، ویژگی‌های پلن‌ها و گزارش‌های سیستم طراحی شده‌اند. ساختار مربوط به هر کدام از جداول در بخش زیر مشخص است:

پیاده‌سازی مدل‌ها

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

• مدل User: مدیریت کاربران سیستم، شامل اطلاعات کاربری و روابط مرتبط.
• مدل Plan: نمایش‌دهنده‌ی اشتراک‌های کاربری، شامل ویژگی‌ها و مشخصات هر پلن.
• مدل Subscription: ثبت اطلاعات اشتراک کاربران در اشتراک‌های مختلف.
• مدل Invoice: صورت‌حساب‌های مربوط به خرید اشتراک و پرداخت‌های کاربران.
• مدل Feature: ویژگی‌هایی که برای هر اشتراک کاربری قابل ارائه هستند.
• مدل Coupon: کدهای تخفیف که کاربران می‌توانند برای کاهش هزینه خرید اشتراک کاربری استفاده کنند.
• مدل Referral: ثبت سیستم ارجاع کاربران و پاداش‌های مربوط به معرفی کاربران جدید.
• مدل Log: ثبت اقدامات کاربران در سیستم جهت نظارت و بررسی تاریخچه فعالیت‌ها.
• مدل SubscriptionLog: مدیریت تغییرات اشتراک کاربران و تاریخچه ارتقا یا کاهش پلن.

پیاده‌سازی روابط بین مدل‌ها

• هر کاربر (User) می‌تواند دارای یک اشتراک کاربری (Subscription) باشد.
• هر اشتراک کاربری (Subscription) به یک اشتراک (Plan) متصل است.
• هر اشتراک (Plan) می‌تواند چندین ویژگی (Feature) داشته باشد.
• هر ویژگی (Feature) می‌تواند به چندین اشتراک (Plan) مرتبط باشد.
• هر کاربر می‌تواند چندین صورت‌حساب (Invoice) برای خرید پلن‌های مختلف داشته باشد.
• هر صورت‌حساب (Invoice) به دقیقا یک اشتراک (Plan) و دقیقا یک کاربر (User) مرتبط است.
• هر کاربر (User) می‌تواند از کدهای تخفیف (Coupon) استفاده کند.
• هر کاربر (User) می‌تواند از طریق سیستم ارجاع، کاربران جدید را معرفی کرده و پاداش دریافت کند.
• هر کاربر (User) می‌تواند چندین لاگ (Log) از فعالیت‌های خود داشته باشد. همچنین هر لاگ مربوط به دقیقا یک کاربر (User) است.
• هر کاربر (User) می‌تواند چندین تاریخچه تغییرات اشتراک (SubscriptionLogs) داشته باشد.

پیاده‌سازی فکتوری‌ها‌ (Factories)

در این بخش، فکتوری‌های تعریف شده برای تولید داده‌های تصادفی جهت تست برنامه معرفی شده‌اند. این فکتوری‌ها به منظور تولید داده‌های آزمایشی برای جداول مرتبط در پایگاه داده استفاده می‌شوند:

پیاده‌سازی سیدر (Seeder)

درون پروژه اولیه تعدادی سیدر (Seeder) وجود دارد که باید به شکل زیر پیاده‌سازی شوند، در نهایت قرار است تا این سیدر‌ها با ترتیب درستی در سیدر DatabaseSeeder مورد استفاده قرار بگیرند. سیدر‌ها باید به شکل زیر ایجاد شوند:

1. دقیقا ۵۰ کد تخفیف (Coupon) با استفاده از فکتوری Coupon ساخته شود.
2. دقیقا ۲۰ قابلیت (Feature) با استفاده از فکتوری Feature ساخته شود. همچنین یک اشتراک کاربری با عنوان (Slug) vip که توسط سیدر مربوطه ساخته شده باید به تمام قابلیت‌های ساخته شده توسط این سیدر دسترسی داشته باشد.
3. دقیقا ۱۰۰ صورت حساب (Invoice) با استفاده از فکتوری Invoice ساخته شود.
4. دقیقا ۲۰۰ لاگ (Log) با استفاده از فکتوری Log ساخته شود.
5. دقیقا ۱۰ اشتراک (Plan) با استفاده از فکتوری Plan ساخته شود. همچنین باید سه اشتراک کاربری دیگر توسط این سیدر به صورت زیر ساخته شود:
   • اشتراک پایه با نام (Name) ‌Basic، عنوان (Slug) basic، قیمت (Price) 0 و مدت‌زمان (Duration) 30 روز
   • اشتراک پریمیوم با نام (Name) ‌Premium، عنوان (Slug) premium، قیمت (Price) 100 و مدت‌زمان (Duration) 30 روز
   • اشتراک ویژه با نام (Name) ‌Vip، عنوان (Slug) vip، قیمت (Price) 200 و مدت‌زمان (Duration) 30 روز
6. دقیقا ۵۰ ارجاع (Referral) با استفاده از فکتوری Referral ساخته شود.
7. دقیقا ۱۵۰ گزارش اشتراک (SubscriptionLog) با استفاده از فکتوری SubscriptionLog ساخته شود.
8. دقیقا ۱۰۰ اشتراک کاربری (Subscription) با استفاده از فکتوری Subscription ساخته شود.
9. دقیقا ۵۰ کاربر (User) با استفاده از فکتوری User ساخته شود. تمامی این ۵۰ کاربر باید در اشتراک کاربری basic که قبلا توسط سیدر مربوطه ساخته شده است، مشترک شوند.

پیاده‌سازی پالیسی‌ها (Policies)

در این سوال شما باید دو پالیسی FeaturePolicy و SubscriptionPolicy را برای مدیریت دسترسی به ویژگی‌های خاص و اشتراک‌های کاربری خاص به صورت زیر پیاده‌سازی کنید:

<?php

namespace App\Policies;

use App\Models\User;
use App\Models\Feature;

class FeaturePolicy
{
    public function accessFeature(User $user, Feature $feature)
    {
        // TODO
    }
}

<?php

namespace App\Policies;

use App\Models\Subscription;
use App\Models\User;
use App\Models\Plan;

class SubscriptionPolicy
{
    public function accessVip(User $user, Subscription $subscription)
    {
        // TODO
    }

    public function accessPremium(User $user, Subscription $subscription)
    {
        // TODO
    }

    public function accessBasic(User $user, Subscription $subscription)
    {
        // TODO
    }
}

پیاده‌سازی Observer SubscriptionObserver

در این پروژه شما باید یک Observer را برای مدل Subscription به صورتی پیاده‌سازی کنید که هنگام بروزرسانی (Update) شناسه اشتراک کاربری (plan_id) برای یک کاربر، یک SubscriptionLog جدید ایجاد کند که مقدار user_id آن برابر با شناسه کاربری است که اشتراک کاربری آن تغییر کرده است، مقدار old_subscription_level آن برابر با مقدار عنوان (Slug) اشتراک کاربری قبلی کاربر و مقدار new_subscription_level آن برابر با مقدار عنوان (Slug) اشتراک جدید کاربر می‌باشد.

پیاده‌سازی وظایف (Jobs) و اسکجول (Schedule) کردن

در این پروژه شما باید دو جاب ExpireSubscriptionsJob و DowngradePendingInvoicesJob را برای انجام بخشی از پردازش‌های مربوط به پنل کاربری به صورت زیر پیاده‌سازی کنید:

<?php

namespace App\Jobs;

use App\Models\User;
use App\Models\Plan;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class DowngradePendingInvoicesJob implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;

    public function handle()
    {
        // TODO
    }
}

<?php

namespace App\Jobs;

use App\Models\Subscription;
use App\Models\Plan;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class ExpireSubscriptionsJob implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;

    public function handle()
    {
        // TODO
    }
}

در نهایت پس از تعریف وظایف (Jobs) های مشخص شده، شما باید این دو وظیفه (Job) را طوری در لاراول اسکجول (Schedule) کنید تا به صورت خودکار و هر دقیقه یک بار پردازش شوند.

پیاده‌سازی میدلور (Middleware)

در نهایت شما قرار است تا میدلور (Middleware) CheckFeatureAccess را برای پردازش دسترسی در درخواست (Request) کاربر به صورت زیر پیاده‌سازی کنید:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class CheckFeatureAccess
{
    public function handle(Request $request, Closure $next): Response
    {
        // TODO
    }
}

این میدلور با استفاده از پالیسی‌های تعریف شده در مراحل قبل بررسی می‌کند که آیا کاربر فعلی می‌تواند به مسیر مشخص شده که از این میدلور استفاده می‌کند و مشخص کننده مسیر یکی از قابلیت‌های موجود در برنامه است دسترسی دارد یا نه. در صورتی که کاربر در تلاش بود تا به مسیر مربوط به قابلیتی دسترسی پیدا کند که در برنامه به کل وجود ندارد باید خطای 404 به همراه پیام "این صفحه یافت نشد." و در صورتی که در تلاش بود تا به مسیر مربوط به قابلیتی دسترسی پیدا کند که اشتراک کاربری‌اش اجازه دسترسی به آن را ندارد، باید خطای 403 به همراه پیام "شما دسترسی به این بخش را ندارید." نمایش داده شود. در غیر این صورت ادامه پردازش درخواست کاربر انجام می‌شود.

آن‌چه باید آپلود کنید

• توجه: پس از پیاده‌سازی موارد خواسته شده، کل فایل‌های پروژه به‌جز پوشه‌ی vendor را زیپ کرده و ارسال کنید.
• توجه: شما مجاز به افزودن فایل جدیدی در این ساختار نیستید و تنها باید تغییرات را در فایل‌های موجود اعمال کنید.
• توجه: که نام فایل Zip اهمیتی ندارد.