Skip to main content
#P1811

GET /b2c/v1/articles

GET /b2c/v1/articles

این اندپوینت برای دریافت فهرست مقالات در سیستم B2C استفاده می‌شود. امکان فیلتر بر اساس دسته‌بندی‌ها، تگ‌ها و موقعیت‌ها (places) و همچنین مرتب‌سازی بر اساس امتیاز (score) یا تعداد بازدید (views) فراهم شده است. در حالت عادی خروجی صفحه‌بندی‌شده برمی‌گردد، اما در حالت مرتب‌سازی خاص، داده‌ها به صورت محدود و غیر صفحه‌بندی بازگردانده می‌شوند.

Endpoint Information

URL: /b2c/v1/articles
Method: GET
Controller: V1ArticleController@index
Middleware: web (بدون JWT)
Model: Article
Resource: ArticleResource

پارامترهای Query قابل استفاده

نام پارامتر نوع الزامی توضیح
branch integer ✅ شناسه دفتر یا شعبه‌ای که مقاله در آن تعریف شده است
categories array (JSON) ❌ لیست شناسه‌های دسته‌بندی برای فیلتر (مثلاً [1,5,7])
tags array (JSON) ❌ لیست شناسه‌های تگ‌ها برای فیلتر
places array (JSON) ❌ لیست شناسه‌ نواحی مکانی مرتبط با مقاله
sortByScore boolean ❌ مرتب‌سازی بر اساس بیشترین امتیاز (برترین ۱۰ مقاله)
sortByViews boolean ❌ مرتب‌سازی بر اساس بیشترین بازدید (۶ مقاله برتر)

منطق پردازشی و جریان داده (Flowchart)

📥 ۱. دریافت پارامترها از Query (categories, tags, places, sortBy…)
↓
⚙️ ۲. ایجاد Query Builder روی مدل Article با شرط اولیه branch = $request->branch
↓
🔍 ۳. بررسی فیلترها:
  • اگر categories ارسال شده → orWhereJsonContains('categories', $value) در حلقه
  • اگر tags ارسال شده → orWhereJsonContains('tags', $value)
  • اگر places ارسال شده → orWhereJsonContains('places', $value)
↓
✳️ ۴. اعمال مرتب‌سازی‌ها:
  • در صورت وجود sortByScore: مرتب‌سازی بر اساس امتیاز نزولی و محدودیت به ۱۰ نتیجه
  • در صورت وجود sortByViews: مرتب‌سازی بر اساس بازدید نزولی و محدودیت به ۶ نتیجه
↓
📑 ۵. خروجی داده‌ها:
  • اگر sortByScore یا sortByViews فعال باشد → خروجی get() بدون pagination
  • در غیر این صورت → خروجی paginate(15)
↓
✅ ۶. ساخت پاسخ JSON شامل وضعیت، زمان، داده‌ها و لینک‌های صفحه‌بندی.

📦 ساختار پاسخ JSON

پاسخ موفق

{
  "status": true,
  "time": 1733799551,
  "data": [
    {
      "id": 245,
      "title": "راهنمای سفر مشهد",
      "excerpt": "در این مقاله به جاذبه‌های گردشگری...",
      "cover": "https://cdn.site.com/uploads/article245.jpg",
      "views": 932,
      "score": 4.8,
      "categories": [5, 7],
      "tags": [12, 98],
      "created_at": "2025-11-22T10:00:00Z"
    },
    ...
  ],
  "links": {
    "first": "https://api.domain.com/b2c/v1/articles?page=1",
    "last": "https://api.domain.com/b2c/v1/articles?page=15",
    "prev": null,
    "next": "https://api.domain.com/b2c/v1/articles?page=2"
  }
}

🔹 پاسخ در حالت مرتب‌سازی (بدون pagination)

{
  "status": true,
  "time": 1733799553,
  "data": [ { ... }, { ... }, ... ],
  "links": false
}

نکات فنی

  • فیلترها با استفاده از orWhereJsonContains اعمال می‌شوند، بنابراین اگر مقاله شامل هرکدام از مقادیر داده‌شده باشد در نتایج بازمی‌گردد.
  • رتبه‌بندی بر اساس score یا views باعث بای‌پس شدن pagination می‌شود تا فقط n نتیجه برتر برگردد.
  • در خروجی از ArticleResource برای ساختاردهی داده‌ها استفاده شده است.
  • پارامتر branch الزامی است و باید در Query لحاظ شود؛ در غیر این صورت هیچ رکوردی پیدا نخواهد شد.

🚀 پیشنهادات بهبود برای توسعه آینده

  • افزودن پارامتر limit دلخواه برای sortByScore و sortByViews جهت کنترل خروجی.
  • بهینه‌سازی Query با استفاده از ->whereIn() در صورتی که فیلترها زیاد تکرار شوند تا از تکرار orWhereJsonContains جلوگیری شود.
  • افزودن cache با کلید articles:list:{branch}:{hash_of_params} جهت افزایش سرعت واکشی مقالات محبوب.
Back to top