تحليل المتطلبات → قصص المستخدمين → اختيار البنية → تصميم ER → تصميم API → اختيار التقنيات → بدء البرمجة

بصفتي Alice (مدير المستأجر)، أريد:
- US-01: إضافة متجر تجارة إلكترونية جديد حتى أتمكن من تتبع مقاييسه
- US-02: دعوة أعضاء الفريق حتى يتمكن Charlie من الوصول إلى التحليلات
- US-03: عرض لوحة معلومات تعرض الإيرادات/الطلبات عبر جميع متاجري
- US-04: الاشتراك في خطة تناسب عدد متاجري
- US-05: تصدير التقارير بصيغة CSV/Excel
- US-06: إعداد تنبيهات عندما تنخفض الإيرادات عن حد معين

بصفتي Bob (مشغل المنصة)، أريد:
- US-07: إدارة حسابات المستأجرين (إنشاء/تعليق/حذف)
- US-08: تحديد خطط اشتراك بحدود ميزات مختلفة
- US-09: عرض مقاييس المنصة بالكامل (إجمالي المستأجرين/MRR/التفعيلات)
- US-10: معالجة مدفوعات الاشتراك عبر Stripe
- US-11: إرسال إشعارات للمستأجرين حول الاشتراكات المنتهية

بصفتي Charlie (محلل بيانات)، أريد:
- US-12: بناء تقارير تحليلية مخصصة بنطاق تاريخ وفلاتر
- US-13: مقارنة أداء المتاجر جنبًا إلى جنب
- US-14: جدولة إنشاء تقارير آلية (يومي/أسبوعي/شهري)
- US-15: استقبال إشعارات فورية عند حدوث أحداث مهمة

// قصص المستخدمين → تعيين الوحدات الوظيفية
return [
    'إدارة المستأجرين' => [
        'US-07: إدارة حسابات المستأجرين',
        'US-01: إضافة متاجر تجارة إلكترونية',
        'US-02: دعوة أعضاء الفريق',
    ],
    'الاشتراك والفواتير' => [
        'US-04: الاشتراك في خطة',
        'US-08: تحديد خطط الاشتراك',
        'US-10: معالجة مدفوعات Stripe',
        'US-11: إشعارات انتهاء الصلاحية',
    ],
    'التحليلات والتقارير' => [
        'US-03: عرض لوحة معلومات الإيرادات',
        'US-05: تصدير التقارير',
        'US-12: بناء تقارير مخصصة',
        'US-13: مقارنة أداء المتاجر',
        'US-14: جدولة إنشاء التقارير',
    ],
    'التنبيهات والإشعارات' => [
        'US-06: تنبيهات انخفاض الإيرادات',
        'US-15: إشعارات الأحداث الفورية',
    ],
    'إدارة المنصة' => [
        'US-09: مقاييس المنصة بالكامل',
    ],
];

// تم التنفيذ بنجاح

// app/Models/Traits/BelongsToTenant.php
trait BelongsToTenant
{
    protected static function bootBelongsToTenant(): void
    {
        static::addGlobalScope('tenant', function (Builder $builder) {
            $tenantId = Tenant::current()?->id;
            if ($tenantId) {
                $builder->where('tenant_id', $tenantId);
            }
        });

        static::creating(function (Model $model) {
            $tenantId = Tenant::current()?->id;
            if ($tenantId && ! $model->isDirty('tenant_id')) {
                $model->tenant_id = $tenantId;
            }
        });
    }
}

// app/Models/Tenant.php
class Tenant extends Model
{
    protected static Tenant $currentTenant;

    public static function setCurrent(self $tenant): void
    {
        static::$currentTenant = $tenant;
    }

    public static function current(): ?self
    {
        return static::$currentTenant ?? null;
    }
}

// app/Http/Middleware/SetTenantContext.php
class SetTenantContext
{
    public function handle(Request $request, Closure $next): Response
    {
        if ($user = $request->user()) {
            Tenant::setCurrent($user->tenant);
        }
        return $next($request);
    }
}

// تم التنفيذ بنجاح

// app/Models/Tenant.php
class Tenant extends Model
{
    use HasFactory, SoftDeletes;

    protected $fillable = ['name', 'slug', 'domain', 'status'];

    protected static function booted(): void
    {
        static::creating(function (self $tenant) {
            $tenant->slug ??= Str::slug($tenant->name);
            $tenant->domain ??= "{$tenant->slug}.shopmetrics.io";
        });
    }

    public function users(): HasMany
    {
        return $this->hasMany(User::class);
    }

    public function shops(): HasMany
    {
        return $this->hasMany(Shop::class);
    }

    public function subscription(): HasOne
    {
        return $this->hasOne(Subscription::class)->ofMany([], fn ($q) => $q->orderByDesc('created_at'));
    }

    public function alerts(): HasMany
    {
        return $this->hasMany(Alert::class);
    }

    public function isActive(): bool
    {
        return $this->status === 'active' &&
               $this->subscription?->stripe_status === 'active';
    }

    public function canAddShop(): bool
    {
        $limit = $this->subscription?->plan->shop_limit ?? 0;
        return $this->shops()->count() < $limit;
    }
}

// app/Models/Order.php
class Order extends Model
{
    use BelongsToTenant, HasFactory;

    protected $fillable = [
        'tenant_id', 'shop_id', 'external_id',
        'customer_email', 'total_cents', 'status', 'ordered_at',
    ];

    protected $casts = [
        'total_cents' => 'integer',
        'ordered_at' => 'datetime',
    ];

    public function shop(): BelongsTo
    {
        return $this->belongsTo(Shop::class);
    }

    public function items(): HasMany
    {
        return $this->hasMany(OrderItem::class);
    }

    public function getTotalDollarsAttribute(): float
    {
        return $this->total_cents / 100;
    }
}

// تم التنفيذ بنجاح

{
    "data": {
        "id": 1,
        "type": "shop",
        "attributes": {
            "name": "متجر Alice على Amazon",
            "platform": "amazon",
            "status": "active",
            "created_at": "2024-01-15T10:00:00Z"
        },
        "relationships": {
            "tenant": { "data": { "id": 1, "type": "tenant" } }
        }
    },
    "meta": {
        "request_id": "req_abc123",
        "timestamp": "2024-03-15T14:30:00Z"
    }
}

// routes/api.php
Route::prefix('v1')->group(function () {

    // عام: المصادقة
    Route::post('auth/login', [AuthController::class, 'login']);
    Route::post('auth/register', [AuthController::class, 'register']);

    // المسارات المصادق عليها
    Route::middleware(['auth:sanctum', 'set-tenant-context'])->group(function () {

        // المصادقة
        Route::post('auth/logout', [AuthController::class, 'logout']);
        Route::get('auth/me', [AuthController::class, 'me']);

        // المستأجر (مستأجر المستخدم الحالي)
        Route::get('tenant', [TenantController::class, 'show']);
        Route::patch('tenant', [TenantController::class, 'update']);

        // المتاجر
        Route::apiResource('shops', ShopController::class);

        // موارد متداخلة تحت المتاجر
        Route::prefix('shops/{shop}')->group(function () {
            Route::apiResource('orders', OrderController::class)->only(['index', 'show']);
            Route::apiResource('products', ProductController::class);
        });

        // لوحة المعلومات
        Route::prefix('dashboard')->group(function () {
            Route::get('overview', [DashboardController::class, 'overview']);
            Route::get('top-products', [DashboardController::class, 'topProducts']);
            Route::get('revenue', [DashboardController::class, 'revenueChart']);
        });

        // التقارير
        Route::apiResource('reports', ReportController::class)->only(['index', 'store', 'show']);
        Route::post('reports/{report}/download', [ReportController::class, 'download']);

        // التنبيهات
        Route::apiResource('alerts', AlertController::class);

        // الاشتراك
        Route::get('plans', [PlanController::class, 'index']);
        Route::post('subscriptions', [SubscriptionController::class, 'store']);
        Route::get('subscription', [SubscriptionController::class, 'show']);
        Route::delete('subscription', [SubscriptionController::class, 'cancel']);

        // إدارة الفريق (tenant_owner فقط)
        Route::middleware('role:tenant_owner')->prefix('team')->group(function () {
            Route::get('members', [TeamController::class, 'index']);
            Route::post('invite', [TeamController::class, 'invite']);
            Route::delete('members/{user}', [TeamController::class, 'remove']);
        });
    });

    // Stripe Webhooks (بدون مصادقة)
    Route::post('webhooks/stripe', [WebhookController::class, 'handleStripe']);
});

// تم التنفيذ بنجاح

// config/shopmetrics.php
return [
    'tenant' => [
        'strategy' => env('TENANT_STRATEGY', 'shared_schema'),
        'default_plan' => env('DEFAULT_PLAN_SLUG', 'starter'),
        'trial_days' => env('TRIAL_DAYS', 14),
    ],

    'limits' => [
        'starter' => ['shops' => 3, 'users' => 5, 'reports_per_month' => 10],
        'pro' => ['shops' => 25, 'users' => 25, 'reports_per_month' => 100],
        'enterprise' => ['shops' => -1, 'users' => -1, 'reports_per_month' => -1],
    ],

    'reports' => [
        'max_date_range_days' => 365,
        'formats' => ['csv', 'xlsx', 'json'],
        'storage_disk' => env('REPORT_DISK', 's3'),
        'retention_days' => env('REPORT_RETENTION_DAYS', 90),
    ],

    'sync' => [
        'platforms' => ['amazon', 'shopify', 'ebay', 'etsy'],
        'sync_interval_minutes' => env('SYNC_INTERVAL', 60),
        'batch_size' => env('SYNC_BATCH_SIZE', 500),
    ],

    'alerts' => [
        'channels' => ['email', 'slack', 'webhook'],
        'check_interval_minutes' => env('ALERT_CHECK_INTERVAL', 15),
    ],
];

// تم التنفيذ بنجاح

// ============================================
// شامل: هيكل المشروع والإعداد الأولي
// ترحيلات قاعدة البيانات، النماذج، والضبط
// ============================================

// database/migrations/2024_01_01_000001_create_tenants_table.php
Schema::create('tenants', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('slug')->unique();
    $table->string('domain')->unique();
    $table->string('status')->default('active'); // active/suspended/cancelled
    $table->softDeletes();
    $table->timestamps();

    $table->index('status');
});

// database/migrations/2024_01_01_000002_create_plans_table.php
Schema::create('plans', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('slug')->unique();
    $table->integer('shop_limit')->default(3);
    $table->integer('user_limit')->default(5);
    $table->integer('price_cents')->default(0);
    $table->string('stripe_price_id')->nullable();
    $table->boolean('is_active')->default(true);
    $table->timestamps();
});

// database/migrations/2024_01_01_000003_create_subscriptions_table.php
Schema::create('subscriptions', function (Blueprint $table) {
    $table->id();
    $table->foreignId('tenant_id')->constrained()->cascadeOnDelete();
    $table->foreignId('plan_id')->constrained();
    $table->string('stripe_id')->unique();
    $table->string('stripe_status');
    $table->timestamp('trial_ends_at')->nullable();
    $table->timestamp('ends_at')->nullable();
    $table->timestamps();

    $table->index(['tenant_id', 'stripe_status']);
});

// database/migrations/2024_01_01_000004_create_shops_table.php
Schema::create('shops', function (Blueprint $table) {
    $table->id();
    $table->foreignId('tenant_id')->constrained()->cascadeOnDelete();
    $table->string('name');
    $table->string('platform'); // amazon/shopify/ebay/etsy
    $table->string('external_id');
    $table->string('status')->default('active');
    $table->json('metadata')->nullable();
    $table->timestamps();

    $table->unique(['tenant_id', 'platform', 'external_id']);
    $table->index(['tenant_id', 'status']);
});

// database/migrations/2024_01_01_000005_create_orders_table.php
Schema::create('orders', function (Blueprint $table) {
    $table->id();
    $table->foreignId('tenant_id')->constrained()->cascadeOnDelete();
    $table->foreignId('shop_id')->constrained()->cascadeOnDelete();
    $table->string('external_id');
    $table->string('customer_email')->nullable();
    $table->unsignedBigInteger('total_cents')->default(0);
    $table->string('status')->default('pending');
    $table->timestamp('ordered_at');
    $table->timestamps();

    $table->unique(['tenant_id', 'external_id']);
    $table->index(['tenant_id', 'shop_id', 'status', 'ordered_at']);
    $table->index(['tenant_id', 'ordered_at']);
});