# دليل الاستخدام - SOLID Principles & Clean Code & Security

## 📚 كيفية استخدام التحسينات الجديدة

### 1️⃣ استخدام Form Requests للـ Validation

**بدلاً من:**
```php
public function store(Request $request)
{
    $data = $request->validate([
        'customer_id' => 'required|exists:customers,id',
        'amount' => 'required|numeric|min:0',
    ]);
}
```

**استخدم:**
```php
use App\Http\Requests\Api\CustomerStatementRequest;

public function store(CustomerStatementRequest $request)
{
    $validated = $request->validated();
    // البيانات محققة ومنظفة تلقائياً
}
```

**لإنشاء Form Request جديد:**
```bash
php artisan make:request StoreProductRequest
```

---

### 2️⃣ استخدام Services للـ Business Logic

**بدلاً من:**
```php
// في Controller أو Model
public function processSale($sale)
{
    foreach ($sale->items as $item) {
        // 50+ سطر من Business Logic
    }
}
```

**استخدم:**
```php
use App\Services\Stock\StockService;
use App\Services\Cash\CashService;

class SaleController extends Controller
{
    public function __construct(
        private readonly StockService $stockService,
        private readonly CashService $cashService
    ) {}

    public function confirm(Sale $sale)
    {
        try {
            $this->stockService->processSaleStock($sale);
            $this->cashService->processSaleCashMovement($sale);
            
            return response()->json(['message' => 'تم التأكيد بنجاح']);
        } catch (InsufficientStockException $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }
}
```

**لإنشاء Service جديد:**
```php
// app/Services/Payment/PaymentService.php
namespace App\Services\Payment;

class PaymentService
{
    public function __construct(
        private readonly PaymentGatewayInterface $gateway
    ) {}

    public function processPayment(Order $order): bool
    {
        // Business Logic هنا
    }
}
```

---

### 3️⃣ استخدام Repository Pattern

**بدلاً من:**
```php
// استعلامات مباشرة في Controller
public function index()
{
    $products = Product::where('warehouse_id', $id)
        ->where('stock', '>', 0)
        ->get();
}
```

**استخدم:**
```php
// 1. أنشئ Interface
namespace App\Contracts\Repositories;

interface ProductRepositoryInterface
{
    public function findByWarehouse(int $warehouseId): Collection;
    public function findInStock(): Collection;
}

// 2. أنشئ Implementation
namespace App\Repositories;

class ProductRepository implements ProductRepositoryInterface
{
    public function findByWarehouse(int $warehouseId): Collection
    {
        return Product::where('warehouse_id', $warehouseId)->get();
    }
}

// 3. اربطه في Service Provider
public function register(): void
{
    $this->app->bind(
        ProductRepositoryInterface::class,
        ProductRepository::class
    );
}

// 4. استخدمه في Controller
public function __construct(
    private readonly ProductRepositoryInterface $productRepo
) {}

public function index()
{
    return $this->productRepo->findInStock();
}
```

---

### 4️⃣ استخدام Custom Exceptions

**بدلاً من:**
```php
if ($stock < $required) {
    throw new \Exception('المخزون غير كافٍ');
}
```

**استخدم:**
```php
use App\Exceptions\InsufficientStockException;

if ($stock < $required) {
    throw new InsufficientStockException(
        productName: $product->name,
        availableStock: $stock,
        requestedStock: $required
    );
}

// في Controller
try {
    $this->service->process();
} catch (InsufficientStockException $e) {
    return response()->json([
        'error' => $e->getMessage()
    ], $e->getCode());
}
```

**لإنشاء Exception جديد:**
```php
namespace App\Exceptions;

class InvalidPaymentException extends Exception
{
    protected $message = 'عملية الدفع غير صالحة';
    protected $code = 400;
}
```

---

### 5️⃣ تطبيق Security Headers

**في `app/Http/Kernel.php`:**
```php
protected $middleware = [
    // ...
    \App\Http\Middleware\SecurityHeaders::class,
];
```

**أو لـ API فقط:**
```php
protected $middlewareGroups = [
    'api' => [
        \App\Http\Middleware\SecurityHeaders::class,
        \App\Http\Middleware\ApiRateLimit::class,
    ],
];
```

---

### 6️⃣ استخدام Rate Limiting

**في Routes:**
```php
Route::middleware(['api.rate.limit:100'])->group(function () {
    Route::get('/products', [ProductController::class, 'index']);
});
```

**أو في Controller:**
```php
public function __construct()
{
    $this->middleware('api.rate.limit:60');
}
```

---

### 7️⃣ Database Transactions

**استخدم دائماً Transactions للعمليات المعقدة:**

```php
use Illuminate\Support\Facades\DB;

DB::transaction(function () use ($data) {
    $sale = Sale::create($data);
    
    foreach ($items as $item) {
        SaleItem::create([
            'sale_id' => $sale->id,
            'product_id' => $item['product_id'],
            'quantity' => $item['quantity'],
        ]);
    }
    
    $this->stockService->updateStock($sale);
});

// مع معالجة الأخطاء
try {
    DB::transaction(function () {
        // Operations
    });
} catch (\Exception $e) {
    Log::error('Transaction failed', ['error' => $e->getMessage()]);
    throw $e;
}
```

---

### 8️⃣ Logging بشكل صحيح

**استخدم مستويات Log مناسبة:**

```php
use Illuminate\Support\Facades\Log;

// معلومات عامة
Log::info('User logged in', ['user_id' => $user->id]);

// تحذيرات
Log::warning('Stock is low', ['product_id' => $id, 'stock' => $stock]);

// أخطاء
Log::error('Payment failed', [
    'order_id' => $order->id,
    'error' => $e->getMessage()
]);

// للـ Debugging
Log::debug('Processing sale', ['data' => $data]);
```

---

### 9️⃣ Type Hints و Return Types

**استخدم دائماً Type Hints:**

```php
// ❌ سيء
public function process($data)
{
    return $result;
}

// ✅ جيد
public function process(array $data): bool
{
    return true;
}

// ✅ أفضل مع DocBlock
/**
 * Process sale data
 *
 * @param array<string, mixed> $data
 * @return bool
 * @throws InvalidArgumentException
 */
public function process(array $data): bool
{
    return true;
}
```

---

### 🔟 Named Arguments

**استخدم Named Arguments للوضوح:**

```php
// ❌ غير واضح
$this->service->create($id, $name, true, false, 'active', null);

// ✅ واضح
$this->service->create(
    id: $id,
    name: $name,
    isActive: true,
    isDeleted: false,
    status: 'active',
    notes: null
);
```

---

## 🎯 أمثلة عملية كاملة

### مثال 1: إضافة Feature جديد - معالجة المرتجعات

```php
// 1. أنشئ Form Request
// app/Http/Requests/StoreSaleReturnRequest.php
namespace App\Http\Requests;

class StoreSaleReturnRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'sale_id' => 'required|exists:sales,id',
            'items' => 'required|array',
            'items.*.product_id' => 'required|exists:products,id',
            'items.*.quantity' => 'required|numeric|min:0',
        ];
    }
}

// 2. أنشئ Service
// app/Services/Sales/SaleReturnService.php
namespace App\Services\Sales;

use App\Services\Stock\StockService;

class SaleReturnService
{
    public function __construct(
        private readonly StockService $stockService
    ) {}

    public function processSaleReturn(SaleReturn $return): void
    {
        DB::transaction(function () use ($return) {
            // معالجة المرتجع
            $this->stockService->returnStock($return);
            
            // تحديث الحسابات
            $return->sale->update([
                'total_amount' => $return->sale->total_amount - $return->total_amount
            ]);
        });
    }
}

// 3. Controller
namespace App\Http\Controllers;

class SaleReturnController extends Controller
{
    public function __construct(
        private readonly SaleReturnService $returnService
    ) {}

    public function store(StoreSaleReturnRequest $request)
    {
        try {
            $return = SaleReturn::create($request->validated());
            $this->returnService->processSaleReturn($return);
            
            return response()->json([
                'success' => true,
                'message' => 'تم معالجة المرتجع بنجاح'
            ]);
        } catch (\Exception $e) {
            Log::error('Sale return failed', [
                'error' => $e->getMessage(),
                'data' => $request->validated()
            ]);
            
            return response()->json([
                'success' => false,
                'message' => $e->getMessage()
            ], 400);
        }
    }
}
```

---

## 📋 Checklist للكود الجديد

قبل commit أي كود جديد، تأكد من:

- [ ] استخدام Form Requests للـ Validation
- [ ] فصل Business Logic في Services
- [ ] استخدام Repository Pattern للـ Data Access
- [ ] إضافة Type Hints و Return Types
- [ ] استخدام Database Transactions
- [ ] معالجة الأخطاء بشكل صحيح
- [ ] إضافة Logging مناسب
- [ ] استخدام Custom Exceptions
- [ ] كتابة DocBlocks واضحة
- [ ] التأكد من Security (Validation, Sanitization)
- [ ] اختبار الكود

---

## 🚀 الخطوات التالية

1. **قراءة التقرير الكامل:** [SOLID_CLEAN_CODE_SECURITY_REPORT.md](SOLID_CLEAN_CODE_SECURITY_REPORT.md)
2. **تطبيق نفس المبادئ** على باقي Controllers و Models
3. **كتابة Unit Tests** للـ Services الجديدة
4. **مراجعة الكود** بشكل دوري
5. **استخدام PHPStan** لفحص الكود

---

## 📞 الدعم

للأسئلة أو الاستفسارات:
- راجع التوثيق الكامل في `SOLID_CLEAN_CODE_SECURITY_REPORT.md`
- ابحث عن أمثلة في الملفات المنشأة
- اتبع نفس الأنماط المستخدمة في الكود الموجود