# 📚 مستندات کامل API پنل VPN

## 🔐 Authentication API

### 1️⃣ ورود (Login)

**Endpoint:** `POST /backend/api/auth/login.php`

**Request Body:**
```json
{
  "username": "admin",
  "password": "your_password"
}
```

**Response (Success):**
```json
{
  "success": true,
  "message": "ورود موفقیت‌آمیز",
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "full_name": "مدیر سیستم",
    "role": "admin",
    "created_at": "2024-01-01 12:00:00",
    "last_login": "2024-01-15 10:30:00"
  },
  "session": {
    "expires_in": 1440
  }
}
```

**Response (Error):**
```json
{
  "success": false,
  "message": "نام کاربری یا رمز عبور اشتباه است"
}
```

---

### 2️⃣ خروج (Logout)

**Endpoint:** `POST /backend/api/auth/logout.php`

**Headers:**
```
Cookie: PHPSESSID=xxx
```

**Response:**
```json
{
  "success": true,
  "message": "با موفقیت خارج شدید"
}
```

---

### 3️⃣ بررسی وضعیت لاگین (Check Session)

**Endpoint:** `GET /backend/api/auth/check-session.php`

**Response:**
```json
{
  "success": true,
  "logged_in": true,
  "user_id": 1,
  "username": "admin",
  "role": "admin",
  "last_activity": 1705320600,
  "timeout": 1800
}
```

---

### 4️⃣ تمدید توکن (Refresh Token)

**Endpoint:** `POST /backend/api/auth/refresh.php`

**Response:**
```json
{
  "success": true,
  "logged_in": true,
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "full_name": "مدیر سیستم",
    "role": "admin",
    "created_at": "2024-01-01 12:00:00",
    "last_login": "2024-01-15 10:30:00"
  },
  "session": {
    "expires_in": 1440,
    "last_activity": 1705320600
  }
}
```

---

### 5️⃣ تغییر رمز عبور (Change Password)

**Endpoint:** `POST /backend/api/auth/change-password.php`

**Request Body:**
```json
{
  "current_password": "old_password",
  "new_password": "new_password"
}
```

**Response (Success):**
```json
{
  "success": true,
  "message": "رمز عبور با موفقیت تغییر کرد"
}
```

**Response (Error):**
```json
{
  "success": false,
  "message": "رمز عبور فعلی اشتباه است"
}
```

---

### 6️⃣ ثبت نام (Register)

**Endpoint:** `POST /backend/api/auth/register.php`

**Request Body:**
```json
{
  "username": "newuser",
  "email": "user@example.com",
  "password": "secure_password",
  "full_name": "نام کامل"
}
```

**Response:**
```json
{
  "success": true,
  "message": "ثبت نام با موفقیت انجام شد",
  "user_id": 5
}
```

---

## 🔒 استفاده از Middleware

### مثال استفاده در PHP:

```php
<?php
require_once __DIR__ . '/../middleware/auth.php';

// بررسی لاگین بودن
AuthMiddleware::check();

// بررسی نقش ادمین
AuthMiddleware::requireAdmin();

// دریافت ID کاربر
$userId = AuthMiddleware::getUserId();

// دریافت نقش کاربر
$role = AuthMiddleware::getRole();
?>
```

---

## 🌐 استفاده در JavaScript/React

### 1. تابع Login:

```javascript
async function login(username, password) {
  try {
    const response = await fetch('/backend/api/auth/login.php', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ username, password }),
      credentials: 'include' // مهم: برای ارسال کوکی
    });
    
    const data = await response.json();
    
    if (data.success) {
      console.log('ورود موفق:', data.user);
      // ذخیره اطلاعات کاربر
      localStorage.setItem('user', JSON.stringify(data.user));
      return data;
    } else {
      throw new Error(data.message);
    }
  } catch (error) {
    console.error('خطا در ورود:', error);
    throw error;
  }
}
```

### 2. تابع Logout:

```javascript
async function logout() {
  try {
    const response = await fetch('/backend/api/auth/logout.php', {
      method: 'POST',
      credentials: 'include'
    });
    
    const data = await response.json();
    
    if (data.success) {
      localStorage.removeItem('user');
      window.location.href = '/login';
    }
  } catch (error) {
    console.error('خطا در خروج:', error);
  }
}
```

### 3. بررسی وضعیت لاگین:

```javascript
async function checkAuth() {
  try {
    const response = await fetch('/backend/api/auth/check-session.php', {
      credentials: 'include'
    });
    
    const data = await response.json();
    
    if (!data.logged_in) {
      window.location.href = '/login';
    }
    
    return data;
  } catch (error) {
    console.error('خطا در بررسی احراز هویت:', error);
    return { logged_in: false };
  }
}

// استفاده در React با useEffect
useEffect(() => {
  checkAuth();
}, []);
```

### 4. تغییر رمز عبور:

```javascript
async function changePassword(currentPassword, newPassword) {
  try {
    const response = await fetch('/backend/api/auth/change-password.php', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        current_password: currentPassword,
        new_password: newPassword
      }),
      credentials: 'include'
    });
    
    const data = await response.json();
    
    if (data.success) {
      alert('رمز عبور با موفقیت تغییر کرد');
    } else {
      throw new Error(data.message);
    }
  } catch (error) {
    console.error('خطا در تغییر رمز عبور:', error);
    throw error;
  }
}
```

---

## 🛡️ امنیت

### ویژگی‌های امنیتی:

1. **Password Hashing:** استفاده از `password_hash()` و `PASSWORD_DEFAULT`
2. **Session Regeneration:** جلوگیری از Session Fixation
3. **Timeout:** نشست بعد از 30 دقیقه غیرفعال می‌شود
4. **IP Logging:** ثبت IP و User Agent
5. **Failed Login Logging:** ثبت تلاش‌های ناموفق
6. **CORS Headers:** کنترل دسترسی
7. **HTTP Only Cookies:** محافظت از Session Cookie

### توصیه‌های امنیتی:

- همیشه از HTTPS استفاده کنید
- رمز عبور حداقل 8 کاراکتر
- فعال‌سازی Rate Limiting
- استفاده از CAPTCHA برای لاگین
- فعال‌سازی Two-Factor Authentication (2FA)

---

## 📊 کدهای وضعیت HTTP

| کد | معنی | استفاده |
|-----|------|---------|
| 200 | OK | موفق |
| 400 | Bad Request | داده نامعتبر |
| 401 | Unauthorized | لاگین نشده |
| 403 | Forbidden | دسترسی ندارد |
| 404 | Not Found | یافت نشد |
| 405 | Method Not Allowed | متد اشتباه |
| 500 | Internal Server Error | خطای سرور |

---

## 🧪 تست API با cURL

### Login:
```bash
curl -X POST http://localhost/vpn-panel/backend/api/auth/login.php \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' \
  -c cookies.txt
```

### Check Session:
```bash
curl http://localhost/vpn-panel/backend/api/auth/check-session.php \
  -b cookies.txt
```

### Logout:
```bash
curl -X POST http://localhost/vpn-panel/backend/api/auth/logout.php \
  -b cookies.txt
```

---

## 📝 جدول Logs

برای ذخیره لاگ‌ها، این جدول را ایجاد کنید:

```sql
CREATE TABLE user_logs (
  id INT AUTO_INCREMENT PRIMARY KEY,
  user_id INT NOT NULL,
  action VARCHAR(50) NOT NULL,
  ip_address VARCHAR(45),
  user_agent TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  INDEX idx_user_id (user_id),
  INDEX idx_action (action),
  INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

---

## 🎯 نکات مهم

1. **همیشه** `credentials: 'include'` را در fetch استفاده کنید
2. بعد از لاگین، کوکی Session خودکار ذخیره می‌شود
3. Session بعد از 30 دقیقه غیرفعال شدن منقضی می‌شود
4. برای API های محافظت شده، از Middleware استفاده کنید
5. خطاها را همیشه به صورت JSON برگردانید

---

پایان مستندات 🎉