admin/dashboard-api-requirements.md

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

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

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

---

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

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

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

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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) - در صورت وجود داده

---

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

# دریافت آمار کلی
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‌ها را در اسرع وقت پیاده‌سازی کنید تا بتوانیم داشبورد را کامل کنیم. 🙏

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