hesabixCore/docs/OAuth_Frontend_Integration.md

# یکپارچه‌سازی OAuth با Frontend

## مشکل اصلی

سیستم OAuth قبلی در backend پیاده‌سازی شده بود اما frontend از axios استفاده می‌کند و نیاز به احراز هویت دارد. این باعث می‌شد که صفحه authorization نتواند با سیستم احراز هویت موجود کار کند.

## راه‌حل پیاده‌سازی شده

### 1. صفحه Authorization در Frontend

**فایل:** `webUI/src/views/oauth/authorize.vue`

این صفحه شامل:
- **احراز هویت خودکار:** بررسی وضعیت لاگین کاربر با axios
- **نمایش اطلاعات برنامه:** نام، توضیحات، وب‌سایت
- **لیست Scope ها:** نمایش محدوده‌های دسترسی درخواستی
- **دکمه‌های تأیید/رد:** با طراحی زیبا و responsive
- **مدیریت خطا:** نمایش خطاها و loading states

### 2. Route جدید در Router

**فایل:** `webUI/src/router/index.ts`

```javascript
{
    path: '/oauth/authorize',
    name: 'oauth_authorize',
    component: () => import('../views/oauth/authorize.vue'),
    meta: {
        'title': 'مجوزدهی OAuth',
        'login': true
    }
}
```

### 3. API Endpoints جدید در Backend

#### الف) دریافت اطلاعات برنامه بر اساس Client ID
**Route:** `GET /api/admin/oauth/applications/client/{clientId}`

```php
#[Route('/applications/client/{clientId}', name: 'api_admin_oauth_applications_by_client_id', methods: ['GET'])]
public function getApplicationByClientId(string $clientId): JsonResponse
```

#### ب) API endpoint برای پردازش مجوز
**Route:** `POST /api/oauth/authorize`

```php
#[Route('/api/oauth/authorize', name: 'api_oauth_authorize', methods: ['POST'])]
public function authorizeApi(Request $request): JsonResponse
```

### 4. تغییرات در OAuthController

**فایل:** `hesabixCore/src/Controller/OAuthController.php`

- **هدایت به Frontend:** به جای نمایش صفحه Twig، کاربر به frontend هدایت می‌شود
- **API endpoint جدید:** برای پردازش مجوز از frontend

### 5. تنظیمات Security

**فایل:** `hesabixCore/config/packages/security.yaml`

```yaml
- { path: ^/api/oauth, roles: ROLE_USER }
```

## جریان کار جدید

### 1. درخواست مجوز
```
GET /oauth/authorize?client_id=...&redirect_uri=...&scope=...&state=...
```

### 2. هدایت به Frontend
Backend کاربر را به صفحه frontend هدایت می‌کند:
```
/u/oauth/authorize?client_id=...&redirect_uri=...&scope=...&state=...
```

### 3. احراز هویت در Frontend
- بررسی وضعیت لاگین با axios
- اگر لاگین نیست، هدایت به صفحه لاگین
- دریافت اطلاعات برنامه از API

### 4. نمایش صفحه مجوزدهی
- نمایش اطلاعات برنامه
- لیست scope های درخواستی
- دکمه‌های تأیید/رد

### 5. پردازش مجوز
- ارسال درخواست به `/api/oauth/authorize`
- ایجاد authorization code
- هدایت به redirect_uri

## مزایای این روش

### ✅ سازگاری با سیستم موجود
- استفاده از axios و احراز هویت موجود
- سازگار با router و navigation guard ها

### ✅ تجربه کاربری بهتر
- طراحی مدرن و responsive
- Loading states و error handling
- UI/UX یکپارچه با بقیه برنامه

### ✅ امنیت بیشتر
- احراز هویت خودکار
- بررسی دسترسی‌ها
- مدیریت خطا

### ✅ قابلیت توسعه
- کد تمیز و قابل نگهداری
- جداسازی منطق frontend و backend
- امکان اضافه کردن ویژگی‌های جدید

## تست سیستم

### 1. تست درخواست مجوز
```bash
curl "https://your-domain.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://your-app.com/callback&response_type=code&scope=read_profile&state=test123"
```

### 2. تست API endpoint
```bash
curl -X POST "https://your-domain.com/api/oauth/authorize" \
  -H "Content-Type: application/json" \
  -H "X-AUTH-TOKEN: YOUR_TOKEN" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "https://your-app.com/callback",
    "scope": "read_profile",
    "state": "test123",
    "approved": true
  }'
```

### 3. تست دریافت اطلاعات برنامه
```bash
curl -X GET "https://your-domain.com/api/admin/oauth/applications/client/YOUR_CLIENT_ID" \
  -H "X-AUTH-TOKEN: YOUR_TOKEN"
```

## نکات مهم

### 🔒 امنیت
- تمام درخواست‌ها باید احراز هویت شوند
- بررسی دسترسی‌ها در هر مرحله
- اعتبارسنجی پارامترها

### 🎨 UI/UX
- طراحی responsive
- Loading states
- Error handling
- Accessibility

### 🔧 نگهداری
- کد تمیز و قابل خواندن
- مستندات کامل
- تست‌های مناسب

## آینده

### ویژگی‌های پیشنهادی
- [ ] صفحه callback در frontend
- [ ] مدیریت توکن‌ها
- [ ] آمار استفاده
- [ ] تنظیمات امنیتی پیشرفته

### بهبودها
- [ ] Caching اطلاعات برنامه
- [ ] Offline support
- [ ] Progressive Web App features
- [ ] Analytics و monitoring

---

**تاریخ ایجاد:** 2025-08-16  
**وضعیت:** فعال ✅  
**توسعه‌دهنده:** Hesabix Team