admin/dashboard-api-requirements.md

# درخواست API‌های داشبورد

سلام تیم بک‌اند 👋

برای تکمیل صفحه داشبورد نیاز به API‌های زیر داریم. لطفاً این API‌ها را پیاده‌سازی کنید:

---

## 1. API آمار کلی داشبورد (Dashboard Overview Stats)

**Endpoint:** `GET /api/v1/admin/dashboard/stats`

**Description:** دریافت آمار کلی سیستم شامل سفارشات، درآمد، کاربران و محصولات

**Response:**

```json
{
  "orders": {
    "total": 1250,
    "pending": 45,
    "completed": 1100,
    "cancelled": 105,
    "today_count": 23,
    "today_amount": 45000000
  },
  "revenue": {
    "total": 2500000000,
    "today": 45000000,
    "this_month": 350000000,
    "last_month": 320000000,
    "growth_percentage": 9.4
  },
  "users": {
    "total": 8500,
    "active": 7200,
    "new_today": 15,
    "new_this_month": 450
  },
  "products": {
    "total": 1250,
    "active": 1100,
    "low_stock": 25,
    "out_of_stock": 8
  }
}
```

---

## 2. API فروش ماهانه (Monthly Sales Chart)

**Endpoint:** `GET /api/v1/admin/dashboard/monthly-sales`

**Description:** دریافت آمار فروش به صورت ماهانه برای نمایش در چارت

**Query Parameters:**

- `months` (optional, default: 6) - تعداد ماه‌های گذشته که باید برگردانده شود

**Response:**

```json
{
  "data": [
    {
      "month": "فروردین",
      "month_number": 1,
      "year": 1403,
      "total_amount": 350000000,
      "order_count": 450
    },
    {
      "month": "اردیبهشت",
      "month_number": 2,
      "year": 1403,
      "total_amount": 420000000,
      "order_count": 520
    }
    // ... برای تعداد ماه‌های درخواستی
  ]
}
```

**Note:** داده‌ها باید به ترتیب زمانی (از قدیمی‌ترین به جدیدترین) مرتب باشند.

---

## 3. API روند رشد (Growth Trend)

**Endpoint:** `GET /api/v1/admin/dashboard/growth-trend`

**Description:** دریافت روند رشد سیستم در بازه‌های زمانی مختلف

**Query Parameters:**

- `period` (optional, default: "monthly") - نوع بازه زمانی: `"daily"`, `"weekly"`, `"monthly"`
- `days` (optional, default: 30) - تعداد روزها برای `period=daily`
- `weeks` (optional, default: 12) - تعداد هفته‌ها برای `period=weekly`
- `months` (optional, default: 12) - تعداد ماه‌ها برای `period=monthly`

**Response:**

```json
{
  "period": "monthly",
  "data": [
    {
      "date": "1403/01",
      "revenue": 350000000,
      "orders": 450,
      "users": 120
    },
    {
      "date": "1403/02",
      "revenue": 420000000,
      "orders": 520,
      "users": 135
    }
    // ...
  ],
  "growth_rate": 9.4
}
```

---

## 4. API کاربران اخیر (Recent Users)

**Endpoint:** `GET /api/v1/admin/dashboard/recent-users`

**Description:** دریافت لیست کاربران جدید که اخیراً ثبت‌نام کرده‌اند

**Query Parameters:**

- `limit` (optional, default: 10) - تعداد کاربران

**Response:**

```json
{
  "users": [
    {
      "id": 1,
      "first_name": "علی",
      "last_name": "احمدی",
      "username": "ali_ahmadi",
      "email": "ali@example.com",
      "phone": "09123456789",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "first_name": "فاطمه",
      "last_name": "حسینی",
      "username": "fateme_hosseini",
      "email": "fateme@example.com",
      "phone": "09123456790",
      "status": "active",
      "created_at": "2024-01-14T15:20:00Z"
    }
    // ...
  ],
  "total": 10
}
```

**Note:** کاربران باید به ترتیب تاریخ ثبت‌نام (جدیدترین اول) مرتب باشند.

---

## 5. API توزیع دستگاه‌های کاربری (Device Distribution)

**Endpoint:** `GET /api/v1/admin/dashboard/device-distribution`

**Description:** دریافت آمار توزیع دستگاه‌های کاربری (دسکتاپ، موبایل، تبلت)

**Response:**

```json
{
  "data": [
    {
      "device_type": "desktop",
      "label": "دسکتاپ",
      "count": 4500,
      "percentage": 45.5
    },
    {
      "device_type": "mobile",
      "label": "موبایل",
      "count": 3500,
      "percentage": 35.2
    },
    {
      "device_type": "tablet",
      "label": "تبلت",
      "count": 2000,
      "percentage": 19.3
    }
  ],
  "total": 10000
}
```

**Note:** درصدها باید به صورت عدد صحیح (بدون اعشار) برگردانده شوند.

---

## 6. API سفارش‌های اخیر (Recent Orders)

**Endpoint:** `GET /api/v1/admin/dashboard/recent-orders`

**Description:** دریافت لیست آخرین سفارش‌های ثبت شده

**Query Parameters:**

- `limit` (optional, default: 10) - تعداد سفارش‌ها

**Response:**

```json
{
  "orders": [
    {
      "id": 1234,
      "order_number": "ORD-2024-001234",
      "customer_name": "علی احمدی",
      "customer_id": 45,
      "total_amount": 2500000,
      "status": "pending",
      "payment_status": "paid",
      "created_at": "2024-01-15T14:30:00Z"
    },
    {
      "id": 1233,
      "order_number": "ORD-2024-001233",
      "customer_name": "فاطمه حسینی",
      "customer_id": 46,
      "total_amount": 1800000,
      "status": "completed",
      "payment_status": "paid",
      "created_at": "2024-01-15T13:20:00Z"
    }
    // ...
  ],
  "total": 10
}
```

**Note:** سفارش‌ها باید به ترتیب تاریخ ایجاد (جدیدترین اول) مرتب باشند.

---

## 7. API محصولات پرفروش (Top Selling Products)

**Endpoint:** `GET /api/v1/admin/dashboard/top-products`

**Description:** دریافت لیست محصولات پرفروش

**Query Parameters:**

- `limit` (optional, default: 5) - تعداد محصولات
- `period` (optional, default: "month") - بازه زمانی: `"day"`, `"week"`, `"month"`

**Response:**

```json
{
  "products": [
    {
      "id": 45,
      "name": "محصول نمونه",
      "sku": "PRD-001",
      "sold_count": 250,
      "revenue": 125000000,
      "image_url": "https://example.com/images/product-45.jpg"
    },
    {
      "id": 78,
      "name": "محصول دیگر",
      "sku": "PRD-002",
      "sold_count": 180,
      "revenue": 90000000,
      "image_url": "https://example.com/images/product-78.jpg"
    }
    // ...
  ]
}
```

**Note:** محصولات باید به ترتیب تعداد فروش (بیشترین اول) مرتب باشند.

---

## 8. API آمار مقایسه‌ای (Comparison Stats)

**Endpoint:** `GET /api/v1/admin/dashboard/comparison`

**Description:** دریافت آمار مقایسه‌ای بین دوره فعلی و دوره قبلی

**Query Parameters:**

- `compare_with` (optional, default: "last_period") - نوع مقایسه: `"last_period"`, `"last_year"`
- `period` (optional, default: "month") - نوع دوره: `"day"`, `"week"`, `"month"`

**Response:**

```json
{
  "current": {
    "revenue": 350000000,
    "orders": 450,
    "users": 120
  },
  "previous": {
    "revenue": 320000000,
    "orders": 410,
    "users": 105
  },
  "changes": {
    "revenue": {
      "amount": 30000000,
      "percentage": 9.4,
      "trend": "up"
    },
    "orders": {
      "amount": 40,
      "percentage": 9.8,
      "trend": "up"
    },
    "users": {
      "amount": 15,
      "percentage": 14.3,
      "trend": "up"
    }
  }
}
```

**Note:**

- `trend` می‌تواند `"up"`, `"down"` یا `"stable"` باشد
- درصدها می‌توانند اعشار داشته باشند

---

## نکات مهم و الزامات:

1. **احراز هویت:** همه API‌ها باید نیاز به احراز هویت داشته باشند (Bearer Token)

2. **فیلتر تاریخ:** در صورت امکان، همه API‌ها باید قابلیت فیلتر بر اساس بازه زمانی را داشته باشند:

   - `from_date` (optional) - تاریخ شروع
   - `to_date` (optional) - تاریخ پایان

3. **فرمت تاریخ:**

   - تاریخ‌ها در Response باید به فرمت ISO 8601 برگردانده شوند: `"2024-01-15T14:30:00Z"`
   - تاریخ‌های ورودی می‌توانند به فرمت ISO 8601 یا timestamp باشند

4. **فرمت مبالغ:**

   - همه مبالغ به تومان هستند
   - مبالغ باید به صورت عدد (integer) برگردانده شوند

5. **ترتیب داده‌ها:**

   - داده‌های زمانی باید به ترتیب زمانی (از قدیمی‌ترین به جدیدترین) مرتب باشند
   - داده‌های مرتب‌سازی شده (مثل پرفروش‌ترین) باید به ترتیب مناسب مرتب باشند

6. **مقدار پیش‌فرض:**

   - در صورت نبود داده، آرایه خالی `[]` یا `null` برگردانده شود
   - مقادیر عددی در صورت نبود داده باید `0` باشند

7. **خطاها:**

   - در صورت خطا، کد HTTP مناسب برگردانده شود
   - پیام خطا به فارسی و واضح باشد

8. **Performance:**
   - برای بهینه‌سازی، می‌توان از کش استفاده کرد
   - Query‌ها باید بهینه باشند تا زمان پاسخگویی کم باشد

---

## اولویت پیاده‌سازی:

1. **اولویت بالا:**

   - API آمار کلی داشبورد (#1)
   - API فروش ماهانه (#2)
   - API کاربران اخیر (#4)
   - API سفارش‌های اخیر (#6)

2. **اولویت متوسط:**

   - API روند رشد (#3)
   - API محصولات پرفروش (#7)
   - API آمار مقایسه‌ای (#8)

3. **اولویت پایین:**
   - API توزیع دستگاه‌های کاربری (#5) - در صورت وجود داده

---

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

```bash
# دریافت آمار کلی
curl -X GET "https://api.example.com/api/v1/admin/dashboard/stats" \
  -H "Authorization: Bearer YOUR_TOKEN"

# دریافت فروش 6 ماه گذشته
curl -X GET "https://api.example.com/api/v1/admin/dashboard/monthly-sales?months=6" \
  -H "Authorization: Bearer YOUR_TOKEN"

# دریافت کاربران اخیر
curl -X GET "https://api.example.com/api/v1/admin/dashboard/recent-users?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

**ممنون می‌شوم اگر این API‌ها را در اسرع وقت پیاده‌سازی کنید تا بتوانیم داشبورد را کامل کنیم.** 🙏

**در صورت نیاز به توضیحات بیشتر یا تغییرات، لطفاً اطلاع دهید.**