# GET /b2c/v1/articles

## GET /b2c/v1/articles

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

<div class="api-docs" id="bkmrk-">---

</div>### Endpoint Information

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Farticle"><div class="endpoint-info"><div>**URL:** `/b2c/v1/articles`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** `V1ArticleController@index`</div><div>**Middleware:** `web` (بدون JWT)</div><div>**Model:** `Article`</div><div>**Resource:** `ArticleResource`</div></div>---

</div>### پارامترهای Query قابل استفاده

<div class="api-docs" id="bkmrk-%D9%86%D8%A7%D9%85-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7"><table class="schema-table" dir="rtl"><thead><tr><th>نام پارامتر</th><th>نوع</th><th>الزامی</th><th>توضیح</th></tr></thead><tbody><tr><td>`branch`</td><td>integer</td><td>✅</td><td>شناسه دفتر یا شعبه‌ای که مقاله در آن تعریف شده است</td></tr><tr><td>`categories`</td><td>array (JSON)</td><td>❌</td><td>لیست شناسه‌های دسته‌بندی برای فیلتر (مثلاً \[1,5,7\])</td></tr><tr><td>`tags`</td><td>array (JSON)</td><td>❌</td><td>لیست شناسه‌های تگ‌ها برای فیلتر</td></tr><tr><td>`places`</td><td>array (JSON)</td><td>❌</td><td>لیست شناسه‌ نواحی مکانی مرتبط با مقاله</td></tr><tr><td>`sortByScore`</td><td>boolean</td><td>❌</td><td>مرتب‌سازی بر اساس بیشترین امتیاز (برترین ۱۰ مقاله)</td></tr><tr><td>`sortByViews`</td><td>boolean</td><td>❌</td><td>مرتب‌سازی بر اساس بیشترین بازدید (۶ مقاله برتر)</td></tr></tbody></table>

---

</div>### منطق پردازشی و جریان داده (Flowchart)

<div class="api-docs" id="bkmrk-%F0%9F%93%A5-%DB%B1.-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%D9%87"><div class="flowchart" dir="rtl"><div class="flow-item">📥 ۱. دریافت پارامترها از Query (categories, tags, places, sortBy…)</div><div class="flow-arrow">↓</div><div class="flow-item-process">⚙️ ۲. ایجاد Query Builder روی مدل `Article` با شرط اولیه `branch = $request->branch`</div><div class="flow-arrow">↓</div><div class="flow-item-decision">🔍 ۳. بررسی فیلترها: - اگر `categories` ارسال شده → `orWhereJsonContains('categories', $value)` در حلقه
- اگر `tags` ارسال شده → `orWhereJsonContains('tags', $value)`
- اگر `places` ارسال شده → `orWhereJsonContains('places', $value)`

</div><div class="flow-arrow">↓</div><div class="flow-item-decision">✳️ ۴. اعمال مرتب‌سازی‌ها: - در صورت وجود `sortByScore`: مرتب‌سازی بر اساس امتیاز نزولی و محدودیت به ۱۰ نتیجه
- در صورت وجود `sortByViews`: مرتب‌سازی بر اساس بازدید نزولی و محدودیت به ۶ نتیجه

</div><div class="flow-arrow">↓</div><div class="flow-item-process">📑 ۵. خروجی داده‌ها: - اگر `sortByScore` یا `sortByViews` فعال باشد → خروجی `get()` بدون pagination
- در غیر این صورت → خروجی `paginate(15)`

</div><div class="flow-arrow">↓</div><div class="flow-item-success">✅ ۶. ساخت پاسخ JSON شامل وضعیت، زمان، داده‌ها و لینک‌های صفحه‌بندی.</div></div>---

</div>### 📦 ساختار پاسخ 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)

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

<div class="api-docs" id="bkmrk--1">---

</div>### نکات فنی

<div class="api-docs" id="bkmrk-%D9%81%DB%8C%D9%84%D8%AA%D8%B1%D9%87%D8%A7-%D8%A8%D8%A7-%D8%A7%D8%B3%D8%AA%D9%81%D8%A7%D8%AF%D9%87-%D8%A7">- فیلترها با استفاده از `orWhereJsonContains` اعمال می‌شوند، بنابراین اگر مقاله شامل هرکدام از مقادیر داده‌شده باشد در نتایج بازمی‌گردد.
- رتبه‌بندی بر اساس `score` یا `views` باعث بای‌پس شدن pagination می‌شود تا فقط n نتیجه برتر برگردد.
- در خروجی از `ArticleResource` برای ساختاردهی داده‌ها استفاده شده است.
- پارامتر `branch` الزامی است و باید در Query لحاظ شود؛ در غیر این صورت هیچ رکوردی پیدا نخواهد شد.

---

</div>### 🚀 پیشنهادات بهبود برای توسعه آینده

<div class="api-docs" id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-limit">- افزودن پارامتر `limit` دلخواه برای sortByScore و sortByViews جهت کنترل خروجی.
- بهینه‌سازی Query با استفاده از `->whereIn()` در صورتی که فیلترها زیاد تکرار شوند تا از تکرار `orWhereJsonContains` جلوگیری شود.
- افزودن cache با کلید `articles:list:{branch}:{hash_of_params}` جهت افزایش سرعت واکشی مقالات محبوب.

</div>