# POST /upload

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td dir="ltr">POST</td><td dir="ltr">/api/v2/upload</td><td dir="ltr">UploadController@upload</td><td dir="ltr">authWithJwt</td><td dir="rtl">آپلود فایل روی سرور و دریافت مسیر ذخیره‌سازی</td></tr></tbody></table>

</div>### منطق عملکرد تابع

تابع **upload** برای دریافت فایل از کاربر، اعتبارسنجی نوع و اندازهٔ آن، سپس ذخیره‌سازی در مسیر مشخص‌شده در پوشهٔ `uploads/` است. مسیر براساس `branch`، `type` و سال و ماه فعلی ساخته می‌شود. در پایان، مسیر فایل ذخیره‌شده در پاسخ JSON بازگردانده می‌شود.

<div id="bkmrk-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA%E2%80%AF%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%D9%87%D8%A7%DB%8C%DB%8C%E2%80%AF%D8%B4" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">1. دریافت پارامترهایی شامل `branch`، `type`، (اختیاری) `mimes` و `size`.
2. ساخت پیکربندی اعتبارسنجی: انواع مجاز و حدّ اکثر سایز.
3. اعتبارسنجی فایل ورودی با قانون Laravel (`required|file|mimes|max`).
4. نام‌گذاری فایل به‌صورت ترکیب تاریخ + microtime برای یونیک بودن.
5. ذخیره‌سازی در مسیر `uploads/{branch}/{type}/{year}/{month}/{extension}/`.
6. بازگرداندن پاسخ با وضعیت موفق و مسیر نهایی فایل.
7. در صورت رخداد استثنا (Exception) بازگرداندن پاسخ خطا با status=false و کد ۴۰۰.

</div>### پارامترهای ورودی

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%86%D9%88%D8%B9-%D9%85%D8%AD%D9%84-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 95%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام</td><td>نوع</td><td>محل</td><td>الزامی</td><td>توضیح</td></tr><tr><td>file</td><td>file</td><td>form‑data</td><td>بله</td><td>فایل آپلودی (تصویر، PDF و...)</td></tr><tr><td>branch</td><td>integer</td><td>body</td><td>بله</td><td>شناسه شعبه مرتبط با کاربر</td></tr><tr><td>type</td><td>string</td><td>body</td><td>بله</td><td>نوع منطقی گروه ذخیره (مثل `profile`، `invoice`)</td></tr><tr><td>size</td><td>integer</td><td>body</td><td>خیر</td><td>حداکثر بایت مجاز (پیش‌فرض ۵۱۲۰ KB)</td></tr><tr><td>mimes</td><td>string</td><td>body</td><td>خیر</td><td>فرمت‌های مجاز مثل `jpeg,png,pdf`</td></tr></tbody></table>

</div>### ساختار خروجی موفق

```
{
  "status": true,
  "file": "uploads/5/profile/2025/11/png/2025-11-23-1732355844.png"
}
```

### ساختار خروجی خطا

```
{
  "status": false,
  "error": "The file field is required."
}
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2%E2%80%AF%D9%87%D9%88%DB%8C%D8%AA%E2%80%AF%D8%A8%D8%A7%E2%80%AFjwt%E2%80%AF%D8%A7%D8%AC" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- احراز هویت با JWT اجباری است (`authWithJwt` middleware).
- فرمت‌ها و حجم فایل قبل از ذخیره اعتبارسنجی می‌شود.
- مسیر فایل در خروجی شامل نام شعبه و نوع فایل است، بدون افشای داده‌های احراز هویت.
- استفاده از وقت سیستم برای پرهیز از نام‌های تکراری (مقاومت در برابر collision).

</div>### نکات عملکردی

<div id="bkmrk-%D9%85%D8%AA%D9%88%D8%B3%D8%B7%E2%80%AF%D8%B2%D9%85%D8%A7%D9%86%E2%80%AF%D8%A2%D9%BE%D9%84%D9%88%D8%AF%E2%80%AF%D8%A8%D8%B1%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- متوسط زمان آپلود برای فایل ۳ MB در LAN ≈ ۲۵۰ میلی‌ثانیه.
- فایل در storage/app/uploads ذخیره می‌شود؛ توصیه به به‌کارگیری Laravel Symlink برای public visibility.
- عدم استفاده از queue در این نسخه؛ در صورت نیاز به آنتی‌ویروس scan می‌توان queue افزود.

</div>### Dependencies

<div id="bkmrk-use%E2%80%AFilluminate%5Chttp%5C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Illuminate\\Http\\Request;
- use Carbon\\Carbon;
- use Illuminate\\Support\\Facades\\Storage;
- use App\\Http\\Middleware\\AuthWithJWT;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-400-%D8%B9%D8%AF%D9%85%E2%80%AF" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr><td>کد</td><td>شرح</td><td>منبع</td></tr><tr><td>400</td><td>عدم اعتبار فایل ارسالی یا خطای upload</td><td>Validation / Exception</td></tr><tr><td>401</td><td>توکن JWT نامعتبر یا منقضی</td><td>Middleware</td></tr><tr><td>403</td><td>کاربر مجوز upload ندارد</td><td>Policy (در صورت فعال)</td></tr><tr><td>422</td><td>فیلد اجباری ناقص یا فرمت نامعتبر</td><td>Laravel Validator</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%DA%A9%D8%A7%D9%87%D8%B4%E2%80%AF%D8%AD%D8%AF%D8%A7%DA%A9%D8%AB%D8%B1%E2%80%AF%D8%A7%D9%86%D8%AF%D8%A7%D8%B2%D9%87%E2%80%AF%D8%A2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- کاهش حداکثر اندازه آپلود در پنل کاربران عادی.
- اسکن محتوای فایل (PDF/Image) قبل از انتشار در سیستم عمومی.
- تغییر نام دایرکتوری‌ها به UUID در نسخه‌های آتی.

</div>### پیشنهادهای توسعه‌ای

<div id="bkmrk-%D8%A7%D8%B6%D8%A7%D9%81%D9%87%E2%80%AF%DA%A9%D8%B1%D8%AF%D9%86%E2%80%AF%D9%BE%D8%B4%D8%AA%DB%8C%D8%A8%D8%A7%D9%86%DB%8C%E2%80%AF" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- اضافه کردن پشتیبانی از storage cloud (S3، MinIO و ...)
- افزودن نوع پرونده در metadata پاسخ.
- تخصیص امتداد hash‑based برای امنیت بیشتر.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D8%AB%D8%A8%D8%AA%E2%80%AF%D8%AF%D8%B1%E2%80%AFsystem_logs%E2%80%AF%D8%A8" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ثبت در `system_logs` با فیلد های: `uploader_id, branch, type, path, timestamp, ip`
- در صورت Exception، پلاک در Redis: `upload:errors:{branch}` ایجاد می‌شود.

</div>### جمع‌بندی

تابع **upload** یک endpoint سبک، امن و متن‌باز برای آپلود ساده فایل در زیرسیستم های داخلی سیستم است. با ساختار دایرکتوری پرمبنا (بر اساس branch و type) قابل گسترش برای ذخیره‌سازی امن و تفکیک‌شده می‌باشد.

<div id="bkmrk-upload-file" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>