# RESOURCE /v2/categories

# Category Resource Management

این بخش شامل مدیریت کامل **دسته‌بندی‌ها (Categories)** است.   
این کنترلر به طور پیش‌فرض در متد لیست‌گیری، فقط **دسته‌بندی‌های اصلی (بدون والد)** را برمی‌گرداند. همچنین از فیلترهای مکان و نوع پشتیبانی می‌کند.

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

</div>## 1. List Categories (Index)

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcategories-"><div class="endpoint-info"><div>**URL:** `/v2/categories`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** CategoryController@index</div></div></div>**نکته مهم:** این اندپوینت دارای فیلتر سخت‌گیرانه `whereNull('main')` است. یعنی فقط دسته‌بندی‌هایی که فیلد `main` آن‌ها خالی است (دسته‌بندی‌های والد) در خروجی ظاهر می‌شوند.

### پارامترهای فیلترینگ (Query Params)

<div class="api-docs" id="bkmrk-parameter-type-descr"><div class="table-wrapper"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>branch</td><td>mixed</td><td>(معمولاً خودکار) فیلتر بر اساس شعبه.</td></tr><tr><td>type</td><td>string</td><td>فیلتر بر اساس نوع دسته‌بندی (مثلاً article, video و...).</td></tr><tr><td>place</td><td>mixed</td><td>شناسه (ID) یا نام مستعار (Slug) مکان.   
سیستم ابتدا شناسه مکان را از جدول `articles_places` پیدا کرده و سپس دسته‌بندی‌هایی که ستون `places` آن‌ها برابر با آن شناسه باشد را فیلتر می‌کند.</td></tr><tr><td>limit</td><td>integer</td><td>محدودیت تعداد آیتم‌ها در هر صفحه.</td></tr></tbody></table>

</div></div>### مثال پاسخ

```json
{
  "status": true,
  "time": 1715011000,
  "data": [
    {
      "id": 5,
      "title": "تکنولوژی",
      "slug": "tech",
      "image": "https://...",
      "main": null, // همیشه null است در این لیست
      "places": "[1, 2]" // JSON String
    }
  ],
  "links": { ... }
}
```

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

</div>## 2. Create Category (Store)

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcategories--1"><div class="endpoint-info"><div>**URL:** `/v2/categories`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** CategoryController@store</div></div></div>یک دسته‌بندی جدید ایجاد می‌کند.

### بدنه درخواست (Body Parameters)

<div class="api-docs" id="bkmrk-field-type-descripti"><div class="table-wrapper"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>title</td><td>string</td><td>(الزامی) عنوان دسته‌بندی</td></tr><tr><td>slug</td><td>string</td><td>(الزامی) آدرس یکتا</td></tr><tr><td>main</td><td>integer|null</td><td>شناسه دسته‌بندی والد (اگر زیرمجموعه است). اگر خالی باشد، دسته اصلی محسوب می‌شود.</td></tr><tr><td>image</td><td>string</td><td>آدرس تصویر</td></tr><tr><td>description</td><td>text</td><td>توضیحات</td></tr><tr><td>places</td><td>array</td><td>لیستی از مکان‌های مرتبط. (در دیتابیس به صورت JSON ذخیره می‌شود).</td></tr><tr><td>branch</td><td>integer</td><td>(از طریق توکن/ریکوئست) شناسه شعبه.</td></tr></tbody></table>

</div>  ---

</div>## 3. Show Category

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcategories%2F"><div class="endpoint-info"><div>**URL:** `/v2/categories/{id}`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** CategoryController@show</div></div></div>مشاهده جزئیات یک دسته‌بندی خاص.

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

</div>## 4. Update Category

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcategories%2F-1"><div class="endpoint-info"><div>**URL:** `/v2/categories/{id}`</div><div>**Method:** <span class="method-put">PUT/PATCH</span></div><div>**Controller:** CategoryController@update</div></div></div>ویرایش اطلاعات دسته‌بندی. ورودی‌ها دقیقاً مشابه متد Store هستند.

```json
{
    "status": true,
    "time": 1715012000
}
```

<div class="api-docs" id="bkmrk--3"><div dir="ltr"></div>  ---

</div>## 5. Delete Category

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcategories%2F-2"><div class="endpoint-info"><div>**URL:** `/v2/categories/{id}`</div><div>**Method:** <span class="method-delete">DELETE</span></div><div>**Controller:** CategoryController@destroy</div></div></div>حذف کامل دسته‌بندی.

<div class="api-docs" id="bkmrk--4">  </div>## Index Logic Flowchart

<div class="api-docs" id="bkmrk-start-request-%E2%86%93-appl"><div class="flowchart"><div class="flow-item">Start Request</div><div class="flow-arrow">↓</div><div class="flow-item-process">Apply Filters:  
1. Branch = Request-&gt;branch  
2. Main IS NULL (Root Categories)</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Has "place" param?</div><div style="display: flex; justify-content: space-between; margin-top: 20px; direction: ltr;"><div style="width: 48%;"><div class="flow-arrow-label-left" style="text-align: center;">Yes</div><div class="flow-item-process" style="background-color: #e3f2fd;">Find ID from `articles_places`  
(by ID or Slug)  
↓  
Filter: `whereIn('places', [ID])`</div></div><div style="width: 48%;"><div class="flow-arrow-label-right" style="text-align: center;">No</div><div class="flow-item-process" style="border: 1px dashed #ccc;">Skip Place Filter</div></div></div><div class="flow-arrow">↓</div><div class="flow-item-process">Pagination (15 items)</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return Resource Collection</div></div></div>