# RESOURCE /v2/media

# Media Management (File Storage)

این ماژول وظیفه مدیریت فایل‌ها و رسانه‌های سیستم را بر عهده دارد.   
برخلاف ذخیره‌سازی محلی، این کنترلر مستقیماً با **فضای ذخیره‌سازی ابری (Liara Object Storage)** در ارتباط است. فایل‌ها بر اساس نوع، شعبه، سال و ماه در پوشه‌بندی‌های منظم ذخیره شده و متادیتای آن‌ها (شامل سایز، مسیر و ارتباط با سایر موجودیت‌ها) در دیتابیس نگهداری می‌شود.

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

</div>## 1. Upload File (Store)

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fmedia-metho"><div class="endpoint-info"><div>**URL:** `/v2/media`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** MediaController@store</div><div>**Content-Type:** multipart/form-data</div></div></div>### Body Parameters

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>file</td><td>File</td><td>**(الزامی)** فایل باینری جهت آپلود (تصویر، سند و...).</td></tr><tr><td>branch</td><td>integer</td><td>**(الزامی)** شناسه شعبه (جهت ساختار پوشه‌بندی).</td></tr><tr><td>type</td><td>string</td><td>**(الزامی)** نوع فایل (مثلاً `slider`, `avatar`, `document`) که نام پوشه اصلی را تعیین می‌کند.</td></tr><tr><td>path</td><td>string</td><td>**(اختیاری)** پیشوند مسیر ذخیره‌سازی. اگر ارسال نشود، پیش‌فرض `uploads` در نظر گرفته می‌شود.</td></tr><tr><td>related\_id</td><td>integer</td><td>**(اختیاری)** شناسه رکورد مرتبط (مثلاً ID هتل یا مقاله).</td></tr><tr><td>related\_category</td><td>string</td><td>**(اختیاری)** دسته‌بندی رکورد مرتبط (مثلاً `articles`).</td></tr><tr><td>operator</td><td>object</td><td>**(تزریق سیستمی)** آبجکت اپراتور (از طریق میدل‌ور Auth) برای ثبت در فیلد `operator_id`.</td></tr></tbody></table>

</div>### Upload Logic Details

<div class="api-docs" id="bkmrk-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%88-%D8%A2%D9%85%D8%A7%D8%AF%D9%87%E2%80%8C%D8%B3%D8%A7%D8%B2%DB%8C-">1. **دریافت و آماده‌سازی فایل:**
    - استخراج پسوند (Extension) و نام اصلی فایل.
    - نام فایل در دیتابیس بدون پسوند ذخیره می‌شود.
2. **ساخت مسیر ذخیره‌سازی (Path Generation):**   
    مسیر فایل به صورت دینامیک بر اساس تاریخ جاری و ورودی‌ها ساخته می‌شود:   
    `{base_path}/{branch}/{type}/{Year}/{Month}/{ext}/`
    - اگر پارامتر `path` ارسال شود، به عنوان `base_path` استفاده می‌شود.
    - در غیر این صورت، `uploads` به عنوان پیش‌فرض قرار می‌گیرد.
3. **ذخیره‌سازی فیزیکی (Liara Disk):**
    - استفاده از `Storage::disk('liara')->putFileAs(...)`.
    - فایل با نام اصلی + پسوند در مسیر ساخته شده آپلود می‌شود.
    - سپس سایز واقعی فایل آپلود شده از دیسک ابری استعلام می‌شود (`size()`).
4. **ثبت در دیتابیس:**
    - رکورد جدید با اطلاعات کامل (شامل مسیر کامل `path`، سایز، نوع و ارتباطات) در جدول `media` ایجاد می‌شود.

</div>### Flowchart (Upload Process)

<div class="api-docs" id="bkmrk-start-request-%E2%86%93-extr"><div class="flowchart"><div class="flow-item">Start Request</div><div class="flow-arrow">↓</div><div class="flow-item-process">Extract File info  
(Ext, Name)</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Has Custom Path?</div><div style="display: flex; justify-content: space-between; margin-top: 10px;"><div style="width: 45%; text-align: center;"><div class="flow-arrow-label-left">Yes</div><div class="flow-item-process" style="font-size: 0.8em;">Base = $request-&gt;path</div></div><div style="width: 45%; text-align: center;"><div class="flow-arrow-label-right">No</div><div class="flow-item-process" style="font-size: 0.8em;">Base = 'uploads'</div></div></div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e3f2fd;">**Generate Path Structure**  
base/branch/type/Y/m/ext/</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fff3e0;">**Liara Storage Upload**  
putFileAs() &amp; get Size()</div><div class="flow-arrow">↓</div><div class="flow-item-success">Create DB Record &amp; Return</div></div>  ---

</div>## 2. List Media (Index)

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fmedia-metho-1"><div class="endpoint-info"><div>**URL:** `/v2/media`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** MediaController@index</div></div></div>لیست فایل‌های آپلود شده به صورت **صفحه‌بندی شده (۱۵ تایی)**.

### فیلترهای جستجو (Query Params)

<div class="api-docs" id="bkmrk-operator_id%3A-%D8%B4%D9%86%D8%A7%D8%B3%D9%87-%D8%A2">- `operator_id`: شناسه آپلود کننده.
- `related_id`: شناسه رکورد مرتبط.
- `related_category`: دسته‌بندی مرتبط.
- `type`: نوع فایل.
- `branch`: شعبه.
- `status`: وضعیت فایل.
- `sortById`: اگر ارسال شود (true)، مرتب‌سازی نزولی (جدیدترین‌ها) اعمال می‌شود.

  ---

</div>## 3. Update Media Status

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fmedia%2F%7Bid%7D-"><div class="endpoint-info"><div>**URL:** `/v2/media/{id}`</div><div>**Method:** <span class="method-put">PUT/PATCH</span></div><div>**Controller:** MediaController@update</div></div></div>**توجه:** در متد آپدیت، فایل فیزیکی یا مسیر آن تغییر نمی‌کند. تنها می‌توان **وضعیت (Status)** فایل را تغییر داد.

```json
{
  "status": 0 // غیرفعال کردن فایل
}
```

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

</div>## 4. Delete Media

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fmedia%2F%7Bid%7D--1"><div class="endpoint-info"><div>**URL:** `/v2/media/{id}`</div><div>**Method:** <span class="method-delete">DELETE</span></div><div>**Controller:** MediaController@destroy</div></div></div>عملیات حذف دومرحله‌ای:

<div class="api-docs" id="bkmrk-%D8%A7%D8%A8%D8%AA%D8%AF%D8%A7-%D8%A8%D8%A7-%D8%A7%D8%B3%D8%AA%D9%81%D8%A7%D8%AF%D9%87-%D8%A7%D8%B2-">1. ابتدا با استفاده از مسیر ذخیره شده در دیتابیس (`path`)، فایل فیزیکی از دیسک **Liara** حذف می‌شود (`Storage::disk('liara')-&gt;delete`).
2. سپس رکورد از دیتابیس پاک می‌شود.

</div>